cavass 1.2.7__py3-none-any.whl

cavass/_io.py

@@ -0,0 +1,71 @@
+import os
+
+import numpy as np
+
+
+def read_mat(input_file, key="scene"):
+    from scipy.io import loadmat
+    if not os.path.isfile(input_file):
+        raise FileNotFoundError(f"Input file {input_file} not found.")
+    data = loadmat(input_file)[key]
+    return data
+
+
+def save_mat(output_file, data, key="scene"):
+    from scipy.io import savemat
+    ensure_output_file_dir_existence(output_file)
+    savemat(output_file, {key: data})
+
+
+def save_nifti(output_file,
+               data,
+               voxel_spacing=None,
+               orientation="LPI"):
+    """
+    Save image with nii format.
+
+    Args:
+        output_file (str):
+        data (numpy.ndarray):
+        voxel_spacing (sequence or None, optional, default=None): `tuple(x, y, z)`. Voxel spacing of each axis. If None,
+            make `voxel_spacing` as `(1.0, 1.0, 1.0)`.
+        orientation (str, optional, default="LPI"): "LPI" | "ARI". LPI: Left-Posterior-Inferior;
+            ARI: Anterior-Right-Inferior.
+
+    Returns:
+
+    """
+    if voxel_spacing is None:
+        voxel_spacing = (1.0, 1.0, 1.0)  # replace this with your desired voxel spacing in millimeters
+
+    match orientation:
+        case "LPI":
+            affine_matrix = np.diag(list(voxel_spacing) + [1.0])
+        case "ARI":
+            # calculate the affine matrix based on the desired voxel spacing and ARI orientation
+            affine_matrix = np.array([
+                [0, -voxel_spacing[0], 0, 0],
+                [-voxel_spacing[1], 0, 0, 0],
+                [0, 0, voxel_spacing[2], 0],
+                [0, 0, 0, 1]
+            ])
+        case _:
+            raise ValueError(f"Unsupported orientation {orientation}.")
+
+    # create a NIfTI image object
+    import nibabel as nib
+    ensure_output_file_dir_existence(output_file)
+    nii_img = nib.Nifti1Image(data, affine=affine_matrix)
+    nib.save(nii_img, output_file)
+
+
+def ensure_output_dir_existence(output_dir):
+    mk_output_dir = not os.path.exists(output_dir)
+    if mk_output_dir:
+        os.makedirs(output_dir)
+    return mk_output_dir, output_dir
+
+
+def ensure_output_file_dir_existence(output_file):
+    output_dir = os.path.split(output_file)[0]
+    return ensure_output_dir_existence(output_dir)

cavass/_log.py

@@ -0,0 +1,9 @@
+import logging
+import sys
+
+logger = logging.getLogger("CAVASS")
+logger.setLevel(logging.INFO)
+log_format = logging.Formatter("%(asctime)s - %(filename)s[line:%(lineno)d] - %(levelname)s: %(message)s")
+console_handler = logging.StreamHandler(stream=sys.stdout)
+console_handler.setFormatter(log_format)
+logger.addHandler(console_handler)

cavass/constants.py

@@ -0,0 +1 @@
+CAVASS_START_INDEX = 1

cavass/contrast_enhancement.py

@@ -0,0 +1,30 @@
+import numpy as np
+
+
+def windowing(input_data, center, window_width, invert=False):
+    min_ = (2 * center - window_width) / 2 + 0.5
+    max_ = (2 * center + window_width) / 2 + 0.5
+    factor = 255 / (max_ - min_)
+
+    data = (input_data - min_) * factor
+
+    data = np.where(data < 0, 0, data)
+    data = np.where(data > 255, 255, data)
+    data = data.astype(np.uint8)
+
+    if invert:
+        data = 255 - data
+
+    return data
+
+
+def cavass_soft_tissue_windowing(input_data):
+    return windowing(input_data, 1000, 500)
+
+
+def cavass_bone_windowing(input_data):
+    return windowing(input_data, 2000, 4000)
+
+
+def cavass_pet_windowing(input_data):
+    return windowing(input_data, 1200, 3500, invert=True)

cavass/converters.py

@@ -0,0 +1,175 @@
+import os
+import shutil
+from uuid import uuid1
+
+import numpy as np
+
+from cavass._io import ensure_output_file_dir_existence, save_nifti
+from cavass.dicom import Modality
+from cavass.nifti2dicom import nifti2dicom
+from cavass.ops import execute_cmd, get_voxel_spacing, read_cavass_file, copy_pose
+from cavass.utils import one_hot
+
+
+def dicom2cavass(input_dicom_dir, output_file, offset=0, copy_pose_file=None):
+    """
+    Note that if the output file path is too long, this command may be failed.
+
+    Args:
+        input_dicom_dir (str):
+        output_file (str):
+        offset (int, optional, default=0):
+        copy_pose_file (str, optional, default=None): if `copy_pose_file` is given, copy pose of this
+        file to the output file.
+
+    """
+
+    if not os.path.exists(input_dicom_dir):
+        raise ValueError(f"Input DICOM series {input_dicom_dir} not found.")
+    if copy_pose_file is not None:
+        if not os.path.isfile(copy_pose_file):
+            raise FileNotFoundError(f"Copy pose file {copy_pose_file} not found.")
+
+    made_output_dir, output_dir = ensure_output_file_dir_existence(output_file)
+
+    input_dicom_dir = input_dicom_dir.replace(" ", "\ ")
+    output_file = output_file.replace(" ", "\ ")
+    try:
+        if copy_pose_file is None:
+            r = execute_cmd(f"from_dicom {input_dicom_dir}/* {output_file} +{offset}")
+        else:
+            split = os.path.splitext(output_file)
+            root = split[0]
+            extension = split[1]
+            output_tmp_file = root + "_TMP" + extension
+            r = execute_cmd(f"from_dicom {input_dicom_dir}/* {output_tmp_file} +{offset}")
+            copy_pose(output_tmp_file, copy_pose_file, output_file)
+
+    except Exception as e:
+        if made_output_dir and os.path.isdir(output_dir):
+            shutil.rmtree(output_dir)
+
+        if copy_pose_file is not None and os.path.exists(output_tmp_file):
+            os.remove(output_tmp_file)
+
+        if os.path.exists(output_file):
+            os.remove(output_file)
+        raise e
+    return r
+
+
+def nifti2cavass(input_nifti_file, output_file, modality, offset=0, copy_pose_file=None):
+    """
+    Convert NIfTI image to cavass image.
+
+    Args:
+        input_nifti_file (str):
+        output_file (str):
+        modality (Modality):
+        offset (int, optional, default=0):
+        copy_pose_file (str, optional, default=None):
+    """
+
+    if not os.path.isfile(input_nifti_file):
+        raise FileNotFoundError(f"Input NIfTI file {input_nifti_file} not found.")
+
+    if copy_pose_file is not None:
+        if not os.path.isfile(copy_pose_file):
+            raise FileNotFoundError(f"Copy pose file {input_nifti_file} not found.")
+
+    made_output_dir, output_dir = ensure_output_file_dir_existence(output_file)
+
+    tmp_dicom_dir = os.path.join(output_dir, f"{uuid1()}")
+    try:
+        r1 = nifti2dicom(input_nifti_file, tmp_dicom_dir, modality=modality, force_overwrite=True)
+        r2 = dicom2cavass(tmp_dicom_dir, output_file, offset, copy_pose_file)
+    except Exception as e:
+        if made_output_dir and os.path.isdir(output_dir):
+            shutil.rmtree(output_dir)
+        if os.path.isdir(tmp_dicom_dir):
+            shutil.rmtree(tmp_dicom_dir)
+        if os.path.exists(output_file):
+            os.remove(output_file)
+
+        raise e
+    shutil.rmtree(tmp_dicom_dir)
+    return r1, r2
+
+
+def cavass2nifti(input_file, output_file, orientation="ARI"):
+    """
+    Convert cavass IM0 and BIM formats to NIfTI.
+
+    Args:
+        input_file (str):
+        output_file (str):
+        orientation (str, optional, default="ARI"): image orientation of NIfTI file, "ARI" or "LPI"
+
+    Returns:
+
+    """
+
+    if not os.path.isfile(input_file):
+        raise FileNotFoundError(f"Input file {input_file} not found.")
+
+    spacing = get_voxel_spacing(input_file)
+    data = read_cavass_file(input_file)
+    save_nifti(output_file, data, spacing, orientation=orientation)
+
+
+def nifti_label2cavass(input_nifti_file, output_file, objects,
+                       modality=Modality.CT, discard_background=True, copy_pose_file=None):
+    """
+    Convert NIfTI format segmentation file to cavass BIM format file. A NIfTI file in where contains arbitrary categories
+    of objects will convert to multiple CAVASS BIM files, which matches to the number of object categories.
+
+    Args:
+        input_nifti_file (str):
+        output_file (str): the final saved file for category i in input segmentation will be
+        `output_file_prefix_{objects[i]}.BIM`
+        objects (sequence or str): objects is an array or a string with comma splitter of object categories,
+        where the index of the category in the array is the number that indicates the category in the segmentation.
+        modality (Modality, optional, default=Modality.CT):
+        discard_background (bool, optional, default True): if True, the regions with label of 0 in the segmentation
+        (typically refer to the background region) will not be saved.
+        copy_pose_file (str, optional, default=None):
+
+    Returns:
+
+    """
+    import nibabel as nib
+
+    if not os.path.isfile(input_nifti_file):
+        raise FileNotFoundError(f"Input NIfTI file {input_nifti_file} not found.")
+
+    if copy_pose_file is not None:
+        if not os.path.isfile(copy_pose_file):
+            raise FileNotFoundError(f"Copy pose file {copy_pose_file} not found.")
+
+    input_data = nib.load(input_nifti_file)
+    image_data = input_data.get_fdata()
+
+    if isinstance(objects, str):
+        objects = objects.split(",")
+    n_classes = len(objects) + 1 if discard_background else len(objects)
+    one_hot_arr = one_hot(image_data, num_classes=n_classes)
+
+    start = 1 if discard_background else 0
+    for i in range(start, one_hot_arr.shape[3]):
+        nifti_label_image = nib.Nifti1Image(one_hot_arr[..., i], input_data.affine, input_data.header, dtype=np.uint8)
+        if discard_background:
+            obj = objects[i - 1]
+        else:
+            obj = objects[i]
+        tmp_nifti_file = f"{output_file}_{obj}.nii.gz"
+        made_output_dir, output_dir = ensure_output_file_dir_existence(tmp_nifti_file)
+        try:
+            nib.save(nifti_label_image, tmp_nifti_file)
+            nifti2cavass(tmp_nifti_file, f"{output_file}_{obj}.BIM", modality, copy_pose_file=copy_pose_file)
+        except Exception as e:
+            if made_output_dir and os.path.isdir(output_dir):
+                shutil.rmtree(output_dir)
+            if os.path.exists(tmp_nifti_file):
+                os.remove(tmp_nifti_file)
+            raise e
+        os.remove(tmp_nifti_file)

cavass/dicom.py

@@ -0,0 +1,167 @@
+import datetime
+from enum import Enum
+from random import randint
+
+from pydicom import Dataset
+from pydicom.dataset import FileDataset, FileMetaDataset
+from pydicom.uid import generate_uid
+
+
+class Modality(Enum):
+    CT = 1
+
+
+def get_dicom_dataset(name, modality: Modality) -> FileDataset:
+    file_meta = FileMetaDataset()
+    file_meta.TransferSyntaxUID = "1.2.840.10008.1.2.1"
+    file_meta.ImplementationVersionName = "DICOM"
+
+    ds = FileDataset(name, {}, file_meta=file_meta, preamble=b"\0" * 128)
+    ds.is_implicit_VR = False
+    ds.is_little_endian = True
+    ds.ImageType = ["DERIVED", "SECONDARY"]
+
+    # add properties
+    patient(ds)
+    general_study(ds)
+    patient_study(ds)
+    frame_of_reference(ds)
+    general_equipment(ds)
+    general_image(ds)
+    general_acquisition(ds)
+    image_plane(ds)
+    image_pixel(ds)
+    SOP_common(ds)
+    VOI_LUT(ds)
+    general_series(ds, file_meta, modality)
+
+    # set datatime
+    dt = datetime.datetime.now()
+    date_str = dt.strftime("%Y%m%d")
+    time_str = dt.strftime("%H%M%S.%f")  # long format with micro seconds
+
+    ds.ContentDate = date_str
+    ds.ContentTime = time_str
+    ds.StudyDate = date_str
+    ds.StudyTime = time_str
+    ds.SeriesDate = date_str
+    ds.SeriesTime = time_str
+    ds.AcquisitionDate = date_str
+    ds.AcquisitionTime = time_str
+    ds.InstanceCreationDate = date_str
+    ds.InstanceCreationTime = time_str
+
+    ds.RescaleIntercept = ""
+    ds.RescaleSlope = ""
+
+    return ds
+
+
+def patient(ds: Dataset):
+    ds.PatientName = "Patient Name"
+    ds.PatientID = "1"
+    ds.PatientSex = ""
+    ds.PatientBirthDate = ""
+
+
+def general_study(ds: Dataset):
+    ds.StudyInstanceUID = generate_uid()
+    ds.StudyDescription = ""
+    ds.ReferringPhysicianName = ""
+
+
+def patient_study(ds: Dataset):
+    ds.PatientAge = ""
+    ds.PatientWeight = ""
+
+
+def general_series(ds: Dataset, file_meta: FileMetaDataset, modality: Modality):
+    ds.Modality = modality.name
+    match modality:
+        case Modality.CT:
+            file_meta.MediaStorageSOPClassUID = "1.2.840.10008.5.1.4.1.1.2"
+            ds.SOPClassUID = "1.2.840.10008.5.1.4.1.1.2"
+            CT_image(ds)
+
+    ds.SeriesInstanceUID = generate_uid(None)
+    ds.SeriesNumber = str(randint(1000, 9999))
+    ds.ProtocolName = "DICOM"
+    ds.PatientPosition = ""
+    ds.AccessionNumber = "123456"
+
+
+def frame_of_reference(ds: Dataset):
+    ds.FrameOfReferenceUID = generate_uid(None)
+
+
+def general_equipment(ds: Dataset):
+    ds.Manufacturer = ""
+    ds.InstitutionName = "INSTITUTION_NAME_UNDEFINED"
+    ds.ManufacturerModelName = ""
+    ds.SoftwareVersions = ""
+
+
+def general_image(ds: Dataset):
+    ds.InstanceNumber = ""
+    ds.PatientOrientation = ""
+    ds.ContentDate = ""
+    ds.ContentTime = ""
+    ds.ImageType = ["SECONDARY", "DERIVED"]
+    ds.LossyImageCompression = "00"
+
+
+def general_acquisition(ds: Dataset):
+    ds.AcquisitionNumber = ""
+    ds.AcquisitionDate = ""
+    ds.AcquisitionTime = ""
+
+
+def image_plane(ds: Dataset):
+    ds.PixelSpacing = ""
+    ds.ImageOrientationPatient = ["1", "0", "0", "0", "1", "0"]
+    ds.ImagePositionPatient = ["0", "0", "0"]
+    ds.SliceThickness = ""
+    ds.SpacingBetweenSlices = ""
+    ds.SliceLocation = ""
+
+
+def image_pixel(ds: Dataset):
+    ds.Rows = 0
+    ds.Columns = 0
+
+    ds.BitsAllocated = 0
+    ds.BitsStored = 0
+    ds.HighBit = 0
+
+    ds.PixelRepresentation = 1
+
+    ds.SmallestImagePixelValue = ""
+    ds.LargestImagePixelValue = ""
+
+    ds.PixelData = ""
+
+
+def SOP_common(ds: Dataset):
+    ds.SOPClassUID = ""
+    ds.SOPInstanceUID = ""
+
+    ds.SpecificCharacterSet = "ISO_IR 100"
+    ds.InstanceCreationDate = ""
+    ds.InstanceCreationTime = ""
+
+    ds.InstanceCreatorUID = ""
+
+
+def VOI_LUT(ds: Dataset):
+    ds.WindowCenter = ""
+    ds.WindowWidth = ""
+
+
+def CT_image(ds: Dataset):
+    ds.SamplesPerPixel = 1
+
+    ds.PhotometricInterpretation = "MONOCHROME2"
+
+    ds.BitsAllocated = 16
+    ds.BitsStored = 12
+    ds.HighBit = ds.BitsStored - 1

cavass/integration.py

@@ -0,0 +1,145 @@
+import os.path
+import shutil
+import uuid
+from typing import Union
+
+from cavass._io import ensure_output_file_dir_existence
+from cavass.constants import CAVASS_START_INDEX
+from cavass.ops import ndvoi, matched_reslice, bin_ops
+from cavass.slice_range import get_slice_range
+
+
+def integrate_trimmed_images(trimmed_files: Union[list[str], tuple[str, ...]],
+                             reference_file: str,
+                             output_file_1: str,
+                             output_file_2: str, ):
+    """
+    Suture trimmed CAVASS files.
+    For the situation that the whole file is trimmed into multiple files of body regions, this script integrates
+    multiple trimmed files into one file.
+    The ROI of the new file is determined by the provided trimmed files, which is the region exactly contains all
+    trimmed files and may not be the same as the ROI of original untrimmed file.
+
+    Args:
+        trimmed_files (tuple or list): trimmed files. trimmed files must be arranged correctly in the order of form inferior to superior.
+        reference_file (str): file to match.
+        output_file_1 (str): `output_file_1` is the output file trimmed from the reference file according to the ROI obtained from the trimmed files.`
+        output_file_2 (str): `output_file_2` is the output file of integrated files of the untrimmed files.
+
+    Returns:
+
+    """
+
+    if not os.path.isfile(reference_file):
+        raise FileNotFoundError(f"Reference file {reference_file} not found.")
+    for each in trimmed_files:
+        if not os.path.isfile(each):
+            raise FileNotFoundError(f"Trimmed file {each} not found.")
+
+    # Get ROI from the first and last untrimmed files.
+    # The inferior location is the inferior location of the first trimmed image in the untrimmed image.
+    # The superior location is the superior location of the last trimmed image in the untrimmed image.
+    all_unmatched_files = []
+    inferior_slice_idx, _, unmatched_files = get_slice_range(trimmed_files[0], reference_file)
+    all_unmatched_files.extend(unmatched_files)
+    _, superior_slice_idx, unmatched_files = get_slice_range(trimmed_files[-1], reference_file)
+    all_unmatched_files.extend(unmatched_files)
+
+    # CAVASS uses index started from 1.
+    inferior_slice_idx -= CAVASS_START_INDEX
+    superior_slice_idx -= CAVASS_START_INDEX
+
+    # The new ROI is [inferior_slice_idx, superior_slice_idx]
+    # Trim from original untrimmed file.
+
+    made_output_dir_1, output_dir_1 = ensure_output_file_dir_existence(output_file_1)
+
+    try:
+        ndvoi(reference_file, output_file_1, min_slice_dim_3=inferior_slice_idx, max_slice_dim_3=superior_slice_idx)
+    except Exception as e:
+        if made_output_dir_1 and os.path.isdir(output_dir_1):
+            shutil.rmtree(output_dir_1)
+        if os.path.exists(output_file_1):
+            os.remove(output_file_1)
+        raise e
+
+    made_output_dir_2, output_dir_2 = ensure_output_file_dir_existence(output_file_2)
+
+    # create reslice files of trimmed files w.r.t untrimmed file.
+    tmp_files = []
+    reslice_files = []
+    file_type = os.path.splitext(trimmed_files[0])[1][1:]
+    interpolation_method = "nearest" if file_type == "BIM" else "linear"
+    for trimmed_file in trimmed_files:
+        reslice_file = os.path.join(output_dir_2, f"{uuid.uuid1()}.{file_type}")
+        tmp_files.append(reslice_file)
+        reslice_files.append(reslice_file)
+        try:
+            matched_reslice(trimmed_file, reference_file, reslice_file, interpolation_method=interpolation_method)
+        except Exception as e:
+            if made_output_dir_1 and os.path.isdir(output_dir_1):
+                shutil.rmtree(output_dir_1)
+            if os.path.exists(output_file_1):
+                os.remove(output_file_1)
+
+            if made_output_dir_2 and os.path.isdir(output_dir_2):
+                shutil.rmtree(output_dir_2)
+            for each in tmp_files:
+                if os.path.exists(each):
+                    os.remove(each)
+            raise e
+
+    # integrate reslice files by OR operation.
+    if len(reslice_files) > 1:
+        or_op_file_1 = reslice_files[0]
+        or_op_file_2 = reslice_files[1]
+        or_op_output_file = os.path.join(output_dir_2, f"{uuid.uuid1()}.{file_type}")
+        or_op_output_files = [or_op_output_file]
+        tmp_files.append(or_op_output_file)
+        bin_ops(or_op_file_1, or_op_file_2, or_op_output_file, op="or")
+        if len(reslice_files) > 2:
+            for reslice_file in reslice_files[2:]:
+                or_op_file_1 = or_op_output_files[-1]
+                or_op_file_2 = reslice_file
+                or_op_output_file = os.path.join(output_dir_2, f"{uuid.uuid1()}.{file_type}")
+                or_op_output_files.append(or_op_output_file)
+                tmp_files.append(or_op_output_file)
+                try:
+                    bin_ops(or_op_file_1, or_op_file_2, or_op_output_file, op="or")
+                except Exception as e:
+                    if made_output_dir_1 and os.path.isdir(output_dir_1):
+                        shutil.rmtree(output_dir_1)
+                    if os.path.exists(output_file_1):
+                        os.remove(output_file_1)
+
+                    if made_output_dir_2 and os.path.isdir(output_dir_2):
+                        shutil.rmtree(output_dir_2)
+                    for each in tmp_files:
+                        if os.path.exists(each):
+                            os.remove(each)
+                    raise e
+
+        output_file = or_op_output_files[-1]
+    else:
+        output_file = reslice_files[0]
+
+    # reslice to otuput file 1
+    try:
+        matched_reslice(output_file, output_file_1, output_file_2, interpolation_method=interpolation_method)
+    except Exception as e:
+        if made_output_dir_1 and os.path.isdir(output_dir_1):
+            shutil.rmtree(output_dir_1)
+        if os.path.exists(output_file_1):
+            os.remove(output_file_1)
+
+        if made_output_dir_2 and os.path.isdir(output_dir_2):
+            shutil.rmtree(output_dir_2)
+        for each in tmp_files:
+            if os.path.exists(each):
+                os.remove(each)
+        raise e
+
+    for each in tmp_files:
+        if os.path.exists(each):
+            os.remove(each)
+    return all_unmatched_files

cavass/match.py

@@ -0,0 +1,38 @@
+import os
+import shutil
+
+from cavass._io import ensure_output_file_dir_existence
+from cavass.constants import CAVASS_START_INDEX
+from cavass.ops import matched_reslice
+from cavass.slice_range import get_slice_range
+
+
+def match(unmatched_file: str,
+          file_to_match: str,
+          output_file: str):
+    """
+    Match body region.
+    Args:
+        unmatched_file (str):
+        file_to_match (str):
+        output_file (str):
+
+    Returns:
+
+    """
+    inferior_slice_idx, superior_slice_idx, unmatched_files = get_slice_range(unmatched_file, file_to_match)
+    inferior_slice_idx -= CAVASS_START_INDEX
+    superior_slice_idx -= CAVASS_START_INDEX
+
+    made_output_dir, output_dir = ensure_output_file_dir_existence(output_file)
+    file_type = os.path.splitext(unmatched_file[0])[1][1:]
+    interpolation_method = "nearest" if file_type == "BIM" else "linear"
+    try:
+        matched_reslice(unmatched_file, file_to_match, output_file, interpolation_method=interpolation_method)
+    except Exception as e:
+        if made_output_dir and os.path.isdir(output_dir):
+            shutil.rmtree(output_dir)
+        if os.path.exists(output_file):
+            os.remove(output_file)
+        raise e
+    return unmatched_files