Tile Source Conventions¶
CATMAID does not serve image data itself. Instead, it stores a few critical pieces of information about the image volume and specifies a set of conventions for retrieving image data from a separate image volume host. These conventions are tile source types, which define parameters and URL formats both the CATMAID backend and frontend can use to access image data for rendering and analysis.
This document provides information on the type source types specified by CATMAID, the parameters which they use to retrieve image data, how this is stored in the CATMAID backend, and how to create a new tile source type in the CATMAID backend and frontend.
Also note that CATMAID will clamp the display of tiled data by default to zero
(i.e. no request is made for tiles at coordinate [-1, 0] in the plane). This
behavior can be changed by adding the boolean field clamp
to the stack’s
metadata
field with a value of false
. The metadata
field expects a
JSON format, so the content would look like {"clamp": false}
.
Tile Source Parameters¶
Each tile source type uses a subset of the following parameters to determine its source regardless of the specific tiles being retrieved. Though specific APIs may use different names for these parameters, the names provided here are used for consistency in defining tile source types below:
sourceBaseURL
(string)This defines a base URL for the source server and volume, including trailing slash.
dimension
(integer array [x, y, z])Dimension of the image volume in pixels at its original scale level.
resolution
(double array [x, y, z])Resolution of the image volume in nanometers at its original scale level.
numZoomLevels
(integer)The number of zoom levels (downsampling octaves) which the source supports.
fileExtension
(string)Filename extension for image tiles served by the source.
tileWidth
(integer)
tileHeight
(integer)Dimensions of image tiles in pixels. For pre-tiled sources, this should be the dimensions of the source tiles, while for dynamic sources this should be the preferred dimension for retrieval and rendering.
orientation
(integer|string)Orientation of the stack relation to project space. Semantically this value is either “XY”, “XZ”, “ZY”, but is usually passed as an integer in {0, 1, 2} enumerating these, respectively.
Currently only DVID tile source types (6, 8) must know orientation directly. Other tile source types encode orientation in the
sourceBaseURL
.tileSourceType
(integer)A integer enumerating the types of tile sources listed below.
Tile Parameters¶
Tile sources may additionally make use of a subset of the following parameters when determining how to retrieve specific tile requests:
row
(integer)The row of the tile in the image grid for this z-slice, e.g., the floor of the tile y origin divided by
tileHeight
.col
(integer)The column of the tile in the image grid for this z-slice, e.g., the floor of the tile x origin divided by
tileWidth
.zoomLevel
(integer)The zoom level of tiles to retrieve. Zoom level 0 is the original scale, zoom level 1 is the first downsampled octave, etc.
pixelPosition
(integer array [x, y, z])The stack space position in pixels of a location in the plane of the tile. Usually this position is shared for many tile requests, e.g., the center of a stack viewer, and is used only to generate a path using the
z
location in the stack.
Tile Source Types¶
Tile source types are listed by the enumeration integer ID referenced by
tileSourceType
:
1. File-based image stack¶
URL format:
<sourceBaseUrl><pixelPosition.z>/<row>_<col>_<zoomLevel>.<fileExtension>
2. Request query-based image stack¶
URL format:
<sourceBaseURL>?x=<col * tileWidth> &y=<row * tileHeight> &z=<pixelPosition.z> &width=<tileWidth> &height=<tileHeight> &scale=<2^-zoomLevel> &row=y &col=x
3. HDF5 via CATMAID backend¶
Note
To use this tile source, the
h5py
Python library has to be installed.This is the only tile source type which the CATMAID backend serves directly. Django retrieves tile requests from an image volume stored in an HDF5 file. This is a convenience source intended for quick exploration of small volumes only and does not scale to large volumes or many users.
As an exceptional source, this uses the following tile source parameters that should not be used by any other source:
catmaidURL
(string)Base URL of the CATMAID instance serving the volume, including trailing slash.
projectId
(integer)ID of the CATMAID project.
stackId
(integer)ID of the CATMAID stack.
URL format:
<catmaidURL><projectId>/stack/<stackID>/tile?x=<col * tileWidth> &y=<row * tileHeight> &z=<pixelPosition.z> &width=<tileWidth> &height=<tileHeight> &scale=<2^-zoomLevel> &row=y &col=x &file_extension=<fileExtension> &basename=<sourceBaseURL> &type=all
4. File-based image stack with zoom level directories¶
A variation on tile source type 1 where the zoom level is also a directory.
URL format:
<sourceBaseUrl><pixelPosition.z>/<zoomLevel>/<row>_<col>.<fileExtension>
5. Directory-based image stack¶
Like tile source types 1 and 4, but with all components being directories.
URL format:
<sourceBaseUrl><zoomLevel>/<pixelPosition.z>/<row>/<col>.<fileExtension>
6. DVID imageblk
voxels¶
This type supports loading tiles from voxel data instances in DVID using
imageblk
(uint8blk
,rgba8blk
) datatypes.For DVID
imageblk
tile sources,sourceBaseURL
should reference the data instance REST resource with orientation information directly, that is:<api URL>/node/<UUID>/<data name>/raw/<dims>/
fileExtension
may also specify a quality parameter, e.g.,jpg:80
.Because orientations are just permutations of coordinates in the voxel volume, each orientation has a slightly different URL format.
XY format:
<sourceBaseUrl><tileWidth>_<tileHeight>/<col * tileWidth>_<row * tileHeight>_<pixelPosition.z>/<fileExtension>XZ format:
<sourceBaseUrl><tileWidth>_<tileHeight>/<col * tileWidth>_<pixelPosition.z>_<row * tileHeight>/<fileExtension>ZY format (actually YZ, see note):
<sourceBaseUrl><tileWidth>_<tileHeight>/<pixelPosition.z>_<row * tileHeight>_<col * tileWidth>/<fileExtension>Note
Because DVID prefers YZ axis ordering over ZY, note that tiles for that orientation must be transposed to be consistent with other tile source types.
7. Render service¶
This tile source type retrieves image tiles from the dynamic render service used at Janelia Research Campus.
URL format:
<sourceBaseURL>largeDataTileSource/<tileWidth>/<tileHeight>/<zoomLevel>/<pixelPosition.z>/<row>/<col>.<fileExtension>
8. DVID imagetile
tiles¶
This type supports loading tiles from tile data instances in DVID using
imagetile
datatypes.For DVID
imagetile
tile sources,sourceBaseURL
should reference the data instance REST resource directly, that is:<api URL>/node/<UUID>/<data name>/tile/Because orientations are just permutations of coordinates in the voxel volume, each orientation has a slightly different URL format.
XY format:
<sourceBaseUrl>xy/<zoomLevel>/<col>_<row>_<pixelPosition.z>XZ format:
<sourceBaseUrl>xz/<zoomLevel>/<col>_<pixelPosition.z>_<row>ZY format (actually YZ, see note):
<sourceBaseUrl>yz/<zoomLevel>/<pixelPosition.z>_<row>_colNote
Because DVID prefers YZ axis ordering over ZY, note that tiles for that orientation must be transposed to be consistent with other tile source types.
9. FlixServer tiles¶
This type supports loading tiles from a FlixServer instance. This tile server generates images dynamically and supports CATMAID’s default tile source URL format:
<sourceBaseUrl><pixelPosition.z>/<row>_<col>_<zoomLevel>.<fileExtension>Additional GET parameters can be used to adjust color, dynamic range and gamma mapping:
color = (red,green|blue|cyan|magenta|yellow|white) for coloring min/max = [0, 2^16] for specifying the dynamic range gamma = [0, 2^16] for the exponent of a non-linear mappingFor multi-channel images, a comma separated list can be used as parameter value (e.g. color=cyan,magenta).
10. H2N5 tiles¶
This type supports loading tiles from the H2N5 server, which dynamically slices tiles from N5 tensor files.
The URL format for this source is:
<sourceBaseUrl>.<fileExtension>However, unlike other sources,
sourceBaseUrl
is not a valid URL on its own. It contains several substitution strings the CATMAID replaces on each tile request. This is necessary to support n-dimensional volumes. The substitution strings are:
%SCALE_DATASET%
(optional)Where to insert the dataset name for different scale levels. Currently these are
s0
,s1
, etc., but in the future may be read from the N5 attributes of the parent dataset of where this substitution string appears.%AXIS_0%
Position in the coordinates part of the H2N5 URL to replace with
col * tileWidth
%AXIS_1%
Position in the coordinates part of the H2N5 URL to replace with
row * tileHeight
%AXIS_2%
Position in the coordinates part of the H2N5 URL to replace with
pixelPosition.z
While
%AXIS_0%
and%AXIS_1%
could be inferred by parsing the URL for the slicing dimensions, note that%AXIS_2%
could not.
11. N5 image blocks¶
This type supports loading image blocks from N5 served over HTTP.
Unlike other sources,
sourceBaseUrl
is not a valid URL on its own. It contains several substitution strings the CATMAID replaces on each tile request. This is necessary to support n-dimensional volumes. The substitution strings are:
%SCALE_DATASET%
(optional)Where to insert the dataset name for different scale levels. Currently these are
s0
,s1
, etc., but in the future may be read from the N5 attributes of the parent dataset of where this substitution string appears.Further,
sourceBaseUrl
has special path components. It should end in a path component specifying the ordered dimensions from which image data should be sliced, separated by underscores. For example,2_1_0
will slices N5 dimensions 2, 1, and 0 as the x, y, and z stack dimensions, respectively.This tile source will also look for a path component ending in
.n5
to use as the N5 root directory. If it does not find such a component, it will assume the origin is the root N5 directory.For example:
https://catmaid.org/path/root.n5/group/dataset/%SCALE_DATASET%/raw/0_1_2
12. JHU/APL Boss tiles¶
This type supports loading tiles from a JHU/APL Boss instance, using a manually entered API token for authorization. The API token entered through the front-end layer control UI is passed in an
Authorization
header with all tile requests.Currently only XY tiles are fully supported.
tileWidth
andtileHeight
must be equal.
sourceBaseURL
should reference the REST resource directly:<instance URL>/v1/tile/<collection>/<experiment>/<channel>/XY URL format:
<sourceBaseURL>xy/<tileWidth>/<zoomLevel>/<col>/<row>/<pixelPosition.z>
13. CloudVolume tiles¶
Using this type, the back-end is instructed to go get a tile through the cloudvolume library. The URL can be anything that CloudVolume can take, e.g. a Neuroglancer Premcomputed image dataset like public Google hosted FAFB dataset:
precomputed://gs://neuroglancer-fafb-data/fafb_v14/fafb_v14_claheCurrently, only HTTPS mode is supported (i.e. no explicit credentials).
14. Neuroglander precomputed image blocks¶
This type supports loading image blocks from Neuroglancer Precomputed format served over HTTP.
Like with N5 image blocks and unlike other sources,
sourceBaseUrl
is not a valid URL on its own. It contains several substitution strings the CATMAID replaces on each tile request. This is necessary to support n-dimensional volumes. The substitution strings are:
%SCALE_DATASET%
(optional)Where to insert the dataset name for different scale levels. Currently these are
s0
,s1
, etc., but in the future may be read from the N5 attributes of the parent dataset of where this substitution string appears.Further, and also like the N5 source,
sourceBaseUrl
has special path components. It should end in a path component specifying the ordered dimensions from which image data should be sliced, separated by underscores. For example,2_1_0
will slices chunk dimensions 2, 1, and 0 as the x, y, and z stack dimensions, respectively.This tile source will also look for a path component ending in
/info
to use as the dataset root directory. If it does not find such a component, it will assume the origin is the root directory.For example:
gs://neuroglancer/pinky100_v0/son_of_alignment_v15_rechunked/%SCALE_DATASET%/0_1_2Also note that Neuroglancer datasets can have a property called
voxelOffset
, which by default is(0, 0, 0)
. If set to other values the dataset will be artificially resized at the origin accordingly. To Match voxel coordinates between CATMAID and Neuroglancer, the respective CATMAID stack needs to have thevoxelsOffset
metadata field set with the the value and “Apply primary stack voxel offset” has to be checked in the Settings Widget (default). For instance, if the zero-zoom level voxel offset is(-3072, -3072, 0)
, then the metadata of the CATMAID stack should look like this:{"voxelOffset": [-3072, -3072, 0]}
.
Backend Representation¶
Tile source parameters are stored in the Stack
Django model. To create a
new tile source type, one needs only to establish a convention for the integer
that enumerates that type (after communication with the developers) and begin
using it in stacks.
To support cropping, the backend also implements tile sources. To support
cropping for a new tile source type, implement a method
in catmaid.control.cropping.CropJob
like
other get_tile_path_<tileSourceType>
methods that returns the correct URL,
then make sure it is called from the CropJob.initialize
method.
Frontend Retrieval¶
The front end implements tile source URL generation in
django/applications/catmaid/static/js/tile-source.js
. To define a new tile
source type, follow the convention of the existing tiles sources by creating
a function that returns an object with the appropriate getTileURL
,
getOverviewURL
, and getOverviewLayer
methods. The overview URL should
locate a thumbnail of the current stack z-section. Then map the
tileSourceType
enumeration of your tile source type to your implementation
in CATMAID.TileSources
.