neuroimjs

A comprehensive neuroimaging library for JavaScript/TypeScript that provides tools for loading, processing, visualizing, and analyzing brain imaging data in the browser and Node.js.

Features

• 🧠 Volume Processing - Load and manipulate NIfTI, AFNI, and other neuroimaging formats
• 📊 4D+ Data Support - Handle time-series and high-dimensional neuroimaging data
• 🎨 Interactive Visualization - WebGL-based 2D slice viewers with PIXI.js
• 🔄 Spatial Filtering - Advanced filtering, resampling, and interpolation
• 📈 Statistical Analysis - Searchlight analysis, clustering, and statistical operations
• 🏗️ Composable Views - Build custom viewer layouts for external applications

Installation

npm install neuroimjs

Quick Start

Basic Volume Loading and Visualization

import { VolStack, SimpleOrthogonalViewer } from 'neuroimjs';

// Load a NIfTI file
const volStack = await VolStack.fromNifti('brain.nii.gz');

// Create a 3-view orthogonal viewer
const viewer = await SimpleOrthogonalViewer.create(
  document.getElementById('viewer-container'),
  volStack
);

Composable Views (NEW!)

Create custom layouts with individual slice views:

import { VolStack, SingleSliceViewer, ViewSynchronizer } from 'neuroimjs';

// Load data
const volStack = await VolStack.fromNifti('brain.nii.gz');

// Create individual views
const axial = await SingleSliceViewer.createAxial(axialContainer, volStack);
const sagittal = await SingleSliceViewer.createSagittal(sagContainer, volStack);
const coronal = await SingleSliceViewer.createCoronal(coronalContainer, volStack);

// Synchronize them
const sync = ViewSynchronizer.createOrthogonal(axial, sagittal, coronal);

// Listen to events
axial.onCoordChange(coord => {
  console.log('Coordinate changed:', coord);
});

Why use composable views?

• 🎯 Place views in any custom panel layout
• 🔗 Wire views across different windows or applications
• ⚙️ Full control over synchronization behavior
• 📡 Event-driven coordination with type-safe APIs

See the Composable Views Guide for complete documentation.

Examples

View Live Demos

# All composable view demos
npm run demo:composable

# Individual demos
npm run demo:single-view      # Single axial view
npm run demo:two-view         # Two synchronized views
npm run demo:multi-panel      # Multi-panel custom layout

# Classic orthogonal viewer
npm run demo:simple-ortho

See examples/README.md for more details.

Core Concepts

Volume Data

import { DenseNeuroVol, NeuroSpace } from 'neuroimjs';

// Create a volume programmatically
const space = new NeuroSpace([64, 64, 64], [3, 3, 3]);
const volume = new DenseNeuroVol(data, space);

// Read/write NIfTI files
import { readVol, writeVol } from 'neuroimjs';
const vol = await readVol('input.nii.gz');
await writeVol(vol, 'output.nii.gz');

4D Time-Series Data

import { NeuroVec } from 'neuroimjs';

// Load 4D fMRI data
const vec = await NeuroVec.fromNifti('fmri.nii.gz');

// Apply detrending
vec.detrend('linear');

// Temporal filtering
vec.temporalFilter({ type: 'bandpass', low: 0.01, high: 0.1 });

Spatial Operations

import { SpatialFilter } from 'neuroimjs';

const filter = new SpatialFilter();

// Gaussian smoothing
const smoothed = await filter.gaussianBlur(volume, { sigma: 2.0 });

// Bilateral filtering (edge-preserving)
const filtered = await filter.bilateralFilter(volume, {
  sigmaSpace: 2.0,
  sigmaIntensity: 0.1
});

Statistical Analysis

import { searchlightIterator } from 'neuroimjs';

// Searchlight analysis
for await (const sphere of searchlightIterator(volume, { radius: 3 })) {
  // Analyze voxels in sphere
  const result = analyzeROI(sphere.voxels);
  results.set(sphere.center, result);
}

Visualization Components

Pre-composed Viewers

• SimpleOrthogonalViewer - Standard 3-view layout (axial, sagittal, coronal)
• OrthogonalImageViewer - Lower-level 3-view orchestration

Composable Views (NEW)

• SingleSliceViewer - Individual orientation views with events
• ViewSynchronizer - Coordinate synchronization across views
• SliceLayer - Custom rendering layer interface

See Composable Views Guide for detailed documentation.

API Documentation

Display Components

• Composable Views Guide - Custom layouts and coordination
• SimpleOrthogonalViewer - Standard 3-view viewer

Volume Processing

• DenseNeuroVol - Dense 3D volume storage
• SparseNeuroVol - Sparse volume storage
• ClusteredNeuroVol - Clustered/labeled volumes
• NeuroSpace - Spatial coordinate system

4D Data

• NeuroVec - 4D time-series data
• EnhancedNeuroVec - Enhanced 4D with preprocessing
• FileBackedNeuroVec - Memory-mapped 4D data
• NeuroHyperVec - 5D+ hyperdimensional data

I/O

• readVol / writeVol - NIfTI file I/O
• VolStack - Multi-layer volume management
• readHeader - Read NIfTI headers without loading data

Spatial Processing

• SpatialFilter - Filtering operations (Gaussian, bilateral, median, morphology)
• Resampler - Resampling and interpolation (nearest, linear, cubic, sinc)

Statistical Operations

• searchlightIterator - Searchlight analysis
• StatFunctions - Mean, std, correlation, t-tests, etc.
• splitBlocks / splitClusters - Volume partitioning

ROI Tools

• sphericalROI / cuboidROI - Create geometric ROIs
• roiFromMask - Create ROI from binary mask
• ROIVol / ROIVec - ROI-based analysis

Development

# Install dependencies
npm install

# Build library
npm run build

# Run tests
npm test

# Run specific tests
npm run test:specific -- src/path/to/test

# Type checking
npm run test:types

# Linting
npm run lint

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Requires:

• ES modules
• WebGL 2.0
• Async/await
• OffscreenCanvas (optional, for better performance)

Contributing

Contributions are welcome! To get started:

1. Fork the repository and create a feature branch
2. Install dependencies with npm install
3. Make your changes and add tests where appropriate
4. Run npm test and npm run lint to ensure everything passes
5. Open a pull request describing your changes

License

MIT

Related Projects

• nilearn - Python neuroimaging library
• NiBabel - Python NIfTI I/O
• AFNI - Analysis of Functional NeuroImages
• FSL - FMRIB Software Library

Citation

If you use neuroimjs in your research, please cite this repository:

@software{neuroimjs,
  author = {Buchsbaum, Bradley},
  title = {neuroimjs: A neuroimaging library for JavaScript},
  url = {https://github.com/bbuchsbaum/neuroimjs},
  license = {MIT}
}

Acknowledgments

Built with:

• PIXI.js - WebGL rendering
• MobX - Reactive state management
• nifti-reader-js - NIfTI parsing
• pako - Compression