tomoscan.esrf.scan.nxtomoscan.NXtomoScan#

class tomoscan.esrf.scan.nxtomoscan.NXtomoScan(scan, entry=None, index=0, ignore_projections=None, nx_version=None)#

Bases: TomoScanBase

This is the implementation of a TomoBase class for an acquisition stored in a HDF5 file. HDF5 may have broken links in virtual layout, considering this the class performs an integrity check on all the links and this can be very long for huge data sets with tens of thousands of links. This check can be set by defining and exportin the shell environment variable TOMOTOOLS_SKIP_DET_CHECK setted either to 1 or y.

For now several property of the acquisition is accessible thought a getter (like get_scan_range) and a property (scan_range).

This is done to be compliant with TomoBase instantiation. But his will be replace progressively by properties at the ‘TomoBase’ level

Parameters
  • scan – scan directory or scan masterfile.h5

  • entry – name of the NXtomo entry to select. If given index is ignored.

  • index – of the NXtomo entry to select. Ignored if an entry is specified. For consistency entries are ordered alphabetically

  • nx_version – Version of the Nexus convention to use. By default (None) it will take the latest one

  • ignore_projections – projection indices to be ignored. If a list of integers is provided: exclude the projections corresponding to these indices in “image_key”. Otherwise, a dict should be provided in the form {“kind”: kind, “values”: values} where “kind” can be: “indices”, “angles”, “range”.

__init__(scan, entry=None, index=0, ignore_projections=None, nx_version=None)#

Methods

__init__(scan[, entry, index, ...])

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_caches()

clear caches.

clear_frames_caches()

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_dict(_dict)

from_identifier(identifier)

Return the Dataset from a identifier

get_bliss_orginal_files()

get_bliss_original_files()

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_data_path()

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_master_file(scan_path)

get_pixel_size([unit])

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[, ...])

param file_name

name of the file to create

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_valid_entries(file_path)

return the list of 'Nxtomo' entries at the root level

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)

return

True if the acquisition has been abort

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.

node_is_nxtomo(node)

check if the given h5py node is an nxtomo node or not

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_check_behavior([run_check, raise_error, ...])

when user require to access to scan frames NXtomoScan build them (frames property).

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

REDUCED_DARKS_DATAURLS

REDUCED_DARKS_METADATAURLS

REDUCED_FLATS_DATAURLS

REDUCED_FLATS_METADATAURLS

SCHEME

alignment_projections

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

count_time

dark_n

darks

list of darks files

detector_transformations

return tuple of Transformation affecting the NXdetector

dim_1

dim_2

distance

electric_current

Return the sample name

end_time

energy

energy in keV

entry

rtype

str

estimated_cor_frm_motor

exposure_time

ff_interval

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

frames

return tuple of frames.

group_size

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

ignore_projections

image_key

image_key_control

instrument_name

return

instrument name

intensity_monitor

intensity_normalization

magnification

number of projection WITHOUT the return projections

nexus_path

nexus_version

path

return

path of the scan root folder.

pixel_size

return x pixel size in meter

projections

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

projections_compacted

Return a compacted view of projection frames.

reduced_darks

reduced_darks_infos

reduced_flats

reduced_flats_infos

return_projs

rotation_angle

sample_detector_distance

return sample detector distance in meter

sample_name

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

scan_range

sequence_name

Return the sequence name

source

source_name

source_sample_distance

return

source / sample distance (in meter). Expected to be negative (NXtomo convention).

source_type

splitted_flat_serie

splitted_flat_series

split flat according to flat indices

start_time

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

return x pixel size in meter

x_real_pixel_size

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

y_flipped

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

y_pixel_size

return y pixel size in meter

y_real_pixel_size

y_translation

z_translation

FRAME_REDUCER_CLASS#

alias of HDF5FrameReducer

property alignment_projections#

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

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_caches()#

clear caches. Might be call if some data changed after first read of data or metadata

Return type

None

compute_reduced_darks(reduced_method='mean', overwrite=True, output_dtype=<class 'numpy.float32'>, return_info=False)#
Parameters
  • method (ReduceMethod) – method to compute the flats

  • overwrite – if some flats have already been computed will overwrite them

  • return_info (bool) – do we return (reduced_frames, info) or directly reduced_frames

compute_reduced_flats(reduced_method='median', overwrite=True, output_dtype=<class 'numpy.float32'>, return_info=False)#
Parameters
  • method (ReduceMethod) – method to compute the flats

  • overwrite – if some flats have already been computed will overwrite them

  • return_info (bool) – do we return (reduced_frames, info) or directly reduced_frames

property darks#

list of darks files

property detector_transformations#

return tuple of Transformation affecting the NXdetector

property electric_current#

Return the sample name

property energy#

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 – 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#

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

property flats#

list of flats files

property frames#

return tuple of frames. Frames contains

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()#

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.

Returns

angles as keys, radios as value.

get_projections_intensity_monitor()#

return intensity monitor values for projections

Return type

dict

get_relative_file(file_name, with_dataset_prefix=True)#
Parameters
  • file_name – name of the file to create

  • with_dataset_prefix – If True will prefix the requested file by the dataset name like datasetname_file_name

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

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_valid_entries(file_path)#

return the list of ‘Nxtomo’ entries at the root level

Parameters

file_path (str) –

Return type

tuple

Returns

list of valid Nxtomo node (ordered alphabetically)

..note: entries are sorted to insure consistency

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#

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

property instrument_name#
Returns

instrument name

is_abort(**kwargs)#
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

Return type

TomoScanBase

Returns

self

Raises

ValueError if dict is invalid

load_reduced_darks(inputs_urls=(DataUrl(valid=True, scheme='silx', file_path='{scan_prefix}_darks.hdf5', data_path='{entry}/darks/{index}', data_slice=None),), metadata_input_urls=(DataUrl(valid=True, scheme='silx', file_path='{scan_prefix}_darks.hdf5', data_path='{entry}/darks/', data_slice=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

load_reduced_flats(inputs_urls=(DataUrl(valid=True, scheme='silx', file_path='{scan_prefix}_flats.hdf5', data_path='{entry}/flats/{index}', data_slice=None),), metadata_input_urls=(DataUrl(valid=True, scheme='silx', file_path='{scan_prefix}_flats.hdf5', data_path='{entry}/flats/', data_slice=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

property magnification#

number of projection WITHOUT the return projections

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

static node_is_nxtomo(node)#

check if the given h5py node is an nxtomo node or not

Return type

bool

property path#
Returns

path of the scan root folder.

property pixel_size#

return x pixel size in meter

property projections#

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

property projections_compacted#

Return a compacted view of projection frames.

Returns

Dictionary where the key is a list of indices, and the value is the corresponding silx.io.url.DataUrl with merged data_slice

property sample_detector_distance#

return sample detector distance in meter

property sample_name#

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

save_reduced_darks(darks, output_urls=(DataUrl(valid=True, scheme='silx', file_path='{scan_prefix}_darks.hdf5', data_path='{entry}/darks/{index}', data_slice=None),), darks_infos=None, metadata_output_urls=(DataUrl(valid=True, scheme='silx', file_path='{scan_prefix}_darks.hdf5', data_path='{entry}/darks/', data_slice=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 – information regarding darks (metadata) like the machine electric current, exposure time…

  • metadata_output_urls – 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,
)
save_reduced_flats(flats, output_urls=(DataUrl(valid=True, scheme='silx', file_path='{scan_prefix}_flats.hdf5', data_path='{entry}/flats/{index}', data_slice=None),), flats_infos=None, metadata_output_urls=(DataUrl(valid=True, scheme='silx', file_path='{scan_prefix}_flats.hdf5', data_path='{entry}/flats/', data_slice=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 – information regarding flats (metadata) like the machine electric current, exposure time…

  • metadata_output_urls (tuple) – 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

dict

property sequence_name#

Return the sequence name

set_check_behavior(run_check=True, raise_error=False, log_level=30)#

when user require to access to scan frames NXtomoScan build them (frames property). Some check can be made during this stage to know if the scan has some broken virtual-dataset (vds) or if the vds is linked to more file than the system might handle.

In this case the ‘vds-check’ can either raise an error or log potential issues with a specific log level

property source_sample_distance#
Returns

source / sample distance (in meter). Expected to be negative (NXtomo convention).

property splitted_flat_series#

split flat according to flat indices

to_dict()#
Return type

dict

Returns

convert the TomoScanBase object to a dictionary. Used to serialize the object for example.

property tomo_n#

number of projection WITHOUT the return projections

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_pixel_size#

return x pixel size in meter

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

property y_pixel_size#

return y pixel size in meter