@niivue/niivue 0.9.3 → 0.12.1

package/README.md

@@ -4,6 +4,10 @@ NiiVue is a WebGL 2.0 medical image viewer. This repository contains the **core
 
 The NiiVue package is intented to be used by individuals developing interactive web pages related to showing [nifti](https://nifti.nimh.nih.gov) images. 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 [web-based user interface implementation](https://github.com/niivue/niivue-ui) (under development) will demonstrate how to integrate NiiVue into a more comprehensive [VueJS](https://vuejs.org/) UI.  
 
+# Getting started Docs and References
+
+[click here to go to the docs web page](https://niivue.github.io/niivue/devdocs/)
+
 # Active Projects
 
 [See our active projects here](https://github.com/orgs/niivue/projects)
@@ -33,8 +37,8 @@ We host many NiiVue examples via github pages. These are updated and deployed au
 # Usage
 
 ## existing html page
-```
-<script src="https://unpkg.com/@niivue/niivue@0.9.3/dist/niivue.js"></script>
+```html
+<script src="https://unpkg.com/@niivue/niivue@0.12.1/dist/niivue.js"></script>
 
 <canvas id="gl" height=480 width=640></canvas>
 
@@ -45,11 +49,8 @@ We host many NiiVue examples via github pages. These are updated and deployed au
         url: "./some_image.nii.gz",
         volume: {hdr: null, img: null},
         name: "some_image",
-        intensityMin: 0, // not used yet
-        intensityMax: 100, // not used yet
-        intensityRange:[0, 100], // not used yet
         colorMap: "gray",
-        opacity: 100,
+        opacity: 1,
         visible: true,
       }
    ]
@@ -59,16 +60,17 @@ We host many NiiVue examples via github pages. These are updated and deployed au
  var nv = new niivue.Niivue()
  nv.attachTo('gl') // the canvas element id
  nv.loadVolumes(volumeList)
- nv.setSliceType(nv.sliceTypeMultiPlanar)
+ nv.setSliceType(nv.sliceTypeMultiPlanar) // press the "v" key to cycle through views
 </script>
 ```
 
 ## VueJS example
 
-```
+install: `npm i @niivue/niivue`
+
+```js
 <script>
 import {Niivue} from '@niivue/niivue'
-console.log(Niivue)
 const nv = new Niivue()
 
 
@@ -84,7 +86,7 @@ export default {
           url: "./mni152.nii.gz",
           volume: {hdr: null, img: null},
           colorMap: "gray",
-          opacity: 100,
+          opacity: 1,
           visible: true,
         }
       ]
@@ -95,7 +97,7 @@ export default {
   mounted() {
 
     nv.attachTo('gl')
-    nv.loadVolumes(this.volumeList)
+    nv.loadVolumes(this.volumeList) // press the "v" key to cycle through views
 
   }
 }
@@ -116,13 +118,41 @@ export default {
 
 ## React example
 
-to come...
- 
+install: `npm i @niivue/niivue`
+
+```js
+import { useRef, useState } from 'react'
+import { Niivue } from '@niivue/niivue'
+
+const NiiVue = ({ imageUrl }) => {
+  const canvas = useRef()
+  useEffect(() => {
+    const volumeList = [
+      {
+        url: imageUrl,
+        volume: { hdr: null, img: null },
+        colorMap: 'gray',
+        opacity: 1,
+        visible: true,
+      },
+    ]
+    const nv = new Niivue()
+    nv.attachToCanvas(canvas)
+    nv.loadVolumes(volumeList) // press the "v" key to cycle through volumes
+  }, [imageUrl])
+
+  return (
+    <canvas ref={canvas} height={480} width={640} />
+  )
+}
+```
+
 # Contributors
 
 - [Taylor Hanayik](https://github.com/hanayik)
 - [Chris Rorden](https://github.com/neurolabusc)
 - [Christopher Drake](https://github.com/cdrake)
+- [Nell Hardcastle](https://github.com/nellh)
 
 *To add yourself please create a PR
 
@@ -183,6 +213,14 @@ Source code can be found in `src/`.
 
 You can edit the sources and then launch demos to see the effect of your changes. See the "Launch inlcluded demos" section.
 
+## Run hot module reload development mode
+
+This will run the vite HMR dev server. Open a browser to the URL output in your terminal. changes made to the source code will be immediately reflected in the browser. 
+
+```
+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.  
@@ -233,7 +271,15 @@ Running the tests will format, build, and copy the bundled `niivue.js` to the `t
 
 ### on macOS and Linux
 
+**If using macOS with Apple Silicon add this to your .zshrc (if zsh). Also ensure Chrome is installed at that location:**
+
+```
+export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+export PUPPETEER_EXECUTABLE_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
+```
+
 ```
+npm install
 npm run test
 ```
 
@@ -297,4 +343,22 @@ You can edit a feature branch as many times as needed to fix broken tests in ord
 
 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
+
+```
+cd src/cmaps
+
+for f in ls *.json; do echo "export { default as `basename $f .json` } from './$f';" >> index.js; done;
+```
+
+## macOS kill test server if kept alive because of failing tests
+
+```
+sudo lsof -iTCP -sTCP:LISTEN -n -P | grep 8888 # 8888 is the test server used by jest
+
+# the process id is the second column in the result
+
+kill <pid> # kill the node process running the server if needed (when tests fail locally)
+```
+