API Reference¶

general¶

pydvid.general.general.get_server_info(connection)[source]¶

Return the json data provided by the /api/server/info DVID call.

pydvid.general.general.get_server_types(connection)[source]¶

Return the json data provided by the /api/server/types DVID call.

pydvid.general.general.get_repos_info(connection)[source]¶

Return the json data provided by the /api/repos/info DVID call.

keyvalue¶

pydvid.keyvalue.keyvalue.create_new(connection, uuid, data_name)[source]¶

Create a new keyvalue table in the dvid server.

pydvid.keyvalue.keyvalue.get_value(connection, uuid, data_name, key)[source]¶

Request the value for the given key and return the whole thing.

pydvid.keyvalue.keyvalue.put_value(connection, uuid, data_name, key, value)[source]¶

Store the given value to the keyvalue data. value should be either str or a file-like object with fileno() and read() methods.

pydvid.keyvalue.keyvalue.get_value_response(connection, uuid, data_name, key)[source]¶

Request the value for the given key return the raw HTTPResponse object. The caller may opt to ‘stream’ the data from the response instead of reading it all at once.

voxels¶

pydvid.voxels.voxels.get_metadata(connection, uuid, data_name)[source]¶

Query the voxels metedata for the given node/data_name.

pydvid.voxels.voxels.create_new(connection, uuid, data_name, voxels_metadata)[source]¶

Create a new volume in the dvid server.

pydvid.voxels.voxels.get_subvolume_response(connection, uuid, data_name, start, stop, format='', query_args=None, throttle=False)[source]¶

Request a subvolume from the server and return the raw HTTPResponse stream it returns.

class pydvid.voxels.VoxelsMetadata(metadata)¶

A dict subclass for the dvid nd-data metadata response. Also provides the following convenience attributes: minindex, shape, dtype, axiskeys

__init__(metadata)[source]¶

Constructor.

Parameters:	metadata – Either a string containing the json text for the DVID metadata, or a corresponding dict of metadata (e.g. parsed from the json). If a string is passed, invalid json will result in a ValueError exception.

dtype¶

Property. The pixel datatype of the remote DVID volume, as a numpy.dtype object.

shape¶

Property. The maximum coordinates in the DVID volume coordinate space. This is the stop coordinate of the volume’s bounding box. All data above this coordinate in any dimension is guaranteed to be invalid.

minindex¶

Property. The starting coordinate of the volume’s bounding box. All data below this coordinate in any dimension is guaranteed to be invalid.

axiskeys¶

Property. A string representing the axis indexing order of the volume, e.g. ‘cxyz’ Always starts with ‘c’ (channel).

Note

By DVID convention, the axiskeys are expressed in fortran order.

to_json()¶

Convenience method: dump this metadata to json string (for transmission to DVID).

classmethod create_default_metadata(shape, dtype, axiskeys, resolution, units)¶

Create a default VoxelsMetadata object from scratch using the given parameters, which can then be customized as needed.

Example usage:

metadata = VoxelsMetadata.create_default_metadata( (3,100,200,300), numpy.uint8, 'cxyz', 1.5, "micrometers" )

# Customize: Adjust resolution for Z-axis
assert metadata["Axes"][2]["Label"] == "Z"
metadata["Axes"][2]["Resolution"] = 6.0

# Customize: name channels
metadata["Properties"]["Values"][0]["Label"] = "intensity-R"
metadata["Properties"]["Values"][1]["Label"] = "intensity-G"
metadata["Properties"]["Values"][2]["Label"] = "intensity-B"

# Prepare for transmission: encode to json
jsontext = metadata.to_json()        

determine_dvid_typename()¶

Based on the dtype and number of channels for this volume, determine the datatype name (in DVID terminology). For example, if this volume contains 1-channel uint8 data, the DVID datatype is ‘grayscale8’.

create_axistags()¶

Generate a vigra.AxisTags object corresponding to this VoxelsMetadata. (Requires vigra.)

classmethod create_from_h5_dataset(dataset)¶

Create a VolumeInfo object to describe the given h5 dataset object.

Parameters:	dataset – An hdf5 dataset object that meets the following criteria: Indexed in F-order Has an ‘axistags’ attribute, produced using vigra.AxisTags.toJSON() Has an explicit channel axis

(Requires h5py.)

class pydvid.voxels.VoxelsAccessor(connection, uuid, data_name, query_args=None, throttle=False, retry_timeout=60.0, retry_interval=1.0, warning_interval=30.0)¶

Http client for retrieving a voxels volume data from a DVID server. An instance of VoxelsAccessor is capable of retrieving data from only one remote data volume. To retrieve data from multiple remote volumes, instantiate multiple DvidClient objects.

TODO:

• Allow users to provide a pre-allocated array when requesting data

__init__(connection, uuid, data_name, query_args=None, throttle=False, retry_timeout=60.0, retry_interval=1.0, warning_interval=30.0)[source]¶

Parameters:

uuid – The node uuid data_name – The name of the volume connection – An httplib.HTTPConnection instance or something like it. throttle – Enable the DVID ‘throttle’ flag for all get/post requests retry_timeout – Total time to spend repeating failed requests before giving up. (Set to 0 to prevent retries.) retry_interval – Time to wait before repeating a failed get/post. warning_interval – If the retry period exceeds this interval (but hasn’t hit the retry_timeout yet), a warning is emitted.

Note

When DVID is overloaded, it may indicate its busy status by returning a 503 (service unavailable) error in response to a get/post request. In that case, the get/post methods below will automatically repeat the failed request until the retry_timeout is reached.

__getitem__(slicing)[source]¶

Implement convenient numpy-like slicing syntax for volume access.

Limitations:

• “Fancy” indexing via index arrays, etc. is not supported, but “normal” slicing, including stepping, is supported.

Examples:

connection = httplib.HTTPConnection( "localhost:8000" ) 
v = VoxelsAccessor( connection, uuid=abc123, data_name='my_3d_rgb_volume' )

# The whole thing
a = v[:]
a = v[...]

# Arbitrary slicing
a = v[...,10,:]

# Note: DVID always returns all channels.
#       Here, you are permitted to slice into the channel axis,
#       but be aware that this implementation requests all 
#       channels and returns the ones you asked for.
blue = v[2]

# Therefore, avoid this, since it results in 2 requests for the same data
red = v[0]
green = v[1]

# Instead, do this:
rgb = v[:]
red, green, blue = rgb[0], rgb[1], rgb[2]

# Similarly, you are permitted to use slices with steps, but be aware that 
# the entire bounding volume will be requested, and the sliced steps will be 
# extracted from the dense volume.

# Extract the upper-left 10x10 tile of every other z-slice:
a = v[:,:10,:10,::2]

# The above is equivalent to this:
a = v[:,:10,:10,:][...,::2]            

__setitem__(slicing, array_data)[source]¶

Implement convenient numpy-like slicing syntax for overwriting regions of a DVID volume.

Limitations:

Unlike the __getitem__ syntax implemented above, we do NOT permit arbitrary slicing. Instead, only “dense” subvolumes may be written. That is, you must include all channels, and your slices may not include a step size.

Examples:

connection = httplib.HTTPConnection( "localhost:8000" ) 
v = VoxelsAccessor( connection, uuid=abc123, data_name='my_3d_rgb_volume' )

# Overwrite the third z-slice
v[...,2] = a

# Forbidden: attempt to stepped slices
v[...,0:10:2] = a # Error!

# Forbidden: attempt to write only a subset of channels (the first axis)
v[1,...] = green_data # Error!

shape¶

Property. The maximum coordinates in the DVID volume coordinate space. This is the stop coordinate of the volume’s bounding box. All data above this coordinate in any dimension is guaranteed to be invalid.

minindex¶

Property. The starting coordinate of the volume’s bounding box. All data below this coordinate in any dimension is guaranteed to be invalid.

dtype¶

Property. The pixel datatype of the remote DVID volume, as a numpy.dtype object.

axiskeys¶

Property. A string representing the axis indexing order of the volume, e.g. ‘cxyz’ Always starts with ‘c’ (channel).

Note

By DVID convention, the axiskeys are expressed in fortran order.

get_ndarray(*args, **kwargs)¶

Request the subvolume specified by the given start and stop pixel coordinates.

post_ndarray(start, stop, new_data)¶

Overwrite subvolume specified by the given start and stop pixel coordinates with new_data.