@niivue/niivue 0.31.0 → 0.33.0

package/README.md

@@ -2,7 +2,7 @@
 
 NiiVue is a WebGL 2.0 medical image viewer. This repository contains the **core NiiVue package**. We have additional projects under development that will demonstrate a [web-based user interface implementation](https://github.com/niivue/niivue-ui), and a [desktop application](https://github.com/niivue/niivue-desktop) built using web technologies.
 
-NiiVue allows developers to create interactive web pages for visualizing  [nifti](https://nifti.nimh.nih.gov) and other formats popular in neuroimaging. NiiVue includes many mouse and keyboard interactions that enable browsing and manipulating images displayed in the canvas. This core package does not include a comprehensive user interface outside of the canvas (e.g. buttons, and other widgets). However, developers who wish to build custom user interfaces around the NiiVue canvas can manipulate the rendered images and change settings via the API. Our [UI wrapper](https://github.com/niivue/niivue-ui) demonstrates how the modular core NiiVue can be embedded into a rich user interface.  
+NiiVue allows developers to create interactive web pages for visualizing [nifti](https://nifti.nimh.nih.gov) and other formats popular in neuroimaging. NiiVue includes many mouse and keyboard interactions that enable browsing and manipulating images displayed in the canvas. This core package does not include a comprehensive user interface outside of the canvas (e.g. buttons, and other widgets). However, developers who wish to build custom user interfaces around the NiiVue canvas can manipulate the rendered images and change settings via the API. Our [UI wrapper](https://github.com/niivue/niivue-ui) demonstrates how the modular core NiiVue can be embedded into a rich user interface.
 
 # Getting started Docs and References
 
@@ -18,7 +18,7 @@ npm install --only=prod @niivue/niivue
 
 # Overview/Mission
 
-NiiVue brings the features of the widely used native desktop applications ([AFNI](https://afni.nimh.nih.gov/about_afni), [FSLeyes](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSLeyes), [MRIcroGL](https://github.com/rordenlab/MRIcroGL), [Surfice](https://github.com/neurolabusc/surf-ice),  [SUMA](https://afni.nimh.nih.gov/Suma)) to the web. The developers of these tools developed NiiVue in collaboration, allowing us to benefit from collective wisdom. This will enable other researchers and developers to build cloud-based medical imaging tools with a powerful viewer that can operate on any device (desktop, tablet, mobile).  
+NiiVue brings the features of the widely used native desktop applications ([AFNI](https://afni.nimh.nih.gov/about_afni), [FSLeyes](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSLeyes), [MRIcroGL](https://github.com/rordenlab/MRIcroGL), [Surfice](https://github.com/neurolabusc/surf-ice), [SUMA](https://afni.nimh.nih.gov/Suma)) to the web. The developers of these tools developed NiiVue in collaboration, allowing us to benefit from collective wisdom. This will enable other researchers and developers to build cloud-based medical imaging tools with a powerful viewer that can operate on any device (desktop, tablet, mobile).
 
 # Projects and People using NiiVue
 
@@ -34,7 +34,7 @@ We host many NiiVue examples via github pages. These are updated and deployed au
 
 [See the examples here](https://niivue.github.io/niivue/)
 
-# Requirements for NiiVue to work  
+# Requirements for NiiVue to work
 
 - [WebGL 2.0 capable](https://caniuse.com/webgl2) web browser (Chrome, FireFox, Safari).
 
@@ -48,22 +48,30 @@ While NiiVue can be wrapped with frameworks (VueJS, React, Angular), you can als
 <!DOCTYPE html>
 <html lang="en">
   <head>
-    <meta charset="utf-8">
+    <meta charset="utf-8" />
     <title>NiiVue</title>
   </head>
   <body>
-    <canvas id="gl"></canvas>
+    <canvas id="gl" width="640" height="640"></canvas>
   </body>
-<script src="https://unpkg.com/@niivue/niivue@0.29.0/dist/niivue.umd.js"></script>
-<script>
- var volumeList = [{url: "https://niivue.github.io/niivue-demo-images/mni152.nii.gz"}]
- var nv = new niivue.Niivue()
- nv.attachTo('gl') 
- nv.loadVolumes(volumeList)
-</script>
+  <script src="https://niivue.github.io/niivue/features/niivue.umd.js"></script>
+  <script>
+    var volumeList = [
+      { url: "https://niivue.github.io/niivue-demo-images/mni152.nii.gz" },
+    ];
+    var nv = new niivue.Niivue({ isResizeCanvas: false });
+    nv.attachTo("gl");
+    nv.loadVolumes(volumeList);
+  </script>
 </html>
 ```
 
+Note that the code above will load the latest current stable release. Alternatively, you can specify a specific NiiVue version. For example, to ensure compatibility with release 0.32.0, you could specify:
+
+```html
+<script src="https://unpkg.com/@niivue/niivue@0.32.0/dist/niivue.umd.js"></script>
+```
+
 ## VueJS example
 
 install: `npm i @niivue/niivue`
@@ -93,7 +101,7 @@ export default {
   mounted() {
 
     nv.attachTo('gl')
-    nv.loadVolumes(this.volumeList) 
+    nv.loadVolumes(this.volumeList)
   }
 }
 
@@ -111,61 +119,60 @@ export default {
 install: `npm i @niivue/niivue`
 
 ```js
-import { useRef, useEffect } from 'react'
-import { Niivue } from '@niivue/niivue'
+import { useRef, useEffect } from "react";
+import { Niivue } from "@niivue/niivue";
 
 const NiiVue = ({ imageUrl }) => {
-  const canvas = useRef()
+  const canvas = useRef();
   useEffect(() => {
     const volumeList = [
       {
         url: imageUrl,
       },
-    ]
-    const nv = new Niivue()
-    nv.attachToCanvas(canvas.current)
-    nv.loadVolumes(volumeList)
-  }, [imageUrl])
-
-  return (
-    <canvas ref={canvas} height={480} width={640} />
-  )
-}
+    ];
+    const nv = new Niivue();
+    nv.attachToCanvas(canvas.current);
+    nv.loadVolumes(volumeList);
+  }, [imageUrl]);
+
+  return <canvas ref={canvas} height={480} width={640} />;
+};
 
 // use as: <NiiVue imageUrl={someUrl}> </NiiVue>
 ```
+
 ## Angular example
+
 Check our [Angular TypeScript development notes](docs/development-notes/angular-typescript.md) for instructions on building an Angular App with Niivue.
 
 install: `npm i @niivue/niivue`
 
 ```ts
-import { Component, OnInit,  ViewChild} from '@angular/core';
+import { Component, OnInit, ViewChild } from "@angular/core";
 
-import {Niivue} from '@niivue/niivue';
+import { Niivue } from "@niivue/niivue";
 
 @Component({
-  selector: 'app-niivue-view',
-  templateUrl: './niivue-view.component.html',
-  styleUrls: ['./niivue-view.component.sass']
+  selector: "app-niivue-view",
+  templateUrl: "./niivue-view.component.html",
+  styleUrls: ["./niivue-view.component.sass"],
 })
 export class NiivueViewComponent implements OnInit {
-  @ViewChild('gl') canvas:HTMLCanvasElement|undefined;
+  @ViewChild("gl") canvas: HTMLCanvasElement | undefined;
 
-  constructor() { }
+  constructor() {}
 
   ngOnInit(): void {
-    const url = '/assets/mni152.nii.gz';
+    const url = "/assets/mni152.nii.gz";
     const volumeList = [
-    {
-      url,
-    },
-  ]
+      {
+        url,
+      },
+    ];
     const niivue = new Niivue();
-    niivue.attachTo('gl');
+    niivue.attachTo("gl");
     niivue.loadVolumes(volumeList);
   }
-  
 }
 ```
 
@@ -186,11 +193,11 @@ export class NiivueViewComponent implements OnInit {
 
 NiiVue can open several formats popular with brain imaging:
 
- - Voxel-based formats: [NIfTI](https://brainder.org/2012/09/23/the-nifti-file-format/), [NRRD](http://teem.sourceforge.net/nrrd/format.html), [MRtrix MIF](https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#mrtrix-image-formats), [AFNI HEAD/BRIK](https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.attributes.html), [MGH/MGZ](https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat), [ITK MHD](https://itk.org/Wiki/ITK/MetaIO/Documentation#Reading_a_Brick-of-Bytes_.28an_N-Dimensional_volume_in_a_single_file.29), [ECAT7](https://github.com/openneuropet/PET2BIDS/tree/28aae3fab22309047d36d867c624cd629c921ca6/ecat_validation/ecat_info).
- - Mesh-based formats: [GIfTI](https://www.nitrc.org/projects/gifti/), [ASC](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [BrainSuite DFS](http://brainsuite.org/formats/dfs/), [PLY](https://en.wikipedia.org/wiki/PLY_(file_format)), [BrainNet NV](https://www.nitrc.org/projects/bnv/), [BrainVoyager SRF](https://support.brainvoyager.com/brainvoyager/automation-development/84-file-formats/344-users-guide-2-3-the-format-of-srf-files), [FreeSurfer](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [MZ3](https://github.com/neurolabusc/surf-ice/tree/master/mz3), [OFF](https://en.wikipedia.org/wiki/OFF_(file_format)), [Wavefront OBJ](https://brainder.org/tag/obj/), [STL](https://medium.com/3d-printing-stories/why-stl-format-is-bad-fea9ecf5e45), [Legacy VTK](https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf), [X3D](https://3dprint.nih.gov/).
- - Mesh overlay formats: [GIfTI](https://www.nitrc.org/projects/gifti/), [CIfTI-2](https://balsa.wustl.edu/about/fileTypes), [MZ3](https://github.com/neurolabusc/surf-ice/tree/master/mz3), [SMP](https://support.brainvoyager.com/brainvoyager/automation-development/84-file-formats/40-the-format-of-smp-files), STC, FreeSurfer (CURV/ANNOT)
- - Tractography formats: [TCK](https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck), [TRK](http://trackvis.org/docs/?subsect=fileformat), [TRX](https://github.com/frheault/tractography_file_format), VTK, AFNI .niml.tract
- - DICOM: [DICOM](https://dicom.nema.org/medical/dicom/current/output/chtml/part10/chapter_7.html) and [DICOM Manifests](docs/development-notes/dicom-manifests.md)
+- Voxel-based formats: [NIfTI](https://brainder.org/2012/09/23/the-nifti-file-format/), [NRRD](http://teem.sourceforge.net/nrrd/format.html), [MRtrix MIF](https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#mrtrix-image-formats), [AFNI HEAD/BRIK](https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.attributes.html), [MGH/MGZ](https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat), [ITK MHD](https://itk.org/Wiki/ITK/MetaIO/Documentation#Reading_a_Brick-of-Bytes_.28an_N-Dimensional_volume_in_a_single_file.29), [ECAT7](https://github.com/openneuropet/PET2BIDS/tree/28aae3fab22309047d36d867c624cd629c921ca6/ecat_validation/ecat_info).
+- Mesh-based formats: [GIfTI](https://www.nitrc.org/projects/gifti/), [ASC](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [BYU/GEO/G](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [BrainSuite DFS](http://brainsuite.org/formats/dfs/), [ICO/TRI](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [PLY](<https://en.wikipedia.org/wiki/PLY_(file_format)>), [BrainNet NV](https://www.nitrc.org/projects/bnv/), [BrainVoyager SRF](https://support.brainvoyager.com/brainvoyager/automation-development/84-file-formats/344-users-guide-2-3-the-format-of-srf-files), [FreeSurfer](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [MZ3](https://github.com/neurolabusc/surf-ice/tree/master/mz3), [OFF](<https://en.wikipedia.org/wiki/OFF_(file_format)>), [Wavefront OBJ](https://brainder.org/tag/obj/), [STL](https://medium.com/3d-printing-stories/why-stl-format-is-bad-fea9ecf5e45), [Legacy VTK](https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf), [X3D](https://3dprint.nih.gov/).
+- Mesh overlay formats: [GIfTI](https://www.nitrc.org/projects/gifti/), [CIfTI-2](https://balsa.wustl.edu/about/fileTypes), [MZ3](https://github.com/neurolabusc/surf-ice/tree/master/mz3), [SMP](https://support.brainvoyager.com/brainvoyager/automation-development/84-file-formats/40-the-format-of-smp-files), STC, FreeSurfer (CURV/ANNOT)
+- Tractography formats: [TCK](https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck), [TRK](http://trackvis.org/docs/?subsect=fileformat), [TRX](https://github.com/frheault/tractography_file_format), VTK, AFNI .niml.tract
+- DICOM: [DICOM](https://dicom.nema.org/medical/dicom/current/output/chtml/part10/chapter_7.html) and [DICOM Manifests](docs/development-notes/dicom-manifests.md)
 
 # Alternatives
 
@@ -229,7 +236,7 @@ npm install --save-dev @niivue/niivue
 
 ## Local Development
 
-Make sure you have nodejs and npm installed. 
+Make sure you have nodejs and npm installed.
 
 ```
 git clone git@github.com:niivue/niivue.git
@@ -240,7 +247,7 @@ npm run dev
 
 ## Launch included demos
 
-Launching the demos will format, build, and serve niivue demo pages. Open the demo URL in your browser to view the demo web pages. You can find the demo URL in your terminal after running `npm run demo`. The demos are intentionally simple, and each canvas showcases different NiiVue features.  
+Launching the demos will format, build, and serve niivue demo pages. Open the demo URL in your browser to view the demo web pages. You can find the demo URL in your terminal after running `npm run demo`. The demos are intentionally simple, and each canvas showcases different NiiVue features.
 
 **When viewing the demos during development, be sure to shift + click the refresh button in your browser in order to avoid using cached versions of files.**
 
@@ -274,7 +281,7 @@ npm run build-win
 
 ## Versioning
 
-NiiVue uses [semantic versioning](https://semver.org/). 
+NiiVue uses [semantic versioning](https://semver.org/).
 
 To update the version run:
 
@@ -314,6 +321,7 @@ npm run test -- -t 'test string'
 ```
 
 ## Creating fonts
+
 ```
 { echo "data:image/png;base64,"; openssl enc -base64 -in fnt.png; } > fnt.txt
 
@@ -322,17 +330,17 @@ npm run test -- -t 'test string'
 
 # Contributing
 
-Contributions to NiiVue are encouraged and welcomed. Feel free to update documentation, add features, fix bugs, or just ask questions on the [issue board](https://github.com/niivue/niivue/issues). 
+Contributions to NiiVue are encouraged and welcomed. Feel free to update documentation, add features, fix bugs, or just ask questions on the [issue board](https://github.com/niivue/niivue/issues).
 
 ## Using Issues
 
-**All** contributions should start as a new issue on the [NiiVue issue board](https://github.com/niivue/niivue/issues). 
+**All** contributions should start as a new issue on the [NiiVue issue board](https://github.com/niivue/niivue/issues).
 
-By starting a new issue for everything we ping everyone watching the project at the same time, and therefore alerting them to the feature, bug, or question. It also gives everyone a change to comment on new posts. 
+By starting a new issue for everything we ping everyone watching the project at the same time, and therefore alerting them to the feature, bug, or question. It also gives everyone a change to comment on new posts.
 
 ## Things to consider
 
-When adding features please keep in mind that we want NiiVue to work on all devices that support WebGL 2.0 (laptops, desktops, tablets, and phones). Therefore, please do your best to test features on as many devices as you have access to. 
+When adding features please keep in mind that we want NiiVue to work on all devices that support WebGL 2.0 (laptops, desktops, tablets, and phones). Therefore, please do your best to test features on as many devices as you have access to.
 
 When testing locally from other devices you can navigate to your development computer's local IP address (assuming your phone and computer are on the same local network) at the port specified in the URL you see when running `npm run demo`.
 
@@ -342,23 +350,23 @@ NiiVue relies on [Jest](https://jestjs.io/)
 
 If you add a feature, or fix a bug please try to add a test for it. You can find tests in the `tests` folder within the niivue project. There are numerous existing tests, so you can probably use one of those as a template. Generally, a test is contained with an `it('test name')` block in the `tests/test.niivue.js` file.
 
-Some tests generate screenshots of the WebGL canvas in order to compare renderings to previous snapshots. Please have a look at the current tests in order to see how you can add this to your new tests if needed. 
+Some tests generate screenshots of the WebGL canvas in order to compare renderings to previous snapshots. Please have a look at the current tests in order to see how you can add this to your new tests if needed.
 
 ## Automated CI/CD
 
 We rely heavily on GitHub's actions to automate testing and checks.
 
-These automated tests only test in a Linux desktop environment. So do please try to visually check that things work on other devices like tablets and phones when needed. 
+These automated tests only test in a Linux desktop environment. So do please try to visually check that things work on other devices like tablets and phones when needed.
 
-Each PR to the main branch must pass the automated checks, and must be reviewed and signed off by at least one other person. 
+Each PR to the main branch must pass the automated checks, and must be reviewed and signed off by at least one other person.
 
-If all checks and tests pass then PRs will be merged into main. 
+If all checks and tests pass then PRs will be merged into main.
 
-You can edit a feature branch as many times as needed to fix broken tests in order to get them passing and merged into main. 
+You can edit a feature branch as many times as needed to fix broken tests in order to get them passing and merged into main.
 
 ## Protected branches
 
-The `main` branch is protected. This means that no one can commit to main directly. All edits must be merged in from forks or feature branches. 
+The `main` branch is protected. This means that no one can commit to main directly. All edits must be merged in from forks or feature branches.
 
 ## Making colormap loader
 
@@ -377,5 +385,3 @@ sudo lsof -iTCP -sTCP:LISTEN -n -P | grep 8888 # 8888 is the test server used by
 
 kill <pid> # kill the node process running the server if needed (when tests fail locally)
 ```
-
-