kneeseg 0.1.0__tar.gz

kneeseg-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include kneeseg/configs/*.json
+include kneeseg/data/*.json
+include README.md
+recursive-include kneeseg *.json

kneeseg-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: kneeseg
+Version: 0.1.0
+Summary: A Python reimplementation of Semantic Context Forests for Knee Cartilage Segmentation
+Author-email: Quan Wang <quanw@google.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: joblib
+Requires-Dist: tqdm
+Requires-Dist: SimpleITK
+
+# kneeseg: Knee Bone & Cartilage Segmentation in 3D MRI
+
+[![Python Package](https://github.com/wq2012/kneeseg/actions/workflows/python-package.yml/badge.svg)](https://github.com/wq2012/kneeseg/actions/workflows/python-package.yml)
+
+**kneeseg** is a Python reimplementation of the paper "Semantic Context Forests for Learning-Based Knee Cartilage Segmentation in 3D MR Images". [[paper](resources/knee_MCV_2013_paper.pdf)] [[slides](resources/knee_MCV_2013_slides.pdf)]
+
+|                 | Original MICCAI Workshop Paper | This Implementation |
+|-----------------|----------------|---------------------|
+| **Bone Segmentation** | Active Shape Model (Siemens proprietary) | Dense Random Forest (Auto-Context) |
+| **Cartilage Segmentation** | [Semantic Context Forest (C++)](https://github.com/wq2012/DecisionForest) | Semantic Context Forest (Python) |
+| **Dataset** |  Osteoarthritis Initiative (OAI) | [SKI10](https://ski10.grand-challenge.org/) |
+
+## Table of Contents
+1. [Installation](#installation)
+2. [Usage](#usage)
+3. [Experiments Folder](#experiments-folder)
+4. [Experiment Results (SKI10)](#experiment-results-ski10)
+5. [Algorithm Details](#algorithm-details)
+6. [Citation](#citation)
+
+## Installation
+
+You can install the package via pip:
+
+```bash
+pip install kneeseg
+```
+
+## Usage
+
+### As a Library
+```python
+from kneeseg.io import load_volume
+from kneeseg.bone_rf import BoneClassifier
+# ...
+```
+
+### Running the Pipeline
+The package includes a unified pipeline script `kneeseg-pipeline` (or via python module):
+
+```bash
+# Run using the installed command
+kneeseg-pipeline --data-dir /path/to/SKI10/data
+```
+
+> For advanced usage and reproduction scripts (e.g., training models from scratch), please refer to the [Experiments Documentation](experiments/README.md).
+
+## Experiments Folder
+The `experiments/` directory contains reproduceable scripts and will store the output models (`models/`) and predictions (`predictions/`) if you run the scripts provided there. See [experiments/README.md](experiments/README.md) for details.
+
+## Experiment Results (SKI10)
+Since the [SKI10 dataset](https://ski10.grand-challenge.org/) doesn not provide the ground truth labels for its default testing set, we evaluated the pipeline on a **20% hold-out set** (20 cases) from the SKI10 training data (Total 80 cases: 60 Train, 20 Eval).
+
+### Metrics
+| Structure | Dice Similarity Coefficient (DSC) |
+|-----------|-----------------------------------|
+| **Femur** | 0.9046 ± 0.0361 |
+| **Tibia** | 0.9292 ± 0.0260 |
+| **Femoral Cartilage** | 0.5944 ± 0.0654 |
+| **Tibial Cartilage** | 0.5805 ± 0.0533 |
+
+### Evaluation Set
+The following 20 cases were held out for evaluation:
+`image-004`, `image-005`, `image-012`, `image-014`, `image-015`, `image-018`, `image-028`, `image-029`, `image-030`, `image-032`, `image-036`, `image-055`, `image-065`, `image-070`, `image-076`, `image-082`, `image-087`, `image-089`, `image-095`, `image-098`.
+
+## Algorithm Details
+
+### Bone Segmentation (Dense Auto-Context RF)
+1.  **Pass 1**: Dense Random Forest voxel classification.
+    - **Features**: Normalized Intensity, Gaussian Smoothed Intensity ($\sigma=2.0, 4.0$), Spatial Coordinates, RSID (20 offsets).
+    - **Target**: 3-class classification (Background, Femur, Tibia).
+
+2.  **Pass 2 (Refinement)**: Auto-Context Random Forest.
+    - **Features**: All Pass 1 features + **Probabilities from Pass 1**.
+    - **Performance**: Achieves >0.90 DSC on Bones.
+
+### Cartilage Segmentation (Semantic Context Forest)
+1.  **Feature Extraction**:
+    - **Semantic Context**: Signed Distance Transforms (SDT) computed from Pass 2 bone masks.
+    - **Texture**: RSID (30 offsets).
+    - **Local**: Intensity, Gaussian ($\sigma=1.0$), Gradient.
+    - **Arithmetic**: DT Sum/Diff.
+2.  **Classification**: Dense Random Forest (100 trees).
+    - **Performance**: Achieves ~0.60 DSC.
+
+## Citation
+
+**Plain Text:**
+
+> Quan Wang, Dijia Wu, Le Lu, Meizhu Liu, Kim L. Boyer, and Shaohua Kevin Zhou.
+> "Semantic Context Forests for Learning-Based Knee Cartilage Segmentation in 3D MR Images."
+> MICCAI 2013: Workshop on Medical Computer Vision.
+
+> Quan Wang.
+> Exploiting Geometric and Spatial Constraints for Vision and Lighting Applications.
+> Ph.D. dissertation, Rensselaer Polytechnic Institute, 2014.
+
+**BibTeX:**
+
+```bibtex
+@inproceedings{wang2013semantic,
+  title={Semantic context forests for learning-based knee cartilage segmentation in 3D MR images},
+  author={Wang, Quan and Wu, Dijia and Lu, Le and Liu, Meizhu and Boyer, Kim L and Zhou, Shaohua Kevin},
+  booktitle={International MICCAI Workshop on Medical Computer Vision},
+  pages={105--115},
+  year={2013},
+  organization={Springer}
+}
+
+@phdthesis{wang2014exploiting,
+  title={Exploiting Geometric and Spatial Constraints for Vision and Lighting Applications},
+  author={Quan Wang},
+  year={2014},
+  school={Rensselaer Polytechnic Institute},
+}
+```

kneeseg-0.1.0/README.md

@@ -0,0 +1,116 @@
+# kneeseg: Knee Bone & Cartilage Segmentation in 3D MRI
+
+[![Python Package](https://github.com/wq2012/kneeseg/actions/workflows/python-package.yml/badge.svg)](https://github.com/wq2012/kneeseg/actions/workflows/python-package.yml)
+
+**kneeseg** is a Python reimplementation of the paper "Semantic Context Forests for Learning-Based Knee Cartilage Segmentation in 3D MR Images". [[paper](resources/knee_MCV_2013_paper.pdf)] [[slides](resources/knee_MCV_2013_slides.pdf)]
+
+|                 | Original MICCAI Workshop Paper | This Implementation |
+|-----------------|----------------|---------------------|
+| **Bone Segmentation** | Active Shape Model (Siemens proprietary) | Dense Random Forest (Auto-Context) |
+| **Cartilage Segmentation** | [Semantic Context Forest (C++)](https://github.com/wq2012/DecisionForest) | Semantic Context Forest (Python) |
+| **Dataset** |  Osteoarthritis Initiative (OAI) | [SKI10](https://ski10.grand-challenge.org/) |
+
+## Table of Contents
+1. [Installation](#installation)
+2. [Usage](#usage)
+3. [Experiments Folder](#experiments-folder)
+4. [Experiment Results (SKI10)](#experiment-results-ski10)
+5. [Algorithm Details](#algorithm-details)
+6. [Citation](#citation)
+
+## Installation
+
+You can install the package via pip:
+
+```bash
+pip install kneeseg
+```
+
+## Usage
+
+### As a Library
+```python
+from kneeseg.io import load_volume
+from kneeseg.bone_rf import BoneClassifier
+# ...
+```
+
+### Running the Pipeline
+The package includes a unified pipeline script `kneeseg-pipeline` (or via python module):
+
+```bash
+# Run using the installed command
+kneeseg-pipeline --data-dir /path/to/SKI10/data
+```
+
+> For advanced usage and reproduction scripts (e.g., training models from scratch), please refer to the [Experiments Documentation](experiments/README.md).
+
+## Experiments Folder
+The `experiments/` directory contains reproduceable scripts and will store the output models (`models/`) and predictions (`predictions/`) if you run the scripts provided there. See [experiments/README.md](experiments/README.md) for details.
+
+## Experiment Results (SKI10)
+Since the [SKI10 dataset](https://ski10.grand-challenge.org/) doesn not provide the ground truth labels for its default testing set, we evaluated the pipeline on a **20% hold-out set** (20 cases) from the SKI10 training data (Total 80 cases: 60 Train, 20 Eval).
+
+### Metrics
+| Structure | Dice Similarity Coefficient (DSC) |
+|-----------|-----------------------------------|
+| **Femur** | 0.9046 ± 0.0361 |
+| **Tibia** | 0.9292 ± 0.0260 |
+| **Femoral Cartilage** | 0.5944 ± 0.0654 |
+| **Tibial Cartilage** | 0.5805 ± 0.0533 |
+
+### Evaluation Set
+The following 20 cases were held out for evaluation:
+`image-004`, `image-005`, `image-012`, `image-014`, `image-015`, `image-018`, `image-028`, `image-029`, `image-030`, `image-032`, `image-036`, `image-055`, `image-065`, `image-070`, `image-076`, `image-082`, `image-087`, `image-089`, `image-095`, `image-098`.
+
+## Algorithm Details
+
+### Bone Segmentation (Dense Auto-Context RF)
+1.  **Pass 1**: Dense Random Forest voxel classification.
+    - **Features**: Normalized Intensity, Gaussian Smoothed Intensity ($\sigma=2.0, 4.0$), Spatial Coordinates, RSID (20 offsets).
+    - **Target**: 3-class classification (Background, Femur, Tibia).
+
+2.  **Pass 2 (Refinement)**: Auto-Context Random Forest.
+    - **Features**: All Pass 1 features + **Probabilities from Pass 1**.
+    - **Performance**: Achieves >0.90 DSC on Bones.
+
+### Cartilage Segmentation (Semantic Context Forest)
+1.  **Feature Extraction**:
+    - **Semantic Context**: Signed Distance Transforms (SDT) computed from Pass 2 bone masks.
+    - **Texture**: RSID (30 offsets).
+    - **Local**: Intensity, Gaussian ($\sigma=1.0$), Gradient.
+    - **Arithmetic**: DT Sum/Diff.
+2.  **Classification**: Dense Random Forest (100 trees).
+    - **Performance**: Achieves ~0.60 DSC.
+
+## Citation
+
+**Plain Text:**
+
+> Quan Wang, Dijia Wu, Le Lu, Meizhu Liu, Kim L. Boyer, and Shaohua Kevin Zhou.
+> "Semantic Context Forests for Learning-Based Knee Cartilage Segmentation in 3D MR Images."
+> MICCAI 2013: Workshop on Medical Computer Vision.
+
+> Quan Wang.
+> Exploiting Geometric and Spatial Constraints for Vision and Lighting Applications.
+> Ph.D. dissertation, Rensselaer Polytechnic Institute, 2014.
+
+**BibTeX:**
+
+```bibtex
+@inproceedings{wang2013semantic,
+  title={Semantic context forests for learning-based knee cartilage segmentation in 3D MR images},
+  author={Wang, Quan and Wu, Dijia and Lu, Le and Liu, Meizhu and Boyer, Kim L and Zhou, Shaohua Kevin},
+  booktitle={International MICCAI Workshop on Medical Computer Vision},
+  pages={105--115},
+  year={2013},
+  organization={Springer}
+}
+
+@phdthesis{wang2014exploiting,
+  title={Exploiting Geometric and Spatial Constraints for Vision and Lighting Applications},
+  author={Quan Wang},
+  year={2014},
+  school={Rensselaer Polytechnic Institute},
+}
+```

kneeseg-0.1.0/kneeseg/bone_rf.py

@@ -0,0 +1,142 @@
+
+from sklearn.ensemble import RandomForestClassifier
+import numpy as np
+import joblib
+from .features import extract_features, compute_rsid_features
+from scipy.ndimage import gaussian_filter
+
+class BoneClassifier:
+    def __init__(self, n_estimators=100, max_depth=25, n_jobs=-1):
+        self.clf = RandomForestClassifier(
+            n_estimators=n_estimators, 
+            max_depth=max_depth, 
+            n_jobs=n_jobs,
+            random_state=42,
+            class_weight='balanced'
+        )
+
+    def extract_bone_features(self, image, prob_map=None, spacing=None):
+        """
+        Extract features suitable for Bone Segmentation.
+        Focuses on larger context and spatial coordinates.
+        """
+        features = []
+        
+        # Normalize
+        img_mean = image.mean()
+        img_std = image.std()
+        img_norm = (image.astype(np.float32) - img_mean) / (img_std + 1e-6)
+        
+        # 1. Intensity & Smooth (Multi-scale)
+        features.append(img_norm.flatten())
+        features.append(gaussian_filter(img_norm, sigma=2.0).flatten())
+        features.append(gaussian_filter(img_norm, sigma=4.0).flatten())
+        
+        # 2. Spatial Coordinates (Normalized 0-1)
+        z, y, x = np.mgrid[0:image.shape[0], 0:image.shape[1], 0:image.shape[2]]
+        features.append(z.flatten() / image.shape[0])
+        features.append(y.flatten() / image.shape[1])
+        features.append(x.flatten() / image.shape[2])
+        
+        # 3. RSID (Texture) - Sparse but helpful
+        # Keep shift small-ish but larger than cartilage
+        # Downsample image for RSID to save memory? No, standard RSID.
+        rsid = compute_rsid_features(img_norm, num_shifts=20, max_shift=20, seed=42)
+        for i in range(rsid.shape[-1]):
+             features.append(rsid[..., i].flatten())
+             
+        # 4. Auto-Context Probabilities
+        if prob_map is not None:
+            # prob_map is (Z, Y, X, C)
+            for c in range(prob_map.shape[-1]):
+                p_ch = prob_map[..., c]
+                features.append(p_ch.flatten())
+                features.append(gaussian_filter(p_ch, sigma=2.0).flatten())
+                
+        return np.stack(features, axis=1)
+
+    def train(self, images, labels, prob_maps=None, subsample=100000):
+        """
+        images: list of 3D arrays
+        labels: list of 3D arrays (0=bg, 1=Femur, 2=FemCart, 3=Tibia, 4=TibCart)
+        prob_maps: list of 3D probability maps (optional)
+        """
+        X_all = []
+        y_all = []
+        
+        print(f"    Extracting features for Bone RF (ProbMap={prob_maps is not None})...")
+        for i, (img, lbl) in enumerate(zip(images, labels)):
+            # Map Labels
+            # Femur(1) + FemCart(2) -> Femur (1)
+            # Tibia(3) + TibCart(4) -> Tibia (2)
+            # Background -> 0
+            
+            y_mapped = np.zeros_like(lbl, dtype=np.uint8)
+            y_mapped[lbl == 1] = 1 # Femur
+            y_mapped[lbl == 2] = 1 # FemCart -> Femur (Segment the whole joint head)
+            y_mapped[lbl == 3] = 2 # Tibia
+            y_mapped[lbl == 4] = 2 # TibCart -> Tibia
+            
+            # Subsample
+            # We need balanced sampling.
+            # 1. All Bone Voxels (or large subset)
+            # 2. Subset of Background (especially near bones)
+            
+            mask_bone = (y_mapped > 0)
+            target_indices = np.argwhere(mask_bone)
+            
+            # Dilate bone mask to find "Near Background"
+            from scipy.ndimage import binary_dilation
+            mask_near = binary_dilation(mask_bone, iterations=10) & (~mask_bone)
+            near_indices = np.argwhere(mask_near)
+            
+            # Far background
+            far_indices = np.argwhere((~mask_bone) & (~mask_near))
+            
+            # Select samples
+            n_bone = len(target_indices)
+            n_near = min(len(near_indices), n_bone) # 1:1 Bone:Near
+            n_far = min(len(far_indices), n_bone // 4) # fewer far samples
+            
+            idx_bone = np.random.choice(len(target_indices), min(n_bone, subsample//2), replace=False)
+            idx_near = np.random.choice(len(near_indices), min(n_near, subsample//4), replace=False)
+            idx_far = np.random.choice(len(far_indices), min(n_far, subsample//8), replace=False)
+            
+            coords = np.vstack([
+                target_indices[idx_bone],
+                near_indices[idx_near],
+                far_indices[idx_far]
+            ])
+            
+            pm = prob_maps[i] if prob_maps else None
+            feats_flat = self.extract_bone_features(img, prob_map=pm) # (N_all, F)
+            
+            # Convert 3D coords to 1D indices
+            flat_indices = np.ravel_multi_index(coords.T, img.shape)
+            
+            X_case = feats_flat[flat_indices]
+            y_case = y_mapped.flatten()[flat_indices]
+            
+            X_all.append(X_case)
+            y_all.append(y_case)
+            
+        print("    Fitting Bone Random Forest...")
+        self.clf.fit(np.vstack(X_all), np.concatenate(y_all))
+
+    def predict(self, image, prob_map=None):
+        feats_flat = self.extract_bone_features(image, prob_map)
+        
+        # Predict in chunks to be safe? Or full.
+        # 100GB RAM. Image ~10M voxels. Features ~30 floats -> 300MB * 4 = 1.2GB.
+        # Easy.
+        
+        y_pred = self.clf.predict(feats_flat)
+        y_prob = self.clf.predict_proba(feats_flat)
+        
+        return y_pred.reshape(image.shape), y_prob.reshape(image.shape + (-1,))
+
+    def save(self, path):
+        joblib.dump(self.clf, path)
+
+    def load(self, path):
+        self.clf = joblib.load(path)

kneeseg-0.1.0/kneeseg/configs/config_schema.json

@@ -0,0 +1,144 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Knee Segmentation Configuration",
+    "type": "object",
+    "properties": {
+        "data_config": {
+            "type": "object",
+            "description": "Configuration for data directories and file lists",
+            "properties": {
+                "image_directory": {
+                    "type": "string",
+                    "description": "Path to the directory containing input image volumes (e.g., .mhd or .hdr files)."
+                },
+                "label_directory": {
+                    "type": "string",
+                    "description": "Path to the directory containing ground truth label volumes. Required for training and optional evaluation."
+                },
+                "split_file": {
+                    "type": "string",
+                    "description": "Optional path to a JSON file defining 'train' and 'eval' file lists."
+                },
+                "select_files": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Explicit list of filenames to process. If provided, overrides all other filtering."
+                }
+            },
+            "required": [
+                "image_directory"
+            ],
+            "additionalProperties": false
+        },
+        "training_config": {
+            "type": "object",
+            "description": "Parameters for model training",
+            "properties": {
+                "augmentation": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether to apply random data augmentation (rotation, noise) during training."
+                },
+                "bone_parameters": {
+                    "type": "object",
+                    "properties": {
+                        "pca_components": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "Number of principal components for the Active Shape Model."
+                        },
+                        "subsample_points": {
+                            "type": "integer",
+                            "default": 1000,
+                            "description": "Number of surface points to sample per case for PCA training."
+                        }
+                    },
+                    "additionalProperties": false
+                },
+                "cartilage_parameters": {
+                    "type": "object",
+                    "properties": {
+                        "n_estimators": {
+                            "type": "integer",
+                            "default": 100,
+                            "description": "Number of trees in the Random Forest classifier."
+                        },
+                        "max_depth": {
+                            "type": "integer",
+                            "default": 15,
+                            "description": "Maximum depth of the Random Forest trees."
+                        },
+                        "subsample_voxels_per_case": {
+                            "type": "integer",
+                            "default": 50000,
+                            "description": "Max number of voxels to sample per training case to balance speed and memory."
+                        },
+                        "training_proximity_mm": {
+                            "type": "number",
+                            "default": 10.0,
+                            "description": "Proximity (in mm) to bone surfaces for selecting cartilage training samples."
+                        }
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "inference_config": {
+            "type": "object",
+            "description": "Parameters for prediction and post-processing",
+            "properties": {
+                "use_random_walker": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether to apply Random Walker refinement to the initial classifier output."
+                },
+                "random_walker_beta": {
+                    "type": "number",
+                    "default": 130.0,
+                    "description": "Beta parameter for the Random Walker (controls edge sensitivity)."
+                },
+                "inference_proximity_mm": {
+                    "type": "number",
+                    "default": 15.0,
+                    "description": "Proximity (in mm) to detected bone surfaces for cartilage classification."
+                },
+                "perform_evaluation": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "If true, the inference script will attempt to calculate Dice scores against ground truth."
+                }
+            },
+            "additionalProperties": false
+        },
+        "output_config": {
+            "type": "object",
+            "description": "Configuration for saving results",
+            "properties": {
+                "model_directory": {
+                    "type": "string",
+                    "description": "Directory where trained models (.joblib) will be saved or loaded from."
+                },
+                "prediction_directory": {
+                    "type": "string",
+                    "description": "Directory where predicted segmentation volumes will be saved."
+                },
+                "evaluation_report_path": {
+                    "type": "string",
+                    "description": "Path to save the final quantitative evaluation report (JSON)."
+                }
+            },
+            "required": [
+                "model_directory"
+            ],
+            "additionalProperties": false
+        }
+    },
+    "required": [
+        "data_config",
+        "output_config"
+    ],
+    "additionalProperties": false
+}

kneeseg-0.1.0/kneeseg/configs/example_train_config.json

@@ -0,0 +1,6 @@
+{
+    "data_dir": "path/to/data",
+    "model_dir": "models",
+    "n_estimators": 100,
+    "max_depth": 15
+}

kneeseg-0.1.0/kneeseg/configs/ski10_full_inference_config.json

@@ -0,0 +1,21 @@
+
+{
+    "data_config": {
+        "image_directory": "/usr/local/google/home/quanw/Code/siemens_2012/Data/SKI10/TrainingData",
+        "label_directory": "/usr/local/google/home/quanw/Code/siemens_2012/Data/SKI10/TrainingData_labels",
+        "split_file": "/usr/local/google/home/quanw/Code/siemens_2012/experiments/ski10_full_split.json"
+    },
+    "inference_config": {
+        "inference_proximity_mm": 10.0,
+        "use_random_walker": true,
+        "random_walker_beta": 130.0,
+        "active_search_iters": 20,
+        "active_search_range": 25
+    },
+    "model_config": {
+        "model_directory": "/usr/local/google/home/quanw/Code/siemens_2012/experiments/ski10_full_models_repro"
+    },
+    "output_config": {
+        "prediction_directory": "/usr/local/google/home/quanw/Code/siemens_2012/experiments/ski10_improved_predictions"
+    }
+}

kneeseg-0.1.0/kneeseg/configs/ski10_full_train_config.json

@@ -0,0 +1,24 @@
+
+{
+    "data_config": {
+        "image_directory": "/usr/local/google/home/quanw/Code/siemens_2012/Data/SKI10/TrainingData",
+        "label_directory": "/usr/local/google/home/quanw/Code/siemens_2012/Data/SKI10/TrainingData_labels",
+        "split_file": "/usr/local/google/home/quanw/Code/siemens_2012/experiments/ski10_full_split.json"
+    },
+    "training_config": {
+        "augmentation": true,
+        "bone_parameters": {
+            "pca_components": 20,
+            "subsample_points": 2000
+        },
+        "cartilage_parameters": {
+            "n_estimators": 100,
+            "max_depth": 20,
+            "subsample_voxels_per_case": 20000,
+            "training_proximity_mm": 15.0
+        }
+    },
+    "output_config": {
+        "model_directory": "/usr/local/google/home/quanw/Code/siemens_2012/experiments/ski10_full_models_repro"
+    }
+}