MedicalImageAnalysis

MedicalImageAnalysis is a comprehensive Python toolkit for managing and analyzing medical imaging data. It can read unorganized DICOM and RTSTRUCTs files, automatically organizing them into separate image instances. The platform supports both 2D and 3D modalities, with the ability to convert 2D contours to 3D surface meshes and vice versa. It also provides rigid registration between images, along with a variety of standard image processing techniques, enabling seamless integration into research and clinical workflows. There are additional reader file types for stl and 3mf, where a fake image is generated based on the boundary of the input mesh.

The module currently imports 6 different modalities:

1. CT
2. MR
3. US
4. RF
5. DX
6. RTSTRUCT

CT and MR images will be converted to Feet-First-Supine (if not so already), and the image position will be updated to reflect the needed rotations.

Disclaimer: All the files will be loaded into memory so be sure you have enough RAM available. Meaning don't select a folder path that contains 100s of different patient folders because you could possibly run out of RAM. Also, this module does not distinguish between patient IDs or patient names, it will make an image instance for each image regardless of patient id/name.

Reader (Dicom)

The reader works by inputting a file path or a list of files. The files are read and split by modality, series instance uid, acquisition number (if it exists), and image orientation matrix. An image class instance is generated for each image. If an RTSTRUCT exist, it will match with an existing imported image, right now there is no method for importing an RTSTRUCT that doesn't have a corresponding image. The match image class contains a ROI dictionary variable that will create a ROI instance for each imported ROI name (the same process exists for POIs).

Utils

The utils folder contains useful meshing, image conversion, and registration techniques. It doesn't require the images to be read in using the reader class or have image or ROI classes based on the reader, it exists completely independent.

Installation

Using pip:

pip install medicalimageanalysis

During install there can be an error with a jupyter dependency file path containing over 260 characters exceeding windows limit. This can be resolved by enabling long paths on Windows or simply trying to install again, it will skip the package causing the error.

Reader Example 1

The user sets a path to the folder containing the dicom files or highest level folder with subfolders containing dicom files.

import medicalimageanalysis as mia

path = r'/path/to/folder'

mia.read_dicoms(folder_path=path)

Reader Example 2

The user has more options if they are specifics requirements.

1. file_list - if the user already has the files wanted to read in, must be in type list
2. exclude_files - if the user wants to not read certain files
3. only_tags - does not read in the pixel array just the tags
4. only_modality - specify which modalities to read in, if not then all modalities will be read
5. only_load_roi_names - will only load rois with input name

Note: if folder_path and file_list are both input, then folder_path will be used and not both.

import medicalimageanalysis as mia

file_list = ['filepath1.dcm', 'filepath2.dcm', ...]
exclude_files = ['filepath10.dcm', 'filepath11.dcm', ...]

mia.read_dicoms(file_list=file_list, exclude_files=exclude_files, only_tags=True, only_modality=['CT'],
                only_load_roi_names=['Liver', 'Tumor'])

Retrieve image and tags:

The images are stored in a list. Each image instance contains a 3D array (None if only_tags=True), all tag information and popular tags have their own respective variable.

Note: Even 2D images will contain a 3D array, along with a fake slice thickness of 1 mm.

import medicalimageanalysis as mia

path = r'/path/to/folder'

mia.read_dicoms(folder_path=path)

image_list = mia.Data.image_list
image = mia.Data[image_list[0]]

array = image.array
tags = image.tags  # list of all the tags, for 100 slice CT scan the tags list would be 0-99 each containing a dict

name = image.patient_name  # or tags[0].PatientName
spacing = image.spacing  # inplane spacing followed by slice thickness

Instance variables: base_position, date, dimensions, filepaths, frame_ref, image_matrix, mrn, orientation, origin, patient_name, plane, pois, rgb, rois, sections, series_uid, skipped_slice, sops, spacing, tags, time, unverified

Retrieve ROI/POIs:

Each image contains a roi and poi dictionary, if a RTSTRUCT file associates with an image then each ROI/POI is added to respective image dictionary.

import medicalimageanalysis as mia

path = r'/path/to/folder'

reader = mia.Reader(folder_path=path)
reader.read_dicoms()

image_list = mia.Data.image_list
image = mia.Data[image_list[0]]

roi_names = mia.Data.roi_list
roi = image.rois[roi_names[0]]
contour_position = roi.contour_position

poi_names = mia.Data.poi_list
poi = image.rois[poi_names[0]]
point_position = poi.point_position