[uss_qualifier] rename and generalize VerticesResource to VolumeResource

Author: Shastick

NEXT_RELEASE_NOTES.md

@@ -33,10 +33,55 @@ The release notes should contain at least the following sections:
 
 --------------------------------------------------------------------------------------------------------------------
 
-# Release Notes for v0.18.0
+# Release Notes for v0.19.0
 
 ## Mandatory migration tasks
 
+### Replacement of `resources.VerticesResource` with `resources.VolumeResource`
+
+[VerticesResource](https://github.com/interuss/monitoring/blob/main/monitoring/uss_qualifier/resources/vertices.py) is being replaced with a new [VolumeResource](https://github.com/interuss/monitoring/blob/main/monitoring/uss_qualifier/resources/volume.py),
+which now contains a `Volume4DTemplate`, which can be used to define anything from a simple 2D polygon to a 3D volume to a full 4D spatio-temporal volume with dynamic time-bounds.
+
+The old resources, defined as:
+
+```yaml
+some_resource:
+  $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
+  resource_type: resources.VerticesResource
+  specification:
+    vertices:
+      - lat: 38
+        lng: -81
+      - lat: 37
+        lng: -81
+      - lat: 37
+        lng: -80
+      - lat: 38
+        lng: -80
+```
+
+Can be straightforwardly replaced with:
+
+```yaml
+planning_area:
+  $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
+  resource_type: resources.PlanningAreaResource
+  specification:
+    template:
+      outline_polygon:
+        vertices:
+          - lat: 38
+            lng: -81
+          - lat: 37
+            lng: -81
+          - lat: 37
+            lng: -80
+          - lat: 38
+            lng: -80
+```
+
+The optional fields of [Volume4DTemplate](https://github.com/interuss/monitoring/blob/master/monitoring/monitorlib/geotemporal.py#L21) (`altitude_lower`, `altitude_upper`, `start_time`, `start_time`, `duration`, `transformations`) can be safely omitted in all contexts that formerly depended on `VerticesResource`.
+
 ## Optional migration tasks
 
 ## Important information

monitoring/uss_qualifier/configurations/dev/f3548_self_contained.yaml

@@ -221,17 +221,19 @@ v1:
         # An area designed to be soo big as to be refused by systems queries with it.
         problematically_big_area:
           $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
-          resource_type: resources.VerticesResource
+          resource_type: resources.VolumeResource
           specification:
-            vertices:
-              - lat: 38
-                lng: -81
-              - lat: 37
-                lng: -81
-              - lat: 37
-                lng: -80
-              - lat: 38
-                lng: -80
+            template:
+              outline_polygon:
+                vertices:
+                  - lat: 38
+                    lng: -81
+                  - lat: 37
+                    lng: -81
+                  - lat: 37
+                    lng: -80
+                  - lat: 38
+                    lng: -80
 
         # Details of conflicting flights (used in nominal planning scenario)
         conflicting_flights:

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

@@ -68,30 +68,34 @@ kentland_planning_area:
 
 au_problematically_big_area: # A huge (as in "too big") area for checks around area sizes
   $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json
-  resource_type: resources.VerticesResource
+  resource_type: resources.VolumeResource
   specification:
-    vertices:
-      - lat: -23
-        lng: 130
-      - lat: -24
-        lng: 130
-      - lat: -24
-        lng: 132
-      - lat: -23
-        lng: 132
+    template:
+      outline_polygon:
+        vertices:
+          - lat: -23
+            lng: 130
+          - lat: -24
+            lng: 130
+          - lat: -24
+            lng: 132
+          - lat: -23
+            lng: 132
 
 kentland_problematically_big_area:
-  resource_type: resources.VerticesResource
+  resource_type: resources.VolumeResource
   specification:
-    vertices:
-      - lat: 38
-        lng: -81
-      - lat: 37
-        lng: -81
-      - lat: 37
-        lng: -80
-      - lat: 38
-        lng: -80
+    template:
+      outline_polygon:
+        vertices:
+          - lat: 38
+            lng: -81
+          - lat: 37
+            lng: -81
+          - lat: 37
+            lng: -80
+          - lat: 38
+            lng: -80
 
 # ===== NetRID flights data =====
 
@@ -169,17 +173,19 @@ che_planning_area:
         units: M
 
 che_problematically_big_area:
-  resource_type: resources.VerticesResource
+  resource_type: resources.VolumeResource
   specification:
-    vertices:
-      - lat: 45
-        lng: 7
-      - lat: 45
-        lng: 8
-      - lat: 46
-        lng: 8
-      - lat: 46
-        lng: 7
+    template:
+      outline_polygon:
+        vertices:
+          - lat: 45
+            lng: 7
+          - lat: 45
+            lng: 8
+          - lat: 46
+            lng: 8
+          - lat: 46
+            lng: 7
 
 che_invalid_flight_auth_flights:
   $content_schema: monitoring/uss_qualifier/resources/definitions/ResourceDeclaration.json

monitoring/uss_qualifier/configurations/dev/utm_implementation_us_lib/baseline.libsonnet

@@ -143,26 +143,30 @@ function(env) {
 
           // An area designed to be soo big as to be refused by systems queries with it.
           problematically_big_area: {
-            resource_type: 'resources.VerticesResource',
+            resource_type: 'resources.VolumeResource',
             specification: {
-              vertices: [
-                {
-                  lat: 33,
-                  lng: -96,
-                },
-                {
-                  lat: 32,
-                  lng: -96,
-                },
-                {
-                  lat: 32,
-                  lng: -95,
-                },
-                {
-                  lat: 33,
-                  lng: -95,
-                },
-              ],
+              template: {
+                outline_polygon: {
+                  vertices: [
+                    {
+                      lat: 33,
+                      lng: -96,
+                    },
+                    {
+                      lat: 32,
+                      lng: -96,
+                    },
+                    {
+                      lat: 32,
+                      lng: -95,
+                    },
+                    {
+                      lat: 33,
+                      lng: -95,
+                    },
+                  ],
+                }
+              },
             },
           },
 

monitoring/uss_qualifier/resources/__init__.py

@@ -1,2 +1,2 @@
 from .planning_area import PlanningAreaResource as PlanningAreaResource
-from .vertices import VerticesResource as VerticesResource
+from .volume import VolumeResource as VolumeResource

monitoring/uss_qualifier/resources/vertices.py

@@ -0,0 +1,48 @@
+import s2sphere
+from implicitdict import ImplicitDict
+
+from monitoring.monitorlib.geo import (
+    LatLngPoint,
+    Volume3D,
+    get_latlngrect_vertices,
+    make_latlng_rect,
+)
+from monitoring.monitorlib.geotemporal import Volume4DTemplate
+from monitoring.uss_qualifier.resources.resource import Resource
+
+
+class VolumeSpecification(ImplicitDict):
+    """Specifies a volume in time and three-dimensional space.
+    The time-bounds, as well as the lower and upper bounds of the Volume3D may be omitted if a timeless and altitude-free two-dimensional area is required.
+    See monitoring.monitorlib.geotemporal.Volume4DTemplate for details.
+    """
+
+    template: Volume4DTemplate
+
+    def s2_vertices(self) -> list[s2sphere.LatLng]:
+        """Returns the vertices of the 2D area represented by this volume specification. If the underlying volume is a Polygon, its
+        original vertices are returned. If it is a Circle, the vertices of the bounding rectangle are returned.
+        """
+        if (
+            self.template.outline_polygon is not None
+            and self.template.outline_polygon.vertices is not None
+        ):
+            return [v.as_s2sphere() for v in self.template.outline_polygon.vertices]
+        else:
+            return get_latlngrect_vertices(
+                make_latlng_rect(Volume3D(outline_circle=self.template.outline_circle))
+            )
+
+    def vertices(self) -> list[LatLngPoint]:
+        """Returns the vertices of the 2D area represented by this volume specification. If the underlying volume is a Polygon, its
+        original vertices are returned. If it is a Circle, the vertices of the bounding rectangle are returned.
+        """
+        return [LatLngPoint.from_s2(v) for v in self.s2_vertices()]
+
+
+class VolumeResource(Resource[VolumeSpecification]):
+    specification: VolumeSpecification
+
+    def __init__(self, specification: VolumeSpecification, resource_origin: str):
+        super().__init__(specification, resource_origin)
+        self.specification = specification

monitoring/uss_qualifier/resources/volume.py

@@ -6,10 +6,10 @@
 from monitoring.monitorlib.fetch import rid as fetch
 from monitoring.monitorlib.mutate import rid as mutate
 from monitoring.prober.infrastructure import register_resource_type
-from monitoring.uss_qualifier.resources import VerticesResource
 from monitoring.uss_qualifier.resources.astm.f3411.dss import DSSInstanceResource
 from monitoring.uss_qualifier.resources.interuss.id_generator import IDGeneratorResource
 from monitoring.uss_qualifier.resources.netrid.service_area import ServiceAreaResource
+from monitoring.uss_qualifier.resources.volume import VolumeResource
 from monitoring.uss_qualifier.scenarios.astm.netrid.common.dss.isa_validator import (
     ISAValidator,
 )
@@ -30,7 +30,7 @@ def __init__(
         dss: DSSInstanceResource,
         id_generator: IDGeneratorResource,
         isa: ServiceAreaResource,
-        problematically_big_area: VerticesResource,
+        problematically_big_area: VolumeResource,
     ):
         super().__init__()
         self._dss = (
@@ -41,9 +41,7 @@ def __init__(
         self._isa_version: str | None = None
         self._isa = isa.specification
         self._isa_area = [vertex.as_s2sphere() for vertex in self._isa.footprint]
-        self._huge_area = [
-            v.as_s2sphere() for v in problematically_big_area.specification.vertices
-        ]
+        self._huge_area = problematically_big_area.specification.s2_vertices()
 
     def run(self, context: ExecutionContext):
         self._shift_isa_time_relative_to_now()

monitoring/uss_qualifier/scenarios/astm/netrid/common/dss/isa_simple.py

@@ -10,10 +10,10 @@
 from monitoring.monitorlib.mutate.rid import ChangedISA
 from monitoring.monitorlib.rid import RIDVersion
 from monitoring.prober.infrastructure import register_resource_type
-from monitoring.uss_qualifier.resources import VerticesResource
 from monitoring.uss_qualifier.resources.astm.f3411.dss import DSSInstanceResource
 from monitoring.uss_qualifier.resources.interuss.id_generator import IDGeneratorResource
 from monitoring.uss_qualifier.resources.netrid.service_area import ServiceAreaResource
+from monitoring.uss_qualifier.resources.volume import VolumeResource
 from monitoring.uss_qualifier.scenarios.astm.netrid.common.dss import utils
 from monitoring.uss_qualifier.scenarios.astm.netrid.dss_wrapper import DSSWrapper
 from monitoring.uss_qualifier.scenarios.scenario import GenericTestScenario
@@ -36,7 +36,7 @@ def __init__(
         dss: DSSInstanceResource,
         id_generator: IDGeneratorResource,
         isa: ServiceAreaResource,
-        problematically_big_area: VerticesResource,
+        problematically_big_area: VolumeResource,
     ):
         super().__init__()
         self._dss = (
@@ -49,9 +49,7 @@ def __init__(
 
         self._isa_area = [vertex.as_s2sphere() for vertex in self._isa.footprint]
 
-        self._huge_area = [
-            v.as_s2sphere() for v in problematically_big_area.specification.vertices
-        ]
+        self._huge_area = problematically_big_area.specification.s2_vertices()
 
         if self._dss.rid_version == RIDVersion.f3411_19:
             self.create_isa_path = v19.api.OPERATIONS[

monitoring/uss_qualifier/scenarios/astm/netrid/common/dss/isa_validation.py

@@ -7,11 +7,11 @@
 from monitoring.monitorlib.fetch.rid import Subscription
 from monitoring.monitorlib.mutate.rid import ChangedSubscription
 from monitoring.prober.infrastructure import register_resource_type
-from monitoring.uss_qualifier.resources import VerticesResource
 from monitoring.uss_qualifier.resources.astm.f3411.dss import DSSInstanceResource
 from monitoring.uss_qualifier.resources.communications import ClientIdentityResource
 from monitoring.uss_qualifier.resources.interuss.id_generator import IDGeneratorResource
 from monitoring.uss_qualifier.resources.netrid.service_area import ServiceAreaResource
+from monitoring.uss_qualifier.resources.volume import VolumeResource
 from monitoring.uss_qualifier.scenarios.astm.netrid.dss_wrapper import DSSWrapper
 from monitoring.uss_qualifier.scenarios.scenario import GenericTestScenario
 from monitoring.uss_qualifier.suites.suite import ExecutionContext
@@ -49,7 +49,7 @@ def __init__(
         dss: DSSInstanceResource,
         id_generator: IDGeneratorResource,
         isa: ServiceAreaResource,
-        problematically_big_area: VerticesResource,
+        problematically_big_area: VolumeResource,
         client_identity: ClientIdentityResource,
     ):
         """
@@ -77,10 +77,9 @@ def __init__(
             self._base_sub_id[:-1] + f"{i}" for i in range(4)
         ]
 
-        self._problematically_big_area = [
-            vertex.as_s2sphere()
-            for vertex in problematically_big_area.specification.vertices
-        ]
+        self._problematically_big_area = (
+            problematically_big_area.specification.s2_vertices()
+        )
 
         self._client_identity = client_identity