neurosurf/README.Rmd at master · bbuchsbaum/neurosurf · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```
[![Travis-CI Build Status](https://app.travis-ci.com/bbuchsbaum/neurosurf.svg?branch=master)](https://app.travis-ci.com/bbuchsbaum/neurosurf)

# neurosurf

`neurosurf` is an R package for reading, manipulating, and visualizing
surface-based neuroimaging data represented as triangle meshes. It focuses on
surface geometry, vertex-wise data, smoothing, geodesic neighborhoods, and
both static and interactive rendering workflows.

The package is under active development.

## Installation

Install the development version from GitHub with:

```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("bbuchsbaum/neurosurf")
```

## Start here

The pkgdown site includes a few good entry points:

- [Introduction to NeuroSurf Data Structures](https://bbuchsbaum.github.io/neurosurf/articles/introduction-to-neurosurf.html)
- [Displaying Surfaces with RGL](https://bbuchsbaum.github.io/neurosurf/articles/displaying-surfaces.html)
- [Interactive Surface Visualization with surfwidget](https://bbuchsbaum.github.io/neurosurf/articles/interactive-surfaces.html)
- [Surfplot-style Figures with neurosurf](https://bbuchsbaum.github.io/neurosurf/articles/surfplot-style-figures.html)
- [Reference index](https://bbuchsbaum.github.io/neurosurf/reference/index.html)

## Development setup

`neurosurf` includes an interactive 3D visualization component powered by
[surfviewjs](https://github.com/bbuchsbaum/surfviewjs). The built UMD bundle is
committed so `devtools::install_github()` works without Node; Node is only
needed if you want to rebuild the JavaScript library locally.

### Prerequisites

- Node.js (v14 or higher)
- npm

### Building surfviewjs

```bash
# Build the surfviewjs library and copy it into neurosurf
make surfview

# Check build status
make status

# Clean build artifacts
make clean-surfview
```

The Makefile will:

1. Install npm dependencies in `surfviewjs` if needed
2. Build the library with Vite
3. Copy the UMD bundle to `inst/htmlwidgets/lib/neurosurface/`
4. Synchronize the version number into `surfwidget.yaml`

### Workflow integration

```bash
# Before R CMD check
make r-check

# Install package
make r-install

# Watch for changes during development
make watch-surfview  # Requires fswatch
```

### Version management

The version number in `surfwidget.yaml` is synchronized with
`surfviewjs/package.json` when `make surfview` runs. To update it manually:

```bash
make update-yaml
make show-version
```