feat: Add interface definition for traffic_area_service and traffic_area_stream

include/MantleAPI/Execution/i_environment.h

@@ -27,6 +27,7 @@
 #include <MantleAPI/Traffic/default_routing_behavior.h>
 #include <MantleAPI/Traffic/i_controller_repository.h>
 #include <MantleAPI/Traffic/i_entity_repository.h>
+#include <MantleAPI/Traffic/i_traffic_area_service.h>
 #include <MantleAPI/Traffic/i_traffic_swarm_service.h>
 
 #include <cstdint>
@@ -198,6 +199,11 @@ public:
   ///
   /// @return reference to the traffic swarm service interface
   [[nodiscard]] virtual ITrafficSwarmService& GetTrafficSwarmService() = 0;
+
+  /// @brief Gets the traffic area service
+  ///
+  /// @return reference to the traffic area service interface
+  [[nodiscard]] virtual ITrafficAreaService& GetTrafficAreaService() = 0;
 };
 }  // namespace mantle_api
 

include/MantleAPI/Traffic/i_traffic_area_service.h

+/*******************************************************************************
+ * Copyright (c) 2024, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+//-----------------------------------------------------------------------------
+/// @file i_traffic_area_service.h
+//-----------------------------------------------------------------------------
+
+#ifndef MANTLEAPI_TRAFFIC_I_TRAFFIC_AREA_SERVICE_H
+#define MANTLEAPI_TRAFFIC_I_TRAFFIC_AREA_SERVICE_H
+
+#include <MantleAPI/Traffic/i_traffic_area_stream.h>
+#include <MantleAPI/Traffic/road_range.h>
+
+namespace mantle_api
+{
+
+using TrafficArea = std::vector<std::shared_ptr<ITrafficAreaStream>>;
+
+/// Abstraction layer for managing traffic area related queries
+class ITrafficAreaService
+{
+public:
+  virtual ~ITrafficAreaService() = default;
+
+  /// Creates a traffic area object
+  /// @note Ownership of the returned object is shared with the caller
+  /// @param roadRange  Road range defining the traffic area
+  /// @returns Collection of traffic area streams
+  virtual mantle_api::TrafficArea CreateTrafficArea(const RoadRange& roadRange) const = 0;
+};
+
+}  // namespace mantle_api
+
+#endif  // MANTLEAPI_TRAFFIC_I_TRAFFIC_AREA_SERVICE_H

include/MantleAPI/Traffic/i_traffic_area_stream.h

+/*******************************************************************************
+ * Copyright (c) 2024, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+//-----------------------------------------------------------------------------
+/// @file i_traffic_area_stream.h
+//-----------------------------------------------------------------------------
+
+#ifndef MANTLEAPI_TRAFFIC_I_TRAFFIC_AREA_STREAM_H
+#define MANTLEAPI_TRAFFIC_I_TRAFFIC_AREA_STREAM_H
+
+#include <optional>
+#include <vector>
+
+namespace mantle_api
+{
+
+/// Map agnostic representation of connected lanes
+class ITrafficAreaStream
+{
+public:
+  /// Represents a position on a stream
+  struct StreamPosition
+  {
+    units::length::meter_t s;    //!< Longitudinal position within the stream (relative to the start)
+    units::length::meter_t t;    //!< Lateral position within the stream (relative to the middle of the stream)
+    units::angle::radian_t hdg;  //!< Heading relative to stream direction
+  };
+
+  enum class SearchDirection
+  {
+    kUndefined = 0,
+    kUpstream = 1,
+    kDownstream = 2
+  };
+
+  /// Get the length of the stream
+  virtual units::length::meter_t GetLength() const = 0;
+
+  /// Check if a given distance value is within the stream
+  virtual bool IsWithin(StreamPosition streamPosition) const = 0;
+
+  /// Get the next entity on the stream
+  /// @param searchDirection Direction to search
+  /// @param startDistance   Distance to start the search
+  /// @param searchDistance  Distance to search measured from the start
+  /// @returns Entity or empty if no entity was found
+  virtual std::weak_ptr<IEntity> GetEntity(
+      SearchDirection searchDirection,
+      units::length::meter_t startDistance,
+      units::length::meter_t searchDistance) const = 0;
+
+  /// Converts a given stream position to an absolute pose
+  /// @returns Pose if convertable, empty otherwise
+  virtual std::optional<Pose> Convert(StreamPosition streamPosition) const = 0;
+
+  /// Converts a given pose to an relative distance on the stream
+  /// @returns StreamPosition if convertable, empty otherwise
+  virtual std::optional<StreamPosition> Convert(Pose pose) const = 0;
+};
+
+}  // namespace mantle_api
+
+#endif  // MANTLEAPI_TRAFFIC_I_TRAFFIC_AREA_STREAM_H