@niivue/niivue 0.32.0 → 0.33.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +68 -61
- package/dist/niivue.es.js +47687 -108162
- package/dist/niivue.umd.js +42 -52
- package/package.json +21 -19
- package/src/cmaps/index.js +2 -2
- package/src/colortables.js +1 -1
- package/src/index.html +68 -64
- package/src/indexDraw.html +351 -342
- package/src/indexFloodFillDraw.html +81 -73
- package/src/indexFullScreen.html +93 -70
- package/src/indexIntelGPU.html +158 -81
- package/src/indexIntensityDraw.html +45 -32
- package/src/niivue.js +281 -138
- package/src/nvcontroller.js +1 -1
- package/src/nvdocument.js +7 -3
- package/src/nvimage.js +42 -22
- package/src/nvmesh.js +488 -186
- package/src/session-bus.js +1 -1
- package/src/shader-srcs.js +24 -1
- package/src/testForFFLATE.html +39 -0
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
-
NiiVue allows developers to create interactive web pages for visualizing
|
|
5
|
+
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.
|
|
6
6
|
|
|
7
7
|
# Getting started Docs and References
|
|
8
8
|
|
|
@@ -16,15 +16,16 @@ Installs without the bloat of the development dependencies or testing frameworks
|
|
|
16
16
|
npm install --only=prod @niivue/niivue
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
#
|
|
19
|
+
# Mission
|
|
20
20
|
|
|
21
|
-
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),
|
|
21
|
+
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), ([FreeSurfer](https://surfer.nmr.mgh.harvard.edu/), [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).
|
|
22
22
|
|
|
23
23
|
# Projects and People using NiiVue
|
|
24
24
|
|
|
25
25
|
- Analysis of Functional NeuroImages (AFNI) [Scientific and Statistical Computing Core](https://afni.nimh.nih.gov/) (National Institutes of Health)
|
|
26
26
|
- [Center for the Study of Aphasia Recovery](https://cstar.sc.edu/) (University of South Carolina)
|
|
27
27
|
- FMRIB's Software Library (FSL) [Wellcome Centre for Integrative Neuroimaging](https://www.win.ox.ac.uk/) (University of Oxford)
|
|
28
|
+
- FreeSurfer [Laboratories for Computational Neuroimaging](https://lcn.martinos.org/) (Massachusetts General Hospital)
|
|
28
29
|
- [OpenNeuro.org](https://openneuro.org)
|
|
29
30
|
- [BrainLife.io](https://brainlife.io/about/)
|
|
30
31
|
|
|
@@ -34,7 +35,7 @@ We host many NiiVue examples via github pages. These are updated and deployed au
|
|
|
34
35
|
|
|
35
36
|
[See the examples here](https://niivue.github.io/niivue/)
|
|
36
37
|
|
|
37
|
-
# Requirements for NiiVue to work
|
|
38
|
+
# Requirements for NiiVue to work
|
|
38
39
|
|
|
39
40
|
- [WebGL 2.0 capable](https://caniuse.com/webgl2) web browser (Chrome, FireFox, Safari).
|
|
40
41
|
|
|
@@ -48,22 +49,30 @@ While NiiVue can be wrapped with frameworks (VueJS, React, Angular), you can als
|
|
|
48
49
|
<!DOCTYPE html>
|
|
49
50
|
<html lang="en">
|
|
50
51
|
<head>
|
|
51
|
-
<meta charset="utf-8"
|
|
52
|
+
<meta charset="utf-8" />
|
|
52
53
|
<title>NiiVue</title>
|
|
53
54
|
</head>
|
|
54
55
|
<body>
|
|
55
|
-
<canvas id="gl"></canvas>
|
|
56
|
+
<canvas id="gl" width="640" height="640"></canvas>
|
|
56
57
|
</body>
|
|
57
|
-
<script src="https://
|
|
58
|
-
<script>
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
nv.
|
|
63
|
-
|
|
58
|
+
<script src="https://niivue.github.io/niivue/features/niivue.umd.js"></script>
|
|
59
|
+
<script>
|
|
60
|
+
var volumeList = [
|
|
61
|
+
{ url: "https://niivue.github.io/niivue-demo-images/mni152.nii.gz" },
|
|
62
|
+
];
|
|
63
|
+
var nv = new niivue.Niivue({ isResizeCanvas: false });
|
|
64
|
+
nv.attachTo("gl");
|
|
65
|
+
nv.loadVolumes(volumeList);
|
|
66
|
+
</script>
|
|
64
67
|
</html>
|
|
65
68
|
```
|
|
66
69
|
|
|
70
|
+
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:
|
|
71
|
+
|
|
72
|
+
```html
|
|
73
|
+
<script src="https://unpkg.com/@niivue/niivue@0.32.0/dist/niivue.umd.js"></script>
|
|
74
|
+
```
|
|
75
|
+
|
|
67
76
|
## VueJS example
|
|
68
77
|
|
|
69
78
|
install: `npm i @niivue/niivue`
|
|
@@ -93,7 +102,7 @@ export default {
|
|
|
93
102
|
mounted() {
|
|
94
103
|
|
|
95
104
|
nv.attachTo('gl')
|
|
96
|
-
nv.loadVolumes(this.volumeList)
|
|
105
|
+
nv.loadVolumes(this.volumeList)
|
|
97
106
|
}
|
|
98
107
|
}
|
|
99
108
|
|
|
@@ -111,61 +120,60 @@ export default {
|
|
|
111
120
|
install: `npm i @niivue/niivue`
|
|
112
121
|
|
|
113
122
|
```js
|
|
114
|
-
import { useRef, useEffect } from
|
|
115
|
-
import { Niivue } from
|
|
123
|
+
import { useRef, useEffect } from "react";
|
|
124
|
+
import { Niivue } from "@niivue/niivue";
|
|
116
125
|
|
|
117
126
|
const NiiVue = ({ imageUrl }) => {
|
|
118
|
-
const canvas = useRef()
|
|
127
|
+
const canvas = useRef();
|
|
119
128
|
useEffect(() => {
|
|
120
129
|
const volumeList = [
|
|
121
130
|
{
|
|
122
131
|
url: imageUrl,
|
|
123
132
|
},
|
|
124
|
-
]
|
|
125
|
-
const nv = new Niivue()
|
|
126
|
-
nv.attachToCanvas(canvas.current)
|
|
127
|
-
nv.loadVolumes(volumeList)
|
|
128
|
-
}, [imageUrl])
|
|
129
|
-
|
|
130
|
-
return
|
|
131
|
-
|
|
132
|
-
)
|
|
133
|
-
}
|
|
133
|
+
];
|
|
134
|
+
const nv = new Niivue();
|
|
135
|
+
nv.attachToCanvas(canvas.current);
|
|
136
|
+
nv.loadVolumes(volumeList);
|
|
137
|
+
}, [imageUrl]);
|
|
138
|
+
|
|
139
|
+
return <canvas ref={canvas} height={480} width={640} />;
|
|
140
|
+
};
|
|
134
141
|
|
|
135
142
|
// use as: <NiiVue imageUrl={someUrl}> </NiiVue>
|
|
136
143
|
```
|
|
144
|
+
|
|
137
145
|
## Angular example
|
|
146
|
+
|
|
138
147
|
Check our [Angular TypeScript development notes](docs/development-notes/angular-typescript.md) for instructions on building an Angular App with Niivue.
|
|
139
148
|
|
|
140
149
|
install: `npm i @niivue/niivue`
|
|
141
150
|
|
|
142
151
|
```ts
|
|
143
|
-
import { Component, OnInit,
|
|
152
|
+
import { Component, OnInit, ViewChild } from "@angular/core";
|
|
144
153
|
|
|
145
|
-
import {Niivue} from
|
|
154
|
+
import { Niivue } from "@niivue/niivue";
|
|
146
155
|
|
|
147
156
|
@Component({
|
|
148
|
-
selector:
|
|
149
|
-
templateUrl:
|
|
150
|
-
styleUrls: [
|
|
157
|
+
selector: "app-niivue-view",
|
|
158
|
+
templateUrl: "./niivue-view.component.html",
|
|
159
|
+
styleUrls: ["./niivue-view.component.sass"],
|
|
151
160
|
})
|
|
152
161
|
export class NiivueViewComponent implements OnInit {
|
|
153
|
-
@ViewChild(
|
|
162
|
+
@ViewChild("gl") canvas: HTMLCanvasElement | undefined;
|
|
154
163
|
|
|
155
|
-
constructor() {
|
|
164
|
+
constructor() {}
|
|
156
165
|
|
|
157
166
|
ngOnInit(): void {
|
|
158
|
-
const url =
|
|
167
|
+
const url = "/assets/mni152.nii.gz";
|
|
159
168
|
const volumeList = [
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
169
|
+
{
|
|
170
|
+
url,
|
|
171
|
+
},
|
|
172
|
+
];
|
|
164
173
|
const niivue = new Niivue();
|
|
165
|
-
niivue.attachTo(
|
|
174
|
+
niivue.attachTo("gl");
|
|
166
175
|
niivue.loadVolumes(volumeList);
|
|
167
176
|
}
|
|
168
|
-
|
|
169
177
|
}
|
|
170
178
|
```
|
|
171
179
|
|
|
@@ -186,11 +194,11 @@ export class NiivueViewComponent implements OnInit {
|
|
|
186
194
|
|
|
187
195
|
NiiVue can open several formats popular with brain imaging:
|
|
188
196
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
197
|
+
- 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).
|
|
198
|
+
- 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/).
|
|
199
|
+
- 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)
|
|
200
|
+
- 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
|
|
201
|
+
- DICOM: [DICOM](https://dicom.nema.org/medical/dicom/current/output/chtml/part10/chapter_7.html) and [DICOM Manifests](docs/development-notes/dicom-manifests.md)
|
|
194
202
|
|
|
195
203
|
# Alternatives
|
|
196
204
|
|
|
@@ -229,7 +237,7 @@ npm install --save-dev @niivue/niivue
|
|
|
229
237
|
|
|
230
238
|
## Local Development
|
|
231
239
|
|
|
232
|
-
Make sure you have nodejs and npm installed.
|
|
240
|
+
Make sure you have nodejs and npm installed.
|
|
233
241
|
|
|
234
242
|
```
|
|
235
243
|
git clone git@github.com:niivue/niivue.git
|
|
@@ -240,7 +248,7 @@ npm run dev
|
|
|
240
248
|
|
|
241
249
|
## Launch included demos
|
|
242
250
|
|
|
243
|
-
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.
|
|
251
|
+
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.
|
|
244
252
|
|
|
245
253
|
**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.**
|
|
246
254
|
|
|
@@ -274,7 +282,7 @@ npm run build-win
|
|
|
274
282
|
|
|
275
283
|
## Versioning
|
|
276
284
|
|
|
277
|
-
NiiVue uses [semantic versioning](https://semver.org/).
|
|
285
|
+
NiiVue uses [semantic versioning](https://semver.org/).
|
|
278
286
|
|
|
279
287
|
To update the version run:
|
|
280
288
|
|
|
@@ -314,6 +322,7 @@ npm run test -- -t 'test string'
|
|
|
314
322
|
```
|
|
315
323
|
|
|
316
324
|
## Creating fonts
|
|
325
|
+
|
|
317
326
|
```
|
|
318
327
|
{ echo "data:image/png;base64,"; openssl enc -base64 -in fnt.png; } > fnt.txt
|
|
319
328
|
|
|
@@ -322,17 +331,17 @@ npm run test -- -t 'test string'
|
|
|
322
331
|
|
|
323
332
|
# Contributing
|
|
324
333
|
|
|
325
|
-
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).
|
|
334
|
+
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).
|
|
326
335
|
|
|
327
336
|
## Using Issues
|
|
328
337
|
|
|
329
|
-
**All** contributions should start as a new issue on the [NiiVue issue board](https://github.com/niivue/niivue/issues).
|
|
338
|
+
**All** contributions should start as a new issue on the [NiiVue issue board](https://github.com/niivue/niivue/issues).
|
|
330
339
|
|
|
331
|
-
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.
|
|
340
|
+
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.
|
|
332
341
|
|
|
333
342
|
## Things to consider
|
|
334
343
|
|
|
335
|
-
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.
|
|
344
|
+
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.
|
|
336
345
|
|
|
337
346
|
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`.
|
|
338
347
|
|
|
@@ -342,23 +351,23 @@ NiiVue relies on [Jest](https://jestjs.io/)
|
|
|
342
351
|
|
|
343
352
|
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.
|
|
344
353
|
|
|
345
|
-
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.
|
|
354
|
+
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.
|
|
346
355
|
|
|
347
356
|
## Automated CI/CD
|
|
348
357
|
|
|
349
358
|
We rely heavily on GitHub's actions to automate testing and checks.
|
|
350
359
|
|
|
351
|
-
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.
|
|
360
|
+
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.
|
|
352
361
|
|
|
353
|
-
Each PR to the main branch must pass the automated checks, and must be reviewed and signed off by at least one other person.
|
|
362
|
+
Each PR to the main branch must pass the automated checks, and must be reviewed and signed off by at least one other person.
|
|
354
363
|
|
|
355
|
-
If all checks and tests pass then PRs will be merged into main.
|
|
364
|
+
If all checks and tests pass then PRs will be merged into main.
|
|
356
365
|
|
|
357
|
-
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.
|
|
366
|
+
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.
|
|
358
367
|
|
|
359
368
|
## Protected branches
|
|
360
369
|
|
|
361
|
-
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.
|
|
370
|
+
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.
|
|
362
371
|
|
|
363
372
|
## Making colormap loader
|
|
364
373
|
|
|
@@ -377,5 +386,3 @@ sudo lsof -iTCP -sTCP:LISTEN -n -P | grep 8888 # 8888 is the test server used by
|
|
|
377
386
|
|
|
378
387
|
kill <pid> # kill the node process running the server if needed (when tests fail locally)
|
|
379
388
|
```
|
|
380
|
-
|
|
381
|
-
|