@niivue/niivue 0.68.2 → 1.0.0-rc.3

package/LICENSE

@@ -0,0 +1,24 @@
+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.

package/README.md

@@ -1,14 +1,120 @@
-# 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         # ESLint check
+bun run lint:fix     # ESLint auto-fix
+bun run typecheck    # TypeScript type checking (tsc --noEmit)
+```
+
+### 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 'niivuegpu'
+
+  const nv = new NiiVue()
+  await nv.attachToCanvas(document.getElementById('gl1'))
+  await nv.loadVolumes([{ url: '/volumes/mni152.nii.gz' }])
+</script>
+```
+
+### Backend-specific distributions
+
+By default, `niivuegpu` includes both backends (WebGPU + WebGL2 fallback):
+
+```js
+import NiiVue from 'niivuegpu'
+```
+
+You can also import backend-only builds to reduce package size:
+
+```js
+import NiiVueWebGPU from 'niivuegpu/webgpu' // WebGPU-only
+import NiiVueWebGL2 from 'niivuegpu/webgl2' // WebGL2-only
 ```
-git clone git@github.com:niivue/niivue.git
-cd niivue
-npm install
-npm run dev
+
+In backend-only builds, selecting the missing backend throws an explicit error.
+
+### Load a mesh
+
+```js
+await nv.loadMeshes([{ url: '/meshes/brain.mz3' }])
 ```
+
+### 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,86 @@
+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;
+}>;
+/** 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);
+}