Imagery Client

Basic imagery client features

ImageryClient(client=None, resolution=None, segmentation=True, imagery=True, image_source=None, segmentation_source=None, image_mip=None, segmentation_mip=None, auth_token=None, timestamp=None)

Bases: object

Tool to help download imagery and segmentation data.

Can either take explicit cloudvolume paths for imagery and segmentation or use the Info Service to look up the right paths.

Parameters:

Name	Type	Description	Default
client	CAVEclient or None	A pre-initialized CAVEclient to use for configuration and authentication. If used, image source, segmentation source, and resolution come from the info service values.	None
resolution	array - like or image or segmentation	Sets the voxel resolution that bounds will be entered in, by default 'image', which is the mip 0 resolution of the imagery. Note that if a client is used to set the sources, the resolution will be set to the client default.	None
segmentation	bool	If False, no segmentation cloudvolume is initialized. By default True	True
imagery	bool	If False, no imagery cloudvolume is initialized. By default True	True
image_source	str	CloudVolume path to an imagery source, by default None	None
segmentation_source	str	CloudVolume path to a segmentation source, by default None	None
image_mip	int	Default mip level to use for imagery lookups, by default 0. Note that the same mip level for imagery and segmentation can correspond to different voxel resolutions.	None
segmentation_mip	int	Default mip level to use for segmentation lookups, by default 0.	None
auth_token	str or None	Auth token to use for cloudvolume. If None, uses the default values from the CAVEclient. Default is None.	None
timestamp	(datetime or None)	Fixed timestamp to use for segmentation lookups. If None, defaults to the present time when each function is run. Default is None.	None

image_cv property

Imagery CloudVolume

image_source property

Image cloudpath

resolution property

The voxel resolution assumed when locations are used for the client.

Returns:

Type	Description
list	X, y, and z voxel resolution.

segmentation_cv property

Segmentation CloudVolume object

segmentation_source property

Segmentation cloudpath

image_and_segmentation_cutout(bounds, image_mip=None, segmentation_mip=None, root_ids='all', resize=True, split_segmentations=False, include_null_root=False, bbox_size=None, resolution=None, timestamp=None, scale_to_bounds=None, convert_to_int64=True)

Download aligned and scaled imagery and segmentation data at a given resolution.

Parameters:

Name	Type	Description	Default
bounds	2x3 list of ints	A list of the lower and upper bound point for the cutout. The units are voxels in the resolution set by the base_resolution parameter.	required
image_mip	int	Mip level of the imagery if something other than the default is wanted, by default None	None
segmentation_mip	int	Mip level of the segmentation if something other than the default is wanted, by default None	None
root_ids	list, None, or 'all'	If a list, the segmentation cutout only includes voxels for a specified set of root ids. If None, default to the supervoxel ids. If 'all', finds all root ids corresponding to the supervoxels in the cutout and get all of them. By default 'all'.	'all'
resize	bool	If True, upscale the lower resolution cutout to the same resolution of the higher one (either imagery or segmentation).	True
split_segmentations	bool	If True, the segmentation is returned as a dict of masks (using split_segmentation_cutout), and if False returned as an array with root_ids (using segmentation_cutout), by default False	False
include_null_root	bool	If True, includes root id of 0, which is usually reserved for a null segmentation value. Default is False.	False
bbox_size	array or None	If not None, bbox_size is a 3 element array of ints giving the dimensions of the cutout. In this case, bounds is treated as the center.	None
resolution	list - like	Voxel resolution used when specifying bounds bounds and bbox_size (but not image_size). If none, defaults to client default.	None
timestamp	datetime or None	Timestamp to use for dynamic segmentation data	None
scale_to_bounds	bool or None	If True, rescales image to the same size as the bounds. Default is None, which rescales if mip is not set but otherwise does not.	None
convert_to_int64	bool	If True, converts segmentation data to int64 from uint64 if it is safe to do so. Default is True. If not safe, raises a warning and does not convert from uint64.	True

Returns:

Type	Description
VolumeCutout	Imagery volume cutout
ndarray or dict	Segmentation volume cutout as either an ndarray or dict of masks depending on the split_segmentations flag.

image_bbox_size_from_dimensions(image_size, mip=None, resolution=None)

Get the bbox_size equivalent for an imagery cutout with specified pixel dimensions

Parameters:

Name	Type	Description	Default
image_size		Image size in pixels (2-element) or voxels (3-element)	required
mip		Mip for which the image would be computed. Defaults to None, which uses the client default.	None
resolution		Resolution to use for the bbox_size. Defaults to None, or the client defauls.	None

Returns:

Name	Type	Description
tuple		Argument for bbox_size that would give the desired pixel dimensions.

image_cutout(bounds, bbox_size=None, image_size=None, mip=None, resolution=None, scale_to_bounds=None)

Get an image cutout for a certain location or set of bounds and a mip level.

Parameters:

Name	Type	Description	Default
bounds	array	Either a 2x3 array of a lower bound and upper bound point to bound the cutout in units of voxels in a resolution set by the base_resolution parameter. Alternatively, if bbox_size or image_size is set, bounds should be a 3-element array specifying the center of the field of view.	required
bbox_size	array or None	If not None, bbox_size is a 3 element array of ints giving the dimensions. In this case, bounds is treated as the center.	None
image_size	array or None	If not None, indicates the size of the image desired in pixels. Cannot be set with bbox_size, since it has potentially conficting information.	None
mip	int	Mip level of imagery to get if something other than the default is wanted, by default None.	None
resolution	list - like	Voxel resolution used when specifying bounds bounds and bbox_size (but not image_size). If none, defaults to client default.	None
scale_to_bounds	bool, optional.	If True, rescales image to the same size as the bounds. Default is None, which rescales if mip is not set but otherwise does not.	None

Returns:

Type	Description
cloudvolume.VolumeCutout	An n-d image of the image requested with image intensity values as the elements.

save_image_and_segmentation_masks(filename_prefix, bounds=None, image_mip=None, segmentation_mip=None, root_ids='all', include_null_root=False, segmentation_colormap={}, resize=True, precomputed_data=None, slice_axis=2, bbox_size=None, resolution=None, timestamp=None, scale_to_bounds=None, **kwargs)

Save aligned and scaled imagery and segmentation mask cutouts as pngs. Kwargs are passed to imageio.imwrite.

Parameters:

Name	Type	Description	Default
filename_prefix	str	Prefix for the segmentation filenames. The full filename will be either {filename_prefix}root_id.png or {filename_prefix}root_id.png, depending on if multiple slices of each root id are saved.}_{i	required
bounds	2x3 list of ints	A list of the lower and upper bound point for the cutout. The units are voxels in the resolution set by the base_resolution parameter. Only used if a precomputed data is not passed. By default, None.	None
image_mip	int	Only used if a precomputed data is not passed. Mip level of imagery to get if something other than the default is wanted, by default None.	None
segmentation_mip	int	Only used if precomputed data is not passed. Mip level of segmentation to get if something other than the default is wanted, by default None	None
root_ids	list, None, or 'all'	If a list, the segmentation cutout only includes voxels for a specified set of root ids. If None, default to the supervoxel ids. If 'all', finds all root ids corresponding to the supervoxels in the cutout and get all of them. By default 'all'.	'all'
include_null_root	bool	If True, includes root id of 0, which is usually reserved for a null segmentation value. By default, False.	False
segmentation_colormap	dict	A dict of root ids to an uint8 RGB color triplet (0-255) or RGBa quadrooplet to optionally color the mask png. Any root id not specified will be rendered in white. Color triplets default to full opacity. Default is an empty dictionary.	{}
resize	bool	If True, upscale the lower resolution cutout to the same resolution of the higher one (either imagery or segmentation).	True
precomputed_data	tuple	Already computed tuple with imagery and segmentation mask data, in that order. If not provided, bounds must be given to download cutout data. By default, None.	None
slice_axis	int	If the image data is truly 3 dimensional, determines which axis to use to save serial images, by default 2 (i.e. z-axis)	2
bbox_size	array or None	If not None, bbox_size is a 3 element array of ints giving the dimensions of the cutout. In this case, bounds is treated as the center.	None
resolution	list - like	Voxel resolution of the bounds provided. If not provided, uses the client defaults.	None
timestamp	datetime	Timestamp to use for the segmentation. If not provided, defaults to the client defaults.	None
scale_to_bounds	bool or None	If True, rescales image to the same size as the bounds. Default is None, which rescales if mip is not set but otherwise does not.	None

save_imagery(filename_prefix, bounds=None, mip=None, precomputed_image=None, slice_axis=2, bbox_size=None, image_size=None, resolution=None, scale_to_bounds=None, verbose=False, **kwargs)

Save queried or precomputed imagery to png files.

Parameters:

Name	Type	Description	Default
filename_prefix	str	Prefix for the imagery filename. The full filename will be {filename_prefix}_imagery.png	required
bounds	2x3 list of ints	A list of the lower and upper bound point for the cutout. The units are voxels in the resolution set by the base_resolution parameter. Only used if a precomputed image is not passed. By default, None.	None
mip	int	Only used if a precomputed image is not passed. Mip level of imagery to get if something other than the default is wanted, by default None	None
precomputed_image	VolumeCutout	Already downloaded VolumeCutout data to save explicitly. If called this way, the bounds and mip arguments will not apply. If a precomputed image is not provided, bounds must be specified to download the cutout data. By default None	None
slice_axis	int	If the image data is truly 3 dimensional, determines which axis to use to save serial images, by default 2 (i.e. z-axis)	2
bbox_size	array or None	If not None, bbox_size is a 3 element array of ints giving the dimensions of the cutout. In this case, bounds is treated as the center.	None
image_size	array or None	If not None, indicates the size of the image desired in pixels. Cannot be set with bbox_size, since it has potentially conficting information.	None
resolution	list - like	Voxel resolution used when specifying bounds bounds and bbox_size (but not image_size). If none, defaults to client default.	None
scale_to_bounds	bool or None	If True, rescales image to the same size as the bounds. Default is None, which rescales if mip is not set but otherwise does not.	None
verbose	bool	If True, prints the progress, by default False	False

save_segmentation_masks(filename_prefix, bounds=None, mip=None, root_ids='all', precomputed_masks=None, segmentation_colormap={}, slice_axis=2, include_null_root=False, bbox_size=None, image_size=None, resolution=None, timestamp=None, scale_to_bounds=None, verbose=False, **kwargs)

Save queried or precomputed segmentation masks to png files. Additional kwargs are passed to imageio.imwrite.

Parameters:

Name	Type	Description	Default
filename_prefix	str	Prefix for the segmentation filenames. The full filename will be either {filename_prefix}root_id.png or {filename_prefix}root_id.png, depending on if multiple slices of each root id are saved.}_{i	required
bounds	2x3 list of ints	A list of the lower and upper bound point for the cutout. The units are voxels in the resolution specified. Only used if a precomputed segmentation is not passed. By default, None.	None
mip	int	Only used if a precomputed segmentation is not passed. Mip level of segmentation to get if something other than the default is wanted, by default None	None
root_ids	list, None, or 'all'	If a list, the segmentation cutout only includes voxels for a specified set of root ids. If None, default to the supervoxel ids. If 'all', finds all root ids corresponding to the supervoxels in the cutout and get all of them. By default 'all'.	'all'
precomputed_masks	dict	Already downloaded dict of mask data to save explicitly. If called this way, the bounds and mip arguments will not apply. If precomputed_masks are not provided, bounds must be given to download cutout data. By default None	None
segmentation_colormap	dict	A dict of root ids to an uint8 RGB color triplet (0-255) or RGBa quadrooplet to optionally color the mask png. Any root id not specified will be rendered in white. Color triplets default to full opacity. Default is an empty dictionary.	{}
slice_axis	int	If the image data is truly 3 dimensional, determines which axis to use to save serial images, by default 2 (i.e. z-axis)	2
include_null_root	bool	If True, includes root id of 0, which is usually reserved for a null segmentation value. Default is False.	False
bbox_size	array or None	If not None, bbox_size is a 3 element array of ints giving the dimensions of the cutout. In this case, bounds is treated as the center.	None
image_size	array or None	If not None, indicates the size of the image desired in pixels. Cannot be set with bbox_size, since it has potentially conficting information.	None
resolution	list - like	Voxel resolution used when specifying bounds bounds and bbox_size (but not image_size). If none, defaults to client default.	None
timestamp	datetime or None	Timestamp to use for dynamic segmentation data	None
scale_to_bounds	bool or None	If True, rescales image to the same size as the bounds. Default is None, which rescales if mip is not set but otherwise does not.	None

segmentation_bbox_size_from_dimensions(image_size, mip=None, resolution=None)

Get the bbox_size equivalent for an segmentation cutout with specified pixel dimensions

Parameters:

Name	Type	Description	Default
image_size		Image size in pixels (2-element) or voxels (3-element)	required
mip		Mip for which the image would be computed. Defaults to None, which uses the client default.	None
resolution		Resolution to use for the bbox_size. Defaults to None, or the client defauls.	None

Returns:

Name	Type	Description
tuple		Argument for bbox_size that would give the desired pixel dimensions.

segmentation_cutout(bounds, root_ids='all', bbox_size=None, image_size=None, mip=None, resolution=None, timestamp=None, scale_to_bounds=None, convert_to_int64=True)

Get a cutout of the segmentation imagery for some or all root ids between set bounds. Note that if all root ids are requested in a large region, it could take a long time to query all supervoxels.

Parameters:

Name	Type	Description	Default
bounds	2x3 list of ints	A list of the lower and upper bound point for the cutout. The units are voxels in the resolution set by the base_resolution parameter.	required
root_ids	list, None, or 'all'	If a list, only compute the voxels for a specified set of root ids. If None, default to the supervoxel ids. If 'all', find all root ids corresponding to the supervoxels in the cutout and get all of them. None, by default 'all'	'all'
bbox_size	array or None	If not None, bbox_size is a 3 element array of ints giving the dimensions. In this case, bounds is treated as the center.	None
image_size	array or None	If not None, indicates the size of the image desired in pixels. Cannot be set with bbox_size, since it has potentially conficting information.	None
mip	int	Mip level of the segmentation if something other than the defualt is wanted, by default None	None
resolution	list - like	Voxel resolution used when specifying bounds bounds and bbox_size (but not image_size). If none, defaults to client default.	None
timestamp	datetime or None	Timestamp to use for dynamic segmentation data	None
scale_to_bounds	bool or None	If True, rescales image to the same size as the bounds. Default is None, which rescales if mip is not set but otherwise does not.	None
convert_to_int64	bool	If True, converts segmentation data to int64 from uint64 if it is safe to do so. Default is True. If not safe, raises a warning and does not convert from uint64.	True

Returns:

Type	Description
ndarray	Array whose elements correspond to the root id (or, if root_ids=None, the supervoxel id) at each voxel.

split_segmentation_cutout(bounds, root_ids='all', include_null_root=False, bbox_size=None, image_size=None, mip=None, resolution=None, timestamp=None, scale_to_bounds=None)

Generate segmentation cutouts with a single binary mask for each root id, organized as a dict with keys as root ids and masks as values.

Parameters:

Name	Type	Description	Default
bounds	2x3 list of ints	A list of the lower and upper bound point for the cutout. The units are voxels in the resolution set by the base_resolution parameter.	required
root_ids	list, None, or 'all'	If a list, only compute the voxels for a specified set of root ids. If None, default to the supervoxel ids. If 'all', find all root ids corresponding to the supervoxels in the cutout and get all of them. None, by default 'all'	'all'
include_null_root	bool	If True, includes root id of 0, which is usually reserved for a null segmentation value. Default is False.	False
bbox_size	array or None	If not None, bbox_size is a 3 element array of ints giving the dimensions. In this case, bounds is treated as the center.	None
image_size	array or None	If not None, indicates the size of the image desired in pixels. Cannot be set with bbox_size, since it has potentially conficting information.	None
mip	int	Mip level of the segmentation if something other than the default is wanted, by default None	None
resolution	list - like	Voxel resolution used when specifying bounds bounds and bbox_size (but not image_size). If none, defaults to client default.	None
timestamp	datetime or None	Timestamp to use for dynamic segmentation data	None
scale_to_bounds	bool or None	If True, rescales image to the same size as the bounds. Default is None, which rescales if mip is not set but otherwise does not.	None

Returns:

Type	Description
dict	Dict whose keys are root ids and whose values are the binary mask for that root id, with a 1 where the object contains the voxel.

bounds_from_center(ctr, width=1, height=1, depth=1)

Generate bounds from a center point and dimensions for each direction

Parameters:

Name	Type	Description	Default
ctr	array - like	x,y,z coordinates of the center of the bounds in voxel dimensions.	required
width		Width of the box in the x direction in. Default is 1.	1
height		Height of the box in the y direction. Default is 1.	1
depth		Depth of the box in the z direction. Default is 1.	1

Returns:

Type	Description
array	2x3 array of lower and upper bounds (in that order).

save_image_slices(filename_prefix, filename_suffix, img, slice_axis, image_type, verbose=False, color=None, **kwargs)

Helper function for generic image saving