CXIFile#

class cdiutils.io.CXIFile(file_path, mode='r')[source]#

Bases: object

CXI-compliant HDF5 file handler for BCDI data storage.

Implements the CXI (Coherent X-ray Imaging) file format specification for storing BCDI reconstruction data, metadata, and processing history. Provides high-level methods for creating groups, datasets, and soft links following NeXus conventions.

The CXI format organises data hierarchically:

  • entry_N: top-level groups for each dataset

  • image_N: detector images and metadata

  • process_N: reconstruction algorithms and parameters

  • result_N: final reconstruction results

See also

CXI format specification: cxidb/CXI

The CXIFile class provides utilities for reading and writing CXI format files. CXI files are HDF5-based containers for coherent X-ray imaging data.

IMAGE_MEMBERS = ('title', 'data', 'data_error', 'data_space', 'data_type', 'detector_', 'dimensionality', 'image_center', 'image_size', 'is_fft_shifted', 'mask', 'process_', 'reciprocal_coordinates', 'source_')#
__init__(file_path, mode='r')[source]#

Initialise CXI file handler.

Parameters:

  • file_path (str) – path to .cxi file.

  • mode (str) – file access mode (‘r’, ‘w’, ‘a’). Defaults to ‘r’ (read-only).

property entry_counters: None#
property current_entry: None#
open(mode=None)[source]#

Open the CXI file in specified mode.

close()[source]#

Close the CXI file.

get_node(path)[source]#

Retrieve the raw node (dataset or group) at the specified path. Allow direct access to entries with cxi[path].

Parameters:

path (str) – Path to the node.

Returns:

The h5py Dataset or Group object.

copy(source_path, dest_file=None, dest_path=None, **kwargs)[source]#

Copy a group or dataset from this CXI file to another location, either within the same file or to a different CXI file.

Parameters:

  • source_path (str) – Path to the object to copy in the source file.

  • dest_file (CXIFile or h5py.File, optional) – Destination file object. If None, the copy will be within the same file. Defaults to None.

  • dest_path (str, optional) – Path in the destination file. If None, defaults to source_path in the destination. Defaults to None.

  • **kwargs – Additional arguments for h5py copy method (e.g., shallow, expand_soft).

Raises:

KeyError – if the source_path does not exist in the CXI file.

set_entry(index=None)[source]#

Create or switch to a specific entry group (e.g., ‘entry_1’).

create_cxi_group(group_type, default=None, index=None, attrs=None, **kwargs)[source]#

Create a CXI-compliant group with optional NeXus class.

Parameters:

  • group_type (str) – the type of group (e.g., ‘image’, ‘process’).

  • default (str, optional) – the default hdf5 attribute. If not provided will use the one stored in GROUP_ATTRIBUTES. Defaults to None.

  • index (int, optional) – explicit index. If None, the next available index is used. Defaults to None.

  • attrs (dict) – Additional attributes for the group.

  • **kwargs – the data to save in the CXI group.

Returns:

The full path of the created group.

Return type:

str

create_group(path, nx_class=None, attrs=None)[source]#

Method to handle the creation of groups in the context of H5 files, not in the context of CXI.

Parameters:

  • path (str) – the path to create the group at

  • nx_class (str, optional) – NeXus class for the group. Defaults to None.

  • attrs (dict, optional) – Additional attributes for the group.

returns: True if the group was created else False (i.e. if

group already exists).

create_cxi_dataset(path, data, dtype=None, nx_class=None, **attrs)[source]#

Create a CXI-compliant dataset with optional NeXus class.

Parameters:

  • path (str) – The path to the dataset.

  • data – The data to store in the dataset (can be a dict).

  • dtype (data-type, optional) – The data type for the dataset. Defaults to None.

  • nx_class (str, optional) – The NeXus class for the dataset, if applicable. Defaults to None.

Returns:

the dataset or group instance created.

Return type:

h5py.Dataset

read_cxi_dataset(path)[source]#

Read a dataset or group and handle inhomogeneous lists.

Parameters:

path (str) – Path to the dataset or group.

Returns:

The reassembled data, either as the original inhomogeneous list or a standard dataset.

Create a soft link at the specified path pointing to an existing target path.

Parameters:

  • path (str) – the path where the soft link will be created.

  • target (str) – the target path that the soft link points to.

Raises:

ValueError – if the target path does not exist in self.file.

stamp()[source]#

Add metadata to the CXI file, recording information about the software and file creation details.

create_cxi_image(data, link_data=True, **members)[source]#

Create a minimal CXI image entry with associated metadata and soft links.

Parameters:

  • data (np.ndarray) – the image data.

  • link_data (bool, optional) – whether to link to a data_N group. Defaults to True.

  • **members – additional members to add to the image group. Keys ending in a digit will be indexed accordingly.

Returns:

The full path of the created group.

Return type:

str

get_explorer()#

Create and return a CXIExplorer for this CXI file.

Returns:

An explorer instance for this file

Return type:

CXIExplorer

Examples#

Reading CXI file:

from cdiutils.io import CXIFile

with CXIFile("results.cxi", mode="r") as cxi:
    # Access data using dictionary-like syntax
    data = cxi["entry_1/data_1/data"][()]
    mask = cxi["entry_1/data_1/mask"][()]

    # Or use get_node method
    obj = cxi.get_node("entry_1/image_1/data")[()]

Writing CXI file:

from cdiutils.io import CXIFile
import numpy as np

with CXIFile("output.cxi", mode="w") as cxi:
    # Set entry and create datasets
    entry = cxi.set_entry(1)
    cxi.file.create_dataset(f"{entry}/data", data=data)

See Also#

CXIExplorer : Interactive CXI file explorer BcdiPipeline : Saves results to CXI format