Skip to content

README.md

Latest commit

 

History

History
97 lines (66 loc) · 4.12 KB

README.md

File metadata and controls

97 lines (66 loc) · 4.12 KB

neuroglancer-python

Python utilities for building, serving, and converting data for Neuroglancer — a WebGL-based viewer for volumetric microscopy data.

Repository structure

neuroglancer-python/
├── neuroglancer_python_examples/   # Standalone example scripts
├── neuroglancer_regression_tests/  # Puppeteer snapshot regression tests
├── neuroglancer_utils/             # Shared Python helpers for viewer & layer setup
├── cloud_io/                       # Shared GCS and S3 upload/download utilities
└── converters/                     # Data conversion pipelines

neuroglancer_python_examples/

Standalone Python scripts demonstrating common neuroglancer-python use cases: loading volumes from N5/Zarr/NRRD/TIFF/GCS, configuring shaders and transfer functions, writing precomputed annotations, and more. A Makefile at the root can generate sample data and launch the viewer (make all).

neuroglancer_regression_tests/

Puppeteer-based snapshot regression tests that load live Neuroglancer states in a headless browser and compare screenshots against reference images. See Running the tests below.

neuroglancer_utils/

Shared Python helpers used by example scripts and converters:

  • viewer_utils.py — launch a viewer, open a browser tab, and apply common viewer settings (3D layout, GPU memory, axis lines, title)
  • layer_utils.py — helpers for configuring layer side panels
  • shaders.py — reusable GLSL shader strings (max-projection, volume rendering, etc.)
  • local_server.py — utilities for serving local data to the viewer
  • create_datasets/ — scripts to generate synthetic test volumes (cubes, spheres, multi-channel data)

cloud_io/

Shared cloud storage utilities importable by any converter or script:

  • gcs.py — list, download, and upload files to Google Cloud Storage, with concurrent transfer via the GCS transfer manager
  • s3.py — equivalent helpers for AWS S3 using boto3

converters/

Self-contained data conversion pipelines, each with its own requirements.txt and .env-based configuration.

  • mrc_to_omezarr/ — Converts MRC microscopy volumes to OME-Zarr 0.5/0.6.
  • tif_to_omezarr/ — Converts single or multi-page TIFF files to OME-Zarr with multiscale pyramids and optional channel processing.
  • dm3_to_omezarr/ — Stitches a 3×3 grid of DM3 tile montages into a single compressed OME-Zarr volume.
  • nrrd_to_precomputed/ — Converts NRRD segmentation files to Neuroglancer Precomputed format with mesh generation for 3D visualisation.
  • stitch_zarr_wells_to_precomputed/ — Reads a grid of OME-Zarr well files (named r{row}c{col}.zarr), stitches them into a single volume, generates multi-resolution MIP levels, and writes the result as a Neuroglancer Precomputed volume. Supports GCS for both input and output.

Installation

git clone https://github.com/MetaCell/neuroglancer-python
cd neuroglancer-python
pip install -e .

git clone -b develop https://github.com/MetaCell/neuroglancer/tree/develop
cd neuroglancer
npm i
npm run build-python
pip install .

Note: Until upstream PRs are merged, install the neuroglancer Python package from the MetaCell fork at https://github.com/MetaCell/neuroglancer/tree/develop.

Usage

See the neuroglancer_python_examples/ folder for runnable scripts. A Makefile is available to generate example data, start the server, and open the browser — edit the variables at the top to point to your data paths.

For the converter pipelines, see the README.md inside each subdirectory of converters/.

Regression tests

cd neuroglancer_regression_tests
npm install
npm run test

Update constants.js to point to different data sources.

Running individual tests

npm install jest --global
cd neuroglancer_regression_tests
jest MATCH --config=jest.config.js

where MATCH is a substring of the test name.

Running a local data server

npx http-server FOLDER_WITH_DATA/ --cors=authorization