Add ring boundary summary analytics

Author: Wood Cell Dev

ENGINEERING_LOG.md

@@ -400,3 +400,8 @@
 
 ## 2025-09-22 20:48 UTC
 - Documented dendro format coverage and reader locations in `docs/reference/dendro_format_support.md` for quick parity auditing.
+
+## 2025-09-22 21:05 UTC
+- Shipped LiPD reader capable of extracting measurement tables and wired it into the dendro importer (`utils/dendro/formats/lipd.py`, `utils/dendro/importer.py`).
+- Extended dendro import API with binary support plus regression for CaTRAS and LiPD (`tests/test_api_v2.py`), added LiPD fixture (`tests/data/lipd_sample.b64`).
+- Delivered ring-boundary metrics endpoint with per-ring area/perimeter summaries to close WinCELL analytics gap (`scripts/api_v2.py`, `tests/test_api_v2.py::test_ring_boundary_summary_endpoint`).

scripts/api_v2.py

@@ -3096,6 +3096,34 @@ class RingBoundaryResponse(BaseModel):
     metadata: Dict[str, Any] = Field(default_factory=dict)
 
 
+class RingBoundaryMetricsEntry(BaseModel):
+    ring_id: str
+    ring_index: int
+    area_pixels: Optional[float] = None
+    area_square_microns: Optional[float] = None
+    perimeter_pixels: Optional[float] = None
+    perimeter_microns: Optional[float] = None
+    radius_pixels: Optional[float] = None
+    radius_microns: Optional[float] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class RingBoundaryMetricsSummary(BaseModel):
+    total_boundaries: int
+    boundaries_with_geometry: int
+    average_area_square_microns: Optional[float] = None
+    average_radius_microns: Optional[float] = None
+    average_perimeter_microns: Optional[float] = None
+    total_area_square_microns: Optional[float] = None
+
+
+class RingBoundaryMetricsResponse(BaseModel):
+    image_id: str
+    pixels_per_micron: Optional[float] = None
+    boundaries: List[RingBoundaryMetricsEntry] = Field(default_factory=list)
+    summary: RingBoundaryMetricsSummary
+
+
 class RingDetectionRequest(BaseModel):
     min_area: float = Field(500.0, ge=10.0)
     max_area: Optional[float] = Field(default=None, ge=10.0)
@@ -9218,6 +9246,81 @@ async def list_ring_boundaries(project_id: str, image_id: str):
     return responses
 
 
+@app.get(
+    "/api/v2/projects/{project_id}/images/{image_id}/ring-boundaries/summary",
+    response_model=RingBoundaryMetricsResponse
+)
+async def summarize_ring_boundaries(project_id: str, image_id: str):
+    image_record = await _get_project_image(project_id, image_id)
+    boundaries = await ring_boundary_store.list(image_id=image_id)
+
+    filtered = [
+        boundary for boundary in boundaries
+        if boundary.get('project_id') == project_id
+    ]
+
+    pixels_per_micron = await _pixels_per_micron_for_image(image_record)
+    width, height = _resolve_image_dimensions(image_record)
+
+    entries: List[RingBoundaryMetricsEntry] = []
+    geometry_count = 0
+    area_microns_sum = 0.0
+    radius_microns_sum = 0.0
+    perimeter_microns_sum = 0.0
+
+    for record in filtered:
+        original_points = record.get('boundary_path') or []
+        absolute_points = _denormalize_points(original_points, width, height)
+        metric_payload = {
+            'boundary_path': [{'x': x, 'y': y} for x, y in absolute_points]
+        }
+        metrics = _ring_boundary_metrics(metric_payload, pixels_per_micron=pixels_per_micron)
+
+        area_pixels = metrics.get('area_pixels')
+        area_square_microns = metrics.get('area_square_microns')
+        radius_microns = metrics.get('radius_microns')
+        perimeter_microns = metrics.get('perimeter_microns')
+
+        if area_pixels:
+            geometry_count += 1
+        if area_square_microns:
+            area_microns_sum += area_square_microns
+        if radius_microns:
+            radius_microns_sum += radius_microns
+        if perimeter_microns:
+            perimeter_microns_sum += perimeter_microns
+
+        entries.append(
+            RingBoundaryMetricsEntry(
+                ring_id=record['id'],
+                ring_index=record['ring_index'],
+                area_pixels=area_pixels,
+                area_square_microns=area_square_microns,
+                perimeter_pixels=metrics.get('perimeter_pixels'),
+                perimeter_microns=perimeter_microns,
+                radius_pixels=metrics.get('radius_pixels'),
+                radius_microns=radius_microns,
+                metadata=record.get('metadata') or {}
+            )
+        )
+
+    summary = RingBoundaryMetricsSummary(
+        total_boundaries=len(filtered),
+        boundaries_with_geometry=geometry_count,
+        average_area_square_microns=(area_microns_sum / geometry_count if geometry_count and area_microns_sum else None),
+        average_radius_microns=(radius_microns_sum / geometry_count if geometry_count and radius_microns_sum else None),
+        average_perimeter_microns=(perimeter_microns_sum / geometry_count if geometry_count and perimeter_microns_sum else None),
+        total_area_square_microns=area_microns_sum if geometry_count and area_microns_sum else None,
+    )
+
+    return RingBoundaryMetricsResponse(
+        image_id=image_id,
+        pixels_per_micron=pixels_per_micron,
+        boundaries=entries,
+        summary=summary,
+    )
+
+
 @app.post(
     "/api/v2/projects/{project_id}/images/{image_id}/ring-boundaries/detect",
     response_model=RingDetectionResponse

tests/test_api_v2.py

@@ -18,6 +18,7 @@
 from fastapi.testclient import TestClient
 from PIL import Image, ImageDraw
 import zipfile
+import pytest
 import jwt
 
 from scripts import api_v2
@@ -252,6 +253,43 @@ def test_dendro_import_endpoint_parses_lipd():
     assert payload['series']
 
 
+def test_ring_boundary_summary_endpoint():
+    project_response = client.post('/api/v2/projects', json={'name': 'Ring Metrics Project'})
+    assert project_response.status_code == 200
+    project = project_response.json()
+
+    link_response = client.post(
+        f"/api/v2/projects/{project['id']}/images/link-dataset",
+        json={'dataset_id': 'test-dataset', 'split': 'train', 'image_name': 'sample.png'}
+    )
+    assert link_response.status_code == 201
+    project_image = link_response.json()
+
+    boundary_payload = {
+        'ring_index': 0,
+        'boundary_path': [
+            {'x': 0.0, 'y': 0.0},
+            {'x': 1.0, 'y': 0.0},
+            {'x': 1.0, 'y': 1.0},
+            {'x': 0.0, 'y': 1.0},
+        ]
+    }
+    create_response = client.post(
+        f"/api/v2/projects/{project['id']}/images/{project_image['id']}/ring-boundaries",
+        json=boundary_payload
+    )
+    assert create_response.status_code == 201
+
+    summary_response = client.get(
+        f"/api/v2/projects/{project['id']}/images/{project_image['id']}/ring-boundaries/summary"
+    )
+    assert summary_response.status_code == 200
+    payload = summary_response.json()
+    assert payload['summary']['total_boundaries'] == 1
+    metrics = payload['boundaries'][0]
+    assert pytest.approx(metrics['area_pixels'], rel=1e-3) == 16384.0
+
+
 def test_measurement_path_update_flow():
     project_response = client.post('/api/v2/projects', json={'name': 'Measurement Project'})
     assert project_response.status_code == 200