Coordinate spaces

A coordinate space associates a semantic meaning to coordinate vectors within that space, vectors of real-valued coordinates specifying a coordinate for each dimension of the coordinate space. At any given time, a coordinate space has a fixed number of dimensions, called the rank of the coordinate space.

Commonly, Neuroglancer is used with 3-dimensional data, and hence coordinate spaces of rank 3, but Neuroglancer supports degenerate coordinate spaces of rank 0, and there is no explicit upper limit on the number of dimensions.

In addition to rank, coordinate spaces have several other properties:

  • The coordinate space specifies a unique name for each dimension, such as x, y, or z. Dimension names must match the regular expression [a-zA-Z][a-zA-Z_0-9]*['^]?: they must consist of an ASCII letter, and followed by zero or more ASCII letters, digits, or underscore characters. The optional suffix of ' or ^ indicates a local or channel dimension, respectively.

  • For each dimension, the coordinate space specify either:

    • a physical unit, which may include both a base unit and a coefficient, such as 4e-9 m, or may omit a base unit to indicate a unitless dimension, such as 1 or 1e3; or

    • a coordinate array specifying a string label associated with some of the coordinates (indicating a discrete dimension).

  • Coordinate spaces may optionally have a list of associated bounding boxes, from which lower and upper bounds for each coordinate may be inferred.

Neuroglancer makes use of a number of interrelated coordinate spaces and associated positions, orientations, and other coordinate transformation parameters:

coordinate_spaces cluster_layer Layer i cluster_layer_space Coordinate space cluster_datasource Data source j cluster_globalcamera Global camera parameters cluster_globalcamera_cross_section Cross-section cluster_globalcamera_projection 3-d projection cluster_layergroupviewer Layer group viewer k cluster_layergroupviewer_cross_section Cross-section views cluster_layergroupviewer_projection 3-d projection view global_space->projection_view_space global_space->cross_section_view_space datasource_space->datasource_transform datasource_transform->layer_local_dims layer_global_dims->global_space Merge global_cross_section_orientation->layergroupviewer_cross_section_orientation global_cross_section_scale->layergroupviewer_cross_section_scale global_cross_section_depth->layergroupviewer_cross_section_depth global_center_position->layergroupviewer_center_position global_display_dimensions->layergroupviewer_display_dimensions global_relative_display_scales->layergroupviewer_relative_display_scales global_projection_orientation->layergroupviewer_projection_orientation global_projection_scale->layergroupviewer_projection_scale global_projection_depth->layergroupviewer_projection_depth layergroupviewer_center_position->projection_view_space layergroupviewer_center_position->cross_section_view_space layergroupviewer_display_dimensions->projection_view_space layergroupviewer_display_dimensions->cross_section_view_space layergroupviewer_relative_display_scales->projection_view_space layergroupviewer_relative_display_scales->cross_section_view_space layergroupviewer_cross_section_orientation->cross_section_view_space layergroupviewer_cross_section_scale->cross_section_view_space layergroupviewer_cross_section_depth->cross_section_view_space layergroupviewer_projection_orientation->projection_view_space layergroupviewer_projection_scale->projection_view_space layergroupviewer_projection_depth->projection_view_space projection_view_space View coordinate space cross_section_view_space View coordinate space global_space Global coordinate space datasource_space Coordinate space Coordinate space datasource_transform Coordinate transform Coordinate transform layer_global_dims Global dimensions layer_local_dims Local dimensions layer_channel_dims Channel dimensions layer_position Local position global_cross_section_orientation Orientation global_cross_section_scale Scale global_cross_section_depth Depth bounds global_center_position Center position global_display_dimensions Display dimensions global_relative_display_scales Relative display scales global_projection_orientation Orientation global_projection_scale Scale global_projection_depth Depth bounds layergroupviewer_center_position Center position layergroupviewer_display_dimensions Display dimensions layergroupviewer_relative_display_scales Relative display scales layergroupviewer_cross_section_orientation Orientation layergroupviewer_cross_section_scale Scale layergroupviewer_cross_section_depth Depth bounds layergroupviewer_projection_orientation Orientation layergroupviewer_projection_scale Scale layergroupviewer_projection_depth Depth bounds

Coordinate spaces and transforms in Neuroglancer. The labels above link to the corresponding description below.

The series of coordinate transformations, starting from the coordinate spaces of each data source, into a common global coordinate space, and then into the coordinate space for each rendered view, is described below.

Data source coordinate space

The starting point for all coordinate transformations in Neuroglancer is the data source itself. Each data source added to a Layer has an inherent associated coordinate space.

The dimension names, physical units or coordinate arrays, and bounds are determined from the source data automatically; if dimension names or units cannot be determined, default values are chosen by the data source implementation. The dimension names and bounds within the source coordinate space are fixed, but the coordinate transform controls how the source data coordinate space maps to the layer and global coordinate spaces.

Coordinate transform

A configurable affine coordinate transform, represented by an affine transformation matrix and a list of output dimension names, maps the source coordinate space to the layer coordinate space and to the global coordinate space.

The data source provides a default value for the coordinate transform, normally an identity matrix.

The user can configure the coordinate transform in three ways:

  1. The affine transformation matrix scaling and translation coefficients may be changed directly. Note that the translation coefficients are in the units specified for the output (layer) dimension.

  2. The names of the output dimensions of the transform may be changed. Permuting the output dimension names has a similar effect to permuting the rows of the transformation matrix in the same way, but may be more convenient.

  3. The source dimension scales/units may be changed, in order to rescale the input. This is equivalent to applying an appropriate scale transformation to the affine transformation matrix, but in many cases is more convenient.

    Note

    Changing the units of an output dimension does not rescale the data, it simply changes the unit used to display coordinates.

The output space of the coordinate transform is a subspace of the layer coordinate space. If two data sources associated with a layer both have a coordinate transform with an output dimension named x, both coordinate transforms are referring to the same dimension x. In contrast, the names of the source dimensions of the coordinate transform are purely descriptive; if two data sources associated with a layer both have a source dimension x, there is no direct correspondence between those two source dimensions.

Layer coordinate space

The output coordinate spaces of the coordinate transforms of each data source in a given layer are merged into a single coordinate space that is called the layer coordinate space:

  • If a layer has just a single data source (most common case), then the layer coordinate space is simply the output coordinate space of the coordinate transform.

  • In general, if a layer has more than one data source, the layer coordinate space consists of the distinct output dimensions of the coordinate transforms of each of the data sources.

Global, local and channel dimensions

A layer coordinate space dimension may be one of three kinds, determined based on the dimension name:

Global dimensions

Global dimensions have names consisting of only ASCII alphanumeric and underscore characters without a special suffix, e.g. x.

  • The global dimensions of each layer are merged into the global coordinate space, which specifies the units for global dimensions.

  • A global dimension x in one layer refers to the same dimension as a global dimension x in another layer.

  • Only global dimensions may be used as display dimensions.

Local dimensions

Local dimensions have names ending in ' (ASCII single quote), e.g. c'.

  • The local coordinate space of each layer consists of the subset of the layer dimensions that are local dimensions, and specifies the units for local dimensions.

  • A local dimension c' in one layer is completely independent from a local dimension with the same name c' in another layer.

  • Local dimensions may not be used as display dimensions. Instead, data views always display a cross section at a single position along each local dimension; this position is determined by the local position.

  • A global dimension with a unique name that is not a display dimension may be used as an alternative to a local dimension; a local dimension simply avoids the need to assign unique names, and may be more convenient in some cases.

Channel dimensions

Image layers additionally support channel dimensions, which have names ending ^ (ASCII caret), e.g. c^.

  • The shader can access the value at every position within the channel dimensions when computing the output pixel color. For example, if there is a single channel dimension with a range of [0, 3), the shader can compute the output pixel color based on the data value at each of the 3 positions.

  • Like local dimensions, a channel dimension c^ in one layer is completely independent from a channel dimension with the same name c^ in another layer.

  • A dimension can be used as a channel dimensions only if the data source is unchunked along that dimension.

Local coordinate space

The local coordinate space of a layer consists of the local dimensions of the layer coordinate space.

By default, dimensions are ordered based on when they are first added, with dimensions added later ordered after dimensions added earlier, but dimensions may be explicitly reordered.

Local position

Each layer has an associated local position, specifying for each dimension in the local coordinate space the single slice for each dimension in the local coordinate space to be displayed in any views of the layer.

Global coordinate space

The global coordinate space consists of the global dimensions from the coordinate spaces of each layer added to the viewer.

By default, dimensions are ordered based on when they are first added to a layer coordinate space, with dimensions added later ordered after dimensions added earlier, but dimensions may be explicitly reordered.

Global center position

The viewer has a single default global position, called the global center position, which specifies a center coordinate for each dimension in the global coordinate space.

Global mouse position

The position within the Global coordinate space corresponding to the current mouse position within a data view is called the global mouse position.

Layer group center position

Additionally, each layer group sub-viewer has a separate center position in the global coordinate space which may optionally be fixed to, or linked by an offset to, the global center position.

Display dimensions

Data views project data from at most three global dimensions; these projected dimensions are called display dimensions. From all other global dimensions, only a cross section of the data is displayed at any given time.