tomoscan.volumebase.VolumeBase#

class tomoscan.volumebase.VolumeBase(url=None, data=None, source_scan=None, metadata=None, data_url=None, metadata_url=None, overwrite=False, data_extension=None, metadata_extension=None)#

Bases: TomoObject

context: we aim at having a common way of saving and loading volumes through the tomotools suite. The goal is to aim handling of volumes when creating them or doing some operations with those like stitching…

Parameters

url – url of the volume. Could be path to a master file if we can provide one per each volume. Otherwise could be a pattern of edf files or tiff file with a data range
source_scan – potential instance of TomoScanBase in order to get extra information. This could be saved in the volume file to (external link)
data – volume data. Expected to be 3D
metadata – metadata associated to the volume. Must be a dict of serializable object
data_url – url to save the data. If provided url must not be provided. If an object is constructed from data and metadata url then no rule to create a VolumeIdentifier can be created and call to et_identifier will raise an error.
metadata_url – url to save the metadata. If provided url must not be provided. If an object is constructed from data and metadata url then no rule to create a VolumeIdentifier can be created and call to et_identifier will raise an error.
overwrite – when save the data if encounter a resource already existing overwrite it (if True) or not.
overwrite – when save the data if encounter a resource already existing overwrite it (if True) or not.

Raises

TypeError –
ValueError –
- if data is a numpy array and not 3D.
OSError –

__init__(url=None, data=None, source_scan=None, metadata=None, data_url=None, metadata_url=None, overwrite=False, data_extension=None, metadata_extension=None)#

Methods

`__init__`([url, data, source_scan, metadata, ...])
`browse_data_files`([url])	param url data url. If not provided will take self.data_url
`browse_data_urls`([url])	generator on data urls used.
`browse_metadata_files`([url])	param url metadata url. If not provided will take self.metadata_url
`browse_slices`([url])	generator of 2D numpy array representing a slice
`build_drac_metadata`()	build the drac (successor of icat) metadata dict from existing volume metadata.
`check_can_provide_identifier`()
`clear_cache`()	remove object stored in data and metadata
`data_file_saver_generator`(n_frames, ...)	Provide a helper class to dump data frame by frame.
`deduce_data_and_metadata_urls`(url)	compute data and metadata urls from 'parent url' :return: data_url: DataUrl \| None, metadata_url: DataUrl \| None
`example_defined_from_str_identifier`()	example as string to explain how users can defined identifiers from a string
`from_identifier`(identifier)	Return the Dataset from a identifier
`get_bounding_box`([axis])	Return the bounding box covered by the Tomo object axis is expected to be in (0, 1, 2) or (x==0, y==1, z==2)
`get_identifier`()	dataset unique identifier.
`get_min_max`()	compute min max of the volume.
`get_min_max_values`([url])	compute min max over 'data' if exists else browsing the volume slice by slice
`get_slice`([index, axis, xy, xz, yz, url])	read a single slice of the volume
`get_slices`(slices)	retrieve a couple of slices along any axis:
`get_volume_shape`([url])	return volume shape as a tuple
`load`()
`load_chunk`(chunk[, url])	Load a sub-volume.
`load_data`([url, store])	load volume data from disk
`load_metadata`([url, store])	load volume metadata from disk
`save`([url])	save volume data and metadata to disk
`save_data`([url])	save data to the provided url or existing one if none is provided
`save_metadata`([url])	save metadata to the provided url or existing one if none is provided
`select`(volume[, xy, xz, yz, axis, index])	select a slice at 'index' along an axis (axis)
`select_slices`(volume, slices)

Attributes

`EXTENSION`
`data`
`data_extension`
`data_url`
`extension`	rtype `str`
`metadata`
`metadata_extension`
`metadata_url`
`overwrite`	rtype `bool`
`pixel_size`
`position`	position are provided as a tuple using the same reference for axis as the volume data.
`source_scan`
`url`
`voxel_size`	voxel size as (axis 0 dim - aka z, axis 1 dim - aka y, axis 2 dim aka z)

browse_data_files(url=None)#

Parameters: url – data url. If not provided will take self.data_url

return a generator go through all the existing files associated to the data volume

browse_data_urls(url=None)#

generator on data urls used.

Parameters: url – data url to be used. If not provided will take self.data_url

browse_metadata_files(url=None)#

Parameters: url – metadata url. If not provided will take self.metadata_url

return a generator go through all the existing files associated to the data volume

browse_slices(url=None)#

generator of 2D numpy array representing a slice

Parameters: url – data url to be used. If not provided will browse self.data if exists else self.data_url
Warning: this will get the slice from the data on disk and never use data property. so before browsing slices you might want to check if data is already loaded

build_drac_metadata()#

build the drac (successor of icat) metadata dict from existing volume metadata.

Return type: dict

clear_cache()#: remove object stored in data and metadata

data_file_saver_generator(n_frames, data_url, overwrite)#

Provide a helper class to dump data frame by frame. For know the only possible interaction is Helper[:] = frame

Parameters

n_frames – number of frame the final volume will contain
data_url (DataUrl) – url to dump data
overwrite (bool) – overwrite existing file ?

deduce_data_and_metadata_urls(url)#: compute data and metadata urls from ‘parent url’ :return: data_url: DataUrl | None, metadata_url: DataUrl | None

static example_defined_from_str_identifier()#

example as string to explain how users can defined identifiers from a string

Return type: str

static from_identifier(identifier)#: Return the Dataset from a identifier

get_bounding_box(axis=None)#: Return the bounding box covered by the Tomo object axis is expected to be in (0, 1, 2) or (x==0, y==1, z==2)

get_identifier()#

dataset unique identifier. Can be for example a hdf5 and en entry from which the dataset can be rebuild

Return type: VolumeIdentifier

get_min_max()#

compute min max of the volume. Can take some time but avoid to load the full volume in memory

Return type: tuple

get_min_max_values(url=None)#

compute min max over ‘data’ if exists else browsing the volume slice by slice

Parameters: url – data url to be used. If not provided will take self.data_url
Return type: tuple

get_slice(index=None, axis=None, xy=None, xz=None, yz=None, url=None)#: read a single slice of the volume

get_slices(slices)#

retrieve a couple of slices along any axis:

For example, if you want to retrieve slice number 2 of axis 0 and slice number 56 of axis 1:

slices = volume.get_slices(
    (0, 2),
    (1, 56),
)
for (axis, slice), data in slices:
    ...

get_volume_shape(url=None)#

return volume shape as a tuple

Return type: tuple

load_chunk(chunk, url=None)#

Load a sub-volume.

Parameters

chunk – tuple of slice objects indicating which chunk of the volume has to be loaded.
url – data url to be used. If not provided will take self.data_url

load_data(url=None, store=True)#: load volume data from disk

load_metadata(url=None, store=True)#: load volume metadata from disk

property position#: position are provided as a tuple using the same reference for axis as the volume data. position is returned as (axis_0_pos, axis_1_pos, axis_2_pos). Can also be see as (z_position, y_position, x_position)

save(url=None, **kwargs)#: save volume data and metadata to disk

save_data(url=None, **kwargs)#: save data to the provided url or existing one if none is provided

save_metadata(url=None)#: save metadata to the provided url or existing one if none is provided

static select(volume, xy=None, xz=None, yz=None, axis=None, index=None)#: select a slice at ‘index’ along an axis (axis)

property voxel_size#: voxel size as (axis 0 dim - aka z, axis 1 dim - aka y, axis 2 dim aka z)