BrAinPI

BrAinPI, pronounced "Brain Pie", is a Flask-based API for serving a variety of multiscale imaging data for access over the web in standard file formats like ome-zarr and neuroglancer precomputed. BrAinPI provides a file browser interface that allows one to expose a file system with basic user and group management. The browser interface can be used for single click access to neuroglancer visualizations. When multiscale chunked imaging file types are available (see "Compatible file types" below), BrAinPI can open the dataset in neuroglancer or provide links to various 'views' of the data structured as ome-zarr. The ome-zarr links are compatible with any application that support ome-zarr, including neuroglancer and napari.

Installing BrAinPI

# Currently, BrAinPI has only been tested on Ubuntu >=16.04

conda create -y -n brainpi python=3.8
conda activate brainpi

git clone https://github.com/CBI-PITT/BrAinPI.git
pip install -e /path/to/cloned/repo/

## Before running BrAinPI

'''
Edit the settings_TEMPLATE.ini and groups_TEMPLATE.ini files and rename them to settings.ini and groups.ini.
'''

Running BrAinPI:

#For development:
python -i /path/to/cloned/repo/brainapi/BrAinPI.py

#In production:
gunicorn --worker-class gevent -b 0.0.0.0:5001 --chdir /path/to/cloned/repo/BrAinPI wsgi:app -w 24 --threads=2 --worker-connections=20
## Adjust these parameters according to your specific needs
# -w = workers (suggest the number of logical CPUs)
# -threads = threads per worker (suggest 2)
# --worker-connections (suggest 5-20)

### We suggest running BrAinPI behind NGINX in a production environment.

Access BrAinPI:

# If running BrAinPI on your local computer

# BrAinPI Browser:
http://localhost:5001:/browser

# HTML links endpoint:
# Returns a json with links to several versions of a dataset on disk
http://localhost:5001:/path_to_html_options/?path=/path/to/physical/location/on/disk.ims
http://localhost:5001:/path_to_html_options/?path=/path/to/physical/location/on/disk.ome.zarr

Compatible file types:

Inputs:

File Type	Links	Notes
Imaris	Library used to read .ims IMS file structure Bitplane Imaris	BrAinPI can read multiscale image data but not annotation information
OME-Zarr	OME-NGFF Spec Histochemistry Paper	BrAinPI can read data in ome-zarr following zarr v2 specification
OME-Zarr-like	Alternative Zarr Stores	BrAinPI can read datasets structured like OME-Zarr but not conforming strictly to the OME-NGFF specification. Currently supported are datasets written in alternative zarr storage classes (supported: H5_Nested_Store)

Outputs:

File Type	Links	Notes
OME-Zarr	OME-NGFF Spec Histochemistry Paper	Output metadata (.zattrs), if absent in the origional dataset may be generated by BrAinPI for compatibility purposes.
neuroglancer precomputed	Neuroglancer github precomputed format README

"File Browser:

A file browsing interface is availabe in BrAinPI at the "/browser" endpoint. At the root of the file browser, paths registered with BrAinPI appear according to their assigned names. Paths exposed for anonymous visitors to BrAinPI can be made under [dir_anon]. Paths that should only be seen by authenticated users can be registed via [dir_auth].

NOTE: Although paths are not exposed and browseable when registed with [dir_auth], links generated against files in these paths can be viewed by anyone.

NOTE: Currently LDAP authentication can be configured only for windows active directory.

In the examples below, the root of the browser path by anonymous browsers would show 'my_fav_location'

# settings.ini
[dir_anon]
my_fav_location = /path/to

[dir_auth]
another_place = /another

"path_to_html_options" endpoint:

This endpoint makes it easy to retrieve links to several views of a compatible file type. For this to work, the settings.ini file must have a path registered that you wish to exponse to BrAinPI in either the [dir_anon] or [dir_auth] fields. The user then passes the full file path to the endpoint to determine if BrAinPI is capable of translating the dataset. A json file is returned with several entries described in the table below. Null values indicate that BrAinPI is not able to generate a link for that dataset - or the path does not exist.

Examples for how to structure a request (see setting.ini above):

http://localhost:5001/path_to_html_options/?path=/path/to/physical/location/on/disk.ims
http://localhost:5001/path_to_html_options/?path=/another/path/to/a/different/physical/location/on/disk.ome.zarr

Links Returned by the "path_to_html_options"

JSON Key	Link
neuroglancer	Link to open a neuroglancer visualization of the dataset. This endpoint will also deliver neuroglancer precomputed format
neuroglancer_metadata	'info' file for neuroglancer precomputed format
omezarr	ome-zarr view of the data
omezarr_metadata	.zattrs for the ome-zarr view of the data
omezarr_validator	ome-ngff validator link for the omezarr url
omezarr_8bit	ome-zarr view of the data returned in a 8bit data type
omezarr_8bit_metadata	.zattrs for the ome-zarr view of the data returned in a 8bit data type
omezarr_8bit_validator	ome-ngff validator link for the omezarr_8bit url
omezarr_neuroglancer_optimized	ome-zarr view of the data where data is chunked along the channel dimension to provide enhanced compatibility with neuroglancer
omezarr_neuroglancer_optimized_validator	ome-ngff validator link for the omezarr_neuroglancer_optimized url
omezarr_8bit_neuroglancer_optimized	ome-zarr view of the data where data is chunked along the channel dimension to provide enhanced compatibility with neuroglancer and returned in a 8bit data type
omezarr_8bit_neuroglancer_optimized_validator	ome-ngff validator link for the omezarr_8bit_neuroglancer_optimized url
path	the path passed to the endpoint

License

Distributed under the terms of the [BSD-3] license, "BrAinPI" is free and open source software