@niivue/niivue 0.44.0 → 0.44.2-dev.1

package/src/nvdocument.ts

@@ -46,7 +46,8 @@ export enum DRAG_MODE {
   measurement = 2,
   pan = 3,
   slicer3D = 4,
-  callbackOnly = 5
+  callbackOnly = 5,
+  roiSelection = 6
 }
 
 // make mutable type
@@ -96,6 +97,7 @@ export type NVConfigOptions = {
   multiplanarPadPixels: number
   // @deprecated
   multiplanarForceRender: boolean
+  multiplanarEqualSize: boolean
   multiplanarShowRender: SHOW_RENDER
   isRadiologicalConvention: boolean
   // string to allow infinity
@@ -139,10 +141,18 @@ export type NVConfigOptions = {
   renderOverlayBlend: number
   sliceMosaicString: string
   centerMosaic: boolean
+  penSize: number
   clickToSegment: boolean
   clickToSegmentRadius: number
-  clickToSegmentSteps: number
   clickToSegmentBright: boolean
+  clickToSegmentAutoIntensity: boolean // new option, but keep clickToSegmentBright for backwards compatibility
+  clickToSegmentIntensityMax: number // also covers NaN
+  clickToSegmentIntensityMin: number // also covers NaN
+  clickToSegmentPercent: number
+  clickToSegmentMaxDistanceMM: number // max distance in mm to consider for click to segment flood fill
+  // selection box outline thickness
+  selectionBoxLineThickness: number
+  selectionBoxIsOutline: boolean
 }
 
 export const DEFAULT_OPTIONS: NVConfigOptions = {
@@ -177,6 +187,7 @@ export const DEFAULT_OPTIONS: NVConfigOptions = {
   multiplanarPadPixels: 0,
   // @deprecated
   multiplanarForceRender: false,
+  multiplanarEqualSize: false,
   multiplanarShowRender: SHOW_RENDER.AUTO, // auto is the same behaviour as multiplanarForceRender: false
   isRadiologicalConvention: false,
   meshThicknessOn2D: Infinity,
@@ -210,13 +221,25 @@ export const DEFAULT_OPTIONS: NVConfigOptions = {
   renderOverlayBlend: 1.0,
   sliceMosaicString: '',
   centerMosaic: false,
+  penSize: 1, // in voxels, since all drawing is done using bitmap indices
   clickToSegment: false,
-  clickToSegmentRadius: 2,
-  clickToSegmentSteps: 10,
-  clickToSegmentBright: true
+  clickToSegmentRadius: 3, // in mm
+  clickToSegmentBright: true,
+  clickToSegmentAutoIntensity: false, // new option, but keep clickToSegmentBright for backwards compatibility
+  clickToSegmentIntensityMax: NaN, // NaN will use auto threshold (default flood fill behavior from before)
+  clickToSegmentIntensityMin: NaN, // NaN will use auto threshold (default flood fill behavior from before)
+  // 0 will use auto threshold (default flood fill behavior from before)
+  // Take the voxel intensity at the click point and use this percentage +/- to threshold the flood fill operation.
+  // If greater than 0, clickedVoxelIntensity +/- clickedVoxelIntensity * clickToSegmentPercent will be used
+  // for the clickToSegmentIntensityMin and clickToSegmentIntensityMax values.
+  clickToSegmentPercent: 0,
+  clickToSegmentMaxDistanceMM: Number.POSITIVE_INFINITY, // default value is infinity for backwards compatibility with flood fill routine.
+  selectionBoxLineThickness: 4,
+  selectionBoxIsOutline: false
 }
 
 type SceneData = {
+  gamma: number
   azimuth: number
   elevation: number
   crosshairPos: vec3
@@ -230,6 +253,7 @@ type SceneData = {
 }
 
 export const INITIAL_SCENE_DATA = {
+  gamma: 1.0,
   azimuth: 110,
   elevation: 10,
   crosshairPos: vec3.create(),
@@ -255,6 +279,7 @@ export type Scene = {
   pan2Dxyzmm: vec4
   _elevation?: number
   _azimuth?: number
+  gamma?: number
 }
 
 export type DocumentData = {
@@ -566,6 +591,12 @@ export class NVDocument {
     }
 
     data.labels = [...this.data.labels]
+
+    // remove any handlers
+    for (const label of data.labels) {
+      delete label.onClick
+    }
+
     data.customData = this.customData
 
     // volumes

package/src/nvimage/index.ts

@@ -1631,7 +1631,7 @@ export class NVImage {
             hdr.datatypeCode = NiiDataType.DT_FLOAT64
             break
           default:
-            throw new Error('Unsupported NRRD data type: ' + items[0])
+            throw new Error('Unsupported MHA data type: ' + items[0])
         }
       }
       if (line.startsWith('ObjectType') && !items[0].includes('Image')) {
@@ -1653,6 +1653,9 @@ export class NVImage {
       [mat33[2], mat33[5], mat33[8], offset[2]],
       [0, 0, 0, 1]
     ]
+    while (bytes[pos] === 10) {
+      pos++
+    }
     hdr.vox_offset = pos
     if (isDetached && pairedImgData) {
       if (isGz) {
@@ -3369,7 +3372,7 @@ export class NVImage {
    * read a 3D slab of voxels from a volume
    * @param voxStart - first row, column and slice (RAS order) for selection
    * @param voxEnd - final row, column and slice (RAS order) for selection
-   * @param dataType - array data type. Options: 'same' (default), 'uint8', 'float32'
+   * @param dataType - array data type. Options: 'same' (default), 'uint8', 'float32', 'scaled', 'normalized', 'windowed'
    * @returns the an array where ret[0] is the voxel values and ret[1] is dimension of selection
    * @see {@link https://niivue.github.io/niivue/features/slab_selection.html | live demo usage}
    */
@@ -3394,7 +3397,12 @@ export class NVImage {
     let dt = this.hdr!.datatypeCode
     if (dataType === 'uint8') {
       dt = NiiDataType.DT_UINT8
-    } else if (dataType === 'float32') {
+    } else if (
+      dataType === 'float32' ||
+      dataType === 'scaled' ||
+      dataType === 'normalized' ||
+      dataType === 'windowed'
+    ) {
       dt = NiiDataType.DT_FLOAT32
     }
     if (dt === NiiDataType.DT_UINT8) {
@@ -3424,6 +3432,24 @@ export class NVImage {
         }
       }
     }
+    if (dataType === 'scaled' || dataType === 'normalized' || dataType === 'windowed') {
+      for (let i = 0; i < img.length; i++) {
+        img[i] = img[i] * this.hdr.scl_slope + this.hdr.scl_inter
+      }
+    }
+    if (dataType === 'normalized' || dataType === 'windowed') {
+      let mn = this.cal_min
+      let mx = this.cal_max
+      if (dataType === 'normalized') {
+        mn = this.global_min
+        mx = this.global_max
+      }
+      const scale = 1 / (mx - mn)
+      for (let i = 0; i < img.length; i++) {
+        img[i] = (img[i] - mn) * scale
+        img[i] = Math.max(Math.min(img[i], 1), 0)
+      }
+    }
     return [img, slabDims]
   } // getVolumeData()
 

package/src/nvimage/utils.ts

@@ -373,10 +373,13 @@ following conditions are met:
   return m
 }
 
-function str2Buffer(str: string): number[] {
+function str2Buffer(str: string, maxLen: number = 80): number[] {
   // emulate node.js Buffer.from
+  // remove characters than could be used for shell expansion
+  str = str.replace(/[`$]/g, '')
   const bytes = []
-  for (let i = 0; i < str.length; i++) {
+  const len = Math.min(maxLen, str.length)
+  for (let i = 0; i < len; i++) {
     const char = str.charCodeAt(i)
     bytes.push(char & 0xff)
   }
@@ -384,70 +387,79 @@ function str2Buffer(str: string): number[] {
 }
 
 // save NIfTI header into UINT8 array for saving to disk
-export function hdrToArrayBuffer(hdr: NiftiHeader, isDrawing8 = false): Uint8Array {
+export function hdrToArrayBuffer(hdr: NiftiHeader, isDrawing8 = false, isInputEndian = false): Uint8Array {
   const SHORT_SIZE = 2
   const FLOAT32_SIZE = 4
-
+  let isLittleEndian = true
+  if (isInputEndian) {
+    isLittleEndian = hdr.littleEndian
+  }
   const byteArray = new Uint8Array(348)
   const view = new DataView(byteArray.buffer)
   // sizeof_hdr
-  view.setInt32(0, 348, hdr.littleEndian)
+  view.setInt32(0, 348, isLittleEndian)
 
   // data_type, db_name, extents, session_error, regular are not used
-
+  // regular set to 'r' (ASCII 114) for Analyze compatibility
+  view.setUint8(38, 114)
   // dim_info
   view.setUint8(39, hdr.dim_info)
 
   // dims
   for (let i = 0; i < 8; i++) {
-    view.setUint16(40 + SHORT_SIZE * i, hdr.dims[i], hdr.littleEndian)
+    view.setUint16(40 + SHORT_SIZE * i, hdr.dims[i], isLittleEndian)
   }
 
   // intent_p1, intent_p2, intent_p3
-  view.setFloat32(56, hdr.intent_p1, hdr.littleEndian)
-  view.setFloat32(60, hdr.intent_p2, hdr.littleEndian)
-  view.setFloat32(64, hdr.intent_p3, hdr.littleEndian)
+  view.setFloat32(56, hdr.intent_p1, isLittleEndian)
+  view.setFloat32(60, hdr.intent_p2, isLittleEndian)
+  view.setFloat32(64, hdr.intent_p3, isLittleEndian)
   // intent_code, datatype, bitpix, slice_start
-  view.setInt16(68, hdr.intent_code, hdr.littleEndian)
+  view.setInt16(68, hdr.intent_code, isLittleEndian)
   if (isDrawing8) {
-    view.setInt16(70, 2, hdr.littleEndian) // 2 = DT_UINT8
-    view.setInt16(72, 8, hdr.littleEndian)
+    view.setInt16(70, 2, isLittleEndian) // 2 = DT_UINT8
+    view.setInt16(72, 8, isLittleEndian)
   } else {
-    view.setInt16(70, hdr.datatypeCode, hdr.littleEndian)
-    view.setInt16(72, hdr.numBitsPerVoxel, hdr.littleEndian)
+    view.setInt16(70, hdr.datatypeCode, isLittleEndian)
+    view.setInt16(72, hdr.numBitsPerVoxel, isLittleEndian)
   }
-  view.setInt16(74, hdr.slice_start, hdr.littleEndian)
+  view.setInt16(74, hdr.slice_start, isLittleEndian)
 
   // pixdim[8], vox_offset, scl_slope, scl_inter
   for (let i = 0; i < 8; i++) {
-    view.setFloat32(76 + FLOAT32_SIZE * i, hdr.pixDims[i], hdr.littleEndian)
+    view.setFloat32(76 + FLOAT32_SIZE * i, hdr.pixDims[i], isLittleEndian)
   }
   if (isDrawing8) {
-    view.setFloat32(108, 352, hdr.littleEndian)
-    view.setFloat32(112, 1.0, hdr.littleEndian)
-    view.setFloat32(116, 0.0, hdr.littleEndian)
+    view.setFloat32(108, 352, isLittleEndian)
+    view.setFloat32(112, 1.0, isLittleEndian)
+    view.setFloat32(116, 0.0, isLittleEndian)
   } else {
-    view.setFloat32(108, hdr.vox_offset, hdr.littleEndian)
-    view.setFloat32(112, hdr.scl_slope, hdr.littleEndian)
-    view.setFloat32(116, hdr.scl_inter, hdr.littleEndian)
+    // view.setFloat32(108, hdr.vox_offset, isLittleEndian)
+    view.setFloat32(108, 352, isLittleEndian)
+    view.setFloat32(112, hdr.scl_slope, isLittleEndian)
+    view.setFloat32(116, hdr.scl_inter, isLittleEndian)
   }
   // slice_end
-  view.setInt16(120, hdr.slice_end, hdr.littleEndian)
+  view.setInt16(120, hdr.slice_end, isLittleEndian)
 
   // slice_code, xyzt_units
   view.setUint8(122, hdr.slice_code)
-  view.setUint8(123, hdr.xyzt_units)
+  if (hdr.xyzt_units === 0) {
+    view.setUint8(123, 10)
+  } else {
+    view.setUint8(123, hdr.xyzt_units)
+  }
 
   // cal_max, cal_min, slice_duration, toffset
   if (isDrawing8) {
-    view.setFloat32(124, 0, hdr.littleEndian)
-    view.setFloat32(128, 0, hdr.littleEndian)
+    view.setFloat32(124, 0, isLittleEndian)
+    view.setFloat32(128, 0, isLittleEndian)
   } else {
-    view.setFloat32(124, hdr.cal_max, hdr.littleEndian)
-    view.setFloat32(128, hdr.cal_min, hdr.littleEndian)
+    view.setFloat32(124, hdr.cal_max, isLittleEndian)
+    view.setFloat32(128, hdr.cal_min, isLittleEndian)
   }
-  view.setFloat32(132, hdr.slice_duration, hdr.littleEndian)
-  view.setFloat32(136, hdr.toffset, hdr.littleEndian)
+  view.setFloat32(132, hdr.slice_duration, isLittleEndian)
+  view.setFloat32(136, hdr.toffset, isLittleEndian)
 
   // glmax, glmin are unused
 
@@ -457,27 +469,34 @@ export function hdrToArrayBuffer(hdr: NiftiHeader, isDrawing8 = false): Uint8Arr
   // node.js: byteArray.set(Buffer.from(hdr.aux_file), 228);
   byteArray.set(str2Buffer(hdr.aux_file), 228)
   // qform_code, sform_code
-  view.setInt16(252, hdr.qform_code, hdr.littleEndian)
-  view.setInt16(254, hdr.sform_code, hdr.littleEndian)
+  view.setInt16(252, hdr.qform_code, isLittleEndian)
+  // if sform unknown, assume NIFTI_XFORM_SCANNER_ANAT
+  if (hdr.sform_code < 1 || hdr.sform_code < 1) {
+    view.setInt16(254, 1, isLittleEndian)
+  } else {
+    view.setInt16(254, hdr.sform_code, isLittleEndian)
+  }
 
   // quatern_b, quatern_c, quatern_d, qoffset_x, qoffset_y, qoffset_z, srow_x[4], srow_y[4], and srow_z[4]
-  view.setFloat32(256, hdr.quatern_b, hdr.littleEndian)
-  view.setFloat32(260, hdr.quatern_c, hdr.littleEndian)
-  view.setFloat32(264, hdr.quatern_d, hdr.littleEndian)
-  view.setFloat32(268, hdr.qoffset_x, hdr.littleEndian)
-  view.setFloat32(272, hdr.qoffset_y, hdr.littleEndian)
-  view.setFloat32(276, hdr.qoffset_z, hdr.littleEndian)
+  view.setFloat32(256, hdr.quatern_b, isLittleEndian)
+  view.setFloat32(260, hdr.quatern_c, isLittleEndian)
+  view.setFloat32(264, hdr.quatern_d, isLittleEndian)
+  view.setFloat32(268, hdr.qoffset_x, isLittleEndian)
+  view.setFloat32(272, hdr.qoffset_y, isLittleEndian)
+  view.setFloat32(276, hdr.qoffset_z, isLittleEndian)
   const flattened = hdr.affine.flat()
   // we only want the first three rows
   for (let i = 0; i < 12; i++) {
-    view.setFloat32(280 + FLOAT32_SIZE * i, flattened[i], hdr.littleEndian)
+    view.setFloat32(280 + FLOAT32_SIZE * i, flattened[i], isLittleEndian)
   }
   // node.js https://www.w3schools.com/nodejs/met_buffer_from.asp
   // intent_name and magic
   // node.js byteArray.set(Buffer.from(hdr.intent_name), 328);
-  byteArray.set(str2Buffer(hdr.intent_name), 328)
+  //  byteArray.set(str2Buffer(hdr.intent_name), 328)
   // node.js byteArray.set(Buffer.from(hdr.magic), 344);
-  byteArray.set(str2Buffer(hdr.magic), 344)
+  // byteArray.set(str2Buffer(hdr.magic), 344)
+  view.setInt32(344, 3222382, true) // "n+1\0"
+
   return byteArray
   // return byteArray.buffer;
 }

package/src/nvlabel.ts

@@ -10,6 +10,29 @@ export enum LabelLineTerminator {
   RING = 'ring'
 }
 
+export enum LabelAnchorFlag {
+  NONE = 0,
+  LEFT = 1 << 0,
+  CENTER = 1 << 1,
+  RIGHT = 1 << 2,
+  TOP = 1 << 3,
+  MIDDLE = 1 << 4,
+  BOTTOM = 1 << 5
+}
+
+export enum LabelAnchorPoint {
+  NONE = LabelAnchorFlag.NONE,
+  TOPLEFT = LabelAnchorFlag.TOP | LabelAnchorFlag.LEFT,
+  TOPCENTER = LabelAnchorFlag.TOP | LabelAnchorFlag.CENTER,
+  TOPRIGHT = LabelAnchorFlag.TOP | LabelAnchorFlag.RIGHT,
+  MIDDLELEFT = LabelAnchorFlag.MIDDLE | LabelAnchorFlag.LEFT,
+  MIDDLECENTER = LabelAnchorFlag.MIDDLE | LabelAnchorFlag.CENTER,
+  MIDDLERIGHT = LabelAnchorFlag.MIDDLE | LabelAnchorFlag.RIGHT,
+  BOTTOMLEFT = LabelAnchorFlag.BOTTOM | LabelAnchorFlag.LEFT,
+  BOTTOMCENTER = LabelAnchorFlag.BOTTOM | LabelAnchorFlag.CENTER,
+  BOTTOMRIGHT = LabelAnchorFlag.BOTTOM | LabelAnchorFlag.RIGHT
+}
+
 /**
  * Class representing label style.
  * @ignore
@@ -65,15 +88,25 @@ export class NVLabel3D {
   text: string
   style: NVLabel3DStyle
   points?: number[] | number[][]
+  anchor: LabelAnchorPoint
+  onClick?: (label: NVLabel3D) => void
 
   /**
    * @param text - The text of the label
    * @param style - The style of the label
    * @param points - An array of points label for label lines
    */
-  constructor(text: string, style: NVLabel3DStyle, points?: number[] | number[][]) {
+  constructor(
+    text: string,
+    style: NVLabel3DStyle,
+    points?: number[] | number[][],
+    anchor?: LabelAnchorPoint,
+    onClick?: (label: NVLabel3D) => void
+  ) {
     this.text = text
     this.style = style
     this.points = points
+    this.anchor = anchor || LabelAnchorPoint.NONE
+    this.onClick = onClick
   }
 }

package/src/nvmesh-loaders.ts

@@ -709,6 +709,12 @@ export class NVMeshLoaders {
     while (lines[pos].length < 1) {
       pos++
     } // skip blank lines
+    if (lines[pos].startsWith('METADATA')) {
+      while (lines[pos].length > 1) {
+        pos++
+      } // skip until blank line
+      pos++
+    }
     items = lines[pos].trim().split(/\s+/)
     pos++
     if (items[0].includes('LINES')) {
@@ -909,7 +915,7 @@ export class NVMeshLoaders {
           layer.values = obj
         }
       }
-    } else if (ext === 'CRV' || ext === 'CURV') {
+    } else if (ext === 'CRV' || ext === 'CURV' || ext === 'THICKNESS' || ext === 'AREA') {
       layer.values = NVMeshLoaders.readCURV(buffer, n_vert)
       layer.isTransparentBelowCalMin = false
     } else if (ext === 'GII') {
@@ -935,6 +941,10 @@ export class NVMeshLoaders {
       layer.values = NVMeshLoaders.readSMP(buffer, n_vert)
     } else if (ext === 'STC') {
       layer.values = NVMeshLoaders.readSTC(buffer, n_vert)
+    } else if (NVMeshLoaders.isCurv(buffer)) {
+      // Unknown layer overlay format - hail mary assume FreeSurfer
+      layer.values = NVMeshLoaders.readCURV(buffer, n_vert)
+      layer.isTransparentBelowCalMin = false
     } else {
       log.warn('Unknown layer overlay format ' + name)
       return layer
@@ -1123,6 +1133,19 @@ export class NVMeshLoaders {
     return f32
   } // readSTC()
 
+  static isCurv(buffer: ArrayBuffer): boolean {
+    const view = new DataView(buffer) // ArrayBuffer to dataview
+    // ALWAYS big endian
+    const sig0 = view.getUint8(0)
+    const sig1 = view.getUint8(1)
+    const sig2 = view.getUint8(2)
+    if (sig0 !== 255 || sig1 !== 255 || sig2 !== 255) {
+      utiltiesLogger.debug('Unable to recognize file type: does not appear to be FreeSurfer format.')
+      return false
+    }
+    return true
+  }
+
   // read freesurfer curv big-endian format
   // https://github.com/bonilhamusclab/MRIcroS/blob/master/%2BfileUtils/%2Bpial/readPial.m
   // http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm
@@ -1171,7 +1194,8 @@ export class NVMeshLoaders {
     const view = new DataView(buffer) // ArrayBuffer to dataview
     // ALWAYS big endian
     const n_vertex = view.getUint32(0, false)
-    if (n_vert !== n_vertex) {
+    const n_vertexDecimated = this.decimateLayerVertices(n_vertex, n_vert)
+    if (n_vert !== n_vertexDecimated) {
       throw new Error('ANNOT file has different number of vertices than mesh')
     }
     if (buffer.byteLength < 4 + 8 * n_vertex) {
@@ -2505,6 +2529,23 @@ export class NVMeshLoaders {
     }
   } // readSTL()
 
+  static decimateLayerVertices(nVertLayer: number, nVertMesh: number): number {
+    // downsample layer vertices if the mesh has been decimated
+    if (nVertLayer % nVertMesh === 0) {
+      return nVertLayer
+    }
+    const V0 = 12
+    const orderLayer = Math.round(Math.log((nVertLayer - 2) / (V0 - 2)) / Math.log(4))
+    const orderMesh = Math.round(Math.log((nVertMesh - 2) / (V0 - 2)) / Math.log(4))
+    // sanity check
+    const nVLayer = Math.pow(4, orderLayer) * (V0 - 2) + 2
+    const nVMesh = Math.pow(4, orderMesh) * (V0 - 2) + 2
+    if (nVLayer !== nVertLayer || nVMesh !== nVertMesh) {
+      return nVertLayer
+    }
+    return nVertMesh
+  }
+
   // read NIfTI2 format with embedded CIfTI
   // this variation very specific to connectome workbench
   // https://brainder.org/2015/04/03/the-nifti-2-file-format/
@@ -2688,8 +2729,9 @@ export class NVMeshLoaders {
       //
       return scalars
     } // is CIfTI
+    nvert = this.decimateLayerVertices(nvert, n_vert)
     if (nvert % n_vert !== 0) {
-      throw new Error('Vertices in NIfTI (' + nvert + ') is not a multiple of number of vertices (' + n_vert + ')')
+      throw new Error('Vertices in layer (' + nvert + ') is not a multiple of number of vertices (' + n_vert + ')')
     }
     if (isLittleEndian) {
       // block read native endian
@@ -2776,8 +2818,9 @@ export class NVMeshLoaders {
       const dim = reader.getUint16(40 + i * 2, isLittleEndian)
       nvert *= Math.max(dim, 1)
     }
+    nvert = this.decimateLayerVertices(nvert, n_vert)
     if (nvert % n_vert !== 0) {
-      throw new Error('Vertices in NIfTI (' + nvert + ') is not a multiple of number of vertices (' + n_vert + ')')
+      throw new Error('Vertices in layer (' + nvert + ') is not a multiple of number of vertices (' + n_vert + ')')
     }
     if (isLittleEndian) {
       // block read native endian
@@ -2835,10 +2878,11 @@ export class NVMeshLoaders {
     if (version !== 1 || mtype < 0 || mtype > 4) {
       log.warn('Not a valid MGH file')
     }
-    const nvert = width * height * depth * nframes
+    let nvert = width * height * depth * nframes
     let scalars: AnyNumberArray = []
+    nvert = this.decimateLayerVertices(nvert, n_vert)
     if (nvert % n_vert !== 0) {
-      log.warn('Vertices in NIfTI (' + nvert + ') is not a multiple of number of vertices (' + n_vert + ')')
+      log.warn('Vertices in layer (' + nvert + ') is not a multiple of number of vertices (' + n_vert + ')')
       return scalars
     }
     if (mtype === 3) {

package/src/nvmesh-utilities.ts

@@ -1,4 +1,5 @@
 import { vec3 } from 'gl-matrix'
+import { gzipSync } from 'fflate/browser'
 
 type Extents = {
   mxDx: number
@@ -38,6 +39,144 @@ export class NVMeshUtilities {
     return border
   }
 
+  static createMZ3(vertices: Float32Array, indices: Uint32Array, compress: boolean = false): ArrayBuffer {
+    // generate binary MZ3 format mesh
+    // n.b. small, precise and small but support is not widespread
+    // n.b. result can be compressed with gzip
+    // https://github.com/neurolabusc/surf-ice/tree/master/mz3
+    const magic = 23117
+    const attr = 3
+    const nface = indices.length / 3
+    const nvert = vertices.length / 3
+    const nskip = 0
+    // Calculate buffer size
+    const headerSize = 16
+    const indexSize = nface * 3 * 4 // Uint32Array
+    const vertexSize = nvert * 3 * 4 // Float32Array
+    const totalSize = headerSize + indexSize + vertexSize
+    const buffer = new ArrayBuffer(totalSize)
+    const writer = new DataView(buffer)
+    // Write header
+    writer.setUint16(0, magic, true)
+    writer.setUint16(2, attr, true)
+    writer.setUint32(4, nface, true)
+    writer.setUint32(8, nvert, true)
+    writer.setUint32(12, nskip, true)
+    // Write indices
+    let offset = headerSize
+    new Uint32Array(buffer, offset, indices.length).set(indices)
+    offset += indexSize
+    // Write vertices
+    new Float32Array(buffer, offset, vertices.length).set(vertices)
+    if (compress) {
+      return gzipSync(new Uint8Array(buffer))
+    }
+    return buffer
+  }
+
+  static createOBJ(vertices: Float32Array, indices: Uint32Array): ArrayBuffer {
+    // generate binary OBJ format mesh
+    // n.b. widespread support, but large and slow due to ASCII
+    // https://en.wikipedia.org/wiki/Wavefront_.obj_file
+    let objContent = ''
+    // Add vertices to OBJ content
+    for (let i = 0; i < vertices.length; i += 3) {
+      objContent += `v ${vertices[i]} ${vertices[i + 1]} ${vertices[i + 2]}\n`
+    }
+    // Add faces to OBJ content (OBJ indices start at 1, not 0)
+    for (let i = 0; i < indices.length; i += 3) {
+      objContent += `f ${indices[i] + 1} ${indices[i + 1] + 1} ${indices[i + 2] + 1}\n`
+    }
+    // Encode the OBJ content as an ArrayBuffer
+    const encoder = new TextEncoder()
+    const arrayBuffer = encoder.encode(objContent).buffer
+    return arrayBuffer
+  }
+
+  static createSTL(vertices: Float32Array, indices: Uint32Array): ArrayBuffer {
+    // generate binary STL format mesh
+    // n.b. inefficient and slow as vertices are not reused
+    // https://en.wikipedia.org/wiki/STL_(file_format)#Binary
+    const numTriangles = indices.length / 3
+    const bufferLength = 84 + numTriangles * 50
+    const arrayBuffer = new ArrayBuffer(bufferLength)
+    const dataView = new DataView(arrayBuffer)
+    // Write header (80 bytes)
+    for (let i = 0; i < 80; i++) {
+      dataView.setUint8(i, 0)
+    }
+    // Write number of triangles (4 bytes)
+    dataView.setUint32(80, numTriangles, true)
+    let offset = 84
+    for (let i = 0; i < indices.length; i += 3) {
+      const i0 = indices[i] * 3
+      const i1 = indices[i + 1] * 3
+      const i2 = indices[i + 2] * 3
+      // Normal vector (12 bytes, set to zero)
+      dataView.setFloat32(offset, 0, true) // Normal X
+      dataView.setFloat32(offset + 4, 0, true) // Normal Y
+      dataView.setFloat32(offset + 8, 0, true) // Normal Z
+      offset += 12
+      // Vertex 1 (12 bytes)
+      dataView.setFloat32(offset, vertices[i0], true) // Vertex 1 X
+      dataView.setFloat32(offset + 4, vertices[i0 + 1], true) // Vertex 1 Y
+      dataView.setFloat32(offset + 8, vertices[i0 + 2], true) // Vertex 1 Z
+      offset += 12
+      // Vertex 2 (12 bytes)
+      dataView.setFloat32(offset, vertices[i1], true) // Vertex 2 X
+      dataView.setFloat32(offset + 4, vertices[i1 + 1], true) // Vertex 2 Y
+      dataView.setFloat32(offset + 8, vertices[i1 + 2], true) // Vertex 2 Z
+      offset += 12
+      // Vertex 3 (12 bytes)
+      dataView.setFloat32(offset, vertices[i2], true) // Vertex 3 X
+      dataView.setFloat32(offset + 4, vertices[i2 + 1], true) // Vertex 3 Y
+      dataView.setFloat32(offset + 8, vertices[i2 + 2], true) // Vertex 3 Z
+      offset += 12
+      // Attribute byte count (2 bytes, set to zero)
+      dataView.setUint16(offset, 0, true)
+      offset += 2
+    }
+    return arrayBuffer
+  }
+
+  static downloadArrayBuffer(buffer: ArrayBuffer, filename: string): void {
+    const blob = new Blob([buffer], { type: 'application/octet-stream' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = filename
+    document.body.appendChild(a)
+    a.style.display = 'none'
+    a.click()
+    setTimeout(() => {
+      document.body.removeChild(a)
+      URL.revokeObjectURL(url)
+    }, 0)
+  }
+
+  static saveMesh(
+    vertices: Float32Array,
+    indices: Uint32Array,
+    filename: string = '.mz3',
+    compress: boolean = false
+  ): ArrayBuffer {
+    let buff = new ArrayBuffer(0)
+    if (/\.obj$/i.test(filename)) {
+      buff = this.createOBJ(vertices, indices)
+    } else if (/\.stl$/i.test(filename)) {
+      buff = this.createSTL(vertices, indices)
+    } else {
+      if (!/\.mz3$/i.test(filename)) {
+        filename += '.mz3'
+      }
+      buff = this.createMZ3(vertices, indices, compress)
+    }
+    if (filename.length > 4) {
+      this.downloadArrayBuffer(buff, filename)
+    }
+    return buff
+  }
+
   static getClusterBoundary(rgba8: Uint8Array, faces: number[] | Uint32Array): boolean[] {
     const rgba32 = new Uint32Array(rgba8.buffer)
     // assume all vertices are not near a border