Merge pull request #1931 from kili-technology/feature/lab-3719-aau-i-can-upload-geojson-labels-directly-without-conversion

RuellePaul · web-flow · commit 81b107b7a45b · 2025-07-09T11:22:29.000+02:00
feat(LAB-3719): support automatic and specific job mapping for GeoJSON imports
diff --git a/src/kili/presentation/client/label.py b/src/kili/presentation/client/label.py
@@ -48,6 +48,10 @@
 from kili.use_cases.label.process_shapefiles import get_json_response_from_shapefiles
 from kili.use_cases.label.types import LabelToCreateUseCaseInput
 from kili.use_cases.project.project import ProjectUseCases
+from kili.utils.labels.geojson import (
+    enrich_geojson_with_kili_properties,
+    enrich_geojson_with_specific_mapping,
+)
 from kili.utils.labels.parsing import ParsedLabel
 from kili.utils.logcontext import for_all_methods, log_call
 
@@ -1402,49 +1406,132 @@ def append_labels_from_shapefiles(
             asset_external_id_array=[asset_external_id],
         )
 
+    # pylint: disable=too-many-branches
     @typechecked
     def append_labels_from_geojson_files(
         self,
         project_id: str,
         asset_external_id: str,
         geojson_file_paths: List[str],
+        job_names: Optional[List[str]] = None,
+        category_names: Optional[List[str]] = None,
     ):
         """Import and convert GeoJSON files into annotations for a specific asset in a Kili project.
 
         This method processes GeoJSON feature collections, converts them to the appropriate
         Kili annotation format, and appends them as labels to the specified asset.
-        The GeoJSON features must contain job names and category information in their properties.
+
+        Three modes of import are supported:
+
+        1. **With `kili` properties**: GeoJSON features contain 'kili' metadata in their properties
+           with job, type, and category information.
+
+        2. **With specific job/category names**: Provide `job_names` and `category_names` to map
+           all compatible geometries from each file to the specified job and category.
+
+        3. **Automatic mapping**: When no 'kili' properties or specific names are provided,
+           geometries are automatically mapped based on type and available jobs.
 
         Args:
             project_id: The ID of the Kili project to add the labels to.
             asset_external_id: The external ID of the asset to label.
             geojson_file_paths: List of file paths to the GeoJSON files to be processed.
-                Each file should contain a FeatureCollection with features that have
-                'kili' metadata in their properties, including 'job', 'type', and 'categories'.
+                Each file should contain a FeatureCollection with features.
+            job_names: Optional list of job names in the Kili project, one for each GeoJSON file.
+                When provided, all compatible geometries from the corresponding file will be
+                mapped to this job. Must have the same length as `geojson_file_paths`.
+            category_names: Optional list of category names, one for each GeoJSON file.
+                When provided, all geometries from the corresponding file will be assigned
+                to this category. Must have the same length as `geojson_file_paths`.
+                Each category must exist in the corresponding job's ontology.
 
         Note:
-            The GeoJSON features must contain a 'kili' property with the following structure:
-            - 'job': The name of the job in the Kili project
-            - 'type': The annotation type ('marker', 'polyline', 'semantic', etc.)
-            - 'categories': List of category objects with 'name' field
+            **Geometry-to-job compatibility:**
+            - Point geometries → jobs with 'marker' tool
+            - LineString geometries → jobs with 'polyline' tool
+            - Polygon geometries → jobs with 'polygon' or 'semantic' tool
+            - MultiPolygon geometries → jobs with 'semantic' tool
+
+            **GeoJSON 'kili' properties structure (Mode 1):**
+            ```json
+            {
+                "properties": {
+                    "kili": {
+                        "job": "job_name",
+                        "type": "marker|polyline|polygon|semantic",
+                        "categories": [{"name": "category_name"}]
+                    }
+                }
+            }
+            ```
 
-            Supported geometries: Point, LineString, Polygon, and MultiPolygon.
-            Polygon and MultiPolygon are always mapped to semantic segmentation jobs in Kili.
+            **Automatic mapping priority (Mode 3):**
+            - Point → first available 'marker' job
+            - LineString → first available 'polyline' job
+            - Polygon → first available 'polygon' job, fallback to 'semantic'
+            - MultiPolygon → first available 'semantic' job
 
         Examples:
+            Mode 1 - With kili properties in GeoJSON:
             >>> kili.append_labels_from_geojson_files(
                     project_id="project_id",
                     asset_external_id="asset_1",
                     geojson_file_paths=["annotations.geojson"]
                 )
+
+            Mode 2 - With specific job/category mapping:
+            >>> kili.append_labels_from_geojson_files(
+                    project_id="project_id",
+                    asset_external_id="asset_1",
+                    geojson_file_paths=["points.geojson", "polygons.geojson"],
+                    job_names=["MARKERS", "POLYGONS"],
+                    category_names=["BUILDING", "ROAD"]
+                )
+
+            Mode 3 - Automatic mapping:
+            >>> kili.append_labels_from_geojson_files(
+                    project_id="project_id",
+                    asset_external_id="asset_1",
+                    geojson_file_paths=["mixed_geometries.geojson"]
+                )
         """
+        if job_names is not None and category_names is not None:
+            if len(job_names) != len(geojson_file_paths):
+                raise ValueError("job_names must have the same length as geojson_file_paths")
+            if len(category_names) != len(geojson_file_paths):
+                raise ValueError("category_names must have the same length as geojson_file_paths")
+            if len(job_names) != len(category_names):
+                raise ValueError("job_names and category_names must have the same length")
+        elif job_names is not None or category_names is not None:
+            raise ValueError(
+                "Both job_names and category_names must be provided together, or both must be None"
+            )
+
+        json_interface = self.kili_api_gateway.get_project(
+            ProjectId(project_id), ("jsonInterface",)
+        )["jsonInterface"]
+
         merged_json_response = {}
 
-        for file_path in geojson_file_paths:
-            with open(file_path, encoding="utf-8") as f:
-                feature_collection = json.load(f)
+        for file_index, file_path in enumerate(geojson_file_paths):
+            with open(file_path, encoding="utf-8") as file:
+                feature_collection = json.load(file)
+
+            if job_names is not None and category_names is not None:
+                enriched_feature_collection = enrich_geojson_with_specific_mapping(
+                    feature_collection,
+                    json_interface,
+                    job_names[file_index],
+                    category_names[file_index],
+                )
+            else:
+                enriched_feature_collection = enrich_geojson_with_kili_properties(
+                    feature_collection, json_interface
+                )
 
-            json_response = geojson_feature_collection_to_kili_json_response(feature_collection)
+            json_response = geojson_feature_collection_to_kili_json_response(
+                enriched_feature_collection
+            )
 
             for job_name, job_data in json_response.items():
                 if job_name not in merged_json_response:
diff --git a/src/kili/utils/labels/geojson.py b/src/kili/utils/labels/geojson.py
@@ -0,0 +1,179 @@
+"""Utility functions to enrich GeoJSON features with Kili properties."""
+
+from typing import Dict
+
+
+# pylint: disable=too-many-statements,too-many-branches
+def enrich_geojson_with_kili_properties(feature_collection: Dict, json_interface: Dict) -> Dict:
+    """Enrich GeoJSON features with kili properties when missing.
+
+    Args:
+        feature_collection: The GeoJSON feature collection to enrich
+        json_interface: The project's JSON interface containing job definitions
+
+    Returns:
+        The enriched feature collection with kili properties added where needed
+    """
+    object_detection_jobs = {}
+    if "jobs" in json_interface:
+        for job_name, job_config in json_interface["jobs"].items():
+            if job_config.get("mlTask") == "OBJECT_DETECTION":
+                object_detection_jobs[job_name] = job_config
+
+    marker_job = None
+    polyline_job = None
+    polygon_job = None
+    semantic_job = None
+
+    for job_name, job_config in object_detection_jobs.items():
+        tools = job_config.get("tools", [])
+        if "marker" in tools and marker_job is None:
+            marker_job = (job_name, job_config)
+        if "polyline" in tools and polyline_job is None:
+            polyline_job = (job_name, job_config)
+        if "polygon" in tools and polygon_job is None:
+            polygon_job = (job_name, job_config)
+        if "semantic" in tools and semantic_job is None:
+            semantic_job = (job_name, job_config)
+
+    def get_first_category_name(job_config):
+        categories = job_config.get("content", {}).get("categories", {})
+        if categories:
+            first_category_key = next(iter(categories.keys()))
+            return first_category_key
+        return None
+
+    def create_kili_property(job_name, job_config, annotation_type):
+        category_name = get_first_category_name(job_config)
+        if category_name:
+            return {
+                "kili": {
+                    "children": {},
+                    "categories": [{"name": category_name}],
+                    "type": annotation_type,
+                    "job": job_name,
+                }
+            }
+        return None
+
+    enriched_features = []
+
+    for feature in feature_collection.get("features", []):
+        # Skip if feature already has kili properties
+        if feature.get("properties", {}).get("kili") is not None:
+            enriched_features.append(feature)
+            continue
+
+        # Skip features with null geometry unless they have kili properties
+        if feature.get("geometry") is None:
+            continue
+
+        geometry_type = feature.get("geometry", {}).get("type")
+        kili_property = None
+
+        if geometry_type == "Point" and marker_job:
+            job_name, job_config = marker_job
+            kili_property = create_kili_property(job_name, job_config, "marker")
+
+        elif geometry_type == "LineString" and polyline_job:
+            job_name, job_config = polyline_job
+            kili_property = create_kili_property(job_name, job_config, "polyline")
+
+        elif geometry_type == "Polygon":
+            if polygon_job:
+                job_name, job_config = polygon_job
+                kili_property = create_kili_property(job_name, job_config, "polygon")
+            elif semantic_job:
+                job_name, job_config = semantic_job
+                kili_property = create_kili_property(job_name, job_config, "semantic")
+
+        elif geometry_type == "MultiPolygon" and semantic_job:
+            job_name, job_config = semantic_job
+            kili_property = create_kili_property(job_name, job_config, "semantic")
+
+        if kili_property:
+            if "properties" not in feature:
+                feature["properties"] = {}
+            feature["properties"].update(kili_property)
+            enriched_features.append(feature)
+        else:
+            continue
+
+    enriched_collection = feature_collection.copy()
+    enriched_collection["features"] = enriched_features
+    return enriched_collection
+
+
+# pylint: disable=too-many-branches
+def enrich_geojson_with_specific_mapping(
+    feature_collection: Dict, json_interface: Dict, target_job_name: str, target_category_name: str
+) -> Dict:
+    """Enrich GeoJSON features with specific job and category mapping.
+
+    Args:
+        feature_collection: The GeoJSON feature collection to enrich
+        json_interface: The project's JSON interface containing job definitions
+        target_job_name: The specific job name to map geometries to
+        target_category_name: The specific category name to assign to all geometries
+
+    Returns:
+        The enriched feature collection with kili properties added
+    """
+    target_job_config = None
+    if "jobs" in json_interface:
+        target_job_config = json_interface["jobs"].get(target_job_name)
+
+    if not target_job_config:
+        raise ValueError(f"Job '{target_job_name}' not found in project")
+
+    if target_job_config.get("mlTask") != "OBJECT_DETECTION":
+        raise ValueError(f"Job '{target_job_name}' is not an OBJECT_DETECTION job")
+
+    categories = target_job_config.get("content", {}).get("categories", {})
+    if target_category_name not in categories:
+        raise ValueError(f"Category '{target_category_name}' not found in job '{target_job_name}'")
+
+    tools = target_job_config.get("tools", [])
+
+    def create_kili_property(annotation_type: str):
+        return {
+            "kili": {
+                "children": {},
+                "categories": [{"name": target_category_name}],
+                "type": annotation_type,
+                "job": target_job_name,
+            }
+        }
+
+    enriched_features = []
+
+    for feature in feature_collection.get("features", []):
+        # Skip features with null geometry
+        if feature.get("geometry") is None:
+            continue
+
+        geometry_type = feature.get("geometry", {}).get("type")
+        kili_property = None
+
+        # Map geometry types to annotation types based on available tools
+        if geometry_type == "Point" and "marker" in tools:
+            kili_property = create_kili_property("marker")
+        elif geometry_type == "LineString" and "polyline" in tools:
+            kili_property = create_kili_property("polyline")
+        elif geometry_type == "Polygon":
+            if "polygon" in tools:
+                kili_property = create_kili_property("polygon")
+            elif "semantic" in tools:
+                kili_property = create_kili_property("semantic")
+        elif geometry_type == "MultiPolygon" and "semantic" in tools:
+            kili_property = create_kili_property("semantic")
+
+        if kili_property:
+            if "properties" not in feature:
+                feature["properties"] = {}
+            feature["properties"].update(kili_property)
+            enriched_features.append(feature)
+
+    enriched_collection = feature_collection.copy()
+    enriched_collection["features"] = enriched_features
+    return enriched_collection
diff --git a/tests/unit/utils/labels/test_geojson_enrichment.py b/tests/unit/utils/labels/test_geojson_enrichment.py
