@niivue/niivue 0.69.0 → 1.0.0-rc.10

package/LICENSE

@@ -0,0 +1,34 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, NiiVue
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+-------------------------------------------------------------------------------
+
+Third-party acknowledgment
+
+The magnetic resonance spectroscopy (MRS/MRSI) features in this package port
+algorithms from fsleyes-plugin-mrs, distributed under the BSD 3-Clause License
+(Copyright (c) 2021, William Clarke, University of Oxford. All rights reserved).
+The upstream license is reproduced verbatim in LICENSE.fsleyes-plugin-mrs and the
+porting provenance is documented in PORTING.md (both shipped in this package).

package/LICENSE.fsleyes-plugin-mrs

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2020-2021, William Clarke, University of Oxford
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/PORTING.md

@@ -0,0 +1,49 @@
+# Porting provenance: fsleyes-plugin-mrs -> NiiVue
+
+NiiVue's MRS support — the core spectral math and the `MrsScene` controller —
+ports algorithms from **fsleyes-plugin-mrs** (BSD-3-Clause, (c) 2021 William
+Clarke, University of Oxford; co-author Vasilis Karlaftis; acks Paul McCarthy).
+The upstream license is shipped verbatim as `LICENSE.fsleyes-plugin-mrs`.
+
+The spectral math lives in NiiVue **core** (`packages/niivue/src/signal/processing.ts`
+and `packages/niivue/src/volume/mrsi.ts`) so it can be shared with single-voxel
+spectroscopy (`svs.html`); this package supplies the FSL-MRS display defaults,
+the range-to-map tool, and the scene controller.
+
+NiiVue follows camelCase / `NV*` naming; where it does not conflict, function
+and constant names mirror the upstream so the port is auditable.
+
+## Function-by-function map
+
+| NiiVue (TypeScript) | Upstream (Python) | Notes |
+|---|---|---|
+| `GYRO_MAG_RATIO`, `PPM_SHIFT`, `PPM_RANGE` (core `processing.ts`) | `constants.py` (`GYRO_MAG_RATIO`, `PPM_SHIFT`, `PPM_RANGE`) | dict literals ported verbatim |
+| `ppmRefForNucleus()` (core) | `PPM_SHIFT[nucleus]` lookup | the additive ppm offset (1H = 4.65) |
+| `halveFirstPoint()` (core) | `calcSpectrum`: `data[..., 0] *= 0.5` (`utils.py`) | first-FID-point scaling |
+| `deriveSpectroscopySeries()` FFT+fftshift (core) | `calcSpectrum`: `np.fft.fft` then `np.fft.fftshift` (`utils.py`) | no conjugation |
+| Hz axis `(i-half)/(nFFT*dwell)` (core) | `calcFrequencies`: `fftfreq(n, dwell)` + `fftshift` (`powerspectrumseries.py`) | dwell = `pixdim[4]` |
+| Hz->ppm `-hz/specFreq + shift` (core) | `_set_mrs_plot_scale`: `xScale = -1/spec_freq`, `xOffset = PPM_SHIFT` (`views.py`) | display-only transform |
+| `apodize()` (core) | `apodize`: `exp(-t/(1/broadening))`, `t = linspace(0, dwell*(N-1), N)` (`utils.py`) | exponential line-broadening |
+| `phaseCorrection()` (core) | `phaseCorrection`: `exp(1j*2*pi*(p0/360 + freqs*p1))` (`powerspectrumseries.py`) | p0 degrees, p1 seconds (UI ms /1000) |
+| `integratePpmBandMap()` (core) | `range_tool.draw_overlay`: apodize -> `calcSpectrum` -> `phaseCorrection` -> `sum(abs|real(spectrum[..., band]), axis=-1)` (`range_tool.py`) | per-voxel band integral |
+| `makeMetaboliteMap()` naming `SpecSum_{lo}_{hi}` | `range_tool.draw_overlay`: `f'SpecSum_{lo:0.1f}_{hi:0.1f}'` | overlay name |
+| transient averaging in `deriveSpectroscopySeries` / `integratePpmBandMap` | `apply_higher_dim_operations` mean branch (`utils.py`) | dims 5-7 mean reduction (index/diff deferred) |
+
+## Reference parity values
+
+`packages/niivue/src/signal/processing.test.ts` mirrors the upstream
+`tests/test_utils.py` cases:
+
+- `calcSpectrum([1,2,3,4])` -> `fftshift(fft([0.5,2,3,4]))` = `[-2.5, -2.5-2j, 9.5, -2.5+2j]`
+- `apodize([1,2,3,4], dwell=0.1, broadening=1)` -> `[1,2,3,4] * exp(-[0,0.1,0.2,0.3])`
+- `phaseCorrection` zero-order rotation (p0 in degrees).
+
+## Deferred / not yet ported
+
+- `apply_higher_dim_operations` index/difference branches and DIM_COIL SVD coil
+  combination (the demo dataset has no higher dims; only the mean branch is used).
+- MRSI fit-results loading (`tools.py`: tree + colourscheme -> fit/baseline/
+  residual spectra and concentration/QC maps). Deferred — the demo dataset has
+  no `fsl_mrsi` results directory. When ported, the upstream restricted-`eval`
+  colourscheme heuristic will be replaced with a safe expression evaluator.
+- Interactive Ctrl/Shift-drag phasing (`profiles.py`): the demo uses sliders.

package/README.md

@@ -1,14 +1,210 @@
-# NiiVue
+# NiiVueGPU
 
-NiiVue is web-based visualization tool for neuroimaging that can run on any operating system and any web device (phone, tablet, computer). This repository contains only the **core NiiVue package** that can be embedded into other projects. See [niivue.com](https://niivue.com/) for examples and documentation. 
+NiiVue is a tool for visualizing volumes, meshes, and tractography streamlines commonly used in neuroimaging. The original NiiVue project evolved organically, resulting in tightly coupled model, view, and controller components. This repository refactors the codebase to improve maintainability and to support emerging technologies such as WebGPU.
 
-## Local Development
+## Getting Started
 
-To run a hot-loading development that is updated whenever you save changes to any source files, you can run:
+### Prerequisites
 
+- [Bun](https://bun.sh/)
+- A browser with WebGPU support (Chrome, Firefox). Safari works if you have a recent MacOS (version 26) or iOS. Older browsers will fall back to the WebGL2 renderer.
+
+### Build Commands
+
+```bash
+bun install          # Install dependencies
+bun run dev          # Hot-reload dev server
+bun run build        # Library build to ./dist (published npm package)
+bun run deploy       # Production examples-site build to ./dist (GitHub Pages)
+bun run demo         # Build examples site and serve locally
+bun run lint         # Biome check
+bun run lint:fix     # Biome auto-fix
+bun run typecheck    # TypeScript type checking (tsc --noEmit)
 ```
-git clone git@github.com:niivue/niivue.git
-cd niivue
-npm install
-npm run dev
+
+### Perf instrumentation
+
+The renderer carries `performance.mark`/`measure` instrumentation
+(`src/view/NVPerfMarks.ts`) gated on a single runtime flag. Consumers:
+
+- **App code:** `nv.perf.enabled = true`, then listen for the
+  `perfFrame` event to receive `{ tag, cpuMs, submitMs, totalMs, phases }`
+  per render. Tag user-driven frames via `nv.perf.tagFrame('myAction')`
+  before mutating state.
+- **Benchmark harness** at `examples/benchmark.html` flips the same
+  flag and reads `consumeFrameStats()` plus the `niivue:render-*`
+  PerformanceObserver entries.
+
+When `enabled` is `false` every helper bails on its first line; cost
+in production is one well-predicted branch per call site. See
+`benchmarks/README.md` for the harness workflow.
+
+### Development Workflows
+
+- **`bun run dev`** — Runs the `demos/` pages with hot reloading. A Vite plugin intercepts `import '../dist/niivuegpu.mjs'` and redirects it to source, so demo scripts stay identical to the deployed versions but get full HMR. Asset directories in `demos/` are symlinked to `public/` on first run.
+- **`bun run demo`** — Builds the library to `demos/dist/`, copies assets, and serves with `http-server`. Use this to test the actual built output or before deploying to GitHub Pages.
+
+## Usage
+
+Add a `<canvas>` to your page and attach NiiVueGPU to it:
+
+```html
+<canvas id="gl1"></canvas>
+<script type="module">
+  import NiiVue from '@niivue/niivue'
+
+  const nv = new NiiVue()
+  await nv.attachToCanvas(document.getElementById('gl1'))
+  await nv.loadVolumes([{ url: '/volumes/mni152.nii.gz' }])
+</script>
 ```
+
+### Backend-specific distributions
+
+By default, `@niivue/niivue` includes both backends (WebGPU + WebGL2 fallback):
+
+```js
+import NiiVue from '@niivue/niivue'
+```
+
+You can also import backend-only builds to reduce package size:
+
+```js
+import NiiVueWebGPU from '@niivue/niivue/webgpu' // WebGPU-only
+import NiiVueWebGL2 from '@niivue/niivue/webgl2' // WebGL2-only
+```
+
+In backend-only builds, selecting the missing backend throws an explicit error.
+
+### Load a mesh
+
+```js
+await nv.loadMeshes([{ url: '/meshes/brain.mz3' }])
+```
+
+### Signals (physio and spectroscopy)
+
+Alongside spatial volumes and meshes, NiiVue can load **signals** — a third,
+non-spatial data class shown as 2-D line plots rather than slices. Two kinds are
+supported: `physio` (BIDS time-series TSV) and `spectroscopy` (NIfTI-MRS complex
+FID). Sibling `.json` sidecars are fetched automatically for axis metadata
+(sampling rate / StartTime for physio, SpectrometerFrequency / ResonantNucleus
+for spectroscopy).
+
+```js
+// BIDS physio (auto-fetches the sibling .json sidecar)
+await nv.loadSignals([{ url: '/signals/recording_physio.tsv.gz' }])
+
+// NIfTI-MRS spectroscopy; setSignal drives the on-demand FFT + ppm windowing
+await nv.loadSignals([{ url: '/signals/svs_se_30.nii.gz' }])
+nv.setSignal(0, { display: { average: true, mode: 'real', ppmRange: [1.9, 3.3] } })
+```
+
+NIfTI files are routed to the signal loader when they have no spatial extent
+(dim1-3 == 1, dim4 > 1); pass `asSignal` to override. MRS sidecar/header fields do
+**not** affect routing — a spatial spectroscopic image (MRSI/CSI) carries them too,
+so it stays on the volume path.
+
+A physio signal can be associated with a 4D volume by passing `attachToId` (the
+volume's id). The graph then shows the crosshair BOLD time-course together with
+each physio trace at its native sampling rate on a shared time axis, clamped to
+the imaging window; clicking the graph scrubs the volume to the nearest frame.
+
+A dense signal graph can be panned and zoomed via on-graph buttons (the view
+follows the cursor on wheel/frame steps) or the controller API (`graphZoom`,
+`graphPan`); `graphLineWidth` / `graphLineAlpha` tune trace thickness and opacity
+for overlapping series, and `graphShowVolumeTimecourse` toggles the BOLD trace.
+Missing physio samples are left as gaps and marked with a short tick along the
+bottom axis (the "missing-data rug").
+
+Signals can carry **annotations** — text labels anchored to a position in the
+graph's own data units (e.g. ppm for spectroscopy). They translate as the x-axis
+window is panned/zoomed and are hidden when out of range. A `y` of `-Infinity` or
+`+Infinity` pins the label to the bottom or top of the plot. Annotations render on
+the signal graph (spectrum / physio plot); they are not currently drawn on the
+volume+physio association time-course view.
+
+```js
+// Label metabolite peaks pinned to the bottom of the spectrum
+await nv.loadSignals([{
+  url: '/signals/svs_se_30.nii.gz',
+  annotations: [
+    { text: 'NAA', x: 2.0, y: -Infinity },
+    { text: 'Cr',  x: 3.0, y: -Infinity },
+    { text: 'Cho', x: 3.2, y: -Infinity },
+  ],
+}])
+nv.setSignal(0, { annotations: [/* replace the full set */] })
+```
+
+See `examples/svs.html` (spectroscopy, with NAA/Cr/Cho annotations and a scene
+selector pairing the spectrum with the participant's T2w and an outline-shaded
+"voxel" marker at the sampling location), `examples/physio.html` (physio), and
+`examples/physio.bold.html` (a task-fMRI run with per-trace fMRI/respiratory/
+cardiac toggles, on-graph pan/zoom, and a volume+physio association graph) for
+interactive demos.
+
+#### Spatial spectroscopic imaging (MRSI/CSI)
+
+A complex 4-D NIfTI-MRS volume (dim1-3 = space, dim4 = FID) stays on the volume
+path and is driven by the core `MrsScene` controller: it loads an anatomy
+reference plus the MRSI grid, shows the crosshair-voxel spectrum (which tracks
+the crosshair like the FSLeyes MRS plugin), and generates ppm-band metabolite
+maps. See `examples/mrsi.html`. The spectral transforms and the `MrsScene`
+controller are ported from
+[fsleyes-plugin-mrs](https://git.fmrib.ox.ac.uk/fsl/fsleyes/fsleyes-plugin-mrs)
+(BSD-3-Clause); see `PORTING.md` for the function-by-function provenance map.
+
+### Change slice type and colormap
+
+```js
+nv.sliceType = 3                        // 0=Axial, 1=Coronal, 2=Sagittal, 3=Multi, 4=Render
+nv.setVolume(0, { colormap: 'hot' })    // apply colormap to first volume
+```
+
+### Configuration options
+
+Pass options to the constructor to customize the viewer:
+
+```js
+const nv = new NiiVue({
+  isColorbarVisible: true,
+  backgroundColor: [0, 0, 0, 1],
+  clipPlaneColor: [1, 1, 1, 0.5],
+})
+```
+
+### Testing
+
+The package includes a unit test suite for non-rendering (server-side) logic using the [Bun test runner](https://bun.sh/docs/cli/test). Tests are co-located with source files as `*.test.ts`.
+
+```bash
+bun test                # Run all tests with coverage
+bun test src/drawing/   # Run tests in a specific directory
+bun test --watch        # Watch mode
+```
+
+Coverage is enabled by default (configured in `bunfig.toml`) and outputs both a console summary and an `lcov` report to `coverage/`. Tested modules include:
+
+- **Drawing tools** — RLE codec, pen/line/flood-fill, undo stack
+- **Annotations** — undo/redo, point-in-polygon, slice projection, shape selection
+- **Math/transforms** — vox↔mm conversions, spherical coordinates, slice plane equations
+- **Volume utilities** — intensity range calculation, NIfTI header creation, voxel lookup, reorientation
+- **Colormaps** — LUT generation, label colormap construction
+- **Mesh I/O** — STL/OBJ writers, STL/OFF readers (roundtrip tests)
+
+To run tests via Nx from the monorepo root:
+
+```bash
+bunx nx test niivue
+```
+
+### Architecture
+
+The codebase is written in **TypeScript** and follows an MVC pattern with dual rendering backends (WebGPU and WebGL2). See [CLAUDE.md](CLAUDE.md) for detailed architecture documentation, directory structure, code style, and module naming conventions.
+
+### Dependencies
+
+- [nifti-reader-js](https://github.com/rii-mango/NIFTI-Reader-JS) — NIfTI file parsing
+- [gl-matrix](https://glmatrix.net/) — Vector/matrix math (vec3, vec4, mat3, mat4)
+- [cbor-x](https://github.com/nicolo-ribaudo/cbor-x) — CBOR encoding/decoding for document save/load and ITK-Wasm (.iwi.cbor) format support

package/dist/NVConstants.d.ts

@@ -0,0 +1,87 @@
+import { AnnotationConfig, DrawConfig, InteractionConfig, LayoutConfig, MeshRenderConfig, UIConfig, VolumeRenderConfig } from './NVTypes';
+export declare const NUM_CLIP_PLANE = 6;
+export declare const DEFAULT_CLIP_PLANE: readonly [0, 0, 0, 2];
+export declare enum COLORMAP_TYPE {
+    MIN_TO_MAX = 0,
+    ZERO_TO_MAX_TRANSPARENT_BELOW_MIN = 1,
+    ZERO_TO_MAX_TRANSLUCENT_BELOW_MIN = 2
+}
+export declare enum DRAG_MODE {
+    none = 0,
+    contrast = 1,
+    measurement = 2,
+    pan = 3,
+    slicer3D = 4,
+    callbackOnly = 5,
+    roiSelection = 6,
+    angle = 7,
+    crosshair = 8,
+    windowing = 9
+}
+export declare enum SHOW_RENDER {
+    NEVER = 0,
+    ALWAYS = 1,
+    AUTO = 2
+}
+export declare const NiiIntentCode: Readonly<{
+    readonly NIFTI_INTENT_NONE: 0;
+    readonly NIFTI_INTENT_CORREL: 2;
+    readonly NIFTI_INTENT_TTEST: 3;
+    readonly NIFTI_INTENT_FTEST: 4;
+    readonly NIFTI_INTENT_ZSCORE: 5;
+    readonly NIFTI_INTENT_LABEL: 1002;
+    readonly NIFTI_INTENT_NEURONAMES: 1005;
+    readonly NIFTI_INTENT_RGB_VECTOR: 2003;
+}>;
+export declare const NiiDataType: Readonly<{
+    readonly DT_NONE: 0;
+    readonly DT_BINARY: 1;
+    readonly DT_UINT8: 2;
+    readonly DT_INT16: 4;
+    readonly DT_INT32: 8;
+    readonly DT_FLOAT32: 16;
+    readonly DT_COMPLEX64: 32;
+    readonly DT_FLOAT64: 64;
+    readonly DT_RGB24: 128;
+    readonly DT_INT8: 256;
+    readonly DT_UINT16: 512;
+    readonly DT_UINT32: 768;
+    readonly DT_INT64: 1024;
+    readonly DT_UINT64: 1280;
+    readonly DT_FLOAT128: 1536;
+    readonly DT_COMPLEX128: 1792;
+    readonly DT_COMPLEX256: 2048;
+    readonly DT_RGBA32: 2304;
+}>;
+/** Check whether a volume is PAQD (Probabilistic Atlas Quad Datatype) */
+export declare function isPaqd(hdr: {
+    intent_code: number;
+    datatypeCode: number;
+}): boolean;
+export declare const MULTIPLANAR_TYPE: {
+    readonly 0: "AUTO";
+    readonly 1: "COLUMN";
+    readonly 2: "GRID";
+    readonly 3: "ROW";
+    readonly AUTO: 0;
+    readonly COLUMN: 1;
+    readonly GRID: 2;
+    readonly ROW: 3;
+};
+export declare const SLICE_TYPE: Readonly<{
+    readonly AXIAL: 0;
+    readonly CORONAL: 1;
+    readonly SAGITTAL: 2;
+    readonly MULTIPLANAR: 3;
+    readonly RENDER: 4;
+    readonly NONE: 5;
+}>;
+/** Maps AXIAL→2, CORONAL→1, SAGITTAL→0 (the RAS dimension perpendicular to the slice). */
+export declare function sliceTypeDim(sliceType: number): number;
+export declare const LAYOUT_DEFAULTS: LayoutConfig;
+export declare const UI_DEFAULTS: UIConfig;
+export declare const VOLUME_DEFAULTS: VolumeRenderConfig;
+export declare const MESH_DEFAULTS: MeshRenderConfig;
+export declare const DRAW_DEFAULTS: DrawConfig;
+export declare const INTERACTION_DEFAULTS: InteractionConfig;
+export declare const ANNOTATION_DEFAULTS: AnnotationConfig;

package/dist/NVControl.d.ts

@@ -0,0 +1,4 @@
+import { default as NiiVueGPUBase, NiiVueOptions } from './NVControlBase';
+export default class NiiVueGPU extends NiiVueGPUBase {
+    constructor(options?: NiiVueOptions);
+}