DVIDNodeService

class DVIDNodeService

Class that helps access different DVID version node actions.

Note

Numpy uses C-order array indexing by default, which means 3D arrays are typically indexed in the order [z,y,x], not the other way around. These python bindings follow the same convention. All functions accepting 3D arrays expect contiguous data, in z-y-x order. The same goes for returned data. Similarly, tuple parameters such as shape and offset should be passed in (z,y,x) order.

Methods List:

Methods Reference:

__init__((object)arg1, (str)web_addr, (str)uuid[, (str)user='anonymous'[, (str)app='libdvid'[, (str)resource_server=''[, (int)resource_port=0]]]]) → None :

Constructor sets up an http connection and checks whether a node of the given uuid and web server exists.

Parameters:
  • web_addr – address of DVID server
  • uuid – uuid corresponding to a DVID node
  • user – username used in DVID requests
  • app – name of the application used in DVID requests
  • resource_server – name of the resource server
  • resource_port – port for resource server
create_keyvalue((DVIDNodeService)arg1, (str)instance_name) → bool :

Create an instance of keyvalue datatype.

Parameters:instance_name – name of new keyvalue instance
Returns:True if created, False if already exists.
put((DVIDNodeService)arg1, (str)instance_name, (str)key, (object)value_bytes) → None :

Put binary blob at a given key location. It will overwrite data that exists at the key for the given node version.

Parameters:
  • instance_name – name of keyvalue instance
  • key – name of key to the keyvalue instance
  • value_bytes – binary blob to store at key (str or bytes)
get((DVIDNodeService)arg1, (str)instance_name, (str)key) → object :

Retrieve binary data at a given key location.

Parameters:
  • instance_name – name of keyvalue instance
  • key – name of key within the keyvalue instance
Returns:

binary data stored at key
get_json((DVIDNodeService)arg1, (str)instance_name, (str)key) → object :

Retrieve json data at a given key location, parsed into a dict.

Parameters:
  • instance_name – name of keyvalue instance
  • key – name of key within the keyvalue instance
Returns:

json stored at key
get_keys((DVIDNodeService)arg1, (str)instance_name) → StringVec :

Retrieve the list of all keys for a given keyvalue instance.

Parameters:instance_name – name of keyvalue instance
Returns:list of strings
create_grayscale8((DVIDNodeService)arg1, (str)instance_name[, (int)blocksize=32]) → bool :

Create an instance of uint8 grayscale datatype.

Parameters:
  • instance_name – name of new datatype instance
  • blocksize – size of block chunks
Returns:

True if created, False if already exists
get_gray3D((DVIDNodeService)service, (str)instance_name, (object)shape_zyx, (object)offset_zyx[, (bool)throttle=True[, (bool)compress=False[, (str)roi=None]]]) → object :

Retrieve a 3D 1-byte grayscale volume with the specified dimension size and spatial offset. The dimension sizes and offset default to X,Y,Z (the DVID 0,1,2 axis order). The data is returned so X corresponds to the matrix column. Because it is easy to overload a single server implementation of DVID with hundreds of volume requests, we support a throttle command that prevents multiple volume GETs/PUTs from executing at the same time. A 2D slice should be requested as X x Y x 1. The requested number of voxels cannot be larger than INT_MAX/8.

Parameters:
  • instance_name – name of grayscale type instance
  • shape_zyx – volume dimensions in voxel coordinates
  • offset_zyx – volume location in voxel coordinates
  • throttle – allow only one request at time (default: true)
  • compress – enable lz4 compression
  • roi – specify DVID roi to mask GET operation (return 0s outside ROI)
Returns:

3D ndarray, with dtype uint8
put_gray3D((DVIDNodeService)service, (str)instance_name, (object)grayscale_vol, (object)offset_zyx[, (bool)throttle=True[, (bool)compress=False]]) → None :

Put a 3D 1-byte grayscale volume to DVID with the specified dimension and spatial offset. THE DIMENSION AND OFFSET ARE IN VOXEL COORDINATS BUT MUST BE BLOCK ALIGNED. The size of DVID blocks are determined at repo creation and is always 32x32x32 currently. The axis order is always X, Y, Z. Because it is easy to overload a single server implementation of DVID with hundreds of volume PUTs, we support a throttle command that prevents multiple volume GETs/PUTs from executing at the same time. The number of voxels put cannot be larger than INT_MAX/8.

Parameters:
  • instance_name – name of the grayscale type instance
  • grayscale_vol – ndarray with dtype uint8
  • offset_zyx – offset in voxel coordinates
  • throttle – allow only one request at time (default: true)
  • compress – enable lz4 compression
create_labelblk((DVIDNodeService)arg1, (str)instance_name[, (str)labelvol_name=None[, (int)blocksize=32]]) → bool :

Create an instance of uint64 labelblk datatype and optionally create a label volume datatype. WARNING: If the function returns false and a label volume is requested it is possible that the two datatypes created will not be synced together. Currently, the syncing configuration needs to be set on creation.

Parameters:
  • instance_name – name of new datatype instance
  • labelvol_name – name of labelvolume to associate with labelblks
  • blocksize – size of block chunks
Returns:

true if both created, false if one already exists
get_labels3D((DVIDNodeService)service, (str)instance_name, (object)shape_zyx, (object)offset_zyx[, (bool)throttle=True[, (bool)compress=True[, (str)roi=None]]]) → object :

Retrieve a 3D 8-byte label volume with the specified dimension size and spatial offset. The dimension sizes and offset default to X,Y,Z (the DVID 0,1,2 axis order). The data is returned so X corresponds to the matrix column. Because it is easy to overload a single server implementation of DVID with hundreds of volume requests, we support a throttle command that prevents multiple volume GETs/PUTs from executing at the same time. A 2D slice should be requested as X x Y x 1. The requested number of voxels cannot be larger than INT_MAX/8.

Parameters:
  • instance_name – name of the labelblk type instance
  • shape_zyx – size of X, Y, Z dimensions in voxel coordinates
  • offset_zyx – offset in voxel coordinates
  • throttle – allow only one request at time (default: true)
  • compress – enable lz4 compression
  • roi – specify DVID roi to mask GET operation (return 0s outside ROI)
Returns:

3D ndarray with dtype uint64
get_label_by_location((DVIDNodeService)service, (str)instance_name, (object)point_zyx) → long :

Retrieve label id at the specified point. If no ID is found, return 0.

Parameters:
  • datatype_instance – name of the labelblk type instance
  • point_zyx – tuple: (z,y,x) of the point to inspect
Returns:

body id for given location (0 if none found)
put_labels3D((DVIDNodeService)service, (str)instance_name, (object)label_vol_zyx, (object)offset_zyx[, (bool)throttle=True[, (bool)compress=True[, (str)roi=None[, (bool)mutate=False]]]]) → None :

Put a 3D 8-byte label volume to DVID with the specified dimension and spatial offset. THE DIMENSION AND OFFSET ARE IN VOXEL COORDINATS BUT MUST BE BLOCK ALIGNED. The size of DVID blocks are determined at instance creation and is 32x32x32 by default. The axis order is always X, Y, Z. Because it is easy to overload a single server implementation of DVID with hundreds of volume PUTs, we support a throttle command that prevents multiple volume GETs/PUTs from executing at the same time. The number of voxels put cannot be larger than INT_MAX/8.

Parameters:
  • instance_name – name of the grayscale type instance
  • volume – label 3D volume encodes dimension sizes and binary buffer
  • offset_zyx – offset in voxel coordinates
  • throttle – allow only one request at time (default: true)
  • roi – specify DVID roi to mask PUT operation (default: empty)
  • compress – enable lz4 compression
  • mutate – set to True if overwriting previous segmentation (default: False)
body_exists((DVIDNodeService)arg1, (str)labelvol_name, (long)bodyid) → bool :

Determine whether body exists in labelvolume.

Parameters:
  • labelvol_name – name of label volume type
  • bodyid – body id being queried (int)
Returns:

True if in label volume, False otherwise
create_roi((DVIDNodeService)arg1, (str)name) → bool :

Create an instance of ROI datatype.

Parameters:name – name of new datatype instance
Returns:True if created, False if already exists
get_roi((DVIDNodeService)service, (str)roi) → list :

Retrieve an ROI and store in a vector of block coordinates. The blocks returned will be ordered by Z then Y then X.

Parameters:roi – name of the roi instance
Returns:list of BlockZYX coordinate tuples
post_roi((DVIDNodeService)arg1, (str)roi_name, (object)blocks_zyx) → None :

Load an ROI defined by a list of blocks. This command will extend the ROI if it defines blocks outside of the currently defined ROI. The blocks can be provided in any order.

Parameters:
  • roi_name – name of the roi instance
  • blocks_zyx – list of tuples (z,y,x)
get_roi_partition((DVIDNodeService)service, (str)roi, (int)partition_size) → tuple :

Retrieve a partition of the ROI covered by substacks of the specified partition size. The substacks will be ordered by Z then Y then X.

Parameters:
  • roi – name of the roi instance
  • substacks – list of SubstackZYX tuples, i.e. (size, z, y, x)
  • partition_size – substack size as number of blocks in one dimension
Returns:

tuple: (substacks, packing_factor) where substacks is a list of SubstackZYX tuples, i.e. (size, z, y, x) and packing_factor is the fraction of substack volumes that cover blocks
roi_ptquery((DVIDNodeService)service, (str)roi, (object)point_list_zyx) → list :

Check whether a list of points (any order) exists in the given ROI. A vector of true and false has the same order as the list of points.

Parameters:
  • roi – name of the roi instance
  • point_list_zyx – list of tuples (z,y,x)
Returns:

list of bool
get_roi3D((DVIDNodeService)service, (str)instance_name, (object)dims_zyx, (object)offset_zyx[, (bool)throttle=True[, (bool)compress=False]]) → object :

Retrieve a 3D 1-byte bool volume for a roi with the specified dimension size and spatial offset. The dimension sizes and offset default to X,Y,Z (the DVID 0,1,2 axis order). The data is returned so X corresponds to the matrix column. Because it is easy to overload a single server implementation of DVID with hundreds of volume requests, we support a throttle command that prevents multiple volume GETs/PUTs from executing at the same time. A 2D slice should be requested as X x Y x 1. The requested number of voxels cannot be larger than INT_MAX/8.

Parameters:
  • roi_name – name of roi mask instance
  • dims_zyx – requested shape in voxel coordinates
  • offset_zyx – requested starting location in voxel coordinates
  • throttle – allow only one request at time (default: true)
  • compress – enable lz4 compression
Returns:

Roi3D object that wraps a byte buffer
get_tile_slice((DVIDNodeService)arg1, (str)instance_name, (Slice2D)slice_type, (int)scaling, (object)tile_numbers) → object :

Retrieve a pre-computed tile from DVID at the specified location and zoom level.

Parameters:
  • instance_name – name of tile type instance
  • slice_type – Slice2D.XY, YZ, or XZ
  • scaling – specify zoom level (1=max res)
  • tile_loc – tuple: X,Y,Z location of tile (X and Y are in tile coordinates)
Returns:

2D ndarray with dtype uint8
get_tile_slice_binary((DVIDNodeService)arg1, (str)instance_name, (Slice2D)slice_type, (int)scaling, (object)tile_numbers) → object :

Retrive the raw pre-computed tile (no decompression) from DVID at the specified location and zoom level. In theory, this could be applied to multi-scale label data, but DVID typically only stores tiles for grayscale data since it is immutable.

Parameters:
  • instance_name – name of tile type instance
  • slice_type – Slice2D.XY, YZ, or XZ
  • scaling – specify zoom level (1=max res)
  • tile_loc – tuple: X,Y,Z location of tile (X and Y are in tile coordinates)
Returns:

byte buffer (str) for the raw compressed data stored (e.g, JPEG or PNG)
create_graph((DVIDNodeService)arg1, (str)name) → bool :

Create an instance of labelgraph datatype.

Parameters:name – name of new datatype instance
Returns:true if create, false if already exists
update_vertices((DVIDNodeService)arg1, (str)graph_name, (object)vertices) → None :

Add the provided vertices to the labelgraph with the associated vertex weights. If the vertex already exists, it will increment the vertex weight by the weight specified. This function can be used for creation and incrementing vertex weights in parallel.

Parameters:
  • graph_name – name of labelgraph instance
  • vertices – list of vertices to create or update
update_edges((DVIDNodeService)arg1, (str)graph_name, (object)vertices) → None :

Add the provided edges to the labelgraph with the associated edge weights. If the edge already exists, it will increment the vertex weight by the weight specified. This function can be used for creation and incrementing edge weights in parallel. The command will fail if the vertices for the given edges were not created first.

Parameters:
  • graph_name – name of labelgraph instance
  • vertices – list of vertices to create or update
get_typeinfo((DVIDNodeService)arg1, (str)datatype_name) → object :

Retrieves meta data for a given datatype instance

Parameters:datatype_name – name of datatype instance
Returns:JSON describing instance meta data
custom_request((DVIDNodeService)arg1, (str)endpoint, (object)payload, (ConnectionMethod)method[, (bool)compress=False[, (long)datasize=1]]) → object :

Allow client to specify a custom http request with an http endpoint for a given node and uuid. A request to /node/<uuid>/blah should provide the endpoint as /blah.

Parameters:
  • endpoint – REST endpoint given the node’s uuid
  • payload – binary data to be sent in the request
  • method – libdvid.ConnectionMethod, (HEAD, GET, POST, PUT, DELETE)
  • compress – use lz4 compression if true
  • datasize – estimate payload if GET (only useful if there is a resource manager)
Returns:

http response as binary data

Slice2D

class Slice2D

Enum for tile orientations.

Members:

  • XY
  • XZ
  • YZ

Graph Primitives

class Vertex

Vertex is its unique ID and its weight (typically representing the size of the vertex in voxels).

__init__((object)arg1, (long)id_, (float)weight) → None :

Constructor to explicitly set vertex information.

Parameters:
  • id – vertex id
  • weight – weight for the vertex
class Edge

Edge constitutes two vertex ids and a weight.

For example, the weight could indicate the sizes of the edge between two vertices in voxels.

__init__((object)arg1, (long)id1, (long)id2, (float)weight) → None :

Constructor using supplied vertex ids and weight.

Parameters:
  • id1 – vertex 1 of edge
  • id2 – vertex 2 of edge
  • weight – weight of edge