HDF5 utils

[dyang37]

This PR is regarding the utility functions to save image data into an HDF5 file and read image data from an HDF5 file. This PR contains two functions mbircone.utils.hdf5_write() and mbircone.utils.hdf5_read(), as well as a demo script demo/demo_hdf5_io.py.

• hdf5_write() saves a reconstruction image as an HDF5 file. The file structure is defined as follows: Dataset:

  • voxels (ndarray): 3D image to be saved. Attributes:
  • README (string): long string defining the structure of the HDF5 file.
  • source (string): source file of the reconstruction. Example: "reconstruction.nsihdr".
  • alu_def (string): definition of arbitrary length units (ALU). Example: "5 mm".
  • delta_pixel_image (float): Image pixel spacing in ALU.
  • recon_unit (string): unit of the reconstruction data. Example: "mm^{-1}"`.

• hdf5_read() read the image data as well as its metadata from an HDF5 file.

• The demo script demonstrates how to save image data as HDF5 file, and how to read image data and metadata from an HDF5 file. It includes:

  1. Generating a 3D Shepp Logan phantom;
  2. Writing the image data as a HDF5 file using function mbircone.utils.hdf5_write;
  3. Reading the image data and metadata from the HDF5 file using function mbircone.utils.hdf5_read;
  4. Printing out the image metadata and displaying the image slices. Printing out the image metadata and displaying the image slices.. Printing out the image metadata and displaying the image slices.4. Printing out the image metadata and displaying the image slices.

[dyang37]

Updated function interfaces (approved by Charlie):

def hdf5_write(image, filename,
              recon_description="", alu_description ="", delta_pixel_image=1.0):
    """ This function writes a reconstructed image to an HDF5 file containing the 3D reconstructed volume along with optional descriptions of the source data, and units. 

    Args:
        image (float, ndarray): 3D reconstructed image to be saved.
        filename (string) Path to save the HDF5 file. Example: "<path_to_directory>/recon.h5".
        recon_description (string, optional) [Default=""] description of CT source data.
        alu_description (string, optional) [Default=""] description of arbitrary length units (ALU). Example: "1 ALU = 5 mm".
        delta_pixel_image (float, optional) [Default=1.0]:  Image pixel spacing in ALU.
    """

def hdf5_read(filename):
    """ Read the image data as well as its metadata from an HDF5 file.

    Args:
        filename (string, optional) [Default="recon.h5"] Path to save the HDF5 file.

    Returns:
        two-element tuple containing:

        - **image** (*ndarray*): 3D image data.
        - **attributes** (*dict*): A dictionary containing attributes of the HDF5 file.
    """

[dyang37]

File content:

    The resulting HDF5 file contains the following entries:
    Dataset:
        - **voxels** (*ndarray*): 3D image to be saved.
    Attributes:
        - **README** (*string*): describes the contents of HDF5 file.
        - **source_data_description** (*string*): description of CT source data.
        - **alu_description** (*string*): description of arbitrary length units (ALU). Example: "1 ALU = 5 mm".
        - **delta_pixel_image** (*float*): Image pixel spacing in ALU.
        - **recon_scale_description** (*string*): description of the reconstruction scale. Example: "mm^{-1}" or "Hounsfield Units".

[dyang37]

Close this PR for further modifications.