Use Pose in Vehicle and VehicleProcessModel

Use Pose to replace and deprecate the previously separate position and orientation angle members in Vehicle and VehicleProcessModel. Also add a new method to InternalVehicleService, allowing a vehicle's pose to be updated. Additionally, allow the position in Pose to be null, which is considered a bug fix. Co-authored-by: Martin Grzenia <[email protected]> Merged-by: Martin Grzenia <[email protected]>
openTCS · Oct 31, 2024 · 5cdd59f · 5cdd59f
1 parent c464ea8
commit 5cdd59f
Show file tree

Hide file tree

Showing 21 changed files with 306 additions and 279 deletions.
diff --git a/opentcs-api-base/src/main/java/org/opentcs/access/to/model/PointCreationTO.java b/opentcs-api-base/src/main/java/org/opentcs/access/to/model/PointCreationTO.java
@@ -81,6 +81,7 @@ private PointCreationTO(
   ) {
     super(name, properties);
     this.pose = requireNonNull(pose, "pose");
+    requireNonNull(pose.getPosition(), "A point requires a pose with a position.");
     this.type = requireNonNull(type, "type");
     this.vehicleEnvelopes = requireNonNull(vehicleEnvelopes, "vehicleEnvelopes");
     this.maxVehicleBoundingBox = requireNonNull(maxVehicleBoundingBox, "maxVehicleBoundingBox");

diff --git a/...api-base/src/main/java/org/opentcs/components/kernel/services/InternalVehicleService.java b/...api-base/src/main/java/org/opentcs/components/kernel/services/InternalVehicleService.java
@@ -2,13 +2,16 @@
 // SPDX-License-Identifier: MIT
 package org.opentcs.components.kernel.services;
 
+import static java.util.Objects.requireNonNull;
+
 import java.util.List;
 import java.util.Set;
 import org.opentcs.access.KernelRuntimeException;
 import org.opentcs.data.ObjectUnknownException;
 import org.opentcs.data.TCSObjectReference;
 import org.opentcs.data.model.BoundingBox;
 import org.opentcs.data.model.Point;
+import org.opentcs.data.model.Pose;
 import org.opentcs.data.model.TCSResourceReference;
 import org.opentcs.data.model.Triple;
 import org.opentcs.data.model.Vehicle;
@@ -80,7 +83,10 @@ void updateVehicleOrderSequence(
    * @param ref A reference to the vehicle to be modified.
    * @param angle The vehicle's orientation angle.
    * @throws ObjectUnknownException If the referenced vehicle does not exist.
+   * @deprecated Use {@link #updateVehiclePose(TCSObjectReference,Pose)} instead.
    */
+  @Deprecated
+  @ScheduledApiChange(when = "7.0", details = "Will be removed.")
   void updateVehicleOrientationAngle(TCSObjectReference<Vehicle> ref, double angle)
       throws ObjectUnknownException;
 
@@ -103,10 +109,30 @@ void updateVehiclePosition(
    * @param ref A reference to the vehicle to be modified.
    * @param position The vehicle's precise position in mm.
    * @throws ObjectUnknownException If the referenced vehicle does not exist.
+   * @deprecated Use {@link #updateVehiclePose(TCSObjectReference,Pose)} instead.
    */
+  @Deprecated
+  @ScheduledApiChange(when = "7.0", details = "Will be removed.")
   void updateVehiclePrecisePosition(TCSObjectReference<Vehicle> ref, Triple position)
       throws ObjectUnknownException;
 
+  /**
+   * Updates the vehicle's pose.
+   *
+   * @param ref A reference to the vehicle to be modified.
+   * @param pose The vehicle's new pose.
+   * @throws ObjectUnknownException If the referenced vehicle does not exist.
+   */
+  @ScheduledApiChange(when = "7.0", details = "Default implementation will be removed.")
+  default void updateVehiclePose(TCSObjectReference<Vehicle> ref, Pose pose)
+      throws ObjectUnknownException {
+    requireNonNull(ref, "ref");
+    requireNonNull(pose, "pose");
+
+    updateVehiclePrecisePosition(ref, pose.getPosition());
+    updateVehicleOrientationAngle(ref, pose.getOrientationAngle());
+  }
+
   /**
    * Updates a vehicle's processing state.
    *

diff --git a/opentcs-api-base/src/main/java/org/opentcs/data/model/Point.java b/opentcs-api-base/src/main/java/org/opentcs/data/model/Point.java
@@ -96,6 +96,7 @@ private Point(
   ) {
     super(name, properties, history);
     this.pose = requireNonNull(pose, "pose");
+    requireNonNull(pose.getPosition(), "A point requires a pose with a position.");
     this.type = requireNonNull(type, "type");
     this.incomingPaths = setWithoutNullValues(requireNonNull(incomingPaths, "incomingPaths"));
     this.outgoingPaths = setWithoutNullValues(requireNonNull(outgoingPaths, "outgoingPaths"));

diff --git a/opentcs-api-base/src/main/java/org/opentcs/data/model/Pose.java b/opentcs-api-base/src/main/java/org/opentcs/data/model/Pose.java
@@ -2,10 +2,9 @@
 // SPDX-License-Identifier: MIT
 package org.opentcs.data.model;
 
-import static java.util.Objects.requireNonNull;
 import static org.opentcs.util.Assertions.checkArgument;
 
-import jakarta.annotation.Nonnull;
+import jakarta.annotation.Nullable;
 import java.io.Serializable;
 import java.util.Objects;
 
@@ -33,11 +32,11 @@ public class Pose
    * unknown/undefined.
    */
   public Pose(
-      @Nonnull
+      @Nullable
       Triple position,
       double orientationAngle
   ) {
-    this.position = requireNonNull(position, "position");
+    this.position = position;
     checkArgument(
         Double.isNaN(orientationAngle)
             || (orientationAngle >= -360.0 && orientationAngle <= 360.0),
@@ -52,7 +51,7 @@ public Pose(
    *
    * @return The position/coordinates in mm.
    */
-  @Nonnull
+  @Nullable
   public Triple getPosition() {
     return position;
   }
@@ -64,7 +63,7 @@ public Triple getPosition() {
    * @return A copy of this object, differing in the given value.
    */
   public Pose withPosition(
-      @Nonnull
+      @Nullable
       Triple position
   ) {
     return new Pose(position, orientationAngle);