diff --git a/.github/workflows/notebook-checks.yml b/.github/workflows/notebook-checks.yml new file mode 100644 index 0000000..39afcfc --- /dev/null +++ b/.github/workflows/notebook-checks.yml @@ -0,0 +1,40 @@ +name: Notebook refactor checks + +on: + pull_request: + paths: + - "Cable_Segmentation_Refactored.ipynb" + - "cable_seg/**" + - "tests/**" + - ".github/workflows/notebook-checks.yml" + push: + branches: + - "refactor/curated-segmentation-notebook" + +jobs: + static-and-unit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Install lightweight test dependencies + run: python -m pip install numpy pytest nbformat + - name: Unit tests + run: python -m pytest -q tests/test_core.py + - name: Validate notebook and code syntax + run: | + python - <<'PY' + import ast + import nbformat + nb = nbformat.read('Cable_Segmentation_Refactored.ipynb', as_version=4) + nbformat.validate(nb) + code_cells = [cell for cell in nb.cells if cell.cell_type == 'code'] + for cell in code_cells: + ast.parse(cell.source) + assert not cell.outputs + assert cell.execution_count is None + assert len(nb.cells) == 22 + print(f'Validated {len(code_cells)} code cells') + PY diff --git a/Cable_Segmentation_Refactored.ipynb b/Cable_Segmentation_Refactored.ipynb new file mode 100644 index 0000000..f9e24c1 --- /dev/null +++ b/Cable_Segmentation_Refactored.ipynb @@ -0,0 +1,444 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "cell-001", + "metadata": {}, + "source": [ + "# Electric cable instance segmentation\n", + "### Curated RF-DETR / COCO / PCA analysis\n", + "\n", + "This notebook provides a readable analysis workflow for thin, elongated cable instances in aerial imagery.\n", + "The original `Segmentation.ipynb` remains **an experimental archive**, with all PCA/RANSAC/SAM/DeepLSD alternatives intact.\n", + "\n", + "**Sequence:** setup → COCO audit → visualisation → optional training → optional inference → validation threshold → locked test evaluation → geometry diagnostics → report.\n", + "\n", + "Historical README values (AP50 **0.528**, AR@10 **0.280**, angular error approximately **0.998°**) are *reported rather than recomputed*. They must not be treated as current outputs." + ] + }, + { + "cell_type": "markdown", + "id": "cell-002", + "metadata": {}, + "source": [ + "## 1. Configuration\n", + "\n", + "Install the packages in `requirements-analysis.txt` for the evaluation path.\n", + "Training/inference require `requirements-training.txt`. Set the dataset and prediction paths in **one** configuration cell.\n", + "\n", + "Expected dataset: `data/coco/{train,valid,test}/_annotations.coco.json` with images in their matching directories. No automatic Drive mount, extraction, cleanup or package uninstall is performed." + ] + }, + { + "cell_type": "code", + "id": "cell-003", + "execution_count": null, + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "from pathlib import Path\n", + "import json\n", + "import random\n", + "import numpy as np\n", + "import pandas as pd\n", + "import matplotlib.pyplot as plt\n", + "from cable_seg.core import (\n", + " ProjectConfig, read_json, inspect_coco, instance_density,\n", + " select_by_score, line_from_mask, axial_angle_error_deg,\n", + ")\n", + "from cable_seg.coco import (\n", + " decode_segmentation, evaluate_coco, geometry_diagnostics, save_predictions,\n", + ")\n", + "\n", + "CFG = ProjectConfig(\n", + " dataset_root=Path(\"data/coco\"),\n", + " checkpoint=Path(\"checkpoint_best_ema.pth\"),\n", + " predictions_valid=Path(\"artifacts/predictions_valid.json\"),\n", + " predictions_test=Path(\"artifacts/predictions_test.json\"),\n", + " output_dir=Path(\"artifacts/reports\"),\n", + " seed=42, score_threshold=0.25,\n", + ")\n", + "random.seed(CFG.seed)\n", + "np.random.seed(CFG.seed)\n", + "print(CFG)" + ] + }, + { + "cell_type": "markdown", + "id": "cell-004", + "metadata": {}, + "source": [ + "## 2. Read-only COCO audit\n", + "\n", + "Inspect image/annotation counts, category consistency, empty images, density and invalid image references. This notebook **never modifies** source annotation JSON files." + ] + }, + { + "cell_type": "code", + "id": "cell-005", + "execution_count": null, + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "split_data = {}\n", + "summaries = []\n", + "for split in (\"train\", \"valid\", \"test\"):\n", + " path = CFG.ann_path(split)\n", + " if not path.exists():\n", + " print(f\"{split}: no annotation file at {path}\")\n", + " continue\n", + " data = read_json(path)\n", + " split_data[split] = data\n", + " summaries.append({\"split\": split, **inspect_coco(data)})\n", + "if summaries:\n", + " display(pd.DataFrame(summaries).set_index(\"split\"))\n", + " if any(s[\"orphan_annotations\"] for s in summaries):\n", + " raise ValueError(\"COCO annotations refer to missing image IDs\")\n", + "else:\n", + " print(\"No dataset found. Configure CFG.dataset_root.\")" + ] + }, + { + "cell_type": "markdown", + "id": "cell-006", + "metadata": {}, + "source": [ + "### 2.1 Cable-instance density\n", + "\n", + "Density is relevant for parallel cables and occluded scenes. The plot describes annotations; it is not a model-performance result." + ] + }, + { + "cell_type": "code", + "id": "cell-007", + "execution_count": null, + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "if split_data:\n", + " fig, axes = plt.subplots(1, len(split_data),\n", + " figsize=(5*len(split_data), 3.5), squeeze=False)\n", + " for ax, (name, data) in zip(axes.flat, split_data.items()):\n", + " arr = list(instance_density(data).values())\n", + " ax.hist(arr, bins=min(30, max(1, len(set(arr)))), edgecolor=\"white\")\n", + " ax.set(title=f\"{name}: cable instances\", xlabel=\"GT cables per image\",\n", + " ylabel=\"Image count\")\n", + " plt.tight_layout()\n", + " plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "cell-008", + "metadata": {}, + "source": [ + "### 2.2 Sample annotation\n", + "\n", + "Overlay the union of cable masks on one annotated sample image. Individual COCO annotations remain distinct for scoring." + ] + }, + { + "cell_type": "code", + "id": "cell-009", + "execution_count": null, + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "from PIL import Image\n", + "\n", + "sample_split = \"valid\" if \"valid\" in split_data else (\n", + " next(iter(split_data)) if split_data else None)\n", + "if sample_split:\n", + " data = split_data[sample_split]\n", + " sample = next((im for im in data[\"images\"]\n", + " if any(a[\"image_id\"] == im[\"id\"] for a in data[\"annotations\"])), None)\n", + " if sample:\n", + " path = CFG.dataset_root / sample_split / sample[\"file_name\"]\n", + " if path.exists():\n", + " image = np.asarray(Image.open(path).convert(\"RGB\"))\n", + " selected = [a for a in data[\"annotations\"] if a[\"image_id\"] == sample[\"id\"]]\n", + " combined = np.zeros(image.shape[:2], dtype=bool)\n", + " for annotation in selected:\n", + " combined |= decode_segmentation(\n", + " annotation[\"segmentation\"],\n", + " height=sample[\"height\"], width=sample[\"width\"])\n", + " fig, axes = plt.subplots(1, 2, figsize=(12, 5))\n", + " axes[0].imshow(image)\n", + " axes[0].set_title(\"Input\")\n", + " axes[1].imshow(image)\n", + " axes[1].imshow(np.ma.masked_where(~combined, combined),\n", + " alpha=0.4, cmap=\"autumn\")\n", + " axes[1].set_title(f\"GT cable pixels ({len(selected)} instances)\")\n", + " for ax in axes: ax.axis(\"off\")\n", + " plt.tight_layout()\n", + " plt.show()\n", + " else:\n", + " print(\"Image missing:\", path)" + ] + }, + { + "cell_type": "markdown", + "id": "cell-010", + "metadata": {}, + "source": [ + "## 3. Optional RF-DETR training (off by default)\n", + "\n", + "The original research used **multiple distinct** training recipes; a representative 60-epoch configuration is shown here for orientation. Its architecture/API must be verified against the installed RF-DETR version and the historical weights.\n", + "\n", + "Train using the train/valid splits only. **Do not tune hyperparameters on test.** This expensive step is deliberately disabled unless explicitly enabled." + ] + }, + { + "cell_type": "code", + "id": "cell-011", + "execution_count": null, + "metadata": { + "tags": [ + "optional", + "requires-gpu" + ] + }, + "outputs": [], + "source": [ + "RUN_TRAINING = False\n", + "if RUN_TRAINING:\n", + " from rfdetr import RFDETRSegPreview\n", + " if not CFG.ann_path(\"train\").exists() or not CFG.ann_path(\"valid\").exists():\n", + " raise FileNotFoundError(\"train and valid COCO annotations required\")\n", + " model = RFDETRSegPreview()\n", + " model.train(\n", + " dataset_dir=str(CFG.dataset_root), dataset_file=\"roboflow\",\n", + " epochs=60, batch_size=1, grad_accum_steps=8,\n", + " lr=1e-4, lr_encoder=1e-5,\n", + " resolution=1200, clip_max_norm=0.1, use_ema=True,\n", + " output_dir=\"artifacts/train_run\",\n", + " )\n", + "else:\n", + " print(\"Training skipped (default).\")" + ] + }, + { + "cell_type": "markdown", + "id": "cell-012", + "metadata": {}, + "source": [ + "## 4. Optional inference (off by default)\n", + "\n", + "Use existing COCO predictions to avoid rerunning the GPU. The optional adapter uses the public `model.predict()` API and converts masks to COCO RLE. Verify class-ID mapping, RF-DETR architecture, and checkpoint version. A Git LFS pointer cannot act as a checkpoint.\n", + "\n", + "Infer at a low cutoff (0.05); optimize confidence **only on validation**." + ] + }, + { + "cell_type": "code", + "id": "cell-013", + "execution_count": null, + "metadata": { + "tags": [ + "optional", + "requires-gpu" + ] + }, + "outputs": [], + "source": [ + "RUN_INFERENCE = False\n", + "MODEL_CLASS = \"RFDETRSegPreview\" # verify model/checkpoint compatibility\n", + "if RUN_INFERENCE:\n", + " import rfdetr\n", + " from cable_seg.inference import predict_coco\n", + " if not CFG.checkpoint.is_file() or CFG.checkpoint.stat().st_size < 1024:\n", + " raise FileNotFoundError(\"Fetch the full LFS checkpoint first\")\n", + " model = getattr(rfdetr, MODEL_CLASS)(pretrain_weights=str(CFG.checkpoint))\n", + " for split, output in (\n", + " (\"valid\", CFG.predictions_valid), (\"test\", CFG.predictions_test)\n", + " ):\n", + " if split not in split_data:\n", + " raise FileNotFoundError(f\"No {split} COCO annotations\")\n", + " records = predict_coco(model, split_data[split],\n", + " CFG.dataset_root / split, threshold=0.05)\n", + " save_predictions(output, records)\n", + " print(f\"{split}: {len(records)} detections -> {output}\")\n", + "else:\n", + " print(\"Inference skipped: expecting precomputed prediction JSONs.\")" + ] + }, + { + "cell_type": "markdown", + "id": "cell-014", + "metadata": {}, + "source": [ + "## 5. Choose score threshold on validation\n", + "\n", + "A test-based threshold sweep creates selection bias. Choose the highest validation AP50 among predeclared cutoffs, with a lower-cutoff tie-break. The selected cutoff is **frozen** before test.\n", + "\n", + "COCO recall metric indices for `maxDets=[1,10,100]`: `stats[6]` is **AR@1**, `stats[7]` is **AR@10**, `stats[8]` is **AR@100**. At least one historical cell incorrectly labels `stats[6]`." + ] + }, + { + "cell_type": "code", + "id": "cell-015", + "execution_count": null, + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "validation_predictions = (\n", + " read_json(CFG.predictions_valid) if CFG.predictions_valid.exists() else None\n", + ")\n", + "selected_threshold = CFG.score_threshold\n", + "validation_metrics = None\n", + "if validation_predictions is not None and CFG.ann_path(\"valid\").exists():\n", + " sweep = []\n", + " for candidate in (0.05, 0.10, 0.20, 0.30, 0.40, 0.50):\n", + " filtered = select_by_score(validation_predictions, candidate)\n", + " sweep.append({\"threshold\": candidate,\n", + " **evaluate_coco(CFG.ann_path(\"valid\"), filtered)})\n", + " display(pd.DataFrame(sweep).round(4))\n", + " validation_metrics = max(sweep, key=lambda row: (row[\"AP50\"], -row[\"threshold\"]))\n", + " selected_threshold = validation_metrics[\"threshold\"]\n", + " print(f\"Frozen score threshold: {selected_threshold:.2f}\")\n", + "else:\n", + " print(f\"Validation predictions not found. Fixed score threshold: {selected_threshold:.2f}\")" + ] + }, + { + "cell_type": "markdown", + "id": "cell-016", + "metadata": {}, + "source": [ + "## 6. Locked test COCO metrics\n", + "\n", + "Evaluate the test split only after threshold selection. These are official COCO segmentation scores; they cannot be compared to the historical notebook until dataset, checkpoint and preprocessing versions are reconciled." + ] + }, + { + "cell_type": "code", + "id": "cell-017", + "execution_count": null, + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "test_predictions = (\n", + " read_json(CFG.predictions_test) if CFG.predictions_test.exists() else None\n", + ")\n", + "test_filtered = None\n", + "if test_predictions is not None and CFG.ann_path(\"test\").exists():\n", + " test_filtered = select_by_score(test_predictions, selected_threshold)\n", + " test_metrics = evaluate_coco(CFG.ann_path(\"test\"), test_filtered)\n", + " display(pd.DataFrame([test_metrics], index=[\"test\"]).round(4))\n", + "else:\n", + " print(\"No test predictions/annotations. No COCO metric was computed.\")" + ] + }, + { + "cell_type": "markdown", + "id": "cell-018", + "metadata": {}, + "source": [ + "## 7. Geometry-aware PCA diagnostics\n", + "\n", + "For each greedily **one-to-one IoU-matched** GT/prediction pair (mask IoU ≥ 0.5), fit an undirected line through the mask pixels with PCA and compute axial error modulo 180°. Report matched-pair coverage to avoid hiding hard instances.\n", + "\n", + "This is a diagnostic and **not** COCO matching or a reproduction of the historical ~0.998° angular error." + ] + }, + { + "cell_type": "code", + "id": "cell-019", + "execution_count": null, + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "if test_filtered is not None:\n", + " geometry = geometry_diagnostics(\n", + " CFG.ann_path(\"test\"), test_filtered,\n", + " min_iou=0.5, min_line_pixels=CFG.min_line_pixels)\n", + " display(pd.DataFrame([geometry], index=[\"test\"]).round(4))\n", + "else:\n", + " print(\"Geometry diagnostics require test predictions.\")" + ] + }, + { + "cell_type": "markdown", + "id": "cell-020", + "metadata": {}, + "source": [ + "## 8. Save report and provenance\n", + "\n", + "Persist parameters and newly computed metrics only when evaluation actually ran. No invented metrics or rerun claims are emitted." + ] + }, + { + "cell_type": "code", + "id": "cell-021", + "execution_count": null, + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "if test_filtered is not None:\n", + " CFG.output_dir.mkdir(parents=True, exist_ok=True)\n", + " report = {\n", + " \"dataset_root\": str(CFG.dataset_root),\n", + " \"test_ground_truth\": str(CFG.ann_path(\"test\")),\n", + " \"valid_predictions\": str(CFG.predictions_valid),\n", + " \"test_predictions\": str(CFG.predictions_test),\n", + " \"seed\": CFG.seed,\n", + " \"selected_threshold\": selected_threshold,\n", + " \"selected_on_validation\": validation_metrics is not None,\n", + " \"validation_metrics\": validation_metrics,\n", + " \"test_coco_metrics\": test_metrics,\n", + " \"geometry_diagnostics\": geometry,\n", + " \"note\": \"Newly evaluated metrics; historical values not independently reproduced\",\n", + " }\n", + " target = CFG.output_dir / \"evaluation_summary.json\"\n", + " target.write_text(json.dumps(report, indent=2), encoding=\"utf-8\")\n", + " print(\"Report saved:\", target)\n", + "else:\n", + " print(\"No report generated without test evaluation.\")" + ] + }, + { + "cell_type": "markdown", + "id": "cell-022", + "metadata": {}, + "source": [ + "## 9. Discussion and future evaluation\n", + "\n", + "Thin, filamentary cable masks may have low pixel overlap despite plausible global orientation. This motivates measuring **both** segmentation quality and geometric consistency.\n", + "\n", + "**Known limits:** dense scenes, touching/occluded cables, broken masks, variations in cable thickness, and sensitivity to matching and instance count.\n", + "\n", + "**Next rigorous experiments:** freeze the dataset split and model checkpoint, keep preprocessing constant, test AP/AR stratified by scene density and compare PCA/RANSAC/SAM/DeepLSD only through matching validation/test protocols.\n", + "\n", + "**Research integrity:** this curated workflow does not claim new accuracy improvements or rerun the archived 106 experimental cells. The original notebook remains the detailed experimental record." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/README_REFACTOR.md b/README_REFACTOR.md new file mode 100644 index 0000000..62f923d --- /dev/null +++ b/README_REFACTOR.md @@ -0,0 +1,51 @@ +# Curated RF-DETR cable segmentation notebook + +The original **Segmentation.ipynb** is an experimental archive (106 code cells, +multiple dataset versions/checkpoints, and several PCA/RANSAC/SAM/DeepLSD variants). +This refactor introduces a separate and much shorter analysis workflow without +removing that evidence or rewriting the underlying original experiment. + +## Reproduction + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r requirements-analysis.txt +jupyter notebook Cable_Segmentation_Refactored.ipynb +``` + +Edit the notebook's `ProjectConfig` paths: COCO `train/`, `valid/`, `test/`, +prediction JSON paths, checkpoint, report folder. The dataset and complete weights +are not included in these refactoring files. A tracked LFS pointer is **not** +a usable `.pth` file until LFS content is fetched. + +The training/inference cells are opt-in and may need RF-DETR API adjustments to +match the **exact historical checkpoint architecture**. The evaluation-only +path loads COCO prediction JSONs. No dataset is modified on import or on +default execution. + +## Evaluation protocol + +1. COCO dataset read-only audit and density visualisation. +2. Optional training and public `predict()` inference. +3. Confidence threshold chosen with **validation** predictions only. +4. Test AP, AP50, AR1, AR10, AR100 with the selected/frozen threshold. +5. Geometric diagnostics from one-to-one GT-matched instance masks. + +With COCO `maxDets=[1,10,100]`, recall at indices 6/7/8 maps to +AR@1, AR@10, AR@100; the historical code mislabels index 6 at least once. +Greedy geometric matching is diagnostic and **not** equivalent to COCOeval. + +Original README reported AP50 0.528, AR@10 0.280, and ~0.998° orientation error. +These historical values are **not** recalculated or verified by this refactor. +No claims of a new accuracy improvement are made. + +## Limitations + +Dataset/checkpoint/predictions were not available together for a GPU run, +so the analysis code can be validated structurally and on synthetic cases +but actual metrics cannot yet be independently reproduced. Do not +combine results across the historical dataset_finale6 / dataset_finale8 / +dataset_finale_aug variants without checking provenance. + +Original archive remains unchanged on main. This branch is designed for review. diff --git a/REFACTOR_AUDIT.md b/REFACTOR_AUDIT.md new file mode 100644 index 0000000..806e39e --- /dev/null +++ b/REFACTOR_AUDIT.md @@ -0,0 +1,43 @@ +# Refactor audit: Cable-Instance_Segmentation + +## Inspection +The original notebook contains **106 code cells**, no Markdown cells, and +approximately **32.7 MB** of code and saved experiment outputs. It mixes +multiple dataset versions, model checkpoints, training recipes, and distinct +geometric refinement attempts. + +| Original cell (zero-based) | Observation | New treatment | +| --- | --- | --- | +| 1–3 | Extraction cells can delete destination directories | Excluded from run-all | +| 5 | COCO annotations patched in place | Read-only audit; metadata completed in memory | +| 9, 79 | Duplicate polar-line helper | Shared PCA helper with unit tests | +| 12, 66, 67 | Multiple recipes; 66 and 67 duplicated | Representative opt-in training recipe | +| 19, 30 | Test-based confidence threshold sweep | Use **valid** for threshold selection and lock for test | +| 19, 30 | COCO `stats[6]` labeled AR100 | Correct labels AR1=6, AR10=7, AR100=8 | +| 52–58 | SAM refinements mixed with inference and GT checks | Stay in historical archive | +| 80–84 | LDS parameter search and score reranking | Stay exploratory; not canonical | +| 88, 92–94 | External Git clones, environment uninstalls | Excluded from clean workflow | +| 97 | Empty code cell with stored output | Not copied into curated workflow | + +## Added +- Dedicated **22-cell** notebook `Cable_Segmentation_Refactored.ipynb` + with Markdown rationale and disabled-by-default training/inference. +- `cable_seg/core.py`: config, nonmutating inspection, PCA, axial angles, + one-to-one diagnostic matches and score filtering. +- `cable_seg/coco.py`: optional pycocotools COCO RLE/polygon decoding, + official AP/AR and geometry diagnostics. +- `cable_seg/inference.py`: optional model.predict -> COCO adapter. +- Unit tests and separate lightweight analysis/training requirements. + +## Scope and checks +The original `Segmentation.ipynb` is **untouched** and remains the detailed +experimental history. The curated notebook can run without a dataset and +without destructive setup commands; numeric results cannot be reproduced +until the dataset, prediction files, checkpoint weights and matching package +version are available. Reported historical results (AP50=0.528, +AR@10=0.280, angular error approximately 0.998 degrees) are not recomputed. + +A locally assembled equivalent passed **7 Python unit/static tests** and +a no-dataset Jupyter run-all; GitHub-published files have been checked for +presence and notebook JSON structure but no GPU/data execution was performed +on the branch. diff --git a/cable_seg/__init__.py b/cable_seg/__init__.py new file mode 100644 index 0000000..00c2cb0 --- /dev/null +++ b/cable_seg/__init__.py @@ -0,0 +1 @@ +from .core import ProjectConfig, read_json, inspect_coco, instance_density, line_from_mask, axial_angle_error_deg, match_masks, select_by_score diff --git a/cable_seg/coco.py b/cable_seg/coco.py new file mode 100644 index 0000000..7c73438 --- /dev/null +++ b/cable_seg/coco.py @@ -0,0 +1,102 @@ +"""COCO mask decoding, official segmentation AP/AR, and PCA diagnostics.""" +from __future__ import annotations +from pathlib import Path +from copy import deepcopy +import contextlib +import io +import json +import numpy as np +from .core import axial_angle_error_deg, line_from_mask, match_masks + +def _modules(): + try: + from pycocotools import mask as masks + from pycocotools.coco import COCO + from pycocotools.cocoeval import COCOeval + except ImportError as exc: + raise ImportError("Install pycocotools for COCO evaluation") from exc + return masks, COCO, COCOeval + +def decode_segmentation(segmentation, *, height, width): + masks, _, _ = _modules() + if isinstance(segmentation, list): + if not segmentation: + return np.zeros((height, width), dtype=bool) + rle = masks.merge(masks.frPyObjects(segmentation, height, width)) + elif isinstance(segmentation, dict): + rle = (masks.frPyObjects(segmentation, height, width) + if isinstance(segmentation.get("counts"), list) else segmentation) + else: + raise ValueError("Expected COCO polygon or RLE") + out = masks.decode(rle) + if out.ndim == 3: + out = np.any(out, axis=2) + if out.shape != (height, width): + raise ValueError("Decoded mask size mismatch") + return out.astype(bool) + +def encode_mask(mask): + masks, _, _ = _modules() + rle = masks.encode(np.asfortranarray(np.asarray(mask, np.uint8))) + rle["counts"] = rle["counts"].decode("ascii") + return rle + +def load_ground_truth(path): + """Fix optional COCO metadata in memory, never rewrite source annotations.""" + _, COCO, _ = _modules() + source = json.loads(Path(path).read_text(encoding="utf-8")) + gt = COCO() + gt.dataset = deepcopy(source) + gt.dataset.setdefault("info", {"description": "Cable segmentation", "version": "1.0"}) + gt.dataset.setdefault("licenses", []) + with contextlib.redirect_stdout(io.StringIO()): + gt.createIndex() + return gt + +def evaluate_coco(gt_json, predictions, *, max_dets=(1,10,100)): + """COCO segm stats: AP[0], AP50[1], AR1[6], AR10[7], AR100[8].""" + _, _, COCOeval = _modules() + gt = load_ground_truth(gt_json) + if not predictions: + return dict.fromkeys(("AP","AP50","AR1","AR10","AR100"), 0.0) + with contextlib.redirect_stdout(io.StringIO()): + dt = gt.loadRes(predictions) + ev = COCOeval(gt, dt, iouType="segm") + ev.params.maxDets = list(max_dets) + ev.evaluate() + ev.accumulate() + ev.summarize() + stats = ev.stats + return dict(zip(("AP","AP50","AR1","AR10","AR100"), + [float(stats[i]) for i in (0,1,6,7,8)])) + +def geometry_diagnostics(gt_json, predictions, *, min_iou=0.5, min_line_pixels=20): + gt = load_ground_truth(gt_json) + by_image = {} + for p in predictions: + by_image.setdefault(p["image_id"], []).append(p) + errors = [] + pairs = 0 + for image_id in gt.getImgIds(): + im = gt.imgs[image_id] + shape = {"height": im["height"], "width": im["width"]} + anns = gt.loadAnns(gt.getAnnIds(imgIds=[image_id])) + pred = by_image.get(image_id, []) + gt_masks = [decode_segmentation(a["segmentation"], **shape) for a in anns] + pr_masks = [decode_segmentation(p["segmentation"], **shape) for p in pred] + for i, j, iou in match_masks(gt_masks, pr_masks, min_iou=min_iou): + pairs += 1 + a = line_from_mask(gt_masks[i], min_pixels=min_line_pixels) + b = line_from_mask(pr_masks[j], min_pixels=min_line_pixels) + if a is not None and b is not None: + errors.append(axial_angle_error_deg(a[1], b[1])) + return { + "matched_pairs": pairs, "valid_line_pairs": len(errors), + "mean_axial_error_deg": float(np.mean(errors)) if errors else None, + "median_axial_error_deg": float(np.median(errors)) if errors else None, + } + +def save_predictions(path, predictions): + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(predictions, indent=2), encoding="utf-8") diff --git a/cable_seg/core.py b/cable_seg/core.py new file mode 100644 index 0000000..98c55c6 --- /dev/null +++ b/cable_seg/core.py @@ -0,0 +1,105 @@ +"""Side-effect-free COCO summaries, PCA geometry, and mask matching.""" +from __future__ import annotations +from collections import Counter +from dataclasses import dataclass +from pathlib import Path +import json +import math +import numpy as np + +@dataclass(frozen=True) +class ProjectConfig: + dataset_root: Path = Path("data/coco") + checkpoint: Path = Path("checkpoint_best_ema.pth") + predictions_valid: Path = Path("artifacts/predictions_valid.json") + predictions_test: Path = Path("artifacts/predictions_test.json") + output_dir: Path = Path("artifacts/reports") + seed: int = 42 + score_threshold: float = 0.25 + min_line_pixels: int = 20 + + def ann_path(self, split: str) -> Path: + if split not in ("train", "valid", "test"): + raise ValueError("Expected train, valid or test") + return self.dataset_root / split / "_annotations.coco.json" + +def read_json(path: Path): + with Path(path).open("r", encoding="utf-8") as f: + return json.load(f) + +def inspect_coco(annotation: dict) -> dict: + for key in ("images", "annotations", "categories"): + if not isinstance(annotation.get(key), list): + raise ValueError(f"Missing COCO list: {key}") + images, annotations = annotation["images"], annotation["annotations"] + ids = [im["id"] for im in images] + if len(ids) != len(set(ids)): + raise ValueError("Duplicate image IDs") + counts = Counter(a["image_id"] for a in annotations) + arr = np.array([counts.get(i, 0) for i in ids], dtype=int) + return { + "images": len(images), "annotations": len(annotations), + "categories": len(annotation["categories"]), + "images_without_annotations": int(np.sum(arr == 0)), + "orphan_annotations": sum(a["image_id"] not in set(ids) for a in annotations), + "mean_instances_per_image": float(np.mean(arr)) if len(arr) else 0.0, + "median_instances_per_image": float(np.median(arr)) if len(arr) else 0.0, + "max_instances_per_image": int(np.max(arr)) if len(arr) else 0, + } + +def instance_density(annotation: dict) -> dict[int, int]: + counts = Counter(a["image_id"] for a in annotation["annotations"]) + return {im["id"]: counts.get(im["id"], 0) for im in annotation["images"]} + +def line_from_mask(mask: np.ndarray, *, min_pixels=20) -> tuple[float, float] | None: + """PCA normal-form (rho, theta), theta modulo pi, signed rho.""" + if min_pixels < 2: + raise ValueError("min_pixels must be >= 2") + ys, xs = np.nonzero(np.asarray(mask) > 0.5) + if len(xs) < min_pixels: + return None + points = np.column_stack([xs, ys]).astype(float) + mean = points.mean(axis=0) + p = points - mean + cov = p.T @ p / len(points) + eigenvalues, vectors = np.linalg.eigh(cov) + if eigenvalues[-1] <= 1e-12: + return None + direction = vectors[:, -1] + theta = float((math.atan2(direction[1], direction[0]) + math.pi/2) % math.pi) + rho = float(mean @ np.array([math.cos(theta), math.sin(theta)])) + return rho, theta + +def axial_angle_error_deg(theta_a, theta_b) -> float: + d = abs((float(theta_a) - float(theta_b)) % math.pi) + return math.degrees(min(d, math.pi-d)) + +def mask_iou(a, b) -> float: + a, b = np.asarray(a, bool), np.asarray(b, bool) + if a.shape != b.shape: + raise ValueError("Mask shape mismatch") + union = np.count_nonzero(a | b) + return float(np.count_nonzero(a & b)/union) if union else 0.0 + +def match_masks(gt_masks, pred_masks, min_iou=0.5): + """Greedy one-to-one diagnostic matches, NOT official COCO evaluation.""" + if not 0 <= min_iou <= 1: + raise ValueError("Invalid IoU threshold") + candidates = [] + for i, gt in enumerate(gt_masks): + for j, pred in enumerate(pred_masks): + iou = mask_iou(gt, pred) + if iou >= min_iou: + candidates.append((-iou, i, j)) + used_gt, used_pred, matches = set(), set(), [] + for neg_iou, i, j in sorted(candidates): + if i not in used_gt and j not in used_pred: + matches.append((i, j, -neg_iou)) + used_gt.add(i) + used_pred.add(j) + return matches + +def select_by_score(predictions, threshold): + if not 0 <= threshold <= 1: + raise ValueError("Threshold must be within [0,1]") + return [p for p in predictions if float(p.get("score", -1)) >= threshold] diff --git a/cable_seg/inference.py b/cable_seg/inference.py new file mode 100644 index 0000000..5d80bff --- /dev/null +++ b/cable_seg/inference.py @@ -0,0 +1,44 @@ +"""Optional RF-DETR predict adapter, with explicit class-to-COCO mapping.""" +from pathlib import Path +import numpy as np +from .coco import encode_mask + +def predict_coco(model, annotations, image_dir, *, threshold=0.05, + class_index_to_category=None): + if not 0 <= threshold <= 1: + raise ValueError("Threshold must be in [0,1]") + if class_index_to_category is None: + class_index_to_category = { + i: c["id"] for i, c in enumerate( + sorted(annotations["categories"], key=lambda c: c["id"]) + ) + } + output = [] + for im in annotations["images"]: + path = Path(image_dir) / im["file_name"] + if not path.is_file(): + raise FileNotFoundError(path) + detections = model.predict(str(path), threshold=threshold) + if detections.mask is None: + raise ValueError("No segmentation masks returned by RF-DETR") + masks, scores = detections.mask, detections.confidence + labels, boxes = detections.class_id, detections.xyxy + if not (len(masks) == len(scores) == len(labels) == len(boxes)): + raise ValueError("Inconsistent detection lengths") + for mask, score, label, bbox in zip(masks, scores, labels, boxes): + label = int(label) + if label not in class_index_to_category: + raise ValueError(f"Unknown model class index: {label}") + if mask.shape != (im["height"], im["width"]): + raise ValueError("Output mask/image mismatch") + if not np.any(mask): + continue + x1, y1, x2, y2 = [float(v) for v in bbox] + output.append({ + "image_id": im["id"], + "category_id": class_index_to_category[label], + "segmentation": encode_mask(mask), + "bbox": [x1, y1, x2-x1, y2-y1], + "score": float(score), + }) + return output diff --git a/requirements-analysis.txt b/requirements-analysis.txt new file mode 100644 index 0000000..966ab10 --- /dev/null +++ b/requirements-analysis.txt @@ -0,0 +1,7 @@ +numpy +pandas +matplotlib +pillow +pycocotools +jupyter +nbformat diff --git a/requirements-training.txt b/requirements-training.txt new file mode 100644 index 0000000..eeff328 --- /dev/null +++ b/requirements-training.txt @@ -0,0 +1,5 @@ +-r requirements-analysis.txt +rfdetr +torch +torchvision +supervision diff --git a/tests/test_core.py b/tests/test_core.py new file mode 100644 index 0000000..9849872 --- /dev/null +++ b/tests/test_core.py @@ -0,0 +1,36 @@ +import math +import unittest +import numpy as np +from cable_seg.core import (ProjectConfig, inspect_coco, line_from_mask, + axial_angle_error_deg, mask_iou, match_masks, + select_by_score) + +class CoreTests(unittest.TestCase): + def test_coco(self): + data={"images":[{"id":1},{"id":2}], + "annotations":[{"image_id":1}],"categories":[{"id":1}]} + self.assertEqual(inspect_coco(data)["images_without_annotations"],1) + self.assertEqual(inspect_coco(data)["mean_instances_per_image"],0.5) + + def test_lines(self): + h=np.zeros((60,60)); h[10,5:55]=1 + v=np.zeros((60,60)); v[5:55,20]=1 + a=line_from_mask(h); b=line_from_mask(v) + self.assertAlmostEqual(axial_angle_error_deg(a[1],b[1]),90) + self.assertAlmostEqual(axial_angle_error_deg(a[1],a[1]+math.pi),0) + + def test_short(self): + self.assertIsNone(line_from_mask(np.ones((3,3)))) + + def test_one_to_one(self): + m=np.zeros((6,6));m[1:4,1:4]=1 + self.assertEqual(mask_iou(m,m),1.0) + self.assertEqual(len(match_masks([m,m],[m])),1) + + def test_threshold(self): + self.assertEqual(len(select_by_score([{"score":0.2},{"score":0.5}],0.5)),1) + with self.assertRaises(ValueError): select_by_score([],1.2) + with self.assertRaises(ValueError): ProjectConfig().ann_path("validation") + +if __name__=="__main__": + unittest.main()