thigh-us-segmentation 0.1.0__tar.gz

thigh_us_segmentation-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: thigh-us-segmentation
+Version: 0.1.0
+Summary: Pipeline for thigh ultrasound segmentation using nnU-Net and feature extraction
+Author: Mara Concepción Alvarez, Paula Crespo Ortega, Arantxa Villanueva Larre, Rafael Cabeza Laguna
+Requires-Python: <3.12,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: SimpleITK
+Requires-Dist: opencv-python
+Requires-Dist: spicy
+Requires-Dist: matplotlib
+Requires-Dist: pyradiomics
+Requires-Dist: requests
+Requires-Dist: nnunetv2==2.6.4
+
+# ThighUSSegmentation
+
+Python library for automatic thigh ultrasound segmentation and analysis using nnU-Net.
+
+## Features
+
+- Automatic image conversion to `.mha`
+- Preprocessing (active region detection)
+- nnU-Net inference
+- Muscle thickness computation
+- Radiomics feature extraction
+- Export of anatomical landmarks (`.mrk.json`)
+- Automatic model download from Zenodo
+
+## Installation
+
+```bash
+pip install thigh-us-segmentation
+```
+
+## Usage
+
+```python
+from ThighUSSegmentation import run_full_pipeline
+
+result = run_full_pipeline(
+    input_image_path="image.dcm",
+    output_root="outputs",
+    case_id = "case001"
+)
+
+print(result["df_results"])
+
+# OR
+result = run_full_pipeline(
+    input_image_path="image.mha",
+    output_root="outputs",
+    models_root="D:/mis_modelos", #You can also specify your own model path.
+)
+```
+
+## Output
+
+outputs/
+└── case001/
+    ├── image_converted.mha
+    ├── image_preprocessed.mha
+    ├── case001_labelmap.mha
+    ├── markups/
+    └── inference_log.txt
+
+## Returned Results
+
+The pipeline returns a dictionary:
+
+{
+    "case_id": str,
+    "segmentation_path": str,
+    "mrk_paths": dict,
+    "df_distances": pd.DataFrame,
+    "df_textures": pd.DataFrame,
+    "df_results": pd.DataFrame
+}
+
+## Model
+
+The pretrained nnU-Net model is automatically downloaded from Zenodo on first use.
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19914473.svg)](https://doi.org/10.5281/zenodo.19914473)
+
+Expected strucutre:
+
+Dataset001_ThighUS/
+└── nnUNetTrainer__nnUNetPlans__2d/
+    ├── dataset.json
+    ├── plans.json
+    ├── fold_0/
+    ├── fold_1/
+    ├── fold_2/
+    ├── fold_3/
+    └── fold_4/
+
+
+## Requirements
+
+· Python ≥ 3.9
+· SimpleITK
+· PyRadiomics
+· OpenCV
+· NumPy / SciPy / Pandas
+
+## Citation
+
+If you use this work, please cite:
+
+Isensee et al., nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature Methods (2021)
+
+Mara Concepción Alavarez. (2026).
+Thigh Ultrasound Segmentation Model (nnU-Net).
+Zenodo. https://doi.org/10.5281/zenodo.19914473
+
+## License
+
+This project uses the following licenses:
+· Code: MIT License (or the one you choose)
+· Model weights (Zenodo): CC-BY 4.0 
+

thigh_us_segmentation-0.1.0/README.md

@@ -0,0 +1,106 @@
+# ThighUSSegmentation
+
+Python library for automatic thigh ultrasound segmentation and analysis using nnU-Net.
+
+## Features
+
+- Automatic image conversion to `.mha`
+- Preprocessing (active region detection)
+- nnU-Net inference
+- Muscle thickness computation
+- Radiomics feature extraction
+- Export of anatomical landmarks (`.mrk.json`)
+- Automatic model download from Zenodo
+
+## Installation
+
+```bash
+pip install thigh-us-segmentation
+```
+
+## Usage
+
+```python
+from ThighUSSegmentation import run_full_pipeline
+
+result = run_full_pipeline(
+    input_image_path="image.dcm",
+    output_root="outputs",
+    case_id = "case001"
+)
+
+print(result["df_results"])
+
+# OR
+result = run_full_pipeline(
+    input_image_path="image.mha",
+    output_root="outputs",
+    models_root="D:/mis_modelos", #You can also specify your own model path.
+)
+```
+
+## Output
+
+outputs/
+└── case001/
+    ├── image_converted.mha
+    ├── image_preprocessed.mha
+    ├── case001_labelmap.mha
+    ├── markups/
+    └── inference_log.txt
+
+## Returned Results
+
+The pipeline returns a dictionary:
+
+{
+    "case_id": str,
+    "segmentation_path": str,
+    "mrk_paths": dict,
+    "df_distances": pd.DataFrame,
+    "df_textures": pd.DataFrame,
+    "df_results": pd.DataFrame
+}
+
+## Model
+
+The pretrained nnU-Net model is automatically downloaded from Zenodo on first use.
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19914473.svg)](https://doi.org/10.5281/zenodo.19914473)
+
+Expected strucutre:
+
+Dataset001_ThighUS/
+└── nnUNetTrainer__nnUNetPlans__2d/
+    ├── dataset.json
+    ├── plans.json
+    ├── fold_0/
+    ├── fold_1/
+    ├── fold_2/
+    ├── fold_3/
+    └── fold_4/
+
+
+## Requirements
+
+· Python ≥ 3.9
+· SimpleITK
+· PyRadiomics
+· OpenCV
+· NumPy / SciPy / Pandas
+
+## Citation
+
+If you use this work, please cite:
+
+Isensee et al., nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature Methods (2021)
+
+Mara Concepción Alavarez. (2026).
+Thigh Ultrasound Segmentation Model (nnU-Net).
+Zenodo. https://doi.org/10.5281/zenodo.19914473
+
+## License
+
+This project uses the following licenses:
+· Code: MIT License (or the one you choose)
+· Model weights (Zenodo): CC-BY 4.0 
+

thigh_us_segmentation-0.1.0/ThighUSSegmentation/__init__.py

@@ -0,0 +1,11 @@
+from .pipeline import run_full_pipeline
+from .textures import extract_textures_dataframe
+from .distances import extract_distances_dataframe
+from .preprocessing import preprocess_active_region
+
+__all__ = [
+    "run_full_pipeline",
+    "extract_textures_dataframe",
+    "extract_distances_dataframe",
+    "preprocess_active_region",
+]

thigh_us_segmentation-0.1.0/ThighUSSegmentation/distances.py

@@ -0,0 +1,299 @@
+from pathlib import Path
+import json
+
+import numpy as np
+import pandas as pd
+import SimpleITK as sitk
+import scipy.ndimage as ndi
+
+
+def largest_component(mask):
+    labeled, num = ndi.label(mask)
+    if num == 0:
+        return mask
+
+    sizes = ndi.sum(mask, labeled, range(1, num + 1))
+    largest = np.argmax(sizes) + 1
+    return labeled == largest
+
+
+def clean_rf_mask(mask_rf):
+    rf = largest_component(mask_rf)
+    rf = ndi.binary_erosion(rf, iterations=2)
+
+    dist = ndi.distance_transform_edt(rf)
+    rf_valid = dist > 2
+
+    return rf, rf_valid
+
+
+def compute_thickness(masks, img2d):
+    rf = masks["rf_clean"]
+    femur = masks["femur"]
+    epi = masks["epi"]
+
+    H, W = rf.shape
+
+    rf_vals = []
+    rf_max_vals = []
+    muscle_vals = []
+    sat_vals = []
+    vi_vals = []
+    lines = []
+
+    coords = np.column_stack(np.where(femur))
+
+    if len(coords) == 0:
+        return {"lines": []}
+
+    x_center = int(np.mean(coords[:, 1]))
+
+    y_min = np.min(coords[:, 0])
+    top_band = coords[coords[:, 0] < y_min + 3]
+
+    dist = np.abs(top_band[:, 1] - x_center)
+    idx = np.argmin(dist)
+
+    _, x_femur_c = top_band[idx]
+
+    window = 10
+    xmin = max(0, x_femur_c - window)
+    xmax = min(W, x_femur_c + window)
+
+    for x in range(xmin, xmax):
+        col_rf = rf[:, x]
+        col_femur = femur[:, x]
+        col_epi = epi[:, x]
+
+        if np.sum(col_rf) == 0:
+            continue
+
+        col_img = img2d[:, x]
+        y_rf = np.where(col_rf)[0]
+
+        if len(y_rf) < 5:
+            continue
+
+        y_rf_top = y_rf.min()
+        y_rf_bot = y_rf.max()
+
+        rf_max_vals.append(y_rf_bot - y_rf_top)
+
+        top_start = max(0, y_rf_top - 20)
+        top_end = y_rf_top
+        search_top = col_img[top_start:top_end]
+        y_top = np.argmax(search_top) + top_start if len(search_top) > 0 else y_rf_top
+
+        bot_start = y_rf_bot
+        bot_end = min(H, y_rf_bot + 20)
+        search_bot = col_img[bot_start:bot_end]
+        y_bot = np.argmax(search_bot) + bot_start if len(search_bot) > 0 else y_rf_bot
+
+        y_femur = np.where(col_femur)[0].min() if np.any(col_femur) else None
+        y_epi = np.where(col_epi)[0].max() if np.any(col_epi) else None
+
+        rf_vals.append(y_bot - y_top)
+
+        if y_femur is not None:
+            vi_vals.append(y_femur - y_bot)
+            muscle_vals.append(y_femur - y_top)
+
+        if y_epi is not None:
+            sat_vals.append(y_top - y_epi)
+
+        lines.append({
+            "x": int(x),
+            "y_top": int(y_top),
+            "y_bot": int(y_bot),
+            "y_femur": None if y_femur is None else int(y_femur),
+            "y_epi": None if y_epi is None else int(y_epi),
+        })
+
+    return {
+        "rf_mean": np.mean(rf_vals) if rf_vals else None,
+        "rf_median": np.median(rf_vals) if rf_vals else None,
+        "rf_alt": np.max(rf_max_vals) if rf_max_vals else None,
+        "vi_mean": np.mean(vi_vals) if vi_vals else None,
+        "muscle_mean": np.mean(muscle_vals) if muscle_vals else None,
+        "sat_mean": np.mean(sat_vals) if sat_vals else None,
+        "lines": lines,
+    }
+
+
+def make_point(label, x, y, img_sitk, description=""):
+    position = img_sitk.TransformIndexToPhysicalPoint((int(x), int(y), 0))
+
+    return {
+        "label": label,
+        "description": description,
+        "position": [
+            float(position[0]),
+            float(position[1]),
+            float(position[2]),
+        ],
+        "orientation": [
+            1.0, 0.0, 0.0,
+            0.0, 1.0, 0.0,
+            0.0, 0.0, 1.0,
+        ],
+        "selected": True,
+        "locked": False,
+        "visibility": True,
+        "positionStatus": "defined",
+    }
+
+
+def save_single_mrk(output_path, markup_type, control_points, color):
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if output_path.exists():
+        output_path.unlink()
+
+    mrk = {
+        "@schema": "https://raw.githubusercontent.com/Slicer/Slicer/main/Modules/Loadable/Markups/Resources/Schema/markups-schema-v1.0.3.json#",
+        "markups": [
+            {
+                "type": markup_type,
+                "coordinateSystem": "LPS",
+                "locked": False,
+                "labelFormat": "%N-%d",
+                "controlPoints": control_points,
+                "measurements": [],
+                "display": {
+                    "visibility": True,
+                    "color": color,
+                    "selectedColor": color,
+                    "glyphType": "Sphere3D",
+                    "glyphScale": 5.0,
+                    "textScale": 4.5,
+                },
+            }
+        ],
+    }
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(mrk, f, indent=4)
+
+    return output_path
+
+
+def save_points_mrk_json(thickness, output_dir, case_id, img_sitk):
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    lines = thickness.get("lines", [])
+
+    if len(lines) == 0:
+        raise ValueError("No hay líneas de medición para guardar puntos.")
+
+    line_center = lines[len(lines) // 2]
+
+    x_c = line_center["x"]
+    y_top_c = line_center["y_top"]
+    y_bot_c = line_center["y_bot"]
+    y_femur_c = line_center["y_femur"]
+    y_epi_c = line_center["y_epi"]
+
+    saved_paths = {}
+
+    points = {
+        "epidermis": ("Epidermis", y_epi_c, [1.0, 0.0, 0.0]),
+        "fascia_lata": ("Fascia Lata", y_top_c, [0.0, 1.0, 0.0]),
+        "aponeurosis": ("Aponeurosis", y_bot_c, [0.0, 0.0, 1.0]),
+        "femur": ("Femur", y_femur_c, [1.0, 1.0, 0.0]),
+    }
+
+    for key, (label, y, color) in points.items():
+        if y is None:
+            continue
+
+        path = output_dir / f"{case_id}_{key}.mrk.json"
+
+        saved_paths[key] = save_single_mrk(
+            output_path=path,
+            markup_type="Fiducial",
+            control_points=[
+                make_point(label, x_c, y, img_sitk)
+            ],
+            color=color,
+        )
+
+    if y_epi_c is not None and y_femur_c is not None:
+        path = output_dir / f"{case_id}_central_line.mrk.json"
+
+        saved_paths["central_line"] = save_single_mrk(
+            output_path=path,
+            markup_type="Line",
+            control_points=[
+                make_point("Central_start_epi", x_c, y_epi_c, img_sitk, "Central blanca"),
+                make_point("Central_end_femur", x_c, y_femur_c, img_sitk, "Central blanca"),
+            ],
+            color=[1.0, 1.0, 1.0],
+        )
+
+    return saved_paths
+
+
+def extract_distances_dataframe(
+    image_path: str,
+    mask_path: str,
+    output_mrk_json_path: str,
+    case_id: str | None = None,
+    epi_label: int = 1,
+    femur_label: int = 2,
+    rf_label: int = 3,
+):
+    image_path = Path(image_path)
+    mask_path = Path(mask_path)
+
+    if case_id is None:
+        case_id = mask_path.name.replace(".nii.gz", "").replace(".mha", "")
+
+    img_sitk = sitk.ReadImage(str(image_path))
+    lab_sitk = sitk.ReadImage(str(mask_path))
+
+    img = sitk.GetArrayFromImage(img_sitk)
+    lab = sitk.GetArrayFromImage(lab_sitk)
+
+    img2d = img[0]
+    lab2d = lab[0]
+
+    masks = {
+        "epi": lab2d == epi_label,
+        "femur": lab2d == femur_label,
+        "rf": lab2d == rf_label,
+    }
+
+    rf_clean, rf_valid = clean_rf_mask(masks["rf"])
+    masks["rf_clean"] = rf_clean
+    masks["rf_valid"] = rf_valid
+
+    thickness = compute_thickness(masks, img2d)
+
+    spacing = img_sitk.GetSpacing()
+    pixel_size_y = spacing[1]
+
+    def to_mm(value):
+        return None if value is None else float(value * pixel_size_y)
+
+    row = {
+        "case_id": case_id,
+        "rf_mm": to_mm(thickness.get("rf_mean")),
+        "rf_median_mm": to_mm(thickness.get("rf_median")),
+        "rf_alt_mm": to_mm(thickness.get("rf_alt")),
+        "vi_mm": to_mm(thickness.get("vi_mean")),
+        "sat_mm": to_mm(thickness.get("sat_mean")),
+        "muscle_mm": to_mm(thickness.get("muscle_mean")),
+    }
+
+    df = pd.DataFrame([row])
+
+    mrk_paths = save_points_mrk_json(
+        thickness=thickness,
+        output_dir=output_mrk_json_path,
+        case_id=case_id,
+        img_sitk=img_sitk,
+    )
+
+    return df, mrk_paths

thigh_us_segmentation-0.1.0/ThighUSSegmentation/io_conversion.py

@@ -0,0 +1,81 @@
+from pathlib import Path
+import shutil
+import logging
+
+import SimpleITK as sitk
+
+
+logger = logging.getLogger(__name__)
+
+
+def convert_to_mha(
+    input_path: str,
+    output_dir: str,
+    output_filename: str = "image_converted.mha",
+) -> str:
+    """
+    Convierte una imagen de entrada a .mha y la guarda dentro de output_dir.
+
+    Soporta:
+    - .mha
+    - .nii
+    - .nii.gz
+    - .dcm
+    - carpeta DICOM
+
+    La salida será:
+        output_dir / image_converted.mha
+    """
+
+    input_path = Path(input_path)
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if not input_path.exists():
+        raise FileNotFoundError(f"No existe la entrada: {input_path}")
+
+    if not output_filename.endswith(".mha"):
+        raise ValueError("output_filename debe terminar en .mha")
+
+    output_path = output_dir / output_filename
+
+    if output_path.exists():
+        output_path.unlink()
+
+    if input_path.is_file() and input_path.suffix.lower() == ".mha":
+        shutil.copy2(input_path, output_path)
+        return str(output_path)
+
+    if input_path.is_file():
+        logger.info(f"Convirtiendo archivo a .mha: {input_path}")
+        img = sitk.ReadImage(str(input_path))
+        sitk.WriteImage(img, str(output_path))
+        return str(output_path)
+
+    if input_path.is_dir():
+        logger.info(f"Leyendo carpeta DICOM: {input_path}")
+
+        reader = sitk.ImageSeriesReader()
+        series_ids = reader.GetGDCMSeriesIDs(str(input_path))
+
+        if not series_ids:
+            raise ValueError(f"No se encontró ninguna serie DICOM en: {input_path}")
+
+        if len(series_ids) > 1:
+            logger.warning(
+                f"Se encontraron {len(series_ids)} series DICOM. "
+                f"Se usará la primera: {series_ids[0]}"
+            )
+
+        series_files = reader.GetGDCMSeriesFileNames(
+            str(input_path),
+            series_ids[0],
+        )
+
+        reader.SetFileNames(series_files)
+        img = reader.Execute()
+        sitk.WriteImage(img, str(output_path))
+
+        return str(output_path)
+
+    raise ValueError(f"Formato no soportado: {input_path}")