imfusion.io#

IO

imfusion.io.load(path: PathLike | str | bytes) → list#

Load the content of a file or folder as a list of Data.

The list can contain instances of any class deriving from Data, i.e. SharedImage, Mesh, PointCloud, etc…

Parameters:

path – can be path to a file containing a supported file formats, or a folder containing Dicom data, if the imfusion package was built with Dicom support.

Note

An IOError is raised if the file cannot be opened or a ValueError if the filetype is not supported. Some filetypes (like workspaces) cannot be opened by this function, but must be opened with imfusion.gui.ApplicationController.open().

For PointCloud files in .pcd format: PCD files store colors as integers in the range [0, 255], however, the returned PointCloud will have colors converted to floating-point values in the range [0.0, 1.0].

Example

>>> imfusion.io.load('ct_image.png')  
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(USHORT width: 512 height: 512 spacing: 0.661813x0.661813x1 mm)])]  
>>> imfusion.io.load('multi_label_segmentation.nii.gz')  
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(UBYTE width: 128 height: 128 slices: 128 channels: 3 spacing: 1x1x1 mm)])]  
>>> imfusion.io.load('us_sweep.dcm')  
[imfusion.SharedImageSet(size: 20, [  
        imfusion.SharedImage(UBYTE width: 164 height: 552 spacing: 0.228659x0.0724638x1 mm),  
        imfusion.SharedImage(UBYTE width: 164 height: 552 spacing: 0.228659x0.0724638x1 mm),  
        ...  
        imfusion.SharedImage(UBYTE width: 164 height: 552 spacing: 0.228659x0.0724638x1 mm)  
>>> imfusion.io.load('path_to_folder_containing_multiple_dcm_datasets')  
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(FLOAT width: 400 height: 400 slices: 300 spacing: 2.03642x2.03642x3 mm)])]
imfusion.io.save(shared_image_set: SharedImageSet, path: PathLike | str | bytes, **kwargs) → None#
imfusion.io.save(mesh: Mesh, file_path: PathLike | str | bytes) → None
imfusion.io.save(point_cloud: PointCloud, file_path: PathLike | str | bytes) → None
imfusion.io.save(data: Data, file_path: PathLike | str | bytes) → None
imfusion.io.save(data_list: Sequence[Data], file_path: PathLike | str | bytes) → None

Function overload documentation:

imfusion.io.save(shared_image_set: SharedImageSet, path: PathLike | str | bytes, **kwargs) → None

Save a SharedImageSet to the specified file or folder path. The path extension is used to determine which file format to save to. If a folder path is provided instead, then images are saved in the directory as separate png files. Currently supported file formats are:

  • ImFusion File, extension imf

  • NIfTI File, extensions [nii, nii.gz]

  • Folder path

Parameters:

  • shared_image_set – Instance of SharedImageSet.

  • path – Path to output file or folder. The path extension is used to determine the file format.

Keyword Arguments:

  • keep_ras_coordinates (bool) – NIfTI only. Whether to keep to the keep RAS (Right, Anterior, Superior) coordinate system.

  • compression_level (int) – Folder only. Compression level of the output png files. Valid values range from 0-9 (0 - no compression, 9 - “maximal” compression).

Raises:

RuntimeError if path extension is not supported. Currently supported extensions are ['imf', 'nii', 'nii.gz'], or no extension (save to folder). –

Example

>>> image_set = imfusion.SharedImageSet(np.ones((1,8,8,1)))
>>> imfusion.io.save(image_set, tmp_path / 'file.imf')  # saves an ImFusion file
>>> imfusion.io.save(image_set, tmp_path / 'file.nii.gz', keep_ras_coordinates=True)  # saves a NIfTI file
imfusion.io.save(mesh: Mesh, file_path: PathLike | str | bytes) → None

Save a imfusion.Mesh to the specified file path. The path extension is used to determine which file format to save to. Currently supported file formats are:

  • ImFusion File, extension imf

  • Polygon File Format or the Stanford Triangle Format, extension ply

  • STL file format used for 3D printing and computer-aided design (CAD), extension stl

  • Object File Format, extension off

  • OBJ file format developed by Wavefront , extension obj

  • Virtual Reality Modeling Language file format, extension wrl

  • Standard Starlink NDF (SUN/33) file format, extension surf

  • Raster GIS file format developed by Esri, extension grid

  • 3D Manufacturing Format , extension 3mf

Parameters:

  • mesh – Instance of imfusion.Mesh.

  • file_path – Path to output file. The path extension is used to determine the file format.

Raises:

RuntimeError if file_path extension is not supported. Currently supported extensions are ['ply', 'stl', 'off', 'obj', 'wrl', 'surf', 'grid', '3mf']. –

Example

>>> mesh = imfusion.Mesh.create(imfusion.Mesh.Primitive.SPHERE)
>>> imfusion.io.save(mesh, tmp_path / 'mesh.imf')
imfusion.io.save(point_cloud: PointCloud, file_path: PathLike | str | bytes) → None

Save a imfusion.PointCloud to the specified file path. The path extension is used to determine which file format to save to. Currently supported file formats are:

  • ImFusion File, extension imf

  • Point Cloud Data used inside Point Cloud Library (PCL), extension pcd

  • OBJ file format developed by Wavefront , extension obj

  • Polygon File Format or the Stanford Triangle Format, extension ply

For .pcd and .imf files, colors are stored as integers in the range [0, 255], even if the PointCloud has colors in the floating-point range [0.0, 1.0]. When saving to these formats, all color values must be in the range [0.0, 1.0], otherwise a ValueError will be raised.

Parameters:

  • point_cloud – Instance of imfusion.PointCloud.

  • file_path – Path to output file. The path extension is used to determine the file format.

Raises:

  • RuntimeError – If file_path extension is not supported. Supported extensions are imf, pcd, obj, ply, txt, xyz.

  • ValueError – If saving to .pcd or .imf format and any color value is outside the range 0.0 to 1.0.

Example

>>> pc = imfusion.PointCloud([(0,0,0), (1,1,1), (-1,-1,-1)])
>>> imfusion.io.save(pc, tmp_path / 'point_cloud.pcd')
imfusion.io.save(data: Data, file_path: PathLike | str | bytes) → None

Save a Data instance to the specified file path as an ImFusion file.

Parameters:

  • data – Any instance of class deriving from Data can be saved with this method; examples are SharedImageSet, Mesh, and PointCloud.

  • file_path – Path to ImFusion file. The data is saved in a single file. File path must end with .imf.

Note

Raises a RuntimeError on failure or if file_path doesn’t end with .imf extension.

Example

>>> mesh = imfusion.Mesh.create(imfusion.Mesh.Primitive.SPHERE)
>>> imfusion.io.save(mesh, tmp_path / 'mesh.imf')
imfusion.io.save(data_list: Sequence[Data], file_path: PathLike | str | bytes) → None

Save a list of data to the specified file path as an ImFusion file.

Parameters:

  • data_list – List of Data. Any class deriving from Data can be saved with this method. Examples of Data are SharedImageSet, Mesh, PointCloud, etc.

  • file_path – Path to ImFusion file. The entire list of Data is saved in a single file. File path must end with .imf.

Note

Raises a RuntimeError on failure or if file_path doesn’t end with .imf extension.

Example

>>> image_set = imfusion.SharedImageSet(np.ones((1,8,8,1)))
>>> mesh = imfusion.Mesh.create(imfusion.Mesh.Primitive.SPHERE)
>>> point_cloud = imfusion.PointCloud([(0,0,0), (1,1,1), (-1,-1,-1)])
>>> another_image_set = imfusion.SharedImageSet(np.ones((1,8,8,1)))
>>> imfusion.io.save([image_set, mesh, point_cloud, another_image_set], tmp_path / 'file.imf')