tomoscan.esrf.volume.jp2kvolume.JP2KVolume#

class tomoscan.esrf.volume.jp2kvolume.JP2KVolume(folder=None, volume_basename=None, data=None, source_scan=None, metadata=None, data_url=None, metadata_url=None, overwrite=False, start_index=0, data_extension='jp2', metadata_extension='txt', cratios=None, psnr=None, n_threads=None, clip_values=None, rescale_data=True)#

Bases: VolumeSingleFrameBase

Save volume data to single frame jp2k files and metadata to .txt file

Parameters:

cratios (Optional[list]) – list of ints. compression ratio for each jpeg2000 layer
psnr (Optional[list]) – list of int. The PSNR (Peak Signal-to-Noise ratio) for each jpeg2000 layer. This defines a quality metric for lossy compression. The number “0” stands for lossless compression.
n_threads (Optional[int]) – number of thread to use for writing. If None will try to get as much as possible
clip_values (Optional[tuple]) – optional tuple of two float (min, max) to clamp volume value
rescale_data (bool) – rescale data before dumping each frame. Expected to be True when dump a new volume and False when save volume cast for example (and when histogram is know…)

Warning:

each file saved under {volume_basename}_{index_zfill6}.jp2k is considered to be a slice of the volume.

__init__(folder=None, volume_basename=None, data=None, source_scan=None, metadata=None, data_url=None, metadata_url=None, overwrite=False, start_index=0, data_extension='jp2', metadata_extension='txt', cratios=None, psnr=None, n_threads=None, clip_values=None, rescale_data=True)#

Methods

`__init__`([folder, volume_basename, data, ...])
`browse_data_files`([url])	param url: Deprecated 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: Deprecated 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_name_generator`(n_frames, data_url)	browse output files for n_frames
`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' :rtype: `tuple` :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
`format_data_path_for_data`(data_path, index, ...)	Return file path to save the frame at index of the current volume
`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_data_path_pattern_for_data`(data_path, ...)	Return file path pattern (and not full path) to load data.
`get_file_slice_index`(filename)
`get_first_file`()
`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_basename`([url])
`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_frame`(file_name, scheme)	Function dedicated for volume saving each frame on a single file
`load_metadata`([url, store])	Load volume metadata from disk
`read_file`(file_name)	rtype: `tuple`
`remove_existing_data_files`([url])	Clean any existing files (if overwrite and rights) that must be used for saving
`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_frame`(frame, file_name, scheme)	Function dedicated for volune saving each frame on a single file
`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)	rtype: `dict`
`setup_multithread_encoding`([n_threads, ...])	Setup OpenJpeg multi-threaded encoding.

Attributes

`DEFAULT_DATA_EXTENSION`
`DEFAULT_DATA_PATH_PATTERN`
`DEFAULT_DATA_SCHEME`
`DEFAULT_METADATA_EXTENSION`
`DEFAULT_METADATA_PATH_PATTERN`
`DEFAULT_METADATA_SCHEME`
`EXTENSION`
`clip_values`	rtype: `Optional`[`tuple`]
`cratios`	rtype: `Optional`[`list`]
`data`	rtype: `Optional`[`ndarray`]
`data_extension`
`data_url`
`extension`	rtype: `str`
`metadata`	rtype: `Optional`[`dict`]
`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.
`psnr`	rtype: `Optional`[`list`]
`rescale_data`	rtype: `bool`
`skip_existing_data_files_removal`	The loading of the volume for single frame base is done by loading all the file contained in a folder data_url.file_path().
`source_scan`	rtype: `Optional`[`TomoScanBase`]
`start_index`	rtype: `int`
`url`
`voxel_size`	voxel size as (axis 0 dim - aka z, axis 1 dim - aka y, axis 2 dim aka z) Returned in meter
`write_in_descending_order`	Return True if the data is saved with decreasing indices:

browse_data_files(url=None)#

Parameters:: url – Deprecated 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 – Deprecated data url to be used. If not provided will take self.data_url

browse_metadata_files(url=None)#

Parameters:: url – Deprecated 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 – Deprecated 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

property clip_values: tuple | None#

Return type:: Optional[tuple]
Returns:: optional min and max value to clip - as float.

data_file_name_generator(n_frames, data_url)#: browse output files for n_frames

data_file_saver_generator(n_frames, data_url=None, overwrite=False)#

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) – Deprecated url to dump data
overwrite (bool) – overwrite existing file ?

deduce_data_and_metadata_urls(url)#: compute data and metadata urls from ‘parent url’ :rtype: tuple :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

format_data_path_for_data(data_path, index, volume_basename)#

Return file path to save the frame at index of the current volume

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_data_path_pattern_for_data(data_path, volume_basename)#

Return file path pattern (and not full path) to load data. For example in edf it can return ‘myacquisition_*.edf’ in order to be handled by

Return type:: str

get_identifier()#

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

Return type:: JP2KVolumeIdentifier

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 – Deprecated 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:
    ...

Return type:: dict[SliceTuple, ndarray]

get_volume_shape(url=None)#

return volume shape as a tuple

Parameters:: url – Deprecated

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.

Parameters:: url (Optional[DataUrl]) – Deprecated
Return type:: ndarray

load_frame(file_name, scheme)#

Function dedicated for volume saving each frame on a single file

Parameters:

file_name – path to store the data
scheme – scheme to save the data

load_metadata(url=None, store=True)#

Load volume metadata from disk

Parameters:: url (Optional[DataUrl]) – Deprecated
Return type:: dict

property position: tuple | None#

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)

Return type:: Optional[tuple]

remove_existing_data_files(url=None)#

Clean any existing files (if overwrite and rights) that must be used for saving

Return type:: None

save(url=None, **kwargs)#

save volume data and metadata to disk

Parameters:: url (Optional[DataUrl]) – Deprecated

save_data(url=None)#

save data to the provided url or existing one if none is provided

Parameters:: url (Optional[DataUrl]) – Deprecated
Return type:: None

save_frame(frame, file_name, scheme)#

Function dedicated for volune saving each frame on a single file

Parameters:

frame – frame to be save
file_name – path to store the data
scheme – scheme to save the data

save_metadata(url=None)#

save metadata to the provided url or existing one if none is provided

Parameters:: url (Optional[DataUrl]) – Deprecated
Return type:: None

static select(volume, xy=None, xz=None, yz=None, axis=None, index=None)#

select a slice at ‘index’ along an axis (axis)

Return type:: array

static setup_multithread_encoding(n_threads=None, what_if_not_available='ignore')#

Setup OpenJpeg multi-threaded encoding.

Parameters:

n_threads (Optional[int]) – Number of threads. If not provided, all available threads are used.
what_if_not_available (str) – What to do if requirements are not fulfilled. Possible values are: - “ignore”: do nothing, proceed - “print”: show an information message - “raise”: raise an error

property skip_existing_data_files_removal: bool#

The loading of the volume for single frame base is done by loading all the file contained in a folder data_url.file_path(). When saving the data we make sure there is no ‘remaining’ of any previous saving by using the file pattern. But when we want to save a volume from several thread (one thread save the n first frame, second the n next frame …) this could be a limitation. So in this case we can use the ‘ignore_existing_files’ that will avoid calling ‘_remove_existing_data_files’

Return type:: bool

property voxel_size: tuple[float] | None#

voxel size as (axis 0 dim - aka z, axis 1 dim - aka y, axis 2 dim aka z) Returned in meter

Return type:: Optional[tuple[float]]

property write_in_descending_order#

Return True if the data is saved with decreasing indices:

data[0] is written to file with index start_index
data[1] is written to file with index start_index - 1
and so on