@niivue/niivue 0.39.0 → 0.41.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,6 +248,10 @@ type LegacyConnectome = Partial<ConnectomeOptions> & {
 type ValuesArray = Array<{
     id: string;
     vals: number[];
+    global_min?: number;
+    global_max?: number;
+    cal_min?: number;
+    cal_max?: number;
 }>;
 type TypedNumberArray = Float64Array | Float32Array | Uint32Array | Uint16Array | Uint8Array | Int32Array | Int16Array | Int8Array;
 type AnyNumberArray = number[] | TypedNumberArray;
@@ -309,7 +313,7 @@ type MGH = AnyNumberArray | {
     colormapLabel: LUT;
 };
 type X3D = {
-    positions: number[];
+    positions: Float32Array;
     indices: Int32Array;
     rgba255: number[];
 };
@@ -342,7 +346,7 @@ type NVMeshLayer = {
     frame4D: number;
     nFrame4D: number;
     values: number[];
-    isOutlineBorder: boolean;
+    outlineBorder?: number;
     isTransparentBelowCalMin?: boolean;
     alphaThreshold: boolean;
     base64?: string;
@@ -397,6 +401,7 @@ declare class NVMesh {
     indexBuffer: WebGLBuffer;
     vertexBuffer: WebGLBuffer;
     vao: WebGLVertexArrayObject;
+    vaoFiber: WebGLVertexArrayObject;
     pts: number[] | Float32Array;
     tris?: number[] | Uint32Array;
     layers: NVMeshLayer[];
@@ -408,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;
@@ -446,8 +454,10 @@ declare class NVMesh {
      * @param anatomicalStructurePrimary - region for mesh. Default is an empty 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;
@@ -500,6 +510,7 @@ 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;
@@ -539,7 +550,6 @@ type ImageFromUrlOptions = {
     cal_max?: number;
     trustCalMinMax?: boolean;
     percentileFrac?: number;
-    visible?: boolean;
     useQFormNotSForm?: boolean;
     alphaThreshold?: boolean;
     colormapNegative?: string;
@@ -566,7 +576,6 @@ type ImageFromFileOptions = {
     trustCalMinMax?: boolean;
     percentileFrac?: number;
     ignoreZeroVoxels?: boolean;
-    visible?: boolean;
     useQFormNotSForm?: boolean;
     colormapNegative?: string;
     imageType?: ImageType;
@@ -583,7 +592,6 @@ type ImageFromBase64 = {
     trustCalMinMax?: boolean;
     percentileFrac?: number;
     ignoreZeroVoxels?: boolean;
-    visible?: boolean;
 };
 type ImageMetadata = {
     id: string;
@@ -598,7 +606,7 @@ type ImageMetadata = {
     dt: number;
     bpv: number;
 };
-declare const NVImageFromUrlOptions: (url: string, urlImageData?: string, name?: string, colormap?: string, opacity?: number, cal_min?: number, cal_max?: number, trustCalMinMax?: boolean, percentileFrac?: number, ignoreZeroVoxels?: boolean, visible?: boolean, useQFormNotSForm?: boolean, colormapNegative?: string, frame4D?: number, imageType?: ImageType, cal_minNeg?: number, cal_maxNeg?: number, colorbarVisible?: boolean, alphaThreshold?: boolean, colormapLabel?: string[]) => ImageFromUrlOptions;
+declare const NVImageFromUrlOptions: (url: string, urlImageData?: string, name?: string, colormap?: string, opacity?: number, cal_min?: number, cal_max?: number, trustCalMinMax?: boolean, percentileFrac?: number, ignoreZeroVoxels?: boolean, useQFormNotSForm?: boolean, colormapNegative?: string, frame4D?: number, imageType?: ImageType, cal_minNeg?: number, cal_maxNeg?: number, colorbarVisible?: boolean, alphaThreshold?: boolean, colormapLabel?: string[]) => ImageFromUrlOptions;
 
 /**
  * a NVImage encapsulates some images data and provides methods to query and operate on images
@@ -622,7 +630,6 @@ declare class NVImage {
     cal_minNeg: number;
     cal_maxNeg: number;
     colorbarVisible: boolean;
-    visible: boolean;
     modulationImage: number | null;
     modulateAlpha: number;
     series: any;
@@ -697,7 +704,6 @@ declare class NVImage {
      * @param trustCalMinMax - whether or not to trust cal_min and cal_max from the nifti header (trusting results in faster loading)
      * @param percentileFrac - the percentile to use for setting the robust range of the display values (smart intensity setting for images with large ranges)
      * @param ignoreZeroVoxels - whether or not to ignore zero voxels in setting the robust range of display values
-     * @param visible - whether or not this image is to be visible
      * @param useQFormNotSForm - give precedence to QForm (Quaternion) or SForm (Matrix)
      * @param colormapNegative - a color map to use for symmetrical negative intensities
      * @param frame4D - volume displayed, 0 indexed, must be less than nFrame4D
@@ -713,7 +719,7 @@ declare class NVImage {
      * @param colorbarVisible - TODO
      * @param colormapLabel - TODO
      */
-    constructor(dataBuffer?: ArrayBuffer | ArrayBuffer[] | null, name?: string, colormap?: string, opacity?: number, pairedImgData?: ArrayBuffer | null, cal_min?: number, cal_max?: number, trustCalMinMax?: boolean, percentileFrac?: number, ignoreZeroVoxels?: boolean, visible?: boolean, useQFormNotSForm?: boolean, colormapNegative?: string, frame4D?: number, imageType?: ImageType, cal_minNeg?: number, cal_maxNeg?: number, colorbarVisible?: boolean, colormapLabel?: LUT | null);
+    constructor(dataBuffer?: ArrayBuffer | ArrayBuffer[] | null, name?: string, colormap?: string, opacity?: number, pairedImgData?: ArrayBuffer | null, cal_min?: number, cal_max?: number, trustCalMinMax?: boolean, percentileFrac?: number, ignoreZeroVoxels?: boolean, useQFormNotSForm?: boolean, colormapNegative?: string, frame4D?: number, imageType?: ImageType, cal_minNeg?: number, cal_maxNeg?: number, colorbarVisible?: boolean, colormapLabel?: LUT | null);
     computeObliqueAngle(mtx44: mat4): number;
     calculateOblique(): void;
     THD_daxes_to_NIFTI(xyzDelta: number[], xyzOrigin: number[], orientSpecific: number[]): void;
@@ -752,7 +758,7 @@ declare class NVImage {
      * 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, 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>;
@@ -760,7 +766,7 @@ declare class NVImage {
      * factory function to load and return a new NVImage instance from a file in the browser
      */
     static loadFromFile({ file, // file can be an array of file objects or a single file object
-    name, colormap, opacity, urlImgData, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, visible, useQFormNotSForm, colormapNegative, frame4D, limitFrames4D, imageType }: ImageFromFileOptions): Promise<NVImage>;
+    name, colormap, opacity, urlImgData, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, useQFormNotSForm, colormapNegative, frame4D, limitFrames4D, imageType }: ImageFromFileOptions): Promise<NVImage>;
     /**
      * factory function to load and return a new NVImage instance from a base64 encoded string
      *
@@ -768,7 +774,7 @@ declare class NVImage {
      * @example
      * myImage = NVImage.loadFromBase64('SomeBase64String')
      */
-    static loadFromBase64({ base64, name, colormap, opacity, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, visible }: ImageFromBase64): NVImage;
+    static loadFromBase64({ base64, name, colormap, opacity, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels }: ImageFromBase64): NVImage;
     /**
      * make a clone of a NVImage instance and return a new NVImage
      * @returns NVImage instance
@@ -814,6 +820,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 = {
@@ -903,7 +913,7 @@ type NVConfigOptions = {
     longTouchTimeout: number;
     keyDebounceTime: number;
     isNearestInterpolation: boolean;
-    isAtlasOutline: boolean;
+    atlasOutline: number;
     isRuler: boolean;
     isColorbar: boolean;
     isOrientCube: boolean;
@@ -912,13 +922,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;
@@ -1317,6 +1330,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;
 }
 
 /**
@@ -1326,10 +1349,11 @@ 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, outlineBorder?: number): 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;
@@ -1343,6 +1367,7 @@ declare class NVMeshLoaders {
     static readICO(buffer: ArrayBuffer): DefaultMeshType;
     static readGEO(buffer: ArrayBuffer, isFlipWinding?: boolean): DefaultMeshType;
     static readOFF(buffer: ArrayBuffer): DefaultMeshType;
+    static readOBJMNI(buffer: ArrayBuffer): DefaultMeshType;
     static readOBJ(buffer: ArrayBuffer): DefaultMeshType;
     static readFreeSurfer(buffer: ArrayBuffer): DefaultMeshType;
     static readSRF(buffer: ArrayBuffer): DefaultMeshType;
@@ -1455,7 +1480,7 @@ type NiiVueOptions = {
     loadingText?: string;
     dragAndDropEnabled?: boolean;
     isNearestInterpolation?: boolean;
-    isAtlasOutline?: boolean;
+    atlasOutline?: number;
     isRuler?: boolean;
     isColorbar?: boolean;
     isOrientCube?: boolean;
@@ -1467,12 +1492,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;
@@ -1535,6 +1563,7 @@ declare class Niivue {
     overlayTexture: WebGLTexture | null;
     overlayTextureID: WebGLTexture | null;
     sliceMMShader?: Shader;
+    sliceV1Shader?: Shader;
     orientCubeShader?: Shader;
     orientCubeShaderVAO: WebGLVertexArrayObject | null;
     rectShader?: Shader;
@@ -1581,6 +1610,7 @@ declare class Niivue {
     position?: vec3;
     extentsMin?: vec3;
     extentsMax?: vec3;
+    private resizeObserver;
     syncOpts: Record<string, unknown>;
     readyForSync: boolean;
     uiData: UIData;
@@ -1812,7 +1842,7 @@ declare class Niivue {
         longTouchTimeout: number;
         keyDebounceTime: number;
         isNearestInterpolation: boolean;
-        isAtlasOutline: boolean;
+        atlasOutline: number;
         isRuler: boolean;
         isColorbar: boolean;
         isOrientCube: boolean;
@@ -1821,13 +1851,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;
@@ -2209,6 +2242,17 @@ declare class Niivue {
      * @see {@link https://niivue.github.io/niivue/features/meshes.html|live demo usage}
      */
     setMeshProperty(id: number, key: keyof NVMesh, val: number): void;
+    /**
+     * returns the index of the mesh vertex that is closest to the provided coordinates
+     * @param id - identity of mesh to change
+     * @param Xmm - location in left/right dimension
+     * @param Ymm - location in posterior/anterior dimension
+     * @param Zmm - location in foot/head dimension
+     * @returns the an array where ret[0] is the mesh index and ret[1] is distance from vertex to coordinates
+     * @example niivue.indexNearestXYZmm(niivue.meshes[0].id, -22, 42, 13)
+     * @see {@link https://niivue.github.io/niivue/features/clipplanes.html | live demo usage}
+     */
+    indexNearestXYZmm(mesh: number, Xmm: number, Ymm: number, Zmm: number): number[];
     /**
      * reverse triangle winding of mesh (swap front and back faces)
      * @param id - identity of mesh to change
@@ -2348,7 +2392,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)
@@ -2826,7 +2870,7 @@ declare class Niivue {
     drawTextBetween(startXYendXY: number[], str: string, scale?: number, color?: number[] | null): void;
     drawTextBelow(xy: number[], str: string, scale?: number, color?: number[] | null): void;
     updateInterpolation(layer: number, isForceLinear?: boolean): void;
-    setAtlasOutline(isOutline: boolean): void;
+    setAtlasOutline(isOutline: number): void;
     /**
      * select between nearest and linear interpolation for voxel based images
      * @param isNearest - whether nearest neighbor interpolation is used, else linear interpolation