Classify operator background corpus

scripts/prepare_operator_real_data_samples.py

@@ -22,6 +22,9 @@ GRB_GBG_URL = "https://geo.api.vlaanderen.be/GRB/ogc/features/v1/collections/GBG
 DEFAULT_OUTPUT_DIR = Path("/app/storage/operator-data")
 DEFAULT_GRB_PAGE_LIMIT = 1000
 DEFAULT_GRB_MAX_FEATURES = 100000
+REFERENCE_AOI_CATEGORY = "reference_aoi"
+PURE_EMPTY_BACKGROUND_CATEGORY = "pure_empty_negative"
+SPARSE_BACKGROUND_CATEGORY = "sparse_building_context"
 requests: Any = None
 rasterio: Any = None
 Transformer: Any = None
@@ -261,6 +264,12 @@ def selected_samples(raw: str) -> list[OperatorSample]:
     return [SAMPLES[slug] for slug in slugs]
 
 
+def background_category_for_sample(sample: OperatorSample, reference_feature_count: int) -> str:
+    if sample.sample_role != "background_candidate":
+        return REFERENCE_AOI_CATEGORY
+    return PURE_EMPTY_BACKGROUND_CATEGORY if reference_feature_count <= 0 else SPARSE_BACKGROUND_CATEGORY
+
+
 def apply_sample_overrides(
     sample: OperatorSample,
     *,
@@ -471,6 +480,7 @@ def fetch_reference(
     reference["sample_slug"] = sample.slug
     reference["sample_role"] = sample.sample_role
     reference["allow_empty_reference"] = sample.allow_empty_reference
+    reference["background_category"] = background_category_for_sample(sample, len(features))
     reference["reference_page_limit"] = page_limit
     reference["reference_max_features"] = max_features
     reference["reference_pages_fetched"] = len(pages)
@@ -484,6 +494,7 @@ def fetch_reference(
         props.setdefault("reference_layer_name", "buildings")
         props.setdefault("sample_slug", sample.slug)
         props.setdefault("sample_role", sample.sample_role)
+        props.setdefault("background_category", background_category_for_sample(sample, len(features)))
 
     reference_path.write_text(json.dumps(reference, ensure_ascii=False), encoding="utf-8")
     return prepared_url(GRB_GBG_URL, ogc_params), len(features)
@@ -513,6 +524,7 @@ def prepare_sample(
         )
     else:
         reference_feature_count = geojson_feature_count(reference_path)
+    background_category = background_category_for_sample(sample, reference_feature_count)
 
     return {
         "sample_slug": sample.slug,
@@ -524,6 +536,7 @@ def prepare_sample(
         "height": sample.height,
         "sample_role": sample.sample_role,
         "allow_empty_reference": sample.allow_empty_reference,
+        "background_category": background_category,
         "raster_path": str(ortho_path),
         "reference_path": str(reference_path),
         "reference_feature_count": reference_feature_count,
@@ -558,7 +571,8 @@ def write_readme(output_dir: Path, samples: list[dict[str, Any]]) -> None:
         lines.append(
             f"- `{sample['sample_slug']}`: `{Path(sample['raster_path']).name}` and "
             f"`{Path(sample['reference_path']).name}`, "
-            f"{sample['reference_feature_count']} reference features, role `{sample['sample_role']}`."
+            f"{sample['reference_feature_count']} reference features, role `{sample['sample_role']}`, "
+            f"background category `{sample['background_category']}`."
         )
     lines.append("")
     lines.append("Purpose: configured-YOLO detection + persisted QA/QC validation with operator-provided files.")