zincjs 2.4.1-beta.3 → 2.4.1-beta.5

package/README.md

@@ -1,110 +1,126 @@
-ZincJS (Web-based-Zinc-Visualisation)
-=====================================
+ZincJS
+======
 
-Some of the following documentations are currerntly out-of-date .
+ZincJS is a JavaScript library for displaying anatomical and physiological models in the web browser. It is the web counterpart of [OpenCMISS-Zinc](https://github.com/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.
 
-Webapp developed using ZincJS:
-------------------------------
+It is built on [three.js](https://threejs.org/) and renders with WebGPU, falling back to WebGL 2 where WebGPU is unavailable.
 
-[SPARC Portal](https://sparc.science/maps?type=wholebody)
+Why ZincJS?
+-----------
 
-[Fitzlet](https://sites.bioeng.auckland.ac.nz/mwu035/fitzlet/)
+General-purpose 3D libraries can draw meshes, but they know nothing about Zinc models. ZincJS adds the pieces needed for biomedical scaffolds:
 
-[Scaffold Maker](https://mapcore-demo.org/2019/colon/scaffold.html)
+* **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.
 
-[ScaffoldVuer](https://mapcore-demo.org/current/scaffoldvuer)
+Applications built with ZincJS:
 
-Installation:
--------------
+* [SPARC Portal](https://sparc.science/maps?type=wholebody)
+* [ScaffoldVuer](https://mapcore-demo.org/current/scaffoldvuer)
+* [Scaffold Maker](https://mapcore-demo.org/2019/colon/scaffold.html)
+* [Fitzlet](https://sites.bioeng.auckland.ac.nz/mwu035/fitzlet/)
 
-You need NPM to build the ZincJS library. Once NPM has been installed, follow the instructions below:
+Installation
+------------
+
+Install from npm:
 
 ```Shell
-$ npm install
-$ npm run build-bundle
+$ npm install zincjs
 ```
 
-If everything works accordingly, a 'build' folder along with two files zinc.js and zinc.min.js in it should be created. The zinc.js and zinc.min.js can now be consumed in your preferred envirnoment.
-
-Useful links:
--------------
-
-[Examples](https://github.com/alan-wu/ZincJS-Examples/)
+Pre-releases are published under the `beta` tag (`npm install zincjs@beta`).
 
-[Tutorials](https://github.com/alan-wu/ZincJS-Tutorials/)
+Quick start
+-----------
 
-[API Documentation](https://abi-software.github.io/ZincJS/)
+```javascript
+import Zinc from 'zincjs';
 
-How to export models to ZincJS:
--------------------------------
+const container = document.getElementById('zinc-container');
+const renderer = new Zinc.Renderer(container);
+await renderer.initialiseVisualisation();
 
-Here is a short instruction on how to get simple models from CMGUI/Zinc showing on web brwoser quickly.
+const scene = renderer.getCurrentScene();
+scene.loadMetadataURL('models/metadata.json', undefined, () => {
+  scene.viewAll();
+});
 
-For Mapping Tool users:
------------------------
+renderer.animate();
+```
 
-[Argon scene exporter](https://abi-mapping-tools.readthedocs.io/en/v1.2.1/mapclientplugins.argonsceneexporterstep/docs/index.html)
+`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`.
 
-For PyZinc users:
------------------
+### Render on demand
 
-[PyZinc2ZincJS](https://github.com/alan-wu/PyZinc2ZincJS/)
+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:
 
-For Cmgui users:
-----------------
+```javascript
+renderer.setRenderOnDemand(true);
+```
 
-1. Download the latest cmgui from http://physiomeproject.org/software/opencmiss/cmgui/download/developer
+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.
 
-2. Read in your files, set up the graphics and viewing windows.
+Useful links:
 
-3. Export the json files using the following command gfx expore threejs, there are few different options regarding the export, make sure you read the instruction using "gfx export threejs ?" command. Please note down the filename_prefix you have chosen here. The number of files output may vary depending on the type of graphics.
+* [Examples](https://github.com/alan-wu/ZincJS-Examples/)
+* [Tutorials](https://github.com/alan-wu/ZincJS-Tutorials/)
+* [API documentation](https://abi-software.github.io/ZincJS/)
 
-4. A file containing information of the viewport is also required. After adjusting the viewport on Cmgui to the desired setting then note down the values of eye point, interest point, upvector, near plane and far plane from the output of the "gfx list win 1" command. For example with the following output:
+Exporting models to ZincJS
+--------------------------
 
-	farPlane: 601.1211762872496 
-	nearPlane: 14.809855917663832
-	upVector: [0.0, 1.0, 0.0]
-	interest point: [9.704483032226562, 6.385875701904297, -5.001008987426758] 
-	eye point: [9.704483032226562, 6.385875701904297, 291.1961093658496]}
+* **Mapping Tools users** – use the [Argon scene exporter](https://abi-mapping-tools.readthedocs.io/en/v1.2.1/mapclientplugins.argonsceneexporterstep/docs/index.html) step.
+* **PyZinc users** – see [PyZinc2ZincJS](https://github.com/alan-wu/PyZinc2ZincJS/).
 
-The viewport file will look like this: 
+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`.
 
-	{"farPlane": 601.1211762872496, "nearPlane": 14.809855917663832, "upVector": [0.0, 1.0, 0.0], "targetPosition": [9.704483032226562, 6.385875701904297, -5.001008987426758],  "eyePosition": [9.704483032226562, 6.385875701904297, 291.1961093658496]}
+<details>
+<summary>Legacy: exporting from CMGUI</summary>
 
-5. The first exported file -[filename]_1.json is the metadata file and contains
-informations of other required files including primitives type, url and etc. It also contains information of the viewport file (as mentioned above) but as the parameters are not known to the exporters. Users have to add it to the metadata file themselves and it looks something like:
+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:
 
-   {
-      "Type" : "View",
-      "URL" : "new_models_view.json"
-   }
+   ```json
+   {"farPlane": 601.12, "nearPlane": 14.81, "upVector": [0.0, 1.0, 0.0],
+    "targetPosition": [9.70, 6.39, -5.00], "eyePosition": [9.70, 6.39, 291.20]}
+   ```
 
-	
-Make sure all the json files are located in the same folder and now we should have all files required and we are ready to view them.
+4. The first exported file (`[filename_prefix]_1.json`) is the metadata file. Add an entry for the view file to it:
 
-*please not that only surfaces are supported at this moment.
+   ```json
+   { "Type": "View", "URL": "new_models_view.json" }
+   ```
 
-For PyZinc users:
-----------------
+</details>
 
-Take a look at the following page: https://github.com/alan-wu/PyZinc2ZincJS
+Controls
+--------
 
-Using the sample page:
-----------------------
+| 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      |
 
-I have included a simple html page - multiscenes_example.html which will display simple models.
-You can also view the following page to see mroe WebGL based Zinc in action: http://sites.bioeng.auckland.ac.nz/webgl_zinc_collections/
+Building from source
+--------------------
 
-Use of ThreeJS:
-----------------
+Requires Node.js 24.
 
-This library wraps the ThreeJS library and provides a more Zinc-like experience to users.
-I have modified the ThreeJS backend slightly to fit my usage here, you can find the github repository of my ThreeJS fork here: https://github.com/alan-wu/three.js
- 
-Basic controls:
----------------
+```Shell
+$ 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/
+```
 
-* Left click/single finger touch move: Rotate
-* Middle click/three finger touch move: Translate
-* Right click/two finger pinch: Zoom
+License
+-------
 
+[MIT](LICENSE)