[uss_qualifier] migrate service_area to new volume resource (#1214)

Author: Shastick

NEXT_RELEASE_NOTES.md

@@ -108,6 +108,83 @@ planning_area:
     base_url: https://testdummy.interuss.org/interuss/monitoring/uss_qualifier/configurations/dev/f3548_self_contained/planning_area
 ```
 
+### Update ServiceAreaResource
+
+Resources of type `resources.ServiceAreaResource` now have their volume specified via a separate `resource.VolumeResource` resource, which needs to be passed as a dependency.
+
+Previously, a service area would be specified as:
+
+
+```yaml
+kentland_service_area:
+  $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
+  resource_type: resources.netrid.ServiceAreaResource
+  specification:
+    base_url: https://testdummy.interuss.org/interuss/monitoring/uss_qualifier/configurations/dev/library/resources/kentland_service_area
+    footprint:
+      - lat: 37.1853
+        lng: -80.6140
+      - lat: 37.2148
+        lng: -80.6140
+      - lat: 37.2148
+        lng: -80.5440
+      - lat: 37.1853
+        lng: -80.5440
+    altitude_min: 0
+    altitude_max: 3048
+    reference_time: '2023-01-10T00:00:00.123456+00:00'
+    time_start: '2023-01-10T00:00:01.123456+00:00'
+    time_end: '2023-01-10T01:00:01.123456+00:00'
+```
+
+The volume needs to ve moved to a separate `VolumeResource`, and references in the `dependencies` of the existing `PlanningAreaResource`:
+
+```yaml
+kentland_service_area_volume:
+  $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
+  resource_type: resources.VolumeResource
+  specification:
+    template:
+      outline_polygon:
+        vertices:
+          - lat: 37.1853
+            lng: -80.6140
+          - lat: 37.2148
+            lng: -80.6140
+          - lat: 37.2148
+            lng: -80.5440
+          - lat: 37.1853
+            lng: -80.5440
+      altitude_lower:
+        value: 0
+        reference: W84
+        units: M
+      altitude_upper:
+        value: 3048
+        reference: W84
+        units: M
+      start_time:
+        offset_from:
+          starting_from:
+            time_during_test: TimeOfEvaluation
+          offset: 1s
+      end_time:
+        offset_from:
+          starting_from:
+            time_during_test: TimeOfEvaluation
+          offset: 1h0m1s
+
+kentland_service_area:
+  $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
+  resource_type: resources.netrid.ServiceAreaResource
+  dependencies:
+    volume: kentland_service_area_volume
+  specification:
+    base_url: https://testdummy.interuss.org/interuss/monitoring/uss_qualifier/configurations/dev/library/resources/kentland_service_area
+```
+
+Do note that the altitude and time bound fields (`altitude_lower`, `altitude_upper`, `start_time`, `end_time`) require some adaptations beyond simple copy-pasting.
+
 ## Optional migration tasks
 
 ## Important information

monitoring/monitorlib/geo.py

@@ -207,6 +207,18 @@ def to_flight_planning_api(self) -> fp_api.Altitude:
             units=fp_api.AltitudeUnits.M,
         )
 
+    def to_w84_m(self):
+        """This altitude expressed in WGS84 meters, if possible to convert to it."""
+        if self.reference != AltitudeDatum.W84:
+            raise NotImplementedError(
+                f"Cannot convert altitude with reference {self.reference} to WGS84 meters"
+            )
+        if self.units != DistanceUnits.M:
+            raise NotImplementedError(
+                f"Cannot convert altitude with units {self.units} to WGS84 meters"
+            )
+        return self.value
+
     @staticmethod
     def from_f3548v21(vol: f3548v21.Altitude | dict) -> Altitude:
         return ImplicitDict.parse(vol, Altitude)
@@ -297,7 +309,7 @@ def intersects_vol3(self, vol3_2: Volume3D) -> bool:
 
         return footprint1.intersects(footprint2)
 
-    def transform(self, transformation: Transformation):
+    def transform(self, transformation: Transformation) -> Volume3D:
         if (
             "relative_translation" in transformation
             and transformation.relative_translation

monitoring/monitorlib/geotemporal.py

@@ -43,9 +43,7 @@ class Volume4DTemplate(ImplicitDict):
     transformations: list[Transformation] | None = None
     """If specified, transform this volume according to these transformations in order."""
 
-    def resolve(self, times: dict[TimeDuringTest, Time]) -> Volume4D:
-        """Resolve Volume4DTemplate into concrete Volume4D."""
-        # Make 3D volume
+    def _get_volume(self) -> Volume3D:
         kwargs = {}
         if self.outline_circle is not None:
             kwargs["outline_circle"] = self.outline_circle
@@ -55,11 +53,20 @@ def resolve(self, times: dict[TimeDuringTest, Time]) -> Volume4D:
             kwargs["altitude_lower"] = self.altitude_lower
         if self.altitude_upper is not None:
             kwargs["altitude_upper"] = self.altitude_upper
-        volume = Volume3D(**kwargs)
+        return Volume3D(**kwargs)
 
-        # Make 4D volume
-        kwargs = {"volume": volume}
+    def resolve_3d(self) -> Volume3D:
+        """Resolve Volume4DTemplate into concrete Volume3D."""
+        result = self._get_volume()
+        if self.transformations:
+            for xform in self.transformations:
+                result = result.transform(xform)
+        return result
 
+    def resolve_times(
+        self, times: dict[TimeDuringTest, Time]
+    ) -> tuple[Time | None, Time | None]:
+        """Resolve Volume4DTemplate into concrete temporal bounds (start, end)"""
         if self.start_time is not None:
             time_start = self.start_time.resolve(times)
         else:
@@ -84,18 +91,23 @@ def resolve(self, times: dict[TimeDuringTest, Time]) -> Volume4D:
             if time_end is None:
                 time_end = Time(time_start.datetime + self.duration.timedelta)
 
+        return time_start, time_end
+
+    def resolve(self, times: dict[TimeDuringTest, Time]) -> Volume4D:
+        """Resolve Volume4DTemplate into concrete Volume4D."""
+        volume = self.resolve_3d()
+
+        # Make 4D volume
+        kwargs = {"volume": volume}
+
+        time_start, time_end = self.resolve_times(times)
+
         if time_start is not None:
             kwargs["time_start"] = time_start
         if time_end is not None:
             kwargs["time_end"] = time_end
 
-        result = Volume4D(**kwargs)
-
-        if self.transformations:
-            for xform in self.transformations:
-                result = result.transform(xform)
-
-        return result
+        return Volume4D(**kwargs)
 
 
 class Volume4D(ImplicitDict):

monitoring/uss_qualifier/configurations/dev/dss_probing.yaml

@@ -3,6 +3,7 @@ v1:
   test_run:
     resources:
       resource_declarations:
+        kentland_service_area_volume: { $ref: 'library/resources.yaml#/kentland_service_area_volume' }
         kentland_service_area: { $ref: 'library/resources.yaml#/kentland_service_area' }
         kentland_planning_area_volume: { $ref: 'library/resources.yaml#/kentland_planning_area_volume' }
         kentland_planning_area: { $ref: 'library/resources.yaml#/kentland_planning_area' }

monitoring/uss_qualifier/configurations/dev/library/resources.yaml

@@ -21,25 +21,47 @@ id_generator:
     client_identity: utm_client_identity
   specification: { }
 
+kentland_service_area_volume:
+  $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
+  resource_type: resources.VolumeResource
+  specification:
+    template:
+      outline_polygon:
+        vertices:
+          - lat: 37.1853
+            lng: -80.6140
+          - lat: 37.2148
+            lng: -80.6140
+          - lat: 37.2148
+            lng: -80.5440
+          - lat: 37.1853
+            lng: -80.5440
+      altitude_lower:
+        value: 0
+        reference: W84
+        units: M
+      altitude_upper:
+        value: 3048
+        reference: W84
+        units: M
+      start_time:
+        offset_from:
+          starting_from:
+            time_during_test: TimeOfEvaluation
+          offset: 1s
+      end_time:
+        offset_from:
+          starting_from:
+            time_during_test: TimeOfEvaluation
+          offset: 1h0m1s
+
 kentland_service_area:
   $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
   resource_type: resources.netrid.ServiceAreaResource
+  dependencies:
+    volume: kentland_service_area_volume
   specification:
     base_url: https://testdummy.interuss.org/interuss/monitoring/uss_qualifier/configurations/dev/library/resources/kentland_service_area
-    footprint:
-      - lat: 37.1853
-        lng: -80.6140
-      - lat: 37.2148
-        lng: -80.6140
-      - lat: 37.2148
-        lng: -80.5440
-      - lat: 37.1853
-        lng: -80.5440
-    altitude_min: 0
-    altitude_max: 3048
-    reference_time: '2023-01-10T00:00:00.123456+00:00'
-    time_start: '2023-01-10T00:00:01.123456+00:00'
-    time_end: '2023-01-10T01:00:01.123456+00:00'
 
 kentland_planning_area_volume:
   $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
@@ -104,31 +126,53 @@ kentland_problematically_big_area:
           - lat: 38
             lng: -80
 
+zurich_service_area_volume:
+  $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
+  resource_type: resources.VolumeResource
+  specification:
+    template:
+      outline_polygon:
+        vertices:
+          - lat: 47.45237618874023
+            lng: 8.337401667996478
+          - lat: 47.38882810764797
+            lng: 8.343217430398902
+          - lat: 47.3643466256706
+            lng: 8.389932768382156
+          - lat: 47.36323038495268
+            lng: 8.536070011827881
+          - lat: 47.36909451406398
+            lng: 8.580678976356925
+          - lat: 47.4007874493574
+            lng: 8.57764881798931
+          - lat: 47.451319730511365
+            lng: 8.46442103543102
+      altitude_lower:
+        value: 0
+        reference: W84
+        units: M
+      altitude_upper:
+        value: 1000
+        reference: W84
+        units: M
+      start_time:
+        offset_from:
+          starting_from:
+            time_during_test: TimeOfEvaluation
+          offset: 1s
+      end_time:
+        offset_from:
+          starting_from:
+            time_during_test: TimeOfEvaluation
+          offset: 1h0m1s
+
 zurich_service_area:
   $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
   resource_type: resources.netrid.ServiceAreaResource
+  dependencies:
+    volume: zurich_service_area_volume
   specification:
     base_url: https://testdummy.interuss.org/interuss/monitoring/uss_qualifier/configurations/dev/library/resources/zurich_service_area
-    footprint:
-      - lat: 47.45237618874023
-        lng: 8.337401667996478
-      - lat: 47.38882810764797
-        lng: 8.343217430398902
-      - lat: 47.3643466256706
-        lng: 8.389932768382156
-      - lat: 47.36323038495268
-        lng: 8.536070011827881
-      - lat: 47.36909451406398
-        lng: 8.580678976356925
-      - lat: 47.4007874493574
-        lng: 8.57764881798931
-      - lat: 47.451319730511365
-        lng: 8.46442103543102
-    altitude_min: 0
-    altitude_max: 1000
-    reference_time: '2025-10-15T00:00:00.123456+00:00'
-    time_start: '2025-10-15T00:00:01.123456+00:00'
-    time_end: '2025-10-15T01:00:01.123456+00:00'
 
 zurich_planning_area_volume:
   $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json

monitoring/uss_qualifier/configurations/dev/netrid_v19.yaml

@@ -7,6 +7,7 @@ v1:
         netrid_observation_evaluation_configuration: {$ref: 'library/resources.yaml#/netrid_observation_evaluation_configuration'}
         utm_client_identity: {$ref: 'library/resources.yaml#/utm_client_identity'}
         id_generator: {$ref: 'library/resources.yaml#/id_generator'}
+        kentland_service_area_volume: {$ref: 'library/resources.yaml#/kentland_service_area_volume'}
         kentland_service_area: {$ref: 'library/resources.yaml#/kentland_service_area'}
         kentland_planning_area_volume: {$ref: 'library/resources.yaml#/kentland_planning_area_volume'}
         kentland_planning_area: {$ref: 'library/resources.yaml#/kentland_planning_area'}

monitoring/uss_qualifier/configurations/dev/netrid_v22a.yaml

@@ -7,6 +7,7 @@ v1:
         netrid_observation_evaluation_configuration: {$ref: 'library/resources.yaml#/netrid_observation_evaluation_configuration'}
         utm_client_identity: {$ref: 'library/resources.yaml#/utm_client_identity'}
         id_generator: {$ref: 'library/resources.yaml#/id_generator'}
+        kentland_service_area_volume: {$ref: 'library/resources.yaml#/kentland_service_area_volume'}
         kentland_service_area: {$ref: 'library/resources.yaml#/kentland_service_area'}
         kentland_planning_area_volume: {$ref: 'library/resources.yaml#/kentland_planning_area_volume'}
         kentland_planning_area: {$ref: 'library/resources.yaml#/kentland_planning_area'}

monitoring/uss_qualifier/configurations/dev/uspace.yaml

@@ -13,6 +13,7 @@ v1:
         netrid_observation_evaluation_configuration: {$ref: 'library/resources.yaml#/netrid_observation_evaluation_configuration'}
         utm_client_identity: {$ref: 'library/resources.yaml#/utm_client_identity'}
         id_generator: {$ref: 'library/resources.yaml#/id_generator'}
+        zurich_service_area_volume: {$ref: 'library/resources.yaml#/zurich_service_area_volume'}
         zurich_service_area: {$ref: 'library/resources.yaml#/zurich_service_area'}
         zurich_planning_area_volume: {$ref: 'library/resources.yaml#/zurich_planning_area_volume'}
         zurich_planning_area: {$ref: 'library/resources.yaml#/zurich_planning_area'}