Metadata-Version: 2.4
Name: neuroglancer-volume-viewer
Version: 0.1.1
Summary: Launch a Neuroglancer viewer for 3D data stored in a Zarr file.
Author-email: Hanna Ruth <hruth@anl.gov>
License-Expression: MIT
Project-URL: Homepage, https://github.com/AdvancedPhotonSource/neuroglancer-volume-viewer
Project-URL: Repository, https://github.com/AdvancedPhotonSource/neuroglancer-volume-viewer
Project-URL: Issues, https://github.com/AdvancedPhotonSource/neuroglancer-volume-viewer/issues
Keywords: neuroglancer,zarr,volume,viewer,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: neuroglancer
Requires-Dist: numpy
Requires-Dist: zarr
Dynamic: license-file

This repository contains scripts that launch a Neuroglancer viewer to visualize 3D data stored in a Zarr file, making it accessible via a web browser. 

Using Neuroglancer with Zarr files is particularly useful for viewing very large datasets, because the lazy loading scheme prevents the entire array from being loaded into memory.

- `open-zarr-file-remote` — run the viewer on a remote machine and view it locally via an SSH tunnel.
- `open-zarr-file_local` — run the viewer on the same machine you'll view it on (no SSH tunnel needed).

## Remote use: `open-zarr-file-remote`

In this example, I am using port 9090:

1. Create the SSH tunnel
```bash
ssh -L 9090:localhost:9090 -Y my-remote-machine
```

2. Run the script (the port must match the SSH tunnel port)
```bash
open-zarr-file-remote 9090 /path/to/file.zarr
```

3. This script will print the URL where you can access the neuroglancer viewer on your local machine. It will look something like this: `Open in browser: http://localhost:9090/v/14a31d6d2d4d11d95fa35f51daadc97da9100571/`. Open the link in your browser on your local machine.

## Local use: `open-zarr-file-local`

When the zarr file lives on the same machine you'll view it on, no SSH tunnel or port is needed — neuroglancer picks a free port itself:

```bash
open-zarr-file-local /path/to/file.zarr
```

The script will print a URL like `Open in browser: http://127.0.0.1:46789/v/14a31d6d2d4d11d95fa35f51daadc97da9100571/`. Open it in your browser.

## Optional resolution argument

Both scripts accept an optional voxel resolution (in nanometers) as the last argument. For example:

```bash
open-zarr-file-remote 9090 /path/to/file.zarr 10
open-zarr-file-local /path/to/file.zarr 10
```

## Input file types
This package expects data in the zarr format. Zarr version 3 and zarr version 2 are supported. If using zarr version 2, the data must be saved with name 'data'.

Example of how to save zarr v2 files:
```python
import zarr
root = zarr.open_group("/path/to/file.zarr", mode='w', zarr_format=2)
root.create_array('data', data=array)
```

neuroglancer-volume-viewer works with zarr files saved using methods from the pyxalign package.
