ribline 0.3.0__py3-none-any.whl

ribline/__init__.py

@@ -0,0 +1,57 @@
+"""RibLine: 3D Rib Centerline Tracing and Anatomical Labeling in Medical Images."""
+
+__version__ = "0.3.0"
+
+from ribline.data.centerline_parser import parse_rib_xls
+from ribline.data.dataset import RibDataset
+from ribline.data.image_reader import load_image, read_analyze75_header, read_analyze75_numpy
+from ribline.model.anatomy import (
+    RibCageStatisticalAtlas,
+    extract_thoracic_frame,
+    get_anatomical_rib_mask,
+    get_polar_angle,
+    standardize_hu,
+)
+from ribline.model.features import FeatureExtractor
+from ribline.model.forest import RibForest
+from ribline.model.metrics import (
+    aggregate_subject_metrics,
+    centerline_dice,
+    chamfer_distance,
+    dilated_dice,
+    evaluate_subject_ribs,
+    hausdorff_distance_95,
+)
+from ribline.model.reconstruction import CenterlineExtractor
+from ribline.model.refinement import DeformableRibRefiner, RibSnake
+from ribline.model.topology import RibTopologyMatcher
+from ribline.model.unet.model import RibUNet, RibUNet3D
+
+__all__ = [
+    "__version__",
+    "parse_rib_xls",
+    "RibDataset",
+    "load_image",
+    "read_analyze75_header",
+    "read_analyze75_numpy",
+    "RibCageStatisticalAtlas",
+    "extract_thoracic_frame",
+    "get_anatomical_rib_mask",
+    "get_polar_angle",
+    "standardize_hu",
+    "FeatureExtractor",
+    "RibForest",
+    "RibUNet",
+    "RibUNet3D",
+    "chamfer_distance",
+    "hausdorff_distance_95",
+    "centerline_dice",
+    "dilated_dice",
+    "evaluate_subject_ribs",
+    "aggregate_subject_metrics",
+    "CenterlineExtractor",
+    "RibTopologyMatcher",
+    "RibSnake",
+    "DeformableRibRefiner",
+]
+

ribline/configs/config_schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RibLine Configuration",
+  "type": "object",
+  "properties": {
+    "data_config": {
+      "type": "object",
+      "properties": {
+        "image_directory": { "type": "string" },
+        "centerline_directory": { "type": "string" },
+        "split_file": { "type": "string" },
+        "select_files": {
+            "type": "array",
+            "items": { "type": "string" }
+        }
+      },
+      "required": ["image_directory"]
+    },
+    "model_config": {
+      "type": "object",
+      "properties": {
+        "n_estimators": { "type": "integer", "default": 100 },
+        "max_depth": { "type": "integer" },
+        "n_jobs": { "type": "integer", "default": -1 },
+        "dtype": { "type": "string", "enum": ["float32", "bfloat16"], "default": "float32" }
+      }
+    },
+    "training_config": {
+      "type": "object",
+      "properties": {
+        "output_directory": { "type": "string" },
+        "num_passes": { "type": "integer", "default": 1 },
+        "sampling_rate": { "type": "number", "default": 0.01 }
+      },
+      "required": ["output_directory"]
+    },
+    "eval_config": {
+      "type": "object",
+      "properties": {
+        "metrics": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["data_config", "training_config"]
+}

ribline/data/centerline_parser.py

@@ -0,0 +1,39 @@
+import csv
+import collections
+import numpy as np
+
+def parse_rib_xls(filepath):
+    """
+    Parses the custom tab-separated .xls ground truth files for rib centerlines.
+    
+    Args:
+        filepath (str): Path to the .xls file.
+        
+    Returns:
+        dict: Mapping from RibName (e.g., 'R01') to numpy array of coordinates (N, 3).
+    """
+    ribs = collections.defaultdict(list)
+    try:
+        with open(filepath, 'r') as f:
+            reader = csv.reader(f, delimiter='\t')
+            for row in reader:
+                if not row: continue
+                rib_name = row[0]
+                # x, y, z are indices 1, 2, 3
+                # We assume the file format is consistent: Name, X, Y, Z, ...
+                try:
+                    coords = [float(x) for x in row[1:4]]
+                    ribs[rib_name].append(coords)
+                except ValueError:
+                    # Skip lines that might contain headers or malformed data
+                    continue
+                    
+        # Convert lists to numpy arrays
+        rib_dict = {}
+        for r, pts in ribs.items():
+            rib_dict[r] = np.array(pts)
+            
+        return rib_dict
+    except Exception as e:
+        print(f"Error parsing {filepath}: {e}")
+        return {}

ribline/data/dataset.py

@@ -0,0 +1,243 @@
+import os
+import glob
+import numpy as np
+from .image_reader import load_image
+from .centerline_parser import parse_rib_xls
+import SimpleITK as sitk
+
+class RibDataset:
+    def __init__(self, image_dir, centerline_dir, selected_files=None, radius=2.0):
+        """
+        Args:
+            image_dir (str): Directory containing .img/.hdr files.
+            centerline_dir (str): Directory containing .xls centerline files.
+            selected_files (list, optional): List of filenames (without extension) to include.
+            radius (float): Radius around centerline to consider as positive class.
+        """
+        self.image_dir = image_dir
+        self.centerline_dir = centerline_dir
+        self.radius = radius
+        self.subjects = self._discover_subjects(selected_files)
+        
+    def _discover_subjects(self, selected_files):
+        """
+        Matches images with centerline files. 
+        Returns a list of subject IDs (filenames without extension).
+        """
+        # Get all .img files
+        img_files = glob.glob(os.path.join(self.image_dir, "*.img"))
+        subjects = []
+        
+        for img_path in img_files:
+            basename = os.path.basename(img_path)
+            subject_id = os.path.splitext(basename)[0]
+            
+            # Check if matching centerline file exists
+            # Centerline naming convention seems to vary slightly based on file listing earlier.
+            # GT files: "01_Anonymous_0006_interp.xls" for "01_Anonymous_0006.img"?
+            # Let's verify with a flexible matching or assume "_interp.xls" suffix.
+            # Based on previous ls:
+            # Image: 01_Anonymous_0006.img
+            # GT: 01_Anonymous_0006_interp.xls
+            
+            gt_path = os.path.join(self.centerline_dir, f"{subject_id}_interp.xls")
+            
+            if os.path.exists(gt_path) and os.path.getsize(gt_path) > 0:
+                if selected_files is None or subject_id in selected_files:
+                    subjects.append(subject_id)
+            else:
+                # Try exact match if suffix is different
+                gt_path_exact = os.path.join(self.centerline_dir, f"{subject_id}.xls")
+                if os.path.exists(gt_path_exact) and os.path.getsize(gt_path_exact) > 0:
+                     if selected_files is None or subject_id in selected_files:
+                        subjects.append(subject_id)
+        
+        return sorted(subjects)
+
+    @staticmethod
+    def load_centerlines(gt_path):
+        """Loads ground-truth rib centerlines from a tabular .xls file."""
+        return parse_rib_xls(gt_path)
+
+    def __len__(self):
+        return len(self.subjects)
+
+    def load_item(self, idx):
+        """
+        Loads image and centerlines for a given index.
+        Returns:
+            image (sitk.Image): The 3D image.
+            centerlines (dict): Dictionary of centerline coordinates.
+            subject_id (str): Subject identifier.
+        """
+        subject_id = self.subjects[idx]
+        img_path = os.path.join(self.image_dir, f"{subject_id}.img")
+        
+        # Try both suffixes for GT
+        gt_path = os.path.join(self.centerline_dir, f"{subject_id}_interp.xls")
+        if not os.path.exists(gt_path):
+             gt_path = os.path.join(self.centerline_dir, f"{subject_id}.xls")
+             
+        image = load_image(img_path)
+        centerlines = parse_rib_xls(gt_path)
+        
+        return image, centerlines, subject_id
+
+    def generate_mask(self, image, centerlines):
+        """
+        Generates a binary mask where 1 indicates rib centerline vicinity.
+        """
+        # Create empty mask with same size as image
+        mask_arr = np.zeros(image.GetSize()[::-1], dtype=np.uint8) # SITK: x,y,z -> Numpy: z,y,x
+        
+        spacing = image.GetSpacing() # sx, sy, sz
+        origin = image.GetOrigin()
+        
+        for rib_name, points in centerlines.items():
+            for pt in points:
+                phys_pt = pt
+                idx_x = int((phys_pt[0] - origin[0]) / spacing[0])
+                idx_y = int((phys_pt[1] - origin[1]) / spacing[1])
+                idx_z = int((phys_pt[2] - origin[2]) / spacing[2])
+                
+                avg_spacing = np.mean(spacing)
+                radius_vox = int(np.ceil(self.radius / avg_spacing))
+                
+                z_dim, y_dim, x_dim = mask_arr.shape
+                
+                for z in range(max(0, idx_z - radius_vox), min(z_dim, idx_z + radius_vox + 1)):
+                    for y in range(max(0, idx_y - radius_vox), min(y_dim, idx_y + radius_vox + 1)):
+                        for x in range(max(0, idx_x - radius_vox), min(x_dim, idx_x + radius_vox + 1)):
+                            dist_sq = (x - idx_x)**2 + (y - idx_y)**2 + (z - idx_z)**2
+                            if dist_sq <= radius_vox**2:
+                                mask_arr[z, y, x] = 1
+                                
+        mask_img = sitk.GetImageFromArray(mask_arr)
+        mask_img.CopyInformation(image)
+        return mask_img
+
+        
+    def augment_item(self, image, centerlines):
+        """
+        Applies random rigid transformation (Rotation + Translation) to image and centerlines.
+        """
+        # Random Parameters
+        angle_z = np.radians(np.random.uniform(-15, 15))
+        tx = np.random.uniform(-10, 10) # mm
+        ty = np.random.uniform(-10, 10)
+        tz = np.random.uniform(-10, 10)
+        
+        # Transform
+        transform = sitk.Euler3DTransform()
+        
+        # Center of rotation (Image Center)
+        size = image.GetSize()
+        origin = image.GetOrigin()
+        spacing = image.GetSpacing()
+        center_idx = [sz/2.0 for sz in size]
+        # center_phys = origin + center_idx * spacing (element-wise)
+        center_phys = [origin[d] + center_idx[d]*spacing[d] for d in range(3)]
+        
+        transform.SetCenter(center_phys)
+        transform.SetRotation(0, 0, angle_z)
+        transform.SetTranslation((tx, ty, tz))
+        
+        # Resample Image
+        # Use bilinear or bspline? Linear is fast.
+        aug_image = sitk.Resample(image, image, transform, sitk.sitkLinear, 0.0, image.GetPixelID())
+        
+        # Transform Centerlines
+        aug_centerlines = {}
+        for rib, pts in centerlines.items():
+            new_pts = []
+            for pt in pts:
+                # pt is (x,y,z) physical
+                # The transform maps Output Point -> Input Point for resampling.
+                # But for points, we want T(p).
+                # sitk.Resample(ref, transform) means: output(x) = input(transform(x)).
+                # So the transform describes "Where to look in input".
+                # This is the INVERSE of the coordinate transform if we think "Move the object".
+                # If we use transform.TransformPoint(pt), we are applying the "Sampling Transform".
+                # Wait.
+                # Resample: I_new(x) = I_old(T(x)).
+                # T maps New Space -> Old Space.
+                # If T is "Rotation +15 deg", then T(x) rotates x by +15.
+                # So I_new(x) gets value from I_old(x rotated).
+                # This means the content moves by -15 deg ??
+                # Let's verify.
+                # If I_new(0) = I_old(T(0)).
+                # This is standard "Pull back".
+                
+                # For centerlines (Points), we want the points to match the NEW image content.
+                # The new image content at `x` corresponds to old content at `T(x)`.
+                # So if a feature was at `p_old` in old image, where is it in `p_new`?
+                # We want `p_old = T(p_new)`.
+                # So `p_new = T_inv(p_old)`.
+                
+                # So we need the INVERSE transform for points.
+                
+                p_inv = transform.GetInverse().TransformPoint(pt)
+                new_pts.append(p_inv)
+            aug_centerlines[rib] = np.array(new_pts)
+            
+        return aug_image, aug_centerlines
+
+    def get_samples_from_data(self, image, centerlines, num_samples=1000):
+        """
+        Samples points (indices) from the provided image/centerlines.
+        Used by get_training_samples and external callers.
+        """
+        img_arr = sitk.GetArrayFromImage(image) # View might be risky if we modify? GetArray is copy.
+        # Actually we just need shape.
+        z_dim, y_dim, x_dim = img_arr.shape
+        spacing = image.GetSpacing()
+        origin = image.GetOrigin()
+        
+        # 1. Positive Samples
+        pos_samples = []
+        all_rib_points = []
+        for r, pts in centerlines.items():
+            all_rib_points.extend(pts)
+            
+        if not all_rib_points:
+            return [], []
+
+        # Sample random points from centerline
+        selected_indices = np.random.choice(len(all_rib_points), size=num_samples // 2, replace=True)
+        
+        for i in selected_indices:
+            pt = all_rib_points[i]
+            
+            # Physical -> Index
+            # We must use proper rounding or simple cast
+            idx_x = int((pt[0] - origin[0]) / spacing[0])
+            idx_y = int((pt[1] - origin[1]) / spacing[1])
+            idx_z = int((pt[2] - origin[2]) / spacing[2])
+            
+            # Check bounds
+            if (0 <= idx_z < z_dim and 
+                0 <= idx_y < y_dim and 
+                0 <= idx_x < x_dim):
+                pos_samples.append(((idx_x, idx_y, idx_z), 1))
+                
+        # 2. Negative Samples
+        neg_samples = []
+        
+        count = 0
+        while count < num_samples // 2:
+            rz = np.random.randint(0, z_dim)
+            ry = np.random.randint(0, y_dim)
+            rx = np.random.randint(0, x_dim)
+            
+            # TODO: Check collision with positive?
+            neg_samples.append(((rx, ry, rz), 0))
+            count += 1
+            
+        return pos_samples, neg_samples
+
+    def get_training_samples(self, idx, num_samples=1000):
+        """
+        Wrapper to load item and get samples (No augmentation by default).
+        """
+        image, centerlines, _ = self.load_item(idx)
+        return self.get_samples_from_data(image, centerlines, num_samples)

ribline/data/image_reader.py

@@ -0,0 +1,140 @@
+import os
+import struct
+import numpy as np
+import SimpleITK as sitk
+
+def read_custom_header(header_path):
+    """
+    Reads the custom text-based header.
+    Format:
+    dim_x dim_y dim_z
+    spacing_x spacing_y spacing_z
+    min_val max_val (optional/ignored for loading)
+    """
+    with open(header_path, 'r') as f:
+        lines = f.readlines()
+        
+    if len(lines) < 2:
+        raise ValueError("Header too short")
+        
+    dims = [int(x) for x in lines[0].strip().split()]
+    spacing = [float(x) for x in lines[1].strip().split()]
+    
+    # We assume int16 based on file size analysis (2 bytes/pixel)
+    dtype = np.int16
+    
+    # Analyze usually stores x, y, z.
+    # We return shape as (x, y, z) for consistency with previous logic, 
+    # but remember numpy uses (z, y, x)
+    # We return origin as (0,0,0) because GT ignores the header offset
+    origin = (0.0, 0.0, 0.0)
+    return dims, spacing, dtype, origin
+
+def read_analyze75_header(header_path):
+    """
+    Reads the header of an Analyze 7.5 file (binary) or custom text header.
+    """
+    # Try text first as we confirmed it for this dataset
+    try:
+        return read_custom_header(header_path)
+    except Exception:
+        pass
+
+    with open(header_path, 'rb') as f:
+        header_data = f.read()
+
+    if len(header_data) < 348:
+         raise ValueError("Header too short for Analyze 7.5")
+
+    # Dim is at offset 40, 8 shorts (16 bytes)
+    dim = struct.unpack_from('<8h', header_data, 40)
+    
+    # Pixdim is at offset 76, 8 floats (32 bytes)
+    pixdim = struct.unpack_from('<8f', header_data, 76)
+    
+    # DataType is at offset 70 (short)
+    datatype_code = struct.unpack_from('<h', header_data, 70)[0]
+    
+    dtype_map = {
+        2: np.uint8,
+        4: np.int16,
+        8: np.int32,
+        16: np.float32,
+        64: np.float64
+    }
+    
+    if datatype_code not in dtype_map:
+        # Fallback or error? 
+        # If we reached here, text parse failed.
+        # Maybe it IS Big Endian?
+        datatype_code_be = struct.unpack_from('>h', header_data, 70)[0]
+        if datatype_code_be in dtype_map:
+             datatype_code = datatype_code_be
+             # We should switch to BE unpacking for everything, but let's assume LE for now
+        else:
+             raise ValueError(f"Unsupported Analyze 7.5 datatype code: {datatype_code}")
+        
+    dtype = dtype_map[datatype_code]
+    
+    ndim = dim[0]
+    shape = dim[1:ndim+1]
+    spacing = pixdim[1:ndim+1]
+    
+    return shape, spacing, dtype, (0.0, 0.0, 0.0) # Binary fallback origin
+
+def read_analyze75_numpy(path):
+    """
+    Reads an Analyze 7.5 image pair (.img/.hdr) using numpy.
+    Args:
+        path (str): Path to .img or .hdr file.
+    Returns:
+        sitk.Image: SimpleITK Image object created from numpy array.
+    """
+    base, ext = os.path.splitext(path)
+    if ext == '.gz':
+        base, ext2 = os.path.splitext(base)
+        ext = ext2 + ext
+        
+    hdr_path = base + '.hdr'
+    img_path = base + '.img'
+    
+    if not os.path.exists(hdr_path) or not os.path.exists(img_path):
+        raise FileNotFoundError(f"Analyze 7.5 pair not found: {hdr_path}, {img_path}")
+        
+    shape, spacing, dtype, origin = read_analyze75_header(hdr_path)
+    
+    # Determine total elements
+    num_elements = np.prod(shape)
+    
+    # Read raw data
+    arr = np.fromfile(img_path, dtype=dtype)
+    
+    if arr.size != num_elements:
+        raise ValueError(f"File size mismatch. Expected {num_elements} elements, got {arr.size}")
+        
+    # Reshape: ITK expects [z, y, x] for numpy array access
+    # Shape from header is usually [x, y, z]
+    # We reshape to [z, y, x]
+    arr = arr.reshape(shape[::-1]) 
+    
+    image = sitk.GetImageFromArray(arr)
+    image.SetSpacing(spacing)
+    image.SetOrigin((0.0, 0.0, 0.0))  # Force origin to 0 for this dataset
+    
+    return image
+
+def load_image(path):
+    """
+    Robust image loader that attempts SimpleITK first, then falls back to custom Analyze reader.
+    """
+    try:
+        return sitk.ReadImage(path)
+    except Exception as e:
+        if path.endswith('.img') or path.endswith('.hdr'):
+            try:
+                # print(f"SimpleITK failed, attempting custom Analyze 7.5 reader for {path}")
+                return read_analyze75_numpy(path)
+            except Exception as e2:
+                print(f"Custom reader also failed: {e2}")
+                raise e
+        raise e