Add deterministic COCO -> ontology-v2 two‑mask converter with CLI, policy, reports and tests

[InsightofSPb]

Motivation

This PR adds a production-oriented converter for transforming COCO polygon annotations into the repository’s existing heritage_facades_v2_12concepts_two_heads dataset contract.

The converter preserves the independent main-semantic and ornament representations, resolves main-class overlaps deterministically, validates facade-disjoint splits, and records sufficient provenance for downstream training and evaluation.

What changed

• Added the ovs_heritage.coco_converter CLI with three commands:

  • audit — complete read-only dataset preflight;
  • convert — validated and transactional dataset conversion;
  • validate — standalone output-manifest and artifact validation.

• Added the versioned conversion policy ovs_heritage/configs/coco_conversion_v1.json.

• Mapped all 11 source COCO categories to the canonical ontology-v2 classes by name.

• Preserved the two-mask representation:

  • main_masks/*.png contains semantic IDs from {0,1,2,3,4,5,6,7,9,10,11,255};
  • ornament_masks/*.png independently contains {0,1,255};
  • semantic ID 8 is excluded from the main mask and represented through the ornament mask.

• Implemented the agreed deterministic main-class priority:

  1. MISSING_ELEMENT
  2. SPALLING
  3. CRACK
  4. DELAMINATION
  5. CORROSION
  6. REPAIRS
  7. ADVERTISEMENTS
  8. TEXT_OR_IMAGES
  9. EFFLORESCENCE
  10. WATER_STAIN

• Replaced the custom rasterizer with canonical COCO polygon decoding using pycocotools.mask.frPyObjects, merge, and decode.

• Added strict validation for malformed, non-finite, degenerate, zero-area, empty, and unsupported geometry.

• Documented and reported the out-of-bounds coordinate policy: polygons are clipped to the COCO image grid, while geometry that decodes to an empty mask is rejected.

• Added deterministic Label Studio filename resolution with the following order:

  1. exact original basename;
  2. exact basename after removing a valid eight-hex-digit prefix;
  3. case-insensitive original basename;
  4. case-insensitive hash-stripped basename.

• Added missing, ambiguous, normalized-name collision, and portable-output collision checks.

• Added shared preflight validation used by both audit and conversion:

  • COCO structure and identifier validation;
  • category and ontology mapping validation;
  • image existence, readability, and dimension validation;
  • complete polygon decoding;
  • geometry and overlap statistics;
  • optional metadata completeness and facade-leakage validation.

• Added transactional output publishing:

  • generation occurs in a unique sibling staging directory;
  • staged artifacts are validated before publication;
  • an existing output is preserved until staging succeeds;
  • overwrite uses backup, rename, and rollback;
  • failed staging directories are removed.

• Strengthened conversion-policy and manifest validation:

  • exact ontology coverage;
  • complete and duplicate-free main priority;
  • unique sample and image IDs;
  • unique artifact paths;
  • consistent COCO hashes and schema versions;
  • valid dimensions and annotation IDs;
  • mask dtype, grid, and value-domain validation;
  • facade-disjoint split validation.

• Added structured outputs:

  • manifest.jsonl;
  • overlap_report.json;
  • geometry_report.json;
  • filename_resolution_report.json;
  • conversion_summary.json;
  • copied portable source images;
  • lossless main and ornament masks.

• Added pycocotools==2.0.8 to the CPU GitHub Actions workflow.

Safety and provenance

• Source COCO files and source images are never modified.
• Conversion fails closed on ambiguous ontology, geometry, filenames, metadata, dimensions, or facade splits.
• Output summaries record source COCO, ontology, policy, and generated-artifact hashes.
• Main and ornament masks are written as lossless single-channel uint8 PNG files and read back for verification.
• Dataset sizes and local filesystem paths are not hardcoded.

Testing

GitHub Actions completed successfully on commit 2a50f8ad719f914ccdc5638ec6d76b3c90d38e6c.

Executed checks:

python -m compileall -q ovs_heritage
pytest -q ovs_heritage/tests
ruff check ovs_heritage

Results:

• compilation succeeded;
• 96 passed;
• Ruff: All checks passed.

The test suite covers canonical and multipart polygon rasterization, malformed geometry, class priority, annotation-order invariance, ornament independence, filename normalization and ambiguity, transactional rollback, audit preflight, policy validation, manifest validation, artifact validation, and facade leakage.

Remaining dataset-level verification

This PR validates the converter with synthetic fixtures and the complete repository CPU test suite. A full conversion of the real 329-image export is intentionally left for a separate dataset smoke test because it requires the complete source-image directory and reviewed facade metadata table.