Skip to content

README.md

Latest commit

 

History

History
131 lines (92 loc) · 5.53 KB

README.md

File metadata and controls

131 lines (92 loc) · 5.53 KB
Raw

ZincJS

ZincJS is a JavaScript library for displaying anatomical and physiological models in the web browser. It is the web counterpart of OpenCMISS-Zinc: scenes built with PyZinc, Scaffold Maker or the Mapping Tools can be exported and shown interactively on a web page, keeping their region hierarchy, named anatomical groups, graphics settings and time-varying data.

It is built on three.js and renders with WebGPU, falling back to WebGL 2 where WebGPU is unavailable.

Why ZincJS?

General-purpose 3D libraries can draw meshes, but they know nothing about Zinc models. ZincJS adds the pieces needed for biomedical scaffolds:

  • Direct pipeline from Zinc – load scenes exported from PyZinc / the Argon scene exporter through a single metadata file, with no custom loader code.
  • Region hierarchy and named groups – objects are organised in a Zinc-like region tree and identified by anatomical group names, which makes it straightforward to link a 3D structure to search, highlighting and ontology terms.
  • Time-varying models – morph-target animation of geometry and field colours (for example a beating heart or gut motility), with scene-wide playback control.
  • Primitives for scaffolds and fields – surfaces, lines, tube lines, point sets, glyph sets for vector/tensor fields, labels, markers with clustering and level-of-detail switching.
  • Imaging alongside models – volume rendering and texture slices from NIfTI images in the same scene as the scaffold.
  • Application features – multiple scenes per renderer, picking, smooth camera transitions, auto-tumble, stereo, minimap, video synchronisation and glTF import/export.

Applications built with ZincJS:

Installation

Install from npm:

$ npm install zincjs

Pre-releases are published under the beta tag (npm install zincjs@beta).

Quick start

import Zinc from 'zincjs';

const container = document.getElementById('zinc-container');
const renderer = new Zinc.Renderer(container);
await renderer.initialiseVisualisation();

const scene = renderer.getCurrentScene();
scene.loadMetadataURL('models/metadata.json', undefined, () => {
  scene.viewAll();
});

renderer.animate();

initialiseVisualisation is asynchronous and must finish before any scene is used. Other formats can be loaded with scene.loadGLTF, scene.loadOBJ and scene.loadSTL, and NIfTI images with Zinc.createPrimitivesFromNIFTI.

Render on demand

By default the renderer draws every animation frame. To only draw when something has changed, which saves GPU time and battery on idle pages, enable render on demand:

renderer.setRenderOnDemand(true);

Camera movement, playback, loading, changes made through the ZincJS APIs and changes to scene properties such as displayMinimap, displayMiniAxes or displayMarkers request a frame automatically. Call renderer.invalidate() after changing three.js objects directly, or after changing the three.js renderer from getThreeJSRenderer(), e.g. setClearColor. Pre-render callbacks still run every frame and can call invalidate(); post-render callbacks only run when a frame is drawn.

Useful links:

Exporting models to ZincJS

Both produce a metadata JSON file plus the files it references. Keep them in the same folder and pass the metadata file's URL to scene.loadMetadataURL.

Legacy: exporting from CMGUI

  1. Read in your files in CMGUI and set up the graphics and viewing window.

  2. Export with gfx export threejs (run gfx export threejs ? for options) and note the filename_prefix you choose.

  3. Adjust the view, then run gfx list win 1 and copy the eye point, interest point, up vector, near plane and far plane into a view file:

    {
  "farPlane": 601.12,
  "nearPlane": 14.81,
  "upVector": [0.0, 1.0, 0.0],
  "targetPosition": [9.7, 6.39, -5.0],
  "eyePosition": [9.7, 6.39, 291.2]
}

  4. The first exported file ([filename_prefix]_1.json) is the metadata file. Add an entry for the view file to it:

    { "Type": "View", "URL": "new_models_view.json" }

Controls

Action Mouse Touch
Rotate Left button drag One-finger drag
Zoom Middle button drag / scroll wheel Two-finger pinch
Pan Right button drag Three-finger drag

Building from source

Requires Node.js 24.

$ npm install
$ npm run build-bundle   # outputs build/zinc.js and its source map
$ npm run test-standard  # run the test suite
$ npm run jsdoc          # regenerate the API documentation in docs/

License

MIT