Loading Arrays

Supported Formats

Extension	Library	Notes
`.npy`	numpy	Memory-mapped
`.npz`	numpy	Must contain one array
`.nii` / `.nii.gz`	nibabel	Native voxel order; `.nii` is lazy
`.zarr` / `.zarr.zip`	zarr	Chunked access
`.pt` / `.pth`	torch	Converted to numpy
`.h5` / `.hdf5`	h5py	Must contain one dataset
`.tif` / `.tiff`	tifffile	Full load
`.mat`	scipy / h5py	Multi-array: in-viewer picker for array selection

Optional libraries are imported only when needed.

Multi-array formats (.npz, .mat) show an in-viewer picker when they contain more than one array.

Single NIfTI files open in their native voxel order. ArrayView trusts the file's affine for axis labels and voxel sizes, but does not automatically move the voxel data to canonical RAS order. This keeps large uncompressed .nii files disk-backed and makes the initial X/Y slice follow the file's efficient storage layout.

Press A to explicitly convert a NIfTI volume to RAS. This can read or allocate the complete volume. Press A again to return to the native disk-backed data. Compressed .nii.gz files still need a full gzip decode before arbitrary slices are cheap.

CLI

uvx arrayview                                  # interactive tutorial
uvx arrayview volume.nii.gz
uvx arrayview volume.npy --window browser
uvx arrayview image.npy --rgb
uvx arrayview --watch data.npy              # reload on file change
uvx arrayview --version                     # print version

Network-mounted source files

On Linux, ArrayView checks the mount table before touching an explicit source. For recognized CIFS/SMB, NFS, SSHFS, and common network filesystems, it avoids direct access. CIFS mounts also use the kernel connection state, so a mount reported as disconnected or reconnecting fails immediately with a clear error.

Healthy network-mounted files are copied once into local temporary storage by a bounded helper. The server, NIfTI proxy, and renderer then use the local snapshot. The snapshot is removed when its session or transient server is released. Network directory collections are not scanned directly; copy them locally before using --stack. --watch is also disabled for network sources, because polling a mount that disconnects later can block inside the kernel. Network DICOM inputs, including extensionless DICOM files, must be copied as a local series directory so sibling discovery remains complete. ArrayView only uses a staging root whose mount type is known to be local; it fails safely if no such temporary location is available. Network HDF5, MATLAB, PyTorch, and other containers that can refer to external paths are also refused; copy them locally first. Bounded network staging is limited to self-contained NIfTI and NumPy files. The staging deadline defaults to 30 seconds and can be changed with ARRAYVIEW_SOURCE_TIMEOUT_SECONDS for large files on healthy but slow links.

This is preventive, not a way to recover an already stuck process. Linux tasks already sleeping in uninterruptible D state cannot be stopped by ArrayView or kill -9. The mount must recover or be detached. Mount-state detection also has an unavoidable race and cannot reliably see a network filesystem hidden behind a symlink or overlay without touching that target. Filesystems not identified as network-backed by Linux mount information use the normal direct-loading path.

Python

from arrayview import view
import numpy as np

x = np.random.rand(256, 256, 32)
v = view(x)

view() returns a ViewHandle:

v = view(arr)
v.update(arr2)        # refresh without reopening
print(v.sid)          # session ID
print(v.port)         # server port

Key parameters:

Parameter	Type	Description
`data`	array-like	The array to display
`name`	str	Label shown in the viewer tab
`port`	int	Server port (default 8123 for Python API, 8000 for CLI)
`window`	str \| None	How to open the viewer (see below)
`height`	int	Default inline notebook height in pixels
`mode_heights`	dict	Inline height overrides, e.g. `{"ortho": 360, "qmri": 480}`
`rgb`	bool	Treat last/first axis as RGB/RGBA channels
`overlay`	array or list	Arrays composited as overlays

window values:

Value	Behaviour
`None`	Auto: native outside Jupyter, inline inside
`"native"`	Native desktop window
`"browser"`	System browser
`"vscode"`	VS Code tab
`"inline"`	Inline IFrame (Jupyter / VS Code notebook)
`"none"`	Register the session without opening a display

Inline ortho view automatically removes unused height. mode_heights is only needed to override the automatic size.

File Picker

Cmd/Ctrl+O or P opens the file picker.

Drag and Drop

Drop a file onto an open viewer, then choose:

Compare side by side
Open separately
Add as overlay

Compare and overlay require an exact shape match. Incompatible actions stay visible with the required shape. Dropped folders open as stacks; DICOM folders show a series selector when needed. Escape or clicking outside cancels without creating a session.

Notebook output accepts single-file drops. Folder drop stays disabled there; opening separately uses a browser tab.

Startup

The first rendered frame is shown immediately. There is no client-side intro animation. Native windows also show a static preview while the live viewer warms up.

With no file argument, ArrayView opens its generated interactive tutorial. It runs in the normal viewer on real commands rather than a simulated walkthrough, and includes prepared comparison and overlay data.

The tutorial has no panel. A single line near the bottom of the frame names one key and asks you to press it; it does not say what the key does. Once the viewer state actually changes, that line is replaced by what just happened, then dissolves into the next one.

It is in no hurry. Each line holds long enough to read, the frame goes quiet between steps, and the next thing is only asked once you have stopped — so you can stay and play with whatever you just found for as long as you like. When a panel opens over the array, the tutorial fades out and waits rather than talking underneath it.

The tour is divided into sections — moving, looking, shaping, closer, all at once, spectra, values, views, two arrays, marks, flow, a stack, the rest — listed along the bottom of the frame. flow and a stack run on their own generated sessions (a deformation field, and a ragged collection of differently shaped volumes); entering them loads that session and leaving returns you to the main array. Each announces itself before it starts asking for anything. Click a section to jump to it, or use Tab and Shift+Tab. Jumping is safe in either direction: every section sets up the state it needs, so skipping ahead to two arrays loads the pair and going back closes it again. Press Esc to end the tour.

Multiple Arrays

uvx arrayview base.npy moving.npy           # compare mode
uvx arrayview volume.nii.gz --overlay mask.nii.gz
uvx arrayview volume.nii.gz --overlay "ground truth=mask_gt.nii.gz" --overlay "prediction=mask_pred.nii.gz"

An unnamed overlay uses the filename stem as its display name (mask above). Use NAME=FILE when a more descriptive label is useful. The overlay list opens at the top-right of the image and can be repositioned with its small drag grip. Hover a visible row to focus that mask; the other visible masks are dimmed until the pointer leaves the list. Use the HUD filled/outline button, or the same control in / o, to switch masks between filled regions and contour-only outlines. The eye in the HUD header hides or shows all overlays at once.

Folders

Pass a folder anywhere a file is accepted, and arrayview classifies it:

uvx arrayview scans/            # folder of arrays  → one case per file
uvx arrayview patients/         # one array per subfolder → one case per patient
uvx arrayview dicom-series/     # DICOM             → one 3D series

In VS Code, right-click the folder in the Explorer and choose Open Folder in ArrayView for the same result. The collection axis becomes a case slider and never takes over the startup plane.

Directory Pattern Collections

Use --stack when you need explicit patterns — several channels per case, named overlays, or a case id regex. For a plain folder it is equivalent to passing the folder directly.

uvx arrayview --stack scans/
uvx arrayview --stack scans/ --load eager
uvx arrayview --stack scans/ --stack-policy dense
uvx arrayview --stack scans/ --stack-policy ragged

Directory loading is lazy by default. Same-shaped files form a dense virtual stack; mixed-shaped files automatically use a ragged collection. --stack-policy dense requires matching shapes, while --stack-policy ragged forces collection semantics. --load eager is intended for small datasets that should be loaded up front. In the dimbar, · separates ordinary array dimensions while │ marks the boundary before collection dimensions created by a folder or --stack.

Pattern collections, named overlays, multiple overlays, and --overlay-dir: Stack and Overlay Collections.

NIfTI Series

Stack a directory of NIfTI files into a single lazy 4D/5D array. Patient files are loaded only when needed, and the memory cache stays bounded regardless of series size.

uvx arrayview patients/
uvx arrayview patients/ --stack-policy dense

Discovers .nii/.nii.gz recursively, groups by immediate parent folder (= patient), and ignores nested NIfTI folders once the parent has series files. One file per patient → 4D (*vol, P). The viewer opens with X/Y on screen, Z as primary scroll, patient index as a slider.

For multiple files per patient, use explicit --stack patterns:

uvx arrayview --stack \
  "patients/*/*t1*.nii.gz" \
  "patients/*/*t2*.nii.gz" \
  "patients/*/*flair*.nii.gz"

More examples: Stack and Overlay Collections.

DICOM Series

uvx arrayview path/to/dicom-series/
uvx arrayview path/to/one-slice.dcm
uvx arrayview path/to/study/ --series 2

A slice path discovers sibling images from the same series. A directory with multiple series requires --series INDEX; SeriesNumber and exact SeriesInstanceUID selectors are also accepted.

Pass the DICOM folder on its own — do not add --stack. --stack globs every matching file into its own case, so a DICOM folder becomes N duplicate copies of the same series, one per slice. Plain arrayview <folder> and the VS Code Open Folder in ArrayView entry detect DICOM and load one series.

Shift+I shows privacy-filtered acquisition and geometry fields. Patient identity, dates, institutions, and raw UIDs are not sent to the viewer.

First image from compressed patients

For a normal 3D .nii.gz patient, ArrayView shows the requested axial slice as soon as that slice has been unpacked. It keeps unpacking the rest of the same file in the background and saves the completed volume in the existing memory cache. The file is not unpacked a second time.

This shortens the visible wait, but it does not make gzip random-access. A slice near the middle still requires reading roughly the first half of the file. Side views, 4D files, and unusual orientations fall back to loading the complete volume first so their data remains correct. Moving quickly between patients stops outdated background work instead of building a long loading queue.

Zarr

Use zarr_chunk_preset to get chunk shapes optimized for slice navigation:

from arrayview import zarr_chunk_preset

chunks = zarr_chunk_preset((512, 512, 200, 10))
# (512, 512, 1, 2)

Recommended chunk shapes by dimensionality:

ndim	Axes	Chunk pattern
2	Y, X	`(Y, X)`
3	Y, X, Z	`(Y, X, 1)`
4	Y, X, Z, T	`(Y, X, 1, t)`
5	Y, X, Z, T, C	`(Y, X, 1, 1, C)`

XY tile size is capped at 512.

Open a zarr store directly:

uvx arrayview scan.zarr