Add bounding box to endpoints in the Web API

* In the web API, it is now possible to specify a bounding box for vehicles and a maximum vehicle bounding box for points. * Via the endpoint PUT /plantModel the bounding boxes can be specified and via the endpoints GET /plantModel, GET /vehicles and GET /vehicles/name the bounding boxes can be viewed. Co-authored-by: Stefan Walter <[email protected]> Merged-by: Stefan Walter <[email protected]>
openTCS · Nov 11, 2024 · d546510 · d546510
1 parent 4787b45
commit d546510
Show file tree

Hide file tree

Showing 15 changed files with 411 additions and 21 deletions.
diff --git a/opentcs-documentation/src/docs/release-notes/changelog.adoc b/opentcs-documentation/src/docs/release-notes/changelog.adoc
@@ -28,6 +28,7 @@ This change log lists the most relevant changes for past releases in reverse chr
 ** Update web API specification and implementation to version 1.9.0:
 *** Add missing _required_ markers for request and response bodies.
 *** Include a vehicle's 'sufficiently recharged' and 'fully recharged' energy levels when requesting vehicle data.
+*** Add support for specifying bounding boxes for vehicles and maximum vehicle bounding boxes for points via the web API.
 * Bugs fixed:
 ** When receiving a position update from a vehicle, accept any position belonging to the movement commands sent to the vehicle, not just the next one.
    This is necessary to support cases in which a vehicle has completed more than one movement command during state/position updates.

diff --git a/opentcs-documentation/src/docs/service-web-api-v1/openapi.yaml b/opentcs-documentation/src/docs/service-web-api-v1/openapi.yaml
@@ -1808,6 +1808,9 @@ components:
           type: integer
           description: The vehicle's length (in mm).
           example: 1000
+          deprecated: true
+        boundingBox:
+          $ref: "#/components/schemas/BoundingBox"
         energyLevelGood:
           type: integer
           description: The value (in %) at/above which the vehicle's energy level is considered
@@ -1907,6 +1910,7 @@ components:
         - name
         - properties
         - length
+        - boundingBox
         - energyLevelGood
         - energyLevelCritical
         - energyLevelSufficientlyRecharged
@@ -2165,6 +2169,32 @@ components:
         - x
         - y
         - z
+    BoundingBox:
+      type: object
+      additionalProperties: false
+      properties:
+        length:
+          type: integer
+          format: int64
+          description: The bounding box length
+          example: 60
+        width:
+          type: integer
+          format: int64
+          description: The bounding box width
+          example: 40
+        height:
+          type: integer
+          format: int64
+          description: The bounding box height
+          example: 50
+        referenceOffset:
+          $ref: "#/components/schemas/PlantModelCouple"
+      required:
+        - length
+        - width
+        - height
+        - referenceOffset
     PeripheralJobState:
       title: Peripheral Job State
       type: object
@@ -2342,6 +2372,13 @@ components:
                   x: 10
                   y: 10
                 layerId: 0
+              maxVehicleBoundingBox:
+                length: 1000
+                width: 1000
+                height: 1000
+                referenceOffset:
+                  x: 0
+                  y: 0
               properties:
                 - name: isExampleProperty
                   value: true
@@ -2360,6 +2397,13 @@ components:
                   x: 10
                   y: 10
                 layerId: 0
+              maxVehicleBoundingBox:
+                length: 1000
+                width: 1000
+                height: 1000
+                referenceOffset:
+                  x: 0
+                  y: 0
               properties:
                 - name: isExampleProperty
                   value: true
@@ -2378,6 +2422,13 @@ components:
                   x: 10
                   y: 10
                 layerId: 0
+              maxVehicleBoundingBox:
+                length: 1000
+                width: 1000
+                height: 1000
+                referenceOffset:
+                  x: 0
+                  y: 0
             - name: "Point-D"
               position:
                 x: 25000
@@ -2393,6 +2444,13 @@ components:
                   x: 10
                   y: 10
                 layerId: 0
+              maxVehicleBoundingBox:
+                length: 1000
+                width: 1000
+                height: 1000
+                referenceOffset:
+                  x: 0
+                  y: 0
         paths:
           type: array
           description: The plant model's paths.
@@ -2571,6 +2629,13 @@ components:
           example:
             - name: "Vehicle-01"
               length: 1000
+              boundingBox:
+                length: 1000
+                width: 1000
+                height: 1000
+                referenceOffset:
+                  x: 0
+                  y: 0
               energyLevelCritical: 15
               energyLevelGood: 50
               energyLevelFullyRecharged: 97
@@ -2581,6 +2646,13 @@ components:
                 routeColor: "#00FF00"
             - name: "Vehicle-02"
               length: 1000
+              boundingBox:
+                length: 1000
+                width: 1000
+                height: 1000
+                referenceOffset:
+                  x: 0
+                  y: 0
               energyLevelCritical: 15
               energyLevelGood: 50
               energyLevelFullyRecharged: 97
@@ -2630,6 +2702,8 @@ components:
           description: A map of envelope keys to envelopes that vehicles located at this point may occupy.
           items:
             $ref: "#/components/schemas/PlantModelEnvelope"
+        maxVehicleBoundingBox:
+          $ref: "#/components/schemas/BoundingBox"
         layout:
           type: object
           description: Describes the graphical representation of this point.
@@ -2903,6 +2977,9 @@ components:
           type: integer
           description: The vehicle's length (in mm).
           example: 1000
+          deprecated: true
+        boundingBox:
+          $ref: "#/components/schemas/BoundingBox"
         energyLevelCritical:
           type: integer
           description: The energy level value (in %) at/below which the vehicle _must_ be recharged.

diff --git a/...ain/java/org/opentcs/kernel/extensions/servicewebapi/v1/binding/GetVehicleResponseTO.java b/...ain/java/org/opentcs/kernel/extensions/servicewebapi/v1/binding/GetVehicleResponseTO.java
@@ -4,6 +4,8 @@
 
 import static java.util.Objects.requireNonNull;
 
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import jakarta.annotation.Nonnull;
 import jakarta.annotation.Nullable;
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -17,17 +19,33 @@
 import org.opentcs.data.model.Vehicle.IntegrationLevel;
 import org.opentcs.data.model.Vehicle.ProcState;
 import org.opentcs.data.model.Vehicle.State;
+import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.BoundingBoxTO;
+import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.CoupleTO;
 import org.opentcs.util.annotations.ScheduledApiChange;
 
 /**
  */
+@JsonPropertyOrder(
+  {
+      "name", "properties", "length", "boundingBox", "energyLevelGood", "energyLevelCritical",
+      "energyLevelSufficientlyRecharged", "energyLevelFullyRecharged", "energyLevel",
+      "integrationLevel", "paused", "procState", "transportOrder", "currentPosition",
+      "precisePosition", "orientationAngle", "state", "allocatedResources", "claimedResources",
+      "allowedOrderTypes", "envelopeKey"
+  }
+)
 public class GetVehicleResponseTO {
 
-  private String name;
+  private String name = "";
 
   private Map<String, String> properties = new HashMap<>();
 
-  private int length;
+  private BoundingBoxTO boundingBox = new BoundingBoxTO(
+      1000,
+      1000,
+      1000,
+      new CoupleTO(0, 0)
+  );
 
   private int energyLevelGood;
 
@@ -66,21 +84,40 @@ public class GetVehicleResponseTO {
   public GetVehicleResponseTO() {
   }
 
+  @Nonnull
   public String getName() {
     return name;
   }
 
-  public GetVehicleResponseTO setName(String name) {
+  public GetVehicleResponseTO setName(
+      @Nonnull
+      String name
+  ) {
     this.name = requireNonNull(name, "name");
     return this;
   }
 
+  @Deprecated
   public int getLength() {
-    return length;
+    return (int) boundingBox.getLength();
   }
 
+  @Deprecated
   public GetVehicleResponseTO setLength(int length) {
-    this.length = length;
+    this.boundingBox = boundingBox.setLength(length);
+    return this;
+  }
+
+  @Nonnull
+  public BoundingBoxTO getBoundingBox() {
+    return boundingBox;
+  }
+
+  public GetVehicleResponseTO setBoundingBox(
+      @Nonnull
+      BoundingBoxTO boundingBox
+  ) {
+    this.boundingBox = requireNonNull(boundingBox, "boundingBox");
     return this;
   }
 
@@ -268,7 +305,17 @@ public static GetVehicleResponseTO fromVehicle(Vehicle vehicle) {
     GetVehicleResponseTO vehicleState = new GetVehicleResponseTO();
     vehicleState.setName(vehicle.getName());
     vehicleState.setProperties(vehicle.getProperties());
-    vehicleState.setLength((int) vehicle.getBoundingBox().getLength());
+    vehicleState.setBoundingBox(
+        new BoundingBoxTO(
+            vehicle.getBoundingBox().getLength(),
+            vehicle.getBoundingBox().getWidth(),
+            vehicle.getBoundingBox().getHeight(),
+            new CoupleTO(
+                vehicle.getBoundingBox().getReferenceOffset().getX(),
+                vehicle.getBoundingBox().getReferenceOffset().getY()
+            )
+        )
+    );
     vehicleState.setEnergyLevelCritical(
         vehicle.getEnergyLevelThresholdSet().getEnergyLevelCritical()
     );

diff --git a/.../main/java/org/opentcs/kernel/extensions/servicewebapi/v1/binding/plantmodel/PointTO.java b/.../main/java/org/opentcs/kernel/extensions/servicewebapi/v1/binding/plantmodel/PointTO.java
@@ -9,6 +9,7 @@
 import jakarta.annotation.Nonnull;
 import java.util.List;
 import org.opentcs.data.model.Point;
+import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.BoundingBoxTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.CoupleTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.EnvelopeTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.PropertyTO;
@@ -24,6 +25,8 @@ public class PointTO {
   private String type = Point.Type.HALT_POSITION.name();
   private Layout layout = new Layout();
   private List<EnvelopeTO> vehicleEnvelopes = List.of();
+  private BoundingBoxTO maxVehicleBoundingBox
+      = new BoundingBoxTO(1000, 1000, 1000, new CoupleTO(0, 0));
   private List<PropertyTO> properties = List.of();
 
   @JsonCreator
@@ -122,6 +125,15 @@ public PointTO setVehicleEnvelopes(
     return this;
   }
 
+  public BoundingBoxTO getMaxVehicleBoundingBox() {
+    return maxVehicleBoundingBox;
+  }
+
+  public PointTO setMaxVehicleBoundingBox(BoundingBoxTO maxVehicleBoundingBoxTO) {
+    this.maxVehicleBoundingBox = requireNonNull(maxVehicleBoundingBoxTO, "maxVehicleBoundingBox");
+    return this;
+  }
+
   public static class Layout {
 
     private CoupleTO position = new CoupleTO(0, 0);

diff --git a/...ain/java/org/opentcs/kernel/extensions/servicewebapi/v1/binding/plantmodel/VehicleTO.java b/...ain/java/org/opentcs/kernel/extensions/servicewebapi/v1/binding/plantmodel/VehicleTO.java
@@ -6,16 +6,26 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
 import jakarta.annotation.Nonnull;
 import java.util.List;
+import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.BoundingBoxTO;
+import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.CoupleTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.shared.PropertyTO;
 
 /**
  */
+@JsonPropertyOrder(
+  {
+      "name", "length", "boundingBox", "energyLevelCritical", "energyLevelGood",
+      "energyLevelFullyRecharged", "energyLevelFullyRecharged", "energyLevelSufficientlyRecharged",
+      "maxVelocity", "maxReverseVelocity", "layout", "properties"
+  }
+)
 public class VehicleTO {
 
   private String name;
-  private int length = 1000;
+  private BoundingBoxTO boundingBox = new BoundingBoxTO(1000, 1000, 1000, new CoupleTO(0, 0));
   private int energyLevelCritical = 30;
   private int energyLevelGood = 90;
   private int energyLevelFullyRecharged = 90;
@@ -60,12 +70,27 @@ public VehicleTO setProperties(
     return this;
   }
 
+  @Deprecated
   public int getLength() {
-    return length;
+    return (int) boundingBox.getLength();
   }
 
+  @Deprecated
   public VehicleTO setLength(int length) {
-    this.length = length;
+    this.boundingBox = boundingBox.setLength(length);
+    return this;
+  }
+
+  @Nonnull
+  public BoundingBoxTO getBoundingBox() {
+    return boundingBox;
+  }
+
+  public VehicleTO setBoundingBox(
+      @Nonnull
+      BoundingBoxTO boundingBox
+  ) {
+    this.boundingBox = requireNonNull(boundingBox, "boundingBox");
     return this;
   }