# Loading images

> Load volumes and meshes from URLs or local files: load options, overlays, drag and drop, supported formats, and large 4D or OME-Zarr data.

NiiVue loads volumes with `loadVolumes`. Pass it an array of options
objects, one per volume. The only required field is `url`.

```js
await nv.loadVolumes([{ url: '/volumes/mni152.nii.gz' }])
```

`loadVolumes` replaces whatever was loaded before. The old volumes stay on
screen until the new ones are ready, so switching images does not flash a
blank canvas. Pick another image below to see it:

## Volume options

Each entry can set its display options at load time. These are the same keys
that `setVolume` takes later, so you load and adjust with one vocabulary:

| Option | What it does |
|---|---|
| `url` | A URL string or a `File` |
| `name` | Display name (defaults to the file name) |
| `colormap` | Colormap name, `'Gray'` by default. See [Colormaps](https://niivue.com/docs/guide/colormaps/) |
| `calMin`, `calMax` | The intensity window mapped onto the colormap |
| `opacity` | 0 to 1 |
| `visible` | Hide a volume without changing its opacity |
| `isColorbarVisible` | Whether this volume gets a colorbar |
| `urlImageData` | The data file for formats with a separate header, such as AFNI `.HEAD`/`.BRIK` |
| `limitFrames4D` | Load only the first N frames of a 4D series |

## Several volumes

The first volume in the list is the background, and it sets the space the
scene is drawn in. Every later volume is an overlay: it is resampled onto
the background grid and drawn on top of it.

To append one volume without replacing the rest, use `addVolume`:

```js
await nv.addVolume({ url: '/volumes/spmMotor.nii.gz', colormap: 'warm' })
```

[Overlays and thresholds](https://niivue.com/docs/guide/overlays/) covers statistical maps in depth.

## Meshes

Meshes load the same way, with `loadMeshes`, and can share the scene with
volumes:

```js
await nv.loadMeshes([
  { url: '/meshes/BrainMesh_ICBM152.lh.mz3', color: [1, 0.8, 0.6, 1] },
])
```

Like `loadVolumes`, it replaces the meshes already loaded; `addMesh` appends
one. See [Meshes and layers](https://niivue.com/docs/guide/meshes/) for layers and shaders.

## Local files and drag and drop

Any `url` can be a `File` instead of a string. That is how you load from an
`<input type="file">`:

```js
input.onchange = async () => {
  const file = input.files?.[0]
  if (file) await nv.loadVolumes([{ url: file }])
}
```

If you do not know whether a file is a volume, a mesh or a signal, call
`nv.loadImage(file)`. It picks the loader from the file extension.

Drag and drop is on by default. Drop a file on the canvas and NiiVue loads it with `loadImage`, replacing what was shown.
A dropped `.nvd` document goes to `loadDocument`, and a `.json` sidecar
dropped together with its data file is paired with it. To turn it off:

```js
nv.isDragDropEnabled = false
```

## Supported formats

Volumes: NIfTI (`.nii`, `.nii.gz`), NRRD, MRtrix MIF, AFNI HEAD/BRIK,
MGH/MGZ, ITK MHD/MHA, ECAT7, DSI Studio FIB/SRC, BMP, V16, VMR, NPY/NPZ,
TIFF (including OME-TIFF and ImageJ stacks) and the Allen JSON+PNG atlas.
OME-Zarr loads through `@niivue/nv-ext-tile/zarr`.

Meshes: GIfTI, FreeSurfer, PLY, STL, OBJ, VTK, MZ3, OFF, GEO/BYU, BrainSuite
DFS, ICO/TRI, BrainNet NV, BrainVoyager SRF, X3D, ASC, WRL and IWM.
Tractography: TCK, TRK, TRX, TT, TSF, VTK lines and AFNI .niml.tract
(binary).

DICOM is not built in: see [DICOM files](#dicom-files) below. The MINC
and VOX loader plugins from NiiVue 0.x have not been ported.

## DICOM files

NiiVue does not read DICOM directly. The `@niivue/dcm2niix` package runs
dcm2niix (compiled to WebAssembly) in the browser and returns NIfTI series
you can load:

```bash
npm install @niivue/dcm2niix
```

```js
import { convert } from '@niivue/dcm2niix'

// <input id="dicomFolder" type="file" webkitdirectory multiple />
input.addEventListener('change', async () => {
  // A nonzero exit still returns the series that converted.
  const { series } = await convert(input.files)
  await nv.loadVolumes([{ url: series[0].image }])
})
```

Each series also carries its `json` sidecar and any `bval`/`bvec`. For a
dropped folder, `filesFromDataTransfer(e.dataTransfer.items)` collects the
files first; `listSeries` lists series without converting them. The
`Dcm2niix` class gives full control over the dcm2niix flags:

```js
import { Dcm2niix } from '@niivue/dcm2niix'

const dcm2niix = new Dcm2niix()
await dcm2niix.init()
const result = await dcm2niix.input(files).compressionLevel(9).bids('n').run()
```

See [dcm2niix](https://niivue.com/docs/plugins/dcm2niix/) for a live demo and more options.

## Large data

`limitFrames4D` opens a long 4D series partially: NiiVue reads the header
and the first frames only. The [Timeseries](https://niivue.com/docs/gallery/vox-4d/) example uses it.

OME-Zarr stores load one pyramid level at a time. `loadOmeZarrVolumes`
(from `@niivue/nv-ext-tile/zarr`) returns ordinary volume options for `loadVolumes`:

```js
import { loadOmeZarrVolumes } from '@niivue/nv-ext-tile/zarr'

const volumes = await loadOmeZarrVolumes(storeUrl, { level: 2 })
await nv.loadVolumes(volumes)
```

Stores too large to load whole stream brick by brick with
`streamOmeZarr(nv, storeUrl)` (through `nv.loadChunkedVolume`), with finer levels near the crosshair. These pages
show the streaming paths:

- [OME-Zarr multiscale stores](https://niivue.com/demo-ext-tile/ome.zarr.html)
- [Chunk streaming over HTTP range requests](https://niivue.com/demo-ext-tile/range.html)
- [Tiled (oversized) volumes](https://niivue.com/docs/gallery/vox-tiled/)
- [OME-TIFF and TIFF stacks](https://niivue.com/docs/gallery/ome-tiff/)
