tomoscan.scanbase.TomoScanBase#

class tomoscan.scanbase.TomoScanBase(scan, type_, ignore_projections=None)#

Bases: TomoObject

Base Class representing a scan. It is used to obtain core information regarding an acquisition like projections, dark and flat field…

Parameters:: scan (str | None) – path to the root folder containing the scan.

__init__(scan, type_, ignore_projections=None)#

Methods

`__init__`(scan, type_[, ignore_projections])
`build_drac_metadata`()	build icat metadata dictionary filling NXtomo definition following icat definition: https://gitlab.esrf.fr/icat/hdf5-master-config/-/blob/88a975039694d5dba60e240b7bf46c22d34065a0/hdf5_cfg.xml
`clear_cache`()	clear caches.
`clear_caches`()	rtype: `None`
`clear_frames_cache`()
`clear_frames_caches`()	rtype: `None`
`compute_reduced_darks`([reduced_method, ...])	param ReduceMethod method: method to compute the flats
`compute_reduced_flats`([reduced_method, ...])	param ReduceMethod method: method to compute the flats
`equal`(other)	param instance to compare with :rtype: `bool` :return: True if instance are equivalent
`flat_field_correction`(projs, proj_indexes[, ...])	Apply flat field correction on the given data
`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_dark_expected_location`()
`get_dataset_basename`()	rtype: `str`
`get_detector_transformations`(default)
`get_distance`(args, *kwargs)
`get_energy_expected_location`()
`get_flat_expected_location`()
`get_identifier`()	return the dataset identifier of the scan.
`get_ignored_projection_indices`()
`get_pixel_size`([unit])	rtype: float \| None
`get_pixel_size_expected_location`()
`get_proj_angle_url`()	return a dictionary of all the projection.
`get_projection_expected_location`()
`get_projections_intensity_monitor`()	return intensity monitor values for projections
`get_relative_file`(file_name[, ...])	type file_name: str
`get_sample_detector_distance`([unit])	param unit: unit requested for the distance
`get_sample_detector_distance_expected_location`()
`get_sinogram`(line[, subsampling, norm_method])	extract the sinogram from projections
`get_volume_output_file_name`([z, suffix])	if used by tomwer and nabu this should help for tomwer to find out the output files of anbu from a configuration file.
`get_x_flipped`([default])
`get_y_flipped`([default])
`is_abort`(**kwargs)	rtype: `bool`
`is_tomoscan_dir`(directory, **kwargs)	Check if the given directory is holding an acquisition
`load_from_dict`(_dict)	Load properties contained in the dictionary.
`load_reduced_darks`(inputs_urls[, ...])	load reduced dark (median / mean...) into files
`load_reduced_flats`(inputs_urls[, ...])	load reduced flats frames
`map_urls_on_scan_range`(urls, n_projection, ...)	map given urls to an angle regarding scan_range and number of projection.
`save_reduced_darks`(darks, output_urls[, ...])	Dump computed dark (median / mean...) into files.
`save_reduced_flats`(flats, output_urls[, ...])	Dump computed dark (median / mean...) into files.
`set_reduced_darks`(darks[, darks_infos])
`set_reduced_flats`(flats[, flats_infos])
`to_dict`()	rtype: `dict`
`update`()	Parse the root folder and files to update information

Attributes

`DICT_PATH_KEY`
`DICT_TYPE_KEY`
`FRAME_REDUCER_CLASS`	Frame reducer class to be use in order to compute reduced darks and reduced flats
`alignment_projections`	dict of projections made for alignment with acquisition index as key None if not found
`count_time`	rtype: list \| None
`dark_n`	rtype: int \| None
`darks`	list of darks files
`detector_transformations`	return tuple of Transformation applied to the detector
`dim_1`	rtype: int \| None
`dim_2`	rtype: int \| None
`distance`	rtype: float \| None
`electric_current`	Return the sample name
`energy`	rtype: float \| None
`estimated_cor_frm_motor`
`ff_interval`	rtype: int \| None
`field_of_view`	return: field of view of the scan. None if unknown else Full or Half
`flat_n`	number of flat per series (computed on the first series)
`flats`	list of flats files
`group_size`	Used in the case of z-series for example.
`ignore_projections`
`instrument_name`	rtype: str \| None
`intensity_monitor`
`intensity_normalization`
`magnification`	rtype: float \| None
`path`	rtype: str \| None
`pixel_size`	rtype: float \| None
`projections`	if found dict of projections urls with index during acquisition as key
`reduced_darks`
`reduced_darks_infos`
`reduced_flats`
`reduced_flats_infos`
`sample_detector_distance`	rtype: float \| None
`sample_name`	Return the sample name
`scan_range`	rtype: int \| None
`sequence_name`	Return the sequence name
`source`
`source_name`
`source_sample_distance`	rtype: float \| None
`source_type`
`title`
`tomo_n`	number of projection WITHOUT the return projections
`type`	rtype: `str`
`x_flipped`	warning: deprecated !!!!! return True if the frames are flip through x
`x_pixel_size`	rtype: float \| None
`x_real_pixel_size`	rtype: float \| None
`x_rotation_axis_pixel_position`	return: Estimated center of rotation estimated from motor position. In [-frame_width, +frame_width]. None if unable to find it
`x_translation`	rtype: None \| tuple
`y_flipped`	warning: deprecated !!!!! return True if the frames are flip through y
`y_pixel_size`	rtype: float \| None
`y_real_pixel_size`	rtype: float \| None
`y_translation`	rtype: None \| tuple
`z_translation`	rtype: None \| tuple

FRAME_REDUCER_CLASS = None#: Frame reducer class to be use in order to compute reduced darks and reduced flats

property alignment_projections: dict | None#

dict of projections made for alignment with acquisition index as key None if not found

Return type:: dict | None

build_drac_metadata()#

build icat metadata dictionary filling NXtomo definition following icat definition: https://gitlab.esrf.fr/icat/hdf5-master-config/-/blob/88a975039694d5dba60e240b7bf46c22d34065a0/hdf5_cfg.xml

Return type:: dict

clear_cache()#: clear caches. Might be call if some data changed after first read of data or metadata

compute_reduced_darks(reduced_method='mean', overwrite=True, output_dtype=None, return_info=False)#

Parameters:

method (ReduceMethod) – method to compute the flats
overwrite – if some darks have already been computed will overwrite them
return_info – do we return (reduced_frames, info) or directly reduced_frames

compute_reduced_flats(reduced_method='median', overwrite=True, output_dtype=None, return_info=False)#

Parameters:

method (ReduceMethod) – method to compute the flats
overwrite – if some flats have already been computed will overwrite them
return_info – do we return (reduced_frames, info) or directly reduced_frames

property darks: dict | None#

list of darks files

Return type:: dict | None

property detector_transformations: tuple | None#

return tuple of Transformation applied to the detector

Return type:: tuple | None

property electric_current: tuple#

Return the sample name

Return type:: tuple

property energy: float | None#

Return type:: float | None
Returns:: incident beam energy in keV

equal(other)#

:param instance to compare with :rtype: bool :return: True if instance are equivalent

..note:: we cannot use the __eq__ function because this object need to be: picklable

property field_of_view#

Returns:: field of view of the scan. None if unknown else Full or Half

flat_field_correction(projs, proj_indexes, line=None)#

Apply flat field correction on the given data

Parameters:

projs (Iterable) – list of projection (numpy array) to apply correction on
proj_indexes (Iterable data) – list of indexes of the projection in the acquisition sequence. Values can be int or None. If None then the index take will be the one in the middle of the flats taken.
line (int | None) – index of the line to apply flat filed. If not provided consider we want to apply flat filed on the entire frame

Returns:

corrected data: list of numpy array

property flat_n: int | None#

number of flat per series (computed on the first series)

Return type:: int | None

property flats: dict | None#

list of flats files

Return type:: dict | None

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)

Return type:: BoundingBox1D

get_identifier()#

return the dataset identifier of the scan. The identifier is insure to be unique for each scan and allow the user to store the scan as a string identifier and to retrieve it later from this single identifier.

Return type:: ScanIdentifier

get_proj_angle_url()#

return a dictionary of all the projection. key is the angle of the projection and value is the url.

Keys are int for ‘standard’ projections and strings for return projections.

Return type:: dict
Returns:: angles as keys, radios as value.

get_projections_intensity_monitor()#: return intensity monitor values for projections

get_relative_file(file_name, with_dataset_prefix=True)#

Parameters:

file_name (str) – name of the file to create
with_dataset_prefix – If True will prefix the requested file by the dataset name like datasetname_file_name

Return type:

str | None

Returns:

path to the requested file according to the ‘Scan’ / ‘dataset’ location. Return none if Scan has no path

get_sample_detector_distance(unit='m')#

Parameters:: unit – unit requested for the distance
Return type:: float | None
Returns:: sample / detector distance with the requested unit

get_sinogram(line, subsampling=1, norm_method=None, **kwargs)#

extract the sinogram from projections

Parameters:

line – which sinogram we want
subsampling – subsampling to apply. Allows to skip some io

Returns:

computed sinogram from projections

static get_volume_output_file_name(z=None, suffix=None)#: if used by tomwer and nabu this should help for tomwer to find out the output files of anbu from a configuration file. Could help to get some normalization there

property group_size#: Used in the case of z-series for example. Return the number of sequence expected on the acquisition

property instrument_name: str | None#

Return type:: str | None
Returns:: instrument name

is_abort(**kwargs)#

Return type:: bool
Returns:: True if the acquisition has been abort

static is_tomoscan_dir(directory, **kwargs)#

Check if the given directory is holding an acquisition

Parameters:: directory (str) –
Return type:: bool
Returns:: does the given directory contains any acquisition

load_from_dict(_dict)#

Load properties contained in the dictionary.

Parameters:: _dict (dict) – dictionary to load
Returns:: self
Raises:: ValueError if dict is invalid

load_reduced_darks(inputs_urls, metadata_input_urls=None, return_as_url=False, return_info=False)#

load reduced dark (median / mean…) into files

Parameters:

inputs_urls (tuple) – where to load the reduced darks. A default value is provided by the children class. You better know what you are doing if you modify the default value.
metadata_input_urls – where to load the reduced darks metadata. A default value is provided by the children class. You better know what you are doing if you modify the default value.
return_as_url (bool) – if True then instead of returning the reduced frames as 2D numpy arrays it will return them as a silx DataUrl
return_info (bool) – if False only return return the dict of reduced frames (frame index as key (int) and frame as a 2D numpy array or silx Data Url as value) if True then return (dict of reduced frames, darks info / metadata)

Here is an example of usage:

scan = ... # scan must be an instance of TomoScanBase like NXtomoScan()
reduced_darks = scan.load_reduced_darks()
reduced_darks, darks_infos = scan.load_reduced_darks(return_info=True)

dark_frame_np_array = reduced_darks[0]

Return type:: dict | tuple

load_reduced_flats(inputs_urls, metadata_input_urls=None, return_as_url=False, return_info=False)#

load reduced flats frames

Parameters:

inputs_urls (tuple) – where to load the reduced flats. A default value is provided by the children class. You better know what you are doing if you modify the default value.
metadata_input_urls – where to load the reduced flats metadata. A default value is provided by the children class. You better know what you are doing if you modify the default value.
return_as_url (bool) – if True then instead of returning the reduced frames as 2D numpy arrays it will return them as a silx DataUrl
return_info (bool) – if False only return return the dict of reduced frames (frame index as key (int) and frame as a 2D numpy array or silx Data Url as value) if True then return (dict of reduced frames, flats info / metadata)

Here is an example of usage:

scan = ... # scan must be an instance of TomoScanBase like NXtomoScan()
reduced_flats = scan.load_reduced_flats()
reduced_flats, flats_infos = scan.load_reduced_flats(return_info=True)

Return type:: dict | tuple

static map_urls_on_scan_range(urls, n_projection, scan_range)#

map given urls to an angle regarding scan_range and number of projection. We take the hypothesis that ‘extra projection’ are taken regarding the ‘id19’ policy:

If the acquisition has a scan range of 360 then:

if 4 extra projection, the angles are (270, 180, 90, 0)

if 5 extra projection, the angles are (360, 270, 180, 90, 0)

If the acquisition has a scan range of 180 then:

if 2 extra projections: the angles are (90, 0)

if 3 extra projections: the angles are (180, 90, 0)

..warning:: each url should contain only one radio.

Parameters:

urls – dict with all the urls. First url should be the first radio acquire, last url should match the last radio acquire.
n_projection – number of projection for the sample.
scan_range – acquisition range (usually 180 or 360)

Return type:

dict

Returns:

angle in degree as key and url as value

Raises:

ValueError if the number of extra images found and scan_range are incoherent

property path: str | None#

Return type:: str | None
Returns:: path of the scan root folder.

property projections: dict | None#

if found dict of projections urls with index during acquisition as key

Return type:: dict | None

property sample_detector_distance: float | None#

Return type:: float | None
Returns:: sample / detector distance in meter

property sample_name#: Return the sample name

save_reduced_darks(darks, output_urls, darks_infos=None, metadata_output_urls=None, overwrite=False)#

Dump computed dark (median / mean…) into files.

Parameters:

darks (dict) – dictionary with frame indices as key (int) and a 2D numpy array as value.
output_urls (tuple) – tuple of silx DataUrl, where to save the darks. Default value is usually provided by children class directly. You better know what you are doing if you modify the default value.
darks_infos (ReducedFramesInfos | None) – information regarding darks (metadata) like the machine electric current, exposure time…
metadata_output_urls (tuple | None) – tuple of silx DataUrl, where to save the metadata / darks information. Default value is usually provided by children class directly You better know what you are doing if you modify the default value.
overwrtie – if the output files exist then will overwrite them.

Here is an example on how to save your own reduced dark / flat

from tomoscan.framereducer.reducedframesinfos import ReducedFramesInfos
...

scan = ... # scan must be an instance of TomoScanBase like NXtomoScan()
darks_infos.count_time = [2.5]
darks_infos.machine_electric_current = [13.1]
scan.save_reduced_darks(
    darks={
        0: dark_frame,  # dark_frame is a 2d numpy array
    },
    darks_infos=darks_infos,
    overwrite=True,
)

Return type:: None

save_reduced_flats(flats, output_urls, flats_infos=None, metadata_output_urls=None, overwrite=False)#

Dump computed dark (median / mean…) into files.

Parameters:

flats (dict) – dictionary with frame indices as key (int) and a 2D numpy array as value.
output_urls (tuple) – tuple of silx DataUrl, where to save the flats. Default value is usually provided by children class directly. You better know what you are doing if you modify the default value.
flats_infos (ReducedFramesInfos | None) – information regarding flats (metadata) like the machine electric current, exposure time…
metadata_output_urls (tuple | None) – tuple of silx DataUrl, where to save the metadata / flats information. Default value is usually provided by children class directly You better know what you are doing if you modify the default value.
overwrite (bool) – if the output files exist then will overwrite them.

Here is an example on how to save your own reduced dark / flat

from tomoscan.framereducer.reducedframesinfos import ReducedFramesInfos
...

scan = ... # scan must be an instance of TomoScanBase like NXtomoScan()
flats_infos = ReducedFramesInfos()
flats_infos.count_time = [2.5, 1.2]
flats_infos.machine_electric_current = [12.5, 13.1]
# for normalization the first reduced flat (at index 1) will have 2.5 as count time and 12.5 as machine electric current
# the second reduced flat frame (at index 1002) will have 1.2 as count time and 13.1 as machine electric current
scan.save_reduced_darks(
    darks={
        1: flat_frame_1,     # flat_frame_1 is a 2d numpy array
        1002: flat_frame_2,  # flat_frame_2 is another 2d numpy array
    },
    flats_infos=flats_infos,
    overwrite=True,
)

Return type:: None

property sequence_name#: Return the sequence name

property source_sample_distance: float | None#

Return type:: float | None
Returns:: source / sample distance (in meter). Expected to be negative (NXtomo convention).

to_dict()#

Return type:: dict
Returns:: convert the TomoScanBase object to a dictionary. Used to serialize the object for example.

property tomo_n: int | None#

number of projection WITHOUT the return projections

Return type:: int | None

property type: str#

Return type:: str
Returns:: type of the scanBase (can be ‘edf’ or ‘hdf5’ for now).

update()#

Parse the root folder and files to update information

Return type:: None

property x_flipped: bool#

warning: deprecated !!!!! return True if the frames are flip through x

Return type:: bool

property x_rotation_axis_pixel_position#

Returns:: Estimated center of rotation estimated from motor position. In [-frame_width, +frame_width]. None if unable to find it

property y_flipped: bool#

warning: deprecated !!!!! return True if the frames are flip through y

Return type:: bool