@niivue/niivue 0.38.10 → 0.40.0

package/README.md

@@ -26,9 +26,10 @@ The command `npm run demo` will minify the project and locally host all of the [
 # Projects and People using NiiVue
 
 - Analysis of Functional NeuroImages (AFNI) [Scientific and Statistical Computing Core](https://afni.nimh.nih.gov/) (National Institutes of Health)
+- [ChRIS Research Integration System (ChRIS)  from Boston Children's Hospital](https://chrisproject.org/) uses [NiiVue](https://app.chrisproject.org/niivue).
 - [Center for the Study of Aphasia Recovery](https://cstar.sc.edu/) (University of South Carolina)
 - FMRIB's Software Library (FSL) [Wellcome Centre for Integrative Neuroimaging](https://www.win.ox.ac.uk/) (University of Oxford)
-- FreeSurfer [Laboratories for Computational Neuroimaging](https://lcn.martinos.org/) (Massachusetts General Hospital)
+- FreeSurfer [Laboratories for Computational Neuroimaging](https://lcn.martinos.org/) (Massachusetts General Hospital) uses NiiVue for [FreeBrowse](https://github.com/freesurfer/freebrowse)
 - [OpenNeuro.org](https://openneuro.org) uses NiiVue to visualize datasets
 - [BrainLife.io](https://brainlife.io/about/) integrates NiiVue into [ezbids](https://brainlife.io/ezbids/)
 - [nilearn](https://nilearn.github.io/stable/index.html) is extending [ipyniivue](https://github.com/niivue/ipyniivue)
@@ -50,5 +51,5 @@ NiiVue supports many popular brain imaging formats:
 - 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
+- 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), [TSF](https://mrtrix.readthedocs.io/en/dev/getting_started/image_data.html#track-scalar-file-format-tsf), [TT](https://dsi-studio.labsolver.org/doc/cli_data.html), 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)

package/{dist → build}/index.d.ts

@@ -248,8 +248,13 @@ type LegacyConnectome = Partial<ConnectomeOptions> & {
 type ValuesArray = Array<{
     id: string;
     vals: number[];
+    global_min?: number;
+    global_max?: number;
+    cal_min?: number;
+    cal_max?: number;
 }>;
-type AnyNumberArray = number[] | Float64Array | Float32Array | Uint32Array | Uint16Array | Uint8Array | Int32Array | Int16Array | Int8Array;
+type TypedNumberArray = Float64Array | Float32Array | Uint32Array | Uint16Array | Uint8Array | Int32Array | Int16Array | Int8Array;
+type AnyNumberArray = number[] | TypedNumberArray;
 type DefaultMeshType = {
     positions: Float32Array;
     indices: Int32Array;
@@ -260,6 +265,10 @@ type TRACT = {
     offsetPt0: number[];
     dps: ValuesArray;
 };
+type TT = {
+    pts: number[];
+    offsetPt0: number[];
+};
 type TRX = {
     pts: number[];
     offsetPt0: number[];
@@ -269,14 +278,14 @@ type TRX = {
     header: unknown;
 };
 type TRK = {
-    pts: number[];
-    offsetPt0: number[];
+    pts: Float32Array;
+    offsetPt0: Uint32Array;
     dps: ValuesArray;
     dpv: ValuesArray;
 };
 type TCK = {
-    pts: number[];
-    offsetPt0: number[];
+    pts: Float32Array;
+    offsetPt0: Uint32Array;
 };
 type VTK = DefaultMeshType | {
     pts: Float32Array;
@@ -386,14 +395,15 @@ declare class NVMesh {
     opacity: number;
     visible: boolean;
     meshShaderIndex: number;
-    offsetPt0: number[] | null;
+    offsetPt0: number[] | Uint32Array | null;
     colormapInvert: boolean;
     fiberGroupColormap: ColorMap | null;
     indexBuffer: WebGLBuffer;
     vertexBuffer: WebGLBuffer;
     vao: WebGLVertexArrayObject;
-    pts: number[];
-    tris?: number[];
+    vaoFiber: WebGLVertexArrayObject;
+    pts: number[] | Float32Array;
+    tris?: number[] | Uint32Array;
     layers: NVMeshLayer[];
     type: MeshType;
     data_type?: string;
@@ -403,6 +413,9 @@ declare class NVMesh {
     fiberDither: number;
     fiberColor: string;
     fiberDecimationStride: number;
+    fiberSides: number;
+    fiberRadius: number;
+    f32PerVertex: number;
     fiberMask?: unknown[];
     colormap?: ColorMap | LegacyConnectome | string | null;
     dpg?: ValuesArray | null;
@@ -440,14 +453,16 @@ declare class NVMesh {
      * @param colorbarVisible - does this mesh display a colorbar
      * @param anatomicalStructurePrimary - region for mesh. Default is an empty string
      */
-    constructor(pts: number[], tris: number[], name: string | undefined, rgba255: number[] | undefined, opacity: number | undefined, visible: boolean | undefined, gl: WebGL2RenderingContext, connectome?: LegacyConnectome | string | null, dpg?: ValuesArray | null, dps?: ValuesArray | null, dpv?: ValuesArray | null, colorbarVisible?: boolean, anatomicalStructurePrimary?: string);
+    constructor(pts: number[] | Float32Array, tris: number[] | Uint32Array, name: string | undefined, rgba255: number[] | undefined, opacity: number | undefined, visible: boolean | undefined, gl: WebGL2RenderingContext, connectome?: LegacyConnectome | string | null, dpg?: ValuesArray | null, dps?: ValuesArray | null, dpv?: ValuesArray | null, colorbarVisible?: boolean, anatomicalStructurePrimary?: string);
+    linesToCylinders(gl: WebGL2RenderingContext, posClrF32: Float32Array, indices: number[]): void;
     updateFibers(gl: WebGL2RenderingContext): void;
     updateConnectome(gl: WebGL2RenderingContext): void;
+    indexNearestXYZmm(Xmm: number, Ymm: number, Zmm: number): number[];
     updateMesh(gl: WebGL2RenderingContext): void;
     reverseFaces(gl: WebGL2RenderingContext): void;
     setLayerProperty(id: number, key: keyof NVMeshLayer, val: number | string | boolean, gl: WebGL2RenderingContext): void;
     setProperty(key: keyof this, val: unknown, gl: WebGL2RenderingContext): void;
-    generatePosNormClr(pts: number[], tris: number[], rgba255: number[]): Float32Array;
+    generatePosNormClr(pts: number[] | Float32Array, tris: number[] | Uint32Array, rgba255: number[]): Float32Array;
     static loadConnectomeFromFreeSurfer(json: {
         points?: Point[];
         data_type: string;
@@ -495,6 +510,8 @@ declare class NVMesh {
     static readTxtVTK(buffer: ArrayBuffer): VTK;
     static readTRK(buffer: ArrayBuffer): TRK;
     static readTCK(buffer: ArrayBuffer): TCK;
+    static readTSF(buffer: ArrayBuffer): Float32Array;
+    static readTT(buffer: ArrayBuffer): TT;
     static readTRX(buffer: ArrayBuffer): TRX;
     static readTRACT(buffer: ArrayBuffer): TRACT;
 }
@@ -739,14 +756,14 @@ declare class NVImage {
     intensityRaw2Scaled(raw: number): number;
     intensityScaled2Raw(scaled: number): number;
     saveToUint8Array(fnm: string, drawing8?: Uint8Array | null): Uint8Array;
-    saveToDisk(fnm: string, drawing8?: Uint8Array | null): Uint8Array;
+    saveToDisk(fnm?: string, drawing8?: Uint8Array | null): Uint8Array;
     static fetchDicomData(url: string, headers?: Record<string, string>): Promise<ArrayBuffer[]>;
     static fetchPartial(url: string, bytesToLoad: number, headers?: Record<string, string>): Promise<Response>;
     /**
      * factory function to load and return a new NVImage instance from a given URL
      * @returns  NVImage instance
      */
-    static loadFromUrl({ url, urlImgData, headers, name, colormap, opacity, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, visible, useQFormNotSForm, colormapNegative, frame4D, isManifest, limitFrames4D, imageType }?: Partial<Omit<ImageFromUrlOptions, 'url'>> & {
+    static loadFromUrl({ url, urlImgData, headers, name, colormap, opacity, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, visible, useQFormNotSForm, colormapNegative, frame4D, isManifest, limitFrames4D, imageType, colorbarVisible }?: Partial<Omit<ImageFromUrlOptions, 'url'>> & {
         url?: string | Uint8Array | ArrayBuffer;
     }): Promise<NVImage>;
     static readFileAsync(file: File, bytesToLoad?: number): Promise<ArrayBuffer>;
@@ -808,6 +825,10 @@ declare class NVImage {
      * Converts NVImage to NIfTI compliant byte array
      */
     toUint8Array(drawingBytes?: Uint8Array | null): Uint8Array;
+    convertVox2Frac(vox: vec3): vec3;
+    convertFrac2Vox(frac: vec3): vec3;
+    convertFrac2MM(frac: vec3, isForceSliceMM?: boolean): vec4;
+    convertMM2Frac(mm: vec3 | vec4, isForceSliceMM?: boolean): vec3;
 }
 
 type FreeSurferConnectome = {
@@ -906,13 +927,16 @@ type NVConfigOptions = {
     isRadiologicalConvention: boolean;
     meshThicknessOn2D: number | string;
     dragMode: DRAG_MODE;
+    yoke3Dto2DZoom: boolean;
     isDepthPickMesh: boolean;
     isCornerOrientationText: boolean;
     sagittalNoseLeft: boolean;
     isSliceMM: boolean;
+    isV1SliceShader: boolean;
     isHighResolutionCapable: boolean;
     logLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
     loadingText: string;
+    isForceMouseClickToVoxelCenters: boolean;
     dragAndDropEnabled: boolean;
     drawingEnabled: boolean;
     penValue: number;
@@ -1311,6 +1335,16 @@ declare class NVUtilities {
      * @returns filled number array
      */
     static range(start: number, stop: number, step: number): number[];
+    /**
+     * convert spherical AZIMUTH, ELEVATION to Cartesian
+     * @param azimuth - azimuth number
+     * @param elevation - elevation number
+     * @returns the converted [x, y, z] coordinates
+     * @example
+     * xyz = NVUtilities.sph2cartDeg(42, 42)
+     */
+    static sph2cartDeg(azimuth: number, elevation: number): number[];
+    static vox2mm(XYZ: number[], mtx: mat4): vec3;
 }
 
 /**
@@ -1318,11 +1352,13 @@ declare class NVUtilities {
  */
 declare class NVMeshLoaders {
     static readTRACT(buffer: ArrayBuffer): TRACT;
+    static readTT(buffer: ArrayBuffer): TT;
     static readTRX(buffer: ArrayBuffer): TRX;
+    static readTSF(buffer: ArrayBuffer, n_vert?: number): Float32Array;
     static readTCK(buffer: ArrayBuffer): TCK;
     static readTRK(buffer: ArrayBuffer): TRK;
     static readTxtVTK(buffer: ArrayBuffer): VTK;
-    static readLayer(name: string, buffer: ArrayBuffer, nvmesh: NVMesh, opacity?: number, colormap?: string, colormapNegative?: string, useNegativeCmap?: boolean, cal_min?: number | null, cal_max?: number | null, isOutlineBorder?: boolean): void;
+    static readLayer(name: string | undefined, buffer: ArrayBuffer, nvmesh: NVMesh, opacity?: number, colormap?: string, colormapNegative?: string, useNegativeCmap?: boolean, cal_min?: number | null, cal_max?: number | null, isOutlineBorder?: boolean): void;
     static readSMP(buffer: ArrayBuffer, n_vert: number): Float32Array;
     static readSTC(buffer: ArrayBuffer, n_vert: number): Float32Array;
     static readCURV(buffer: ArrayBuffer, n_vert: number): Float32Array;
@@ -1460,12 +1496,15 @@ type NiiVueOptions = {
     isCornerOrientationText?: boolean;
     sagittalNoseLeft?: boolean;
     isSliceMM?: boolean;
+    isV1SliceShader?: boolean;
     isHighResolutionCapable?: boolean;
+    isForceMouseClickToVoxelCenters?: boolean;
     drawingEnabled?: boolean;
     penValue?: number;
     floodFillNeighbors?: number;
     maxDrawUndoBitmaps?: number;
     thumbnail?: string;
+    meshXRay?: number;
 };
 type UIData = {
     mousedown: boolean;
@@ -1493,6 +1532,11 @@ type UIData = {
     loading$: Subject<unknown>;
     dpr?: number;
 };
+type SaveImageOptions = {
+    filename: string;
+    isSaveDrawing: boolean;
+    volumeByIndex: number;
+};
 /**
  * Niivue can be attached to a canvas. An instance of Niivue contains methods for
  * loading and rendering NIFTI image data in a WebGL 2.0 context.
@@ -1523,6 +1567,7 @@ declare class Niivue {
     overlayTexture: WebGLTexture | null;
     overlayTextureID: WebGLTexture | null;
     sliceMMShader?: Shader;
+    sliceV1Shader?: Shader;
     orientCubeShader?: Shader;
     orientCubeShaderVAO: WebGLVertexArrayObject | null;
     rectShader?: Shader;
@@ -1809,13 +1854,16 @@ declare class Niivue {
         isRadiologicalConvention: boolean;
         meshThicknessOn2D: string | number;
         dragMode: DRAG_MODE;
+        yoke3Dto2DZoom: boolean;
         isDepthPickMesh: boolean;
         isCornerOrientationText: boolean;
         sagittalNoseLeft: boolean;
         isSliceMM: boolean;
+        isV1SliceShader: boolean;
         isHighResolutionCapable: boolean;
         logLevel: "debug" | "info" | "warn" | "error" | "fatal" | "silent";
         loadingText: string;
+        isForceMouseClickToVoxelCenters: boolean;
         dragAndDropEnabled: boolean;
         drawingEnabled: boolean;
         penValue: number;
@@ -2183,10 +2231,10 @@ declare class Niivue {
      * @param isSaveDrawing - determines whether drawing or background image is saved
      * @param volumeByIndex - determines layer to save (0 for background)
      * @param volumeByIndex - determines layer to save (0 for background)
-     * @example niivue.saveImage('test.nii', true);
+     * @example niivue.saveImage(\{ filename: "myimage.nii.gz", isSaveDrawing: true \});
      * @see {@link https://niivue.github.io/niivue/features/draw.ui.html|live demo usage}
      */
-    saveImage(fnm: string, isSaveDrawing?: boolean, volumeByIndex?: number): Uint8Array | boolean;
+    saveImage(options?: SaveImageOptions): Uint8Array | boolean;
     getMeshIndexByID(id: string | number): number;
     /**
      * change property of mesh, tractogram or connectome
@@ -2336,7 +2384,7 @@ declare class Niivue {
      * niivue.setCrosshairColor([0, 1, 0, 0.5]) // set crosshair to transparent green
      * @see {@link https://niivue.github.io/niivue/features/colormaps.html|live demo usage}
      */
-    setCrosshairColor(color: number[]): Promise<void>;
+    setCrosshairColor(color: number[]): void;
     /**
      * set thickness of crosshair
      * @example niivue.crosshairWidth(2)
@@ -2786,7 +2834,7 @@ declare class Niivue {
     mouseClick(x: number, y: number, posChange?: number, isDelta?: boolean): void;
     drawRuler(): void;
     drawRuler10cm(startXYendXY: number[]): void;
-    screenXY2mm(x: number, y: number, forceSlice?: number): vec3;
+    screenXY2mm(x: number, y: number, forceSlice?: number): vec4;
     dragForPanZoom(startXYendXY: number[]): void;
     dragForCenterButton(startXYendXY: number[]): void;
     dragForSlicer3D(startXYendXY: number[]): void;