Creating Label Data

Label data, unlike grayscale image data, has a variety of forms tailored to particular use cases. Label data is usually ingested from a series of 64-bit label images, which can be stored in RGBA form or as compressed raw data.

But before we load the images, we need to create the data instances that will hold labels.

Creating label data instances

Note: This example needs to be updated to use the more advanced labelmap datatype, which combines both labelblk and labelvol functionality. It's used for all of FlyEM's supervoxel-oriented segmentation data while labelblk/labelvol was an earlier system.

To create a data instance to hold a volume of data where each voxel could be a different label, use the labelblk data type. You can do it like this:

% dvid repo c7 new labelblk labels

The command above creates a new labelblk instance named "labels" at UUID c7. The API/commands for a labelblk type is similar to uint8blk since they both operate on 2d and 3d images. In the case of labelblk, though, each voxel has a 64-bit label instead of the 8-bit intensity in uint8blk types.

Sparse volumes are an alternative representation of labelblk that accelerate operations on particular labels. For example, you can quickly merge two labels or split some set of voxels off into another label. Let's make an instance of labelvol, the sparse volume data type:

% dvid repo c7 new labelvol bodies

The command above creates a new labelvol instance named "bodies" at UUID c7.

Basically, the labels (labelblk type) and bodies (labelvol type) data instances are different views of the same label data. If you want to read and write 2d/3d label images, you use the "labels" labelblk instance. If you want to operate on a particular label, no matter where it sits in the entire data volume, you use the "bodies" labelvol instance.

We also want the two data instances to sync with each other so that changes in one will be reflected in the other. For that, we have to tell DVID to sync via a "sync" HTTP request. This can be easily done using the httpie command (or curl, not shown):

% echo "{\"sync\": \"bodies\"}" | http http://path-to-dvid/api/node/c7/labels/sync
% echo "{\"sync\": \"labels\"}" | http http://path-to-dvid/api/node/c7/bodies/sync

We POST a JSON message to the labels sync endpoint telling that data instance to sync with the bodies instance. We also POST a JSON message to the bodies sync endpoint telling that data instance to sync with the labels instance, thereby establishing reciprocal syncs. In each case the JSON takes the form:

{"sync": "some-instance,another-instance,last-instance"}

Loading Label Data

Label data is commonly ingested from a series of RGBA-encoded images where we assume each pixel label is 64 bit little-endian and is broken up across 16-bit RGBA values. An example:

% dvid node c7 labels load 0,0,0 /path/to/labels/*.png

The above command loads a sequence of PNG images into the "labels" labelblk instance created above, where the first PNG loaded has top left corner at (0,0,0), the second PNG has top left corner at (0,0,1), etc. Since our research group primarily works with large (TB+) image volumes, we really use the command-line ingestion as above but use scripts that target the HTTP ingestion endpoints. (More on this when we release the python library.)