OsteoLab: 1. Preparación de datos¶

Primer cuaderno de tres, parte de una charla dirigida a público sin experiencia previa en machine learning. No es el pipeline de producción línea a línea: es una versión simplificada del mismo proceso, centrada en las ideas y sin el ruido de infraestructura interna.

Pregunta que responde este cuaderno: si quiero que un programa reconozca huesos en una foto, ¿de dónde saco las imágenes para enseñarle, y cómo las convierto en números que un modelo pueda usar?

Serie completa: este cuaderno (datos) → pycon26_02_entrenamiento.ipynb (modelos) → pycon26_03_inferencia.ipynb (usar los modelos + API).

1. El problema¶

Queremos clasificar huesos a partir de una foto: dado una imagen, decir a qué grupo morfológico pertenece (cráneo, hueso largo, vértebra, costilla...).

Primer obstáculo: conseguir miles de fotos reales de huesos, bien etiquetadas, es carísimo. No existe un dataset público decente para esto. Solución: generar la mayoría de los datos de entrenamiento de forma sintética a partir de modelos 3D (renderizados con Blender desde muchos ángulos), y usar un número pequeño de fotos reales para anclar el modelo al mundo real.

La taxonomía tiene 9 grupos morfológicos: cráneo, mandíbula/maxilar, hueso largo, hueso plano, pelvis, sacro, vértebra, costilla, hueso pequeño. Son formas, no especies ni huesos exactos. Con tan pocos especímenes físicos por hueso, pedirle al modelo que distinga huesos exactos (fémur vs. húmero...) le haría memorizar el objeto concreto de la foto en vez de aprender la forma general.

In [1]:
import os, sys
from pathlib import Path

def find_repo_root():
    start = Path.cwd()
    for candidate in (start, *start.parents):
        if (candidate / "params.yaml").exists() and (candidate / "training").is_dir():
            return candidate
    raise RuntimeError("Abre el notebook desde dentro del repo.")

REPO_ROOT = find_repo_root()
os.chdir(REPO_ROOT)
sys.path.insert(0, str(REPO_ROOT))

BONE_DB = REPO_ROOT / "base_datos_osea"
PROCESSED = REPO_ROOT / "data/processed"
print("Raíz del proyecto:", REPO_ROOT)
Raíz del proyecto: /root/dev/osteolab-ml-platform

Los 9 grupos, de un vistazo¶

Un esqueleto humano completo (homo_sapiens en el dataset) ya trae un ejemplo real de cada grupo. Antes de hablar de números, mejor verlos.

In [2]:
import matplotlib.pyplot as plt
import matplotlib.image as mpimg

GRUPO_A_CARPETA = {
    "cranio": "cranium",
    "mandibula_maxilar": "mandible",
    "hueso_largo": "femur",
    "hueso_plano": "clavicle",
    "pelvis": "pelvis",
    "sacro": "sacrum",
    "vertebra": "lumbar_vertebra",
    "costilla": "rib",
    "hueso_pequeno": "metacarpal_1",
}

def primera_imagen(especie, hueso):
    carpeta = BONE_DB / "renders_lab" / especie / hueso
    vistas = sorted(p for p in carpeta.rglob("*.png") if "_mask" not in p.name)
    return vistas[0] if vistas else None

fig, axes = plt.subplots(3, 3, figsize=(10, 10))
for ax, (grupo, hueso) in zip(axes.ravel(), GRUPO_A_CARPETA.items()):
    img_path = primera_imagen("homo_sapiens", hueso)
    ax.imshow(mpimg.imread(img_path))
    ax.set_title(grupo, fontsize=10)
    ax.axis("off")
plt.suptitle("Los 9 grupos morfológicos, mismo esqueleto (homo_sapiens)", y=1.01)
plt.tight_layout()
plt.show()
No description has been provided for this image

2. De una imagen a números: features geométricas¶

Un modelo no "ve" una foto como nosotros, necesita números. Este paso de convertir imagen en números se llama extracción de features, y aquí es pura geometría clásica con OpenCV, sin aprendizaje automático todavía.

Idea general: se recorta el hueso del fondo (segmentación) y se miden un puñado de propiedades de esa silueta:

  • Tamaño y forma básica: área, proporción ancho/alto, qué tan "llena" está la silueta (solidity).
  • Elongación: qué tan alargado es el hueso (PCA sobre el contorno). Como veremos, es la medida más potente de todas.
  • Perfil de anchura: cortes perpendiculares al eje largo, para notar si se ensancha en los extremos (fémur) o es uniforme (costilla).

Lo calculamos sobre una imagen de ejemplo, con la misma función que usa el proyecto real (shared/cv_extractor/extract.py). Aquí sí reutilizamos el código real: es corto y clarísimo de leer.

In [3]:
sample = BONE_DB / "renders_lab" / "canis_familiaris" / "cranium" / "stock_sinfuente_domestic_dog_skull" / "canis_familiaris_cranium_stock_sinfuente_domestic_dog_skull_drop00_view000.png"
print("Imagen de ejemplo:", sample.relative_to(REPO_ROOT))
Imagen de ejemplo: base_datos_osea/renders_lab/canis_familiaris/cranium/stock_sinfuente_domestic_dog_skull/canis_familiaris_cranium_stock_sinfuente_domestic_dog_skull_drop00_view000.png
In [4]:
from shared.cv_extractor.extract import extract_features

with open(sample, "rb") as fh:
    feats = extract_features(fh, backend="classic")

# Nos quedamos solo con un puñado de medidas clave, para no abrumar.
claves = ["area_ratio", "aspect_ratio", "solidity", "elongation", "circularity", "mean_width"]
for k in claves:
    print(f"{k:14s} {feats[k]}")
area_ratio     0.100388
aspect_ratio   1.7641
solidity       0.836
elongation     0.6503
circularity    0.2264
mean_width     95.64
In [5]:
from IPython.display import HTML, display

display(HTML(
    f'<img src="data:image/png;base64,{feats["annotated_image_base64"]}" style="max-width:420px">'
))
No description has been provided for this image

La misma medida, especies distintas¶

elongation tiene que funcionar igual de bien en un cráneo humano, uno de caballo o uno de perro: ese es justo el punto de medir forma y no memorizar especie. Lo comprobamos sobre los tres.

In [6]:
ESPECIMEN_CRANEO = {
    "homo_sapiens": BONE_DB / "renders_lab" / "homo_sapiens" / "cranium"
        / "sketchfab_c39855833ff74943a2847972c9ff8700"
        / "homo_sapiens_cranium_sketchfab_c39855833ff74943a2847972c9ff8700_drop00_view000.png",
}

especies_craneo = ["homo_sapiens", "equus_caballus", "canis_familiaris"]

fig, axes = plt.subplots(1, 3, figsize=(13, 5))
for ax, especie in zip(axes, especies_craneo):
    img_path = ESPECIMEN_CRANEO.get(especie, primera_imagen(especie, "cranium"))
    with open(img_path, "rb") as fh:
        f = extract_features(fh, backend="classic")
    ax.imshow(mpimg.imread(img_path))
    ax.set_title(f"{especie}\nelongation={f['elongation']:.2f}  solidity={f['solidity']:.2f}", fontsize=9)
    ax.axis("off")
plt.tight_layout()
plt.show()
No description has been provided for this image

3. De imágenes sueltas a una tabla de entrenamiento¶

Repetimos esa medición sobre miles de imágenes y volcamos el resultado en un CSV: una fila por imagen, una columna por medida, más la etiqueta del grupo morfológico.

Trampa a evitar: fuga de datos. Cada malla 3D produce varias vistas desde distintos ángulos. Si repartimos esas vistas al azar entre train y test, el modelo ve el mismo objeto físico en ambos lados y la métrica sale artificialmente alta: no mide si generaliza, mide si reconoce ese espécimen concreto. Solución: los splits se hacen por espécimen completo, nunca por foto suelta.

Antes de la tabla, un ejemplo de qué significa "varias vistas de la misma malla": 24 fotos distintas, mismo hueso físico.

In [7]:
vistas_mismo_espécimen = sorted(sample.parent.glob("*.png"))
vistas_mismo_espécimen = [p for p in vistas_mismo_espécimen if "_mask" not in p.name][:4]

fig, axes = plt.subplots(1, len(vistas_mismo_espécimen), figsize=(13, 4))
for ax, p in zip(axes, vistas_mismo_espécimen):
    ax.imshow(mpimg.imread(p))
    ax.set_title(p.stem.split("_")[-1], fontsize=9)
    ax.axis("off")
plt.suptitle("Mismo espécimen, varios ángulos: por eso el split va por espécimen, no por foto", y=1.03)
plt.tight_layout()
plt.show()
No description has been provided for this image
In [8]:
import pandas as pd

dataset_path = PROCESSED / "bone_geometric_features_combined_lab.csv"
df = pd.read_csv(dataset_path)
print(dataset_path.name, df.shape)

conteo = df.groupby("bone_group").size().sort_values(ascending=False).to_frame("n_imagenes")
conteo.style.bar(color="#c89b2b", width=90).format("{:,}")
bone_geometric_features_combined_lab.csv (5269, 70)
Out[8]:
  n_imagenes
bone_group  
mandibula_maxilar 1,455
hueso_largo 866
vertebra 737
cranio 661
hueso_pequeno 659
costilla 320
hueso_plano 240
sacro 228
pelvis 103
In [9]:
fig, ax = plt.subplots(figsize=(7, 4))
for grupo, sub in df.groupby("bone_group"):
    ax.hist(sub["elongation"].dropna(), bins=25, alpha=0.4, label=grupo)
ax.set_title("elongation por grupo morfológico")
ax.legend(fontsize=7)
plt.show()
No description has been provided for this image

elongation tiene la frontera más limpia entre hueso_largo y el resto. Y, como veremos en el cuaderno de inferencia, es también la que mejor resiste al pasar de renders sintéticos a fotos reales. El resto de medidas separan muy bien en sintético y se degradan mucho en foto real.

4. Mini-comprobación: ¿sirve de algo la geometría, sola?¶

Antes de entrenar ningún modelo "de verdad" (eso es el cuaderno 2): si entrenamos un clasificador simple solo con estas columnas, sin mirar la imagen en absoluto, ¿le ganamos a un baseline que siempre responde la clase más frecuente? Evaluamos dejando especímenes completos fuera (no splits al azar por fila), por la misma razón de la sección 3.

In [10]:
from sklearn.dummy import DummyClassifier
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import GroupKFold, cross_val_score

cols = ["area_ratio", "aspect_ratio", "solidity", "elongation", "circularity", "mean_width", "std_width"]
datos = df.dropna(subset=cols + ["bone_group"])
X, y = datos[cols], datos["bone_group"]
grupos = datos.get("specimen", y)

cv = GroupKFold(n_splits=5)
acc_base = cross_val_score(DummyClassifier(strategy="most_frequent"), X, y, cv=cv, groups=grupos).mean()
acc_rf = cross_val_score(RandomForestClassifier(n_estimators=200, random_state=0, n_jobs=-1),
                          X, y, cv=cv, groups=grupos).mean()

pd.DataFrame({"accuracy": [acc_base, acc_rf]}, index=["baseline (clase más frecuente)", "solo geometría (Random Forest)"]) \
  .style.bar(color="#c89b2b", vmin=0, vmax=1).format("{:.3f}")
Out[10]:
  accuracy
baseline (clase más frecuente) 0.276
solo geometría (Random Forest) 0.708

Con 9 clases, un baseline tonto ronda 0.1-0.3 según el desbalanceo. El Random Forest queda muy por encima: la geometría por sí sola ya es una señal fuerte, antes de que una CNN mire un solo píxel. En el cuaderno 2 vemos si además aporta algo a la CNN, que es la pregunta que de verdad importa en producción.

5. Un primer filtro: ¿esto es un hueso, siquiera?¶

Antes de medir geometría, el sistema real se pregunta algo más básico: ¿la foto subida es siquiera un hueso? Para esto se usa CLIP (un modelo ya entrenado por terceros, en modo zero-shot): se comparan los embeddings de la foto contra frases como "a photo of a bone" frente a "a photo of something that is not a bone". Si gana claramente "no es hueso", el flujo se detiene ahí: no se gasta segmentación ni modelo de clasificación.

In [11]:
from shared.clip_filter.predict import classify_image as clip_classify

with open(sample, "rb") as fh:
    print(clip_classify(fh))
Warning: You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads.
{'is_bone': True, 'confidence': 0.867005, 'probabilities': {'bone': 0.867005, 'not_bone': 0.132995}, 'suggestion': {'type': 'mandibula_maxilar', 'confidence': 0.543294, 'certain': False, 'probabilities': {'cranio': 0.21772, 'mandibula_maxilar': 0.543294, 'hueso_largo': 0.008596, 'hueso_plano': 0.074365, 'pelvis': 0.028704, 'sacro': 0.0245, 'vertebra': 0.031187, 'costilla': 0.005121, 'hueso_pequeno': 0.066513}}}

Cómo seguir desde aquí¶

Explorar imágenes por grupo a mano es lento. Un desplegable y lo tenemos resuelto: elige un grupo, ve un ejemplo real al azar.

In [12]:
import random
from ipywidgets import interact, Dropdown

def ver_ejemplo_de(grupo):
    hueso = GRUPO_A_CARPETA[grupo]
    especie = random.choice(["homo_sapiens"])
    img_path = primera_imagen(especie, hueso)
    plt.figure(figsize=(4, 4))
    plt.imshow(mpimg.imread(img_path))
    plt.title(f"{grupo} ({especie} / {hueso})")
    plt.axis("off")
    plt.show()

interact(ver_ejemplo_de, grupo=Dropdown(options=list(GRUPO_A_CARPETA), description="Grupo:"));

Lo que viene después¶

Tenemos: imágenes (sintéticas + pocas fotos reales), una función que las convierte en números, y una tabla de entrenamiento construida sin fuga entre train y test.

El siguiente cuaderno (pycon26_02_entrenamiento.ipynb) entrena dos modelos sobre esta tabla, uno clásico (Random Forest) y uno de deep learning (CNN híbrida), y los evalúa de forma honesta.