n5¶

The N5 data format driver provides access to N5 single-resolution and multi-resolution arrays.

URL syntax¶

• base-kvstore-url/|n5:

• base-kvstore-url/|n5:additional/path/

Specifying an additional/path/ after the n5 URL scheme is currently equivalent to including it in the base-kvstore-url/, but may be preferred for distinguishing the root of an N5 hierarchy from the path within it.

Multiscale datasets¶

Multiscale datasets are specified by directory tree containing the following files and directories:

• attributes.json (multiscale metadata, also inherits attributes from ancestor directories)

• s0/ (base resolution)

• s1/ (first downsampling level)

• sN/ (Nth downsampling level)

The downsampling factors for each level may be specified in several ways:

• Each sN/attribute.json file may specify a downsamplingFactors attribute as an array specifying the downsampling factor corresponding to each dimension of the array. For example s1/attributes.json may specify:

   {
     "dataType": "uint8",
     "dimensions": [1000, 1000, 1000],
     "blockSize": [100, 100, 100],
     "compression": {"type": "raw"},
     "downsamplingFactors": [2, 2, 1]
  }
  

  to indicate that the first two dimensions are downsampled by 2 and the last dimension is not downsampled. If the base resolution s0/ array does not specify a downsamplingFactors attribute, the downsampling factor is assume to be 1 for all dimensions.

  Note

  In this case, the set of downsampling levels is determined by a list operation on the base key-value store, and fails if listing is not supported.

• The top-level attributes.json may specify a downsamplingFactors or scales attribute as an array of arrays, where the outer array ranges over downsampling levels, starting from 0, and the inner array ranges over dimensions. For example:

  {
    "downsamplingFactors": [
      [1, 1, 1],
      [2, 2, 1],
      [4, 4, 1]
    ]
  }
  

  indicates that there are 3 downsampling levels, where:

  • s0/ has downsampling factors of [1, 1, 1],

  • s1/ has downsampling factors of [2, 2, 1], and

  • s2/ has downsampling factors of [4, 4, 1].

  Note

  When the downsampling factors are specified in the top-level metadata in this way, any downsamplingFactors attributes specified in the individual sN/attributes.json metadata files are ignored, and the base key-value store need not support listing.

  The behavior is identical if the attribute is specified as scales instead of downsamplingFactors.

Data types¶

Supported data types:

• uint8

• int8

• uint16

• int16

• uint32

• int32

• uint64

• float32

Codecs¶

Supported compression types:

• raw

• blosc

• gzip

Coordinate space metadata¶

Dimension names¶

Dimension names may be specified using the axes metadata attribute; if present, the axes attribute must be an array of strings, specifying the name of each dimension in the same order as the dimensions attribute.

Physical units¶

Units may be specified using the resolution and units attributes, which specify the coefficient and unit of each dimension in the same order as the dimensions attribute. For example, for a 3-d array:

{
  "resolution": [4, 4, 30],
  "units": ["nm", "nm", "nm"]
}

Alternatively, units may be specified using the pixelResolution attribute:

{
  "pixelResolution": {
    "unit": "nm",
    "dimensions": [4, 4, 30]
  }
}

The pixelResolution attribute is not recommended, however, since it is less widely supported and requires all dimensions to have the same base unit.

Coordinate arrays¶

As a Neuroglancer-specific extension, coordinate arrays may be specified using the coordinateArrays metadata attribute; if present, the coordinateArrays attribute must be an object, where the keys correspond to dimension names in axes and the values are arrays of strings specifying the coordinate labels starting at 0. For example:

{
  "dimensions": [10000, 10000, 5],
  "dataType": "uint8",
  "blockSize": [512, 512, 1],
  "compression": { "type": "raw" },
  "axes": ["x", "y", "c"],
  "coordinateArrays": {
    "c": ["A", "B", "C", "D", "E"]
  }
}