diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index fc08f416ed3f34bc87ed203239c83e214038581a..85184a4b9f1a53156d83c1ab760067188eed9d62 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -11,14 +11,17 @@
find_package(Doxygen QUIET REQUIRED dot OPTIONAL_COMPONENTS mscgen dia)
set(DOXYGEN_BUILTIN_STL_SUPPORT YES)
-set(DOXYGEN_DOT_IMAGE_FORMAT svg)
-set(DOXYGEN_IMAGE_PATH ${CMAKE_CURRENT_LIST_DIR}/images)
set(DOXYGEN_INCLUDE_PATH ${PROJECT_SOURCE_DIR}/include)
+set(DOXYGEN_DOT_IMAGE_FORMAT svg)
set(DOXYGEN_INTERACTIVE_SVG YES)
set(DOXYGEN_QUIET YES)
set(DOXYGEN_TAB_SIZE 2)
set(DOXYGEN_UML_LOOK YES)
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)
+set(DOXYGEN_WARN_NO_PARAMDOC YES)
+set(DOXYGEN_WARN_LOGFILE ${CMAKE_CURRENT_BINARY_DIR}/DoxygenWarningLog.txt)
+set(DOXYGEN_GENERATE_LATEX NO)
+set(DOXYGEN_RECURSIVE YES)
doxygen_add_docs(
${PROJECT_NAME}_doc ${PROJECT_SOURCE_DIR}/README.md ${PROJECT_SOURCE_DIR}/include COMMENT "Generate html docs"
diff --git a/include/MantleAPI/Common/bounding_box.h b/include/MantleAPI/Common/bounding_box.h
index 34bc098a7796475374e5dfe07397d778c642df9c..5e378f12df7e8155671638773fd727b9fb18cf7a 100644
--- a/include/MantleAPI/Common/bounding_box.h
+++ b/include/MantleAPI/Common/bounding_box.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021-2022, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -22,15 +22,20 @@
namespace mantle_api
{
-/// The geometric center is defined in the local entity coordinate system.
-/// The geometric center is defined in relation to the origin of the
-/// entity coordinate system.
+/// Each entity has its own local, right-handed coordinate system, where x means "forward" (e.g. driving direction), y means left and z means upwards.
+/// The origin of the entity coordinate system is determined by specifying the offset of the geometric bounding box center in entity coordinates.
+/// For vehicles the origin shall be the center of the rear axis.
struct BoundingBox
{
- Vec3<units::length::meter_t> geometric_center{};
- Dimension3 dimension{};
+ Vec3<units::length::meter_t> geometric_center{}; ///< Coordinates of bounding box center in local coordinate system
+ Dimension3 dimension{}; ///< Dimension of the bounding box (i.e. length = x dimension, width = y dimension, height = z dimension)
};
+/// @brief equality
+/// @details Compares the values of two BoundingBoxes.
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the values of lhs exactly equal to the values of rhs.
constexpr bool operator==(const BoundingBox& lhs, const BoundingBox& rhs) noexcept
{
return lhs.geometric_center == rhs.geometric_center &&
diff --git a/include/MantleAPI/Common/dimension.h b/include/MantleAPI/Common/dimension.h
index 647dc3e7f9b8d0b2c976d90e758e9e621ff6aec1..0c455ac5ba7eb35baab6599e539bb7376d5f75a2 100644
--- a/include/MantleAPI/Common/dimension.h
+++ b/include/MantleAPI/Common/dimension.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -21,18 +21,29 @@
namespace mantle_api
{
+/// This struct represents the dimension of the bounding box
struct Dimension3
{
- units::length::meter_t length{0};
- units::length::meter_t width{0};
- units::length::meter_t height{0};
+ units::length::meter_t length{0}; ///< Length of the object’s bounding box
+ units::length::meter_t width{0}; ///< Width of the object’s bounding box
+ units::length::meter_t height{0}; ///< Height of the object’s bounding box
};
+/// @brief almost-equality
+/// @details Compares the values of two dimensions.
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs almost equal to the values of rhs.
constexpr bool operator==(const Dimension3& lhs, const Dimension3& rhs) noexcept
{
return AlmostEqual(lhs.length, rhs.length) && AlmostEqual(lhs.width, rhs.width) && AlmostEqual(lhs.height, rhs.height);
}
+/// @brief inequality
+/// @details Compares the value of two dimensions.
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the value of lhs is not almost equal to the value of rhs.
constexpr bool operator!=(const Dimension3& lhs, const Dimension3& rhs) noexcept
{
return !(lhs == rhs);
diff --git a/include/MantleAPI/Common/floating_point_helper.h b/include/MantleAPI/Common/floating_point_helper.h
index 6db72c2bc7683ad9515e5777f761d93e40c5fb82..f11ef0ca726fda03b7a4018ad0c8e8f61eb51d1f 100644
--- a/include/MantleAPI/Common/floating_point_helper.h
+++ b/include/MantleAPI/Common/floating_point_helper.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
* Copyright (c) 2023, Mercedes-Benz Tech Innovation GmbH
*
* This program and the accompanying materials are made
@@ -23,14 +23,14 @@
#include <type_traits>
#if !defined(MANTLE_API_DEFAULT_EPS)
-/// \brief Default epsilon for floating-point comparison.
+/// @brief Default epsilon for floating-point comparison.
///
-/// > The C++ header <limits> provides a constant std::numeric_limits<float>::epsilon()
+/// > The C++ header `<limits>` provides a constant `std::numeric_limits<float>::epsilon()`
/// > for this purpose. The “standard†epsilon has the value 1.192092896e-07. This is
/// > to [_sic_] small for the problem at hand, where the error is roughly 5.0e-06. Just do the
/// > simplest thing that could work and use 1.0e-05 for epsilon. [1]
///
-/// \par References
+/// @par References
/// [1] Stubert, B. (2019) Comparing two floating-point numbers, Embedded Use. Available at: https://embeddeduse.com/2019/08/26/qt-compare-two-floats/ (Accessed: 10 May 2023).
///
#define MANTLE_API_DEFAULT_EPS 1.0e-05
@@ -42,6 +42,11 @@ namespace mantle_api
namespace details
{
+/// @brief The signum function, that returns the sign of a real number
+///
+/// @tparam T the value type
+/// @param[in] value Real number
+/// @returns sign of a real number
template <typename T, std::enable_if_t<std::is_arithmetic_v<T>, bool> = true>
constexpr int signum(const T value) noexcept
{
@@ -50,18 +55,18 @@ constexpr int signum(const T value) noexcept
} // namespace details
-/// \brief Default epsilon for floating-point comparison.
+/// @brief Default epsilon for floating-point comparison.
///
inline constexpr auto kDefaultEps = MANTLE_API_DEFAULT_EPS;
-/// \brief Compare two values for almost-equality.
-///
-/// \tparam T the value type
-/// \param[in] lhs The left-hand side value
-/// \param[in] rhs The right-hand side value
-/// \param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
-/// \param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @brief Compare two values for almost-equality.
///
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value
+/// @param[in] rhs The right-hand side value
+/// @param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
+/// @param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @returns true if the value of lhs almost equal to the value of rhs.
template <typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true>
constexpr bool AlmostEqual(const T lhs, const T rhs, const T epsilon = static_cast<T>(kDefaultEps), bool absolute_comparison_only = false) noexcept
{
@@ -101,14 +106,14 @@ constexpr bool AlmostEqual(const T lhs, const T rhs, const T epsilon = static_ca
return false;
}
-/// \brief Compare two values for greater-or-almost-equality.
-///
-/// \tparam T the value type
-/// \param[in] lhs The left-hand side value
-/// \param[in] rhs The right-hand side value
-/// \param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
-/// \param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @brief Compare two values for greater-or-almost-equality.
///
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value
+/// @param[in] rhs The right-hand side value
+/// @param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
+/// @param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @returns true if the value of lhs greater or almost equal to the value of rhs.
template <typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true>
constexpr bool GreaterOrEqual(const T lhs, const T rhs, const T epsilon = static_cast<T>(kDefaultEps), bool absolute_comparison_only = false) noexcept
{
@@ -120,14 +125,14 @@ constexpr bool GreaterOrEqual(const T lhs, const T rhs, const T epsilon = static
return AlmostEqual(lhs, rhs, epsilon, absolute_comparison_only);
}
-/// \brief Compare two values for less-or-almost-equality.
-///
-/// \tparam T the value type
-/// \param[in] lhs The left-hand side value
-/// \param[in] rhs The right-hand side value
-/// \param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
-/// \param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @brief Compare two values for less-or-almost-equality.
///
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value
+/// @param[in] rhs The right-hand side value
+/// @param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
+/// @param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @returns true if the value of lhs less or almost equal to the value of rhs.
template <typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true>
constexpr bool LessOrEqual(const T lhs, const T rhs, const T epsilon = static_cast<T>(kDefaultEps), bool absolute_comparison_only = false) noexcept
{
@@ -139,42 +144,42 @@ constexpr bool LessOrEqual(const T lhs, const T rhs, const T epsilon = static_ca
return AlmostEqual(lhs, rhs, epsilon, absolute_comparison_only);
}
-/// \brief Compare two values for almost-equality.
-///
-/// \tparam T the value type
-/// \param[in] lhs The left-hand side value
-/// \param[in] rhs The right-hand side value
-/// \param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
-/// \param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @brief Compare two values for almost-equality.
///
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value
+/// @param[in] rhs The right-hand side value
+/// @param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
+/// @param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @returns true if the value of lhs almost equal to the value of rhs.
template <typename T, std::enable_if_t<units::traits::is_unit_t<T>::value, bool> = true>
constexpr bool AlmostEqual(const T lhs, const T rhs, const T epsilon = T{kDefaultEps}, bool absolute_comparison_only = false) noexcept
{
return AlmostEqual(lhs(), rhs(), epsilon(), absolute_comparison_only);
}
-/// \brief Compare two values for greater-or-almost-equality.
-///
-/// \tparam T the value type
-/// \param[in] lhs The left-hand side value
-/// \param[in] rhs The right-hand side value
-/// \param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
-/// \param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @brief Compare two values for greater-or-almost-equality.
///
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value
+/// @param[in] rhs The right-hand side value
+/// @param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
+/// @param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @returns true if the value of lhs greater or almost equal to the value of rhs.
template <typename T, std::enable_if_t<units::traits::is_unit_t<T>::value, bool> = true>
constexpr bool GreaterOrEqual(const T lhs, const T rhs, const T epsilon = T{kDefaultEps}, bool absolute_comparison_only = false) noexcept
{
return GreaterOrEqual(lhs(), rhs(), epsilon(), absolute_comparison_only);
}
-/// \brief Compare two values for less-or-almost-equality.
-///
-/// \tparam T the value type
-/// \param[in] lhs The left-hand side value
-/// \param[in] rhs The right-hand side value
-/// \param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
-/// \param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @brief Compare two values for less-or-almost-equality.
///
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value
+/// @param[in] rhs The right-hand side value
+/// @param[in] epsilon The epsilon for floating-point comparison. Defaults to kDefaultEps.
+/// @param[in] absolute_comparison_only True if only absolute comparison should be used to test large numbers' equality. Defaults to false.
+/// @returns true if the value of lhs less or almost equal to the value of rhs.
template <typename T, std::enable_if_t<units::traits::is_unit_t<T>::value, bool> = true>
constexpr bool LessOrEqual(const T lhs, const T rhs, const T epsilon = T{kDefaultEps}, bool absolute_comparison_only = false) noexcept
{
diff --git a/include/MantleAPI/Common/i_geometry_helper.h b/include/MantleAPI/Common/i_geometry_helper.h
index ee2094367199b53775ec0a58b015bfbf8f50800f..44f895c4d6c4c2163bec48f25d5b3582db203394 100644
--- a/include/MantleAPI/Common/i_geometry_helper.h
+++ b/include/MantleAPI/Common/i_geometry_helper.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2022, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2022-2023, 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
diff --git a/include/MantleAPI/Common/i_identifiable.h b/include/MantleAPI/Common/i_identifiable.h
index 78a40d51d0a937f123ac06978e11a68ea0deafd3..52ab357099585e8b3d463b29abea7c798f56b7c9 100644
--- a/include/MantleAPI/Common/i_identifiable.h
+++ b/include/MantleAPI/Common/i_identifiable.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -21,8 +21,8 @@
namespace mantle_api
{
-using UniqueId = std::uint64_t;
-constexpr UniqueId InvalidId{std::numeric_limits<UniqueId>::max()};
+using UniqueId = std::uint64_t; ///< Container for unique id
+constexpr UniqueId InvalidId{std::numeric_limits<UniqueId>::max()}; ///< 'invalid' id
/// Common interface for all classes that can be referenced by an ID or name.
class IIdentifiable
@@ -30,12 +30,16 @@ class IIdentifiable
public:
virtual ~IIdentifiable() = default;
- /// The unique id is provided and maintained by the scenario simulator.
+ /// @brief The unique id is provided and maintained by the scenario simulator.
+ /// @return Unique id
[[nodiscard]] virtual UniqueId GetUniqueId() const = 0;
- /// Scenario specific name of an object.
- ///
- /// The scenario description is responsible for keeping the name unique.
+
+ /// @brief The scenario description is responsible for keeping the name unique.
+ /// @param name Scenario specific name of an object
virtual void SetName(const std::string& name) = 0;
+
+ /// @brief The scenario description is responsible for keeping the name unique.
+ /// @return Scenario specific name of an object
[[nodiscard]] virtual const std::string& GetName() const = 0;
};
diff --git a/include/MantleAPI/Common/i_logger.h b/include/MantleAPI/Common/i_logger.h
index c7cec20033bec2517bb7e044f85498349db76b34..88e0c40e45ddfc779fe2150e858891a5ff737fbe 100644
--- a/include/MantleAPI/Common/i_logger.h
+++ b/include/MantleAPI/Common/i_logger.h
@@ -35,51 +35,51 @@ public:
virtual ~ILogger() = default;
/// Get the current log level from the logging interface
- /// \return The current log level
+ /// @return The current log level
[[nodiscard]] virtual LogLevel GetCurrentLogLevel() const noexcept = 0;
/// Log a message on the logging interface
- /// \param[in] level The log level of the message
- /// \param[in] message The log message
+ /// @param[in] level The log level of the message
+ /// @param[in] message The log message
virtual void Log(LogLevel level, std::string_view message) noexcept = 0;
/// Log a message with log level "Trace"
- /// \param[in] message The log message
+ /// @param[in] message The log message
inline void Trace(std::string_view message) noexcept
{
Log(LogLevel::kTrace, message);
}
/// Log a message with log level "Debug"
- /// \param[in] message The log message
+ /// @param[in] message The log message
inline void Debug(std::string_view message) noexcept
{
Log(LogLevel::kDebug, message);
}
/// Log a message with log level "Info"
- /// \param[in] message The log message
+ /// @param[in] message The log message
inline void Info(std::string_view message) noexcept
{
Log(LogLevel::kInfo, message);
}
/// Log a message with log level "Warning"
- /// \param[in] message The log message
+ /// @param[in] message The log message
inline void Warning(std::string_view message) noexcept
{
Log(LogLevel::kWarning, message);
}
/// Log a message with log level "Error"
- /// \param[in] message The log message
+ /// @param[in] message The log message
inline void Error(std::string_view message) noexcept
{
Log(LogLevel::kError, message);
}
/// Log a message with log level "Critical"
- /// \param[in] message The log message
+ /// @param[in] message The log message
inline void Critical(std::string_view message) noexcept
{
Log(LogLevel::kCritical, message);
diff --git a/include/MantleAPI/Common/orientation.h b/include/MantleAPI/Common/orientation.h
index 1cc7e5f8ea4ab3ca36a37b81929f43961773367f..0fb1601b3fcb0f5354bc9a107dc4c792f255954e 100644
--- a/include/MantleAPI/Common/orientation.h
+++ b/include/MantleAPI/Common/orientation.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -21,6 +21,8 @@
namespace units
{
+/// Adds a single new unit to the given namespace, as well as a literal definition and `cout` support based on the given
+/// `abbreviation`.
UNIT_ADD(angular_acceleration,
radians_per_second_squared,
radians_per_second_squared,
@@ -34,6 +36,8 @@ using angular_acceleration_unit = base_unit<detail::meter_ratio<0>, std::ratio<0
UNIT_ADD_CATEGORY_TRAIT(angular_acceleration)
+/// Adds a single new unit to the given namespace, as well as a literal definition and `cout` support based on the given
+/// `abbreviation`.
UNIT_ADD(angular_jerk,
radians_per_second_cubed,
radians_per_second_cubed,
@@ -55,38 +59,69 @@ template <typename T,
class = typename std::enable_if_t<units::traits::is_angle_unit<T>::value ||
units::traits::is_angular_velocity_unit<T>::value ||
units::traits::is_angular_acceleration_unit<T>::value>>
+
+/// Definition of the orientation in terms of the Yaw/Pitch/Roll orientation angles in the Cartesian coordinate system
struct Orientation3
{
Orientation3() = default;
+ /// Constructor
+ ///
+ /// @param[in] yaw_in yaw angle
+ /// @param[in] pitch_in pitch angle
+ /// @param[in] roll_in roll angle
Orientation3(T yaw_in, T pitch_in, T roll_in)
: yaw{yaw_in}, pitch{pitch_in}, roll{roll_in}
{
}
- T yaw{};
- T pitch{};
- T roll{};
+ T yaw{}; ///< Yaw represents the rotation around the vertical axis (heading angle)
+ T pitch{}; ///< Pitch represents the rotation around the lateral axis (elevation angle)
+ T roll{}; ///< Roll represents the rotation around the longitudinal axis (bank angle)
};
+/// @brief almost-equality
+/// @details Compares the values of two orientations.
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs almost equal to the values of rhs.
template <typename T>
constexpr bool operator==(const Orientation3<T>& lhs, const Orientation3<T>& rhs) noexcept
{
return AlmostEqual(lhs.yaw, rhs.yaw) && AlmostEqual(lhs.pitch, rhs.pitch) && AlmostEqual(lhs.roll, rhs.roll);
}
+/// @brief inequality
+/// @details Compares the value of two orientations.
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the value of lhs is not almost equal to the value of rhs.
template <typename T>
constexpr bool operator!=(const Orientation3<T>& lhs, const Orientation3<T>& rhs) noexcept
{
return !(lhs == rhs);
}
+/// @brief addition
+/// @details Returns the sum of two orientations
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value for the sum
+/// @param[in] rhs right-hand side value for the sum
+/// @returns sum of lhs and rhs.
template <typename T>
constexpr Orientation3<T> operator+(const Orientation3<T>& lhs, const Orientation3<T>& rhs) noexcept
{
return Orientation3<T>{lhs.yaw + rhs.yaw, lhs.pitch + rhs.pitch, lhs.roll + rhs.roll};
}
+/// @brief subtraction
+/// @details Returns the difference of two orientations
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value for the difference
+/// @param[in] rhs right-hand side value for the difference
+/// @returns difference of lhs and rhs.
template <typename T>
constexpr Orientation3<T> operator-(const Orientation3<T>& lhs, const Orientation3<T>& rhs) noexcept
{
diff --git a/include/MantleAPI/Common/poly_line.h b/include/MantleAPI/Common/poly_line.h
index 9e9f70a9e7000a219d2c482b02ed78fac3855ffa..6e301b033d5de1906ad78ac64e639f92e0780f6d 100644
--- a/include/MantleAPI/Common/poly_line.h
+++ b/include/MantleAPI/Common/poly_line.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -23,19 +23,32 @@
namespace mantle_api
{
+/// This struct represents the point of a polygonal chain (polyline) trajectory specification
struct PolyLinePoint
{
- Pose pose{};
- std::optional<Time> time{};
+ Pose pose{}; ///< Pose of the PolyLinePoint
+ std::optional<Time> time{}; ///< Time specification of the PolyLinePoint
+ /// @brief Equality comparison for PolyLinePoint.
+ ///
+ /// @param[in] other The left-hand side value for the comparison
+ /// @returns true if the values of `this` exactly equal to the values of other.
bool operator==(const PolyLinePoint& other) const
{
return other.time == time && other.pose == pose;
}
+ /// @brief Prints a human-readable representation of 'polyLinePoint' to 'os'.
+ /// @param os The output stream
+ /// @param polyLinePoint The point of a polygonal chain (polyline) trajectory specification
+ /// @returns 'polyLinePoint' in a human-readable format
friend std::ostream& operator<<(std::ostream& os, const PolyLinePoint& polyLinePoint);
};
+/// @brief Prints a human-readable representation of 'polyLinePoint' to 'os'.
+/// @param os The output stream
+/// @param polyLinePoint The point of a polygonal chain (polyline) trajectory specification
+/// @returns 'polyLinePoint' in a human-readable format
inline std::ostream& operator<<(std::ostream& os, const PolyLinePoint& polyLinePoint)
{
os << polyLinePoint.pose;
@@ -48,6 +61,7 @@ inline std::ostream& operator<<(std::ostream& os, const PolyLinePoint& polyLineP
return os;
}
+/// The list of polyline points
using PolyLine = std::vector<PolyLinePoint>;
} // namespace mantle_api
diff --git a/include/MantleAPI/Common/pose.h b/include/MantleAPI/Common/pose.h
index 11cf539ad1f58c875617c49375307aaddf563402..35fef7c693dbb525b964f22437c11c4ea374aee2 100644
--- a/include/MantleAPI/Common/pose.h
+++ b/include/MantleAPI/Common/pose.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -23,19 +23,34 @@
namespace mantle_api
{
+/// Pose in the Cartesian coordinate system
struct Pose
{
+ /// Position defined in terms of the x/y/z coordinates in the Cartesian coordinate system
Vec3<units::length::meter_t> position{};
+ /// Orientation defined in terms of the Yaw/Pitch/Roll orientation angles in the Cartesian coordinate system
Orientation3<units::angle::radian_t> orientation{};
+ /// @brief Equality comparison for Pose.
+ ///
+ /// @param[in] other The left-hand side value for the comparison
+ /// @returns true if the values of `this` exactly equal to the values of other.
bool operator==(const Pose& other) const
{
return other.position == position && other.orientation == orientation;
}
+ /// @brief Prints a human-readable representation of 'pose' to 'os'.
+ /// @param os The output stream
+ /// @param pose Open scenario pose
+ /// @returns 'pose' in a human-readable format
friend inline std::ostream& operator<<(std::ostream& os, const Pose& pose);
};
+/// @brief Prints a human-readable representation of 'pose' to 'os'.
+/// @param os The output stream
+/// @param pose Open scenario pose
+/// @returns 'pose' in a human-readable format
std::ostream& operator<<(std::ostream& os, const Pose& pose)
{
os << "position ("
diff --git a/include/MantleAPI/Common/position.h b/include/MantleAPI/Common/position.h
index 6b9e6c9f2fc7c61b1986ec8284fb5e4815271e37..0befbc214ecb9961a394b09cddb7a248c27462ae 100644
--- a/include/MantleAPI/Common/position.h
+++ b/include/MantleAPI/Common/position.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -26,6 +26,7 @@
namespace mantle_api
{
+/// Position defined in terms of the road coordinates (t,s) applied to a given road as defined in OpenDRIVE
struct OpenDriveRoadPosition
{
/// @brief RoadId as defined in OpenDRIVE
@@ -36,6 +37,7 @@ struct OpenDriveRoadPosition
units::length::meter_t t_offset{0.0};
};
+/// Position that is determined by a lane (lane ID as defined in OpenDRIVE) and the s coordinate of a given road
struct OpenDriveLanePosition
{
/// @brief RoadId as defined in OpenDRIVE
@@ -48,6 +50,7 @@ struct OpenDriveLanePosition
units::length::meter_t t_offset{0.0};
};
+/// Position defined in terms of the spherical geographic coordinates (angular Longitude and Latitude)
struct LatLonPosition
{
/// @brief GPS latitude, unit: [rad]
@@ -56,11 +59,15 @@ struct LatLonPosition
units::angle::radian_t longitude{0.0};
};
+/// Variant of possible definitions of position (e.g. in terms of the road coordinates, spherical geographic coordinates etc.)
using Position = std::variant<OpenDriveRoadPosition, OpenDriveLanePosition, LatLonPosition, Vec3<units::length::meter_t>>;
/// @brief Equality comparison for OpenDriveRoadPosition.
///
/// **Attention** Floating-point comparision may require tweaks in precision.
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs (almost) equal to the values of rhs.
inline bool operator==(const OpenDriveRoadPosition& lhs, const OpenDriveRoadPosition& rhs) noexcept
{
return lhs.road == rhs.road &&
@@ -68,6 +75,11 @@ inline bool operator==(const OpenDriveRoadPosition& lhs, const OpenDriveRoadPosi
AlmostEqual(lhs.t_offset, rhs.t_offset);
}
+/// @brief Inequality comparison for OpenDriveLanePosition.
+///
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the value of lhs is not almost equal to the value of rhs.
inline bool operator!=(const OpenDriveRoadPosition& lhs, const OpenDriveRoadPosition& rhs) noexcept
{
return !(lhs == rhs);
@@ -76,6 +88,9 @@ inline bool operator!=(const OpenDriveRoadPosition& lhs, const OpenDriveRoadPosi
/// @brief Equality comparison for OpenDriveLanePosition.
///
/// **Attention** Floating-point comparision may require tweaks in precision.
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs (almost) equal to the values of rhs.
inline bool operator==(const OpenDriveLanePosition& lhs, const OpenDriveLanePosition& rhs) noexcept
{
return lhs.road == rhs.road &&
@@ -84,6 +99,11 @@ inline bool operator==(const OpenDriveLanePosition& lhs, const OpenDriveLanePosi
AlmostEqual(lhs.t_offset, rhs.t_offset);
}
+/// @brief Inequality comparison for OpenDriveLanePosition.
+///
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the value of lhs is not almost equal to the value of rhs.
inline bool operator!=(const OpenDriveLanePosition& lhs, const OpenDriveLanePosition& rhs) noexcept
{
return !(lhs == rhs);
@@ -92,11 +112,19 @@ inline bool operator!=(const OpenDriveLanePosition& lhs, const OpenDriveLanePosi
/// @brief Equality comparison for LatLonPosition.
///
/// **Attention** Floating-point comparision may require tweaks in precision.
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs almost equal to the values of rhs.
constexpr bool operator==(const LatLonPosition& lhs, const LatLonPosition& rhs) noexcept
{
return AlmostEqual(lhs.latitude, rhs.latitude) && AlmostEqual(lhs.longitude, rhs.longitude);
}
+/// @brief Inequality comparison for LatLonPosition.
+///
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the value of lhs is not almost equal to the value of rhs.
constexpr bool operator!=(const LatLonPosition& lhs, const LatLonPosition& rhs) noexcept
{
return !(lhs == rhs);
diff --git a/include/MantleAPI/Common/route_definition.h b/include/MantleAPI/Common/route_definition.h
index ff5e5761e42ac7fdcde5c0c7fecffb81a1d590f7..28e084d8fcae79b83779f59162129741148ff7b9 100644
--- a/include/MantleAPI/Common/route_definition.h
+++ b/include/MantleAPI/Common/route_definition.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2022, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2022-2023, 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
@@ -33,7 +33,9 @@ enum class RouteStrategy
/// Groups a Waypoint with a RouteStrategy
struct RouteWaypoint
{
+ /// Reference position used to form a route
mantle_api::Vec3<units::length::meter_t> waypoint{};
+ /// Defines how a route should be calculated
RouteStrategy route_strategy{RouteStrategy::kUndefined};
};
@@ -41,6 +43,7 @@ struct RouteWaypoint
/// linking them, from which the actual route can be calculated
struct RouteDefinition
{
+ /// The list of waypoints with associated RouteStrategies
std::vector<mantle_api::RouteWaypoint> waypoints{};
};
diff --git a/include/MantleAPI/Common/spline.h b/include/MantleAPI/Common/spline.h
index 6f81fbbb7cae3adb6e0ed89b99aadb7511e9deba..468e44a7c4ad8d495b8a55e67ee710f6e04087de 100644
--- a/include/MantleAPI/Common/spline.h
+++ b/include/MantleAPI/Common/spline.h
@@ -1,6 +1,6 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -27,6 +27,8 @@
namespace units
{
+/// Adds unit 'jerk' to the given namespace, as well as a literal definition and `cout` support based on the given
+/// `abbreviation`.
UNIT_ADD(jerk,
meters_per_second_cubed,
meters_per_second_cubed,
@@ -42,6 +44,8 @@ using jerk_unit = base_unit<detail::meter_ratio<1>, std::ratio<0>, std::ratio<-3
UNIT_ADD_CATEGORY_TRAIT(jerk)
+/// Adds new unit 'jerk_acceleration' to the given namespace, as well as a literal definition and `cout` support based on the given
+/// `abbreviation`.
UNIT_ADD(jerk_acceleration,
meters_per_second_to_the_power_of_four,
meters_per_second_to_the_power_of_four,
@@ -62,26 +66,32 @@ UNIT_ADD_CATEGORY_TRAIT(jerk_acceleration)
namespace mantle_api
{
+/// Definition of a spline segment represented by the polynomial parameters a, b, c, d
+/// @tparam T Type of polynomial parameters
template <typename T>
struct SplineSegment
{
- Vec3<T> a;
- Vec3<T> b;
- Vec3<T> c;
- Vec3<T> d;
+ Vec3<T> a; ///< Polynom parameter a, e.g. unit: [m]
+ Vec3<T> b; ///< Polynom parameter b, e.g. unit: [1/m]
+ Vec3<T> c; ///< Polynom parameter c, e.g. unit: [1/m²]
+ Vec3<T> d; ///< Polynom parameter d, e.g. unit: [1/m³]
};
+/// Definition of the section of the spline curve
+/// @tparam T the value type
template <typename T, class = typename std::enable_if_t<units::traits::is_unit<T>::value>>
struct SplineSection
{
+ /// Time specification at the start of the section of the spline curve
Time start_time{0};
+ /// Time specification at the end of the section of the spline curve
Time end_time{0};
/// @brief Represents the polynomial.
///
/// The tuple stores in format \f$[a_3, a_2, a_1, a_0]\f$ for a polynomial in form
- /// \f[
+ /// @f[
/// P(x) = \sum_{i=0}^{3} a_{i} x^{i} = a_3 x^3 + a_2 x^2 + a_1 x + a_0
- /// \f]
+ /// @f]
std::tuple<units::unit_t<units::compound_unit<T, units::inverse<units::cubed<units::time::second>>>>,
units::unit_t<units::compound_unit<T, units::inverse<units::squared<units::time::second>>>>,
units::unit_t<units::compound_unit<T, units::inverse<units::time::second>>>,
@@ -94,6 +104,11 @@ struct SplineSection
};
/// @brief Equality comparison for SplineSection.
+///
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs (almost) equal to the values of rhs.
template <typename T, class = typename std::enable_if_t<units::traits::is_unit<T>::value>>
constexpr bool operator==(const SplineSection<T>& lhs, const SplineSection<T>& rhs) noexcept
{
diff --git a/include/MantleAPI/Common/time_utils.h b/include/MantleAPI/Common/time_utils.h
index 568a0340788d61f392121ceaf0d9421699b239d5..6c12effdf806aa5aa0b49f697fb38508b93d0520 100644
--- a/include/MantleAPI/Common/time_utils.h
+++ b/include/MantleAPI/Common/time_utils.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -21,21 +21,21 @@
namespace mantle_api
{
-using Time = units::time::millisecond_t;
+using Time = units::time::millisecond_t; ///< Time in ms
-/// @brief Converts input in [s] to @ref Time.
+/// @brief Converts input in [s] to @cond \ref Time @endcond.
/// @tparam T Input type, e.g. `double`.
/// @param duration Input value
-/// @return Duration representing the given input in units of @ref Time.
+/// @return Duration representing the given input in units of @cond \ref Time @endcond.
template <typename T>
inline Time SecondsToTime(T duration)
{
return {std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::duration<T>{duration})};
}
-/// @brief Converts input @ref Time to [s].
+/// @brief Converts input @cond \ref Time @endcond to [s].
/// @param time Time
-/// @return Duration in seconds representing the passed in @ref Time.
+/// @return Duration in seconds representing the passed in @cond \ref Time @endcond.
inline double TimeToSeconds(const Time& time)
{
return units::time::second_t{time}.value();
diff --git a/include/MantleAPI/Common/trajectory.h b/include/MantleAPI/Common/trajectory.h
index 8a686d83abbcc14893709cbc991eb4fa3f7d9270..cd001a6fe6efc99b473766a5a11f0425a8b08522 100644
--- a/include/MantleAPI/Common/trajectory.h
+++ b/include/MantleAPI/Common/trajectory.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -22,14 +22,23 @@
namespace mantle_api
{
+/// Definition of a trajectory type in terms of shape
struct Trajectory
{
- std::string name;
- std::variant<PolyLine> type;
+ std::string name; ///< Name of the trajectory type
+ std::variant<PolyLine> type; ///< Trajectory type in terms of shape
+ /// @brief Prints a human-readable representation of 'trajectory' to 'os'.
+ /// @param os The output stream
+ /// @param trajectory Open scenario trajectory
+ /// @returns 'trajectory' in a human-readable format
friend std::ostream& operator<<(std::ostream& os, const Trajectory& trajectory);
};
+/// @brief Prints a human-readable representation of 'trajectory' to 'os'.
+/// @param os The output stream
+/// @param trajectory Open scenario trajectory
+/// @returns 'trajectory' in a human-readable format
inline std::ostream& operator<<(std::ostream& os, const Trajectory& trajectory)
{
os << "Trajectory \"" << trajectory.name;
diff --git a/include/MantleAPI/Common/vector.h b/include/MantleAPI/Common/vector.h
index cdc7644dc59543af1d98c41349f241871fe2fd9b..fddef77fa445715503cd91ae24fb9b640c269cfd 100644
--- a/include/MantleAPI/Common/vector.h
+++ b/include/MantleAPI/Common/vector.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -23,69 +23,130 @@ namespace mantle_api
{
template <typename T, class = typename std::enable_if_t<units::traits::is_unit_t<T>::value>>
+
+/// 3-dimensional vector that contains three components (x, y, z) in the right-handed Cartesian coordinate system
struct Vec3
{
Vec3() = default;
+ /// Constructor
+ ///
+ /// @param[in] x_in x-value
+ /// @param[in] y_in y-value
+ /// @param[in] z_in z-value
Vec3(T x_in, T y_in, T z_in)
: x{x_in}, y{y_in}, z{z_in}
{
}
- T x{0};
- T y{0};
- T z{0};
+ T x{0}; ///< x-component
+ T y{0}; ///< y-component
+ T z{0}; ///< z-component
+ /// @brief Returns length of the vector
+ ///
+ /// @returns length of the vector
inline T Length() const { return units::math::sqrt((x * x) + (y * y) + (z * z)); }
+ /// @brief Changes the sign of the 3d vector
+ ///
+ /// @returns 3d vector
inline Vec3<T> operator-() const noexcept
{
return {-x, -y, -z};
}
};
+/// @brief almost-equality
+/// @details Compares the values of two 3d vectors.
+/// @tparam T the value type
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs almost equal to the values of rhs.
template <typename T>
constexpr bool operator==(const Vec3<T>& lhs, const Vec3<T>& rhs) noexcept
{
return AlmostEqual(lhs.x, rhs.x) && AlmostEqual(lhs.y, rhs.y) && AlmostEqual(lhs.z, rhs.z);
}
+/// @brief inequality
+/// @details Compares the value of two 3d vectors.
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the value of lhs is not almost equal to the value of rhs.
template <typename T>
constexpr bool operator!=(const Vec3<T>& lhs, const Vec3<T>& rhs) noexcept
{
return !(lhs == rhs);
}
+/// @brief subtraction
+/// @details Returns the difference of two 3d vectors
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value for the difference
+/// @param[in] rhs right-hand side value for the difference
+/// @returns difference of lhs and rhs.
template <typename T>
constexpr Vec3<T> operator-(const Vec3<T>& lhs, const Vec3<T>& rhs) noexcept
{
return {lhs.x - rhs.x, lhs.y - rhs.y, lhs.z - rhs.z};
}
+/// @brief addition
+/// @details Returns the sum of two 3d vectors
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value for the sum
+/// @param[in] rhs right-hand side value for the sum
+/// @returns sum of lhs and rhs.
template <typename T>
constexpr Vec3<T> operator+(const Vec3<T>& lhs, const Vec3<T>& rhs) noexcept
{
return {lhs.x + rhs.x, lhs.y + rhs.y, lhs.z + rhs.z};
}
+/// @brief multiplication
+/// @details Multiplication by a scalar for 3d vector
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value for the multiplication
+/// @param[in] d scalar
+/// @returns the scalar multiplied vector
template <typename T>
constexpr Vec3<T> operator*(const Vec3<T>& lhs, double d) noexcept
{
return {lhs.x * d, lhs.y * d, lhs.z * d};
}
+/// @brief multiplication
+/// @details Multiplication by a scalar for 3d vector
+/// @tparam T the value type
+/// @param[in] d scalar
+/// @param[in] rhs right-hand side value for the multiplication
+/// @returns the scalar multiplied vector
template <typename T>
constexpr Vec3<T> operator*(double d, const Vec3<T>& rhs) noexcept
{
return rhs * d;
}
+/// @brief division
+/// @details Division by a scalar for 3d vector
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value for the division
+/// @param[in] d scalar
+/// @returns the lhs divided by d
template <typename T>
constexpr Vec3<T> operator/(const Vec3<T>& lhs, double d) noexcept
{
return {lhs.x / d, lhs.y / d, lhs.z / d};
}
+/// @brief addable
+/// @details Add a 3d vector to a 3d vector
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value
+/// @param[in] rhs right-hand side value, which will be added
+/// @returns the lhs where rhs is added
template <typename T>
constexpr Vec3<T> operator+=(Vec3<T>& lhs, const Vec3<T>& rhs) noexcept
{
@@ -95,6 +156,12 @@ constexpr Vec3<T> operator+=(Vec3<T>& lhs, const Vec3<T>& rhs) noexcept
return lhs;
}
+/// @brief subtractable
+/// @details Subtract a 3d vector from a 3d vector
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value
+/// @param[in] rhs right-hand side value
+/// @returns the lhs from where rhs is subtracted
template <typename T>
constexpr Vec3<T> operator-=(Vec3<T>& lhs, const Vec3<T>& rhs) noexcept
{
@@ -104,6 +171,12 @@ constexpr Vec3<T> operator-=(Vec3<T>& lhs, const Vec3<T>& rhs) noexcept
return lhs;
}
+/// @brief addable
+/// @details Add a scalar to a 3d vector
+/// @tparam T the value type
+/// @param[in] lhs left-hand side value
+/// @param[in] d scalar
+/// @returns the lhs where d is added
template <typename T>
constexpr Vec3<T> operator+=(Vec3<T>& lhs, double d) noexcept
{
@@ -112,6 +185,13 @@ constexpr Vec3<T> operator+=(Vec3<T>& lhs, double d) noexcept
lhs.z += d;
return lhs;
}
+
+/// @brief subtractable
+/// @details Subtract a scalar from a 3d vector
+/// @tparam T Type of vector components
+/// @param[in] lhs left-hand side value
+/// @param[in] d scalar
+/// @returns the lhs from where d is subtracted
template <typename T>
constexpr Vec3<T> operator-=(Vec3<T>& lhs, double d) noexcept
{
diff --git a/include/MantleAPI/EnvironmentalConditions/road_condition.h b/include/MantleAPI/EnvironmentalConditions/road_condition.h
index dbea4b068b93173e2a562015197a11d7f1f77553..41c66cd3aac41e8b9aa540fd12393c41fa5e62d1 100644
--- a/include/MantleAPI/EnvironmentalConditions/road_condition.h
+++ b/include/MantleAPI/EnvironmentalConditions/road_condition.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023 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
@@ -20,15 +20,21 @@
namespace mantle_api
{
+/// Definition of the position of the rectangle
struct Rectangle
{
+ /// The position of the lower left corner of the rectangle
Position bottom_left{};
+ /// The position of upper right corner of the rectangle
Position top_right{};
};
+/// Definition of the road friction patch
struct FrictionPatch
{
+ /// Geometric properties of the road friction patch
Rectangle bounding_box{};
+ /// Percentage of road friction
units::concentration::percent_t friction{100.0};
};
} // namespace mantle_api
diff --git a/include/MantleAPI/EnvironmentalConditions/weather.h b/include/MantleAPI/EnvironmentalConditions/weather.h
index 6a8703f24a836bad4464faf8f907c38943ee0f1f..d2d93b59f8a39ff945a954ddf43adb23396b70bd 100644
--- a/include/MantleAPI/EnvironmentalConditions/weather.h
+++ b/include/MantleAPI/EnvironmentalConditions/weather.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -19,6 +19,7 @@
namespace mantle_api
{
+/// Specify the amount of the precipitation.
enum class Precipitation
{
kUnknown,
@@ -32,6 +33,7 @@ enum class Precipitation
kExtreme
};
+/// Specify the amount of the fog.
enum class Fog
{
kUnknown,
@@ -46,6 +48,7 @@ enum class Fog
kDense
};
+/// Specify the level of illumination.
enum class Illumination
{
kUnknown,
@@ -61,14 +64,15 @@ enum class Illumination
kLevel9
};
+/// Definition of weather conditions in terms of fog, precipitation, illumination, humidity, temperature and atmospheric pressure states
struct Weather
{
- Fog fog{Fog::kExcellentVisibility};
- Precipitation precipitation{Precipitation::kNone};
- Illumination illumination{Illumination::kOther};
- units::concentration::percent_t humidity{0.0};
- units::temperature::kelvin_t temperature{0.0};
- units::pressure::pascal_t atmospheric_pressure{0.0};
+ Fog fog{Fog::kExcellentVisibility}; ///< Defines the fog, i.e. visual range
+ Precipitation precipitation{Precipitation::kNone}; ///< Defines the precipitation, i.e. intensity
+ Illumination illumination{Illumination::kOther}; ///< Defines the illumination using levels
+ units::concentration::percent_t humidity{0.0}; ///< Defines the humidity
+ units::temperature::kelvin_t temperature{0.0}; ///< Defines the outside temperature around the entities of the scenario
+ units::pressure::pascal_t atmospheric_pressure{0.0}; ///< Defines the atmospheric pressure around the entities of the scenario
};
} // namespace mantle_api
diff --git a/include/MantleAPI/Execution/i_environment.h b/include/MantleAPI/Execution/i_environment.h
index 7618dbd1f007c04c36aa41ee6a456bb7c3e249b1..de109a06a64958ff44a5eac1b14b77d3cde86583 100644
--- a/include/MantleAPI/Execution/i_environment.h
+++ b/include/MantleAPI/Execution/i_environment.h
@@ -33,6 +33,7 @@
namespace mantle_api
{
+/// Base interface for the environment conditions (e.g. time of day, weather, road condition) of a scenario
class IEnvironment
{
public:
@@ -40,8 +41,9 @@ public:
/// Load a map file and parse it into the memory.
///
- /// @param file_path map file path from the scenario file. If this path is not resolved by the engine, the
- /// environment must do so.
+ /// @param map_file_path map file path from the scenario file. If this path is not resolved by the engine, the
+ /// environment must do so.
+ /// @param map_details Area of the map
virtual void CreateMap(const std::string& map_file_path, const mantle_api::MapDetails& map_details) = 0;
/// Assigns an entity to the specified controller. This controller needs to be created beforehand.
@@ -67,27 +69,73 @@ public:
///
/// @param entity_id The entity to check
/// @param type The control strategy type
+ /// @return true if a control strategy of a certain type for a specific entity has been fulfilled
[[nodiscard]] virtual bool HasControlStrategyGoalBeenReached(UniqueId entity_id, mantle_api::ControlStrategyType type) const = 0;
+ /// @brief Retrieves the ILaneLocationQueryService that provides abstraction layer for all map related functions
+ ///
+ /// @return reference to the ILaneLocationQueryService
[[nodiscard]] virtual const ILaneLocationQueryService& GetQueryService() const = 0;
+
+ /// @brief Retrieves the coord converter that provides transformation of different position types, curvature, elevation etc.
+ ///
+ /// @return pointer to the coord converter interface
[[nodiscard]] virtual const ICoordConverter* GetConverter() const = 0;
+
+ /// @brief Retrieves the geometry helper that provides functionality to perform geometrical calculations
+ ///
+ /// @return pointer to the geometry helper interface
[[nodiscard]] virtual const IGeometryHelper* GetGeometryHelper() const = 0;
+ /// @brief Retrieves the entity repository that provides CRUD functionality for scenario entities
+ ///
+ /// @return reference to the entity repository interface
virtual IEntityRepository& GetEntityRepository() = 0;
+
+ /// @brief Retrieves the entity repository that provides CRUD functionality for scenario entities
+ ///
+ /// @return const reference to the entity repository interface
[[nodiscard]] virtual const IEntityRepository& GetEntityRepository() const = 0;
+ /// @brief Retrieves the controller repository that provides CRUD functionality for controllers
+ ///
+ /// @return reference to the controller repository interface
virtual IControllerRepository& GetControllerRepository() = 0;
+
+ /// @brief Retrieves the controller repository that provides CRUD functionality for controllers
+ ///
+ /// @return const reference to the controller repository interface
[[nodiscard]] virtual const IControllerRepository& GetControllerRepository() const = 0;
- /// @brief DateTime in UTC (converted from RFC 3339 standard)
+ /// @brief Sets the DateTime in UTC (converted from RFC 3339 standard)
+ ///
+ /// @param time Time in ms
virtual void SetDateTime(mantle_api::Time time) = 0;
+
+ /// @brief Gets the DateTime in UTC
+ ///
+ /// @return time in ms
virtual mantle_api::Time GetDateTime() = 0;
- /// @brief Time since start of simulation
+ /// @brief Gets the time since start of simulation
+ ///
+ /// @return time since start of simulation in ms
virtual mantle_api::Time GetSimulationTime() = 0;
+ /// @brief Sets the weather conditions
+ ///
+ /// @param weather Weather conditions to be used
virtual void SetWeather(Weather weather) = 0;
+
+ /// @brief Sets the road conditions
+ ///
+ /// @param friction_patches Friction patches on the road
virtual void SetRoadCondition(std::vector<FrictionPatch> friction_patches) = 0;
+
+ /// @brief Sets the state of a traffic signal
+ ///
+ /// @param traffic_signal_name ID of the traffic signal
+ /// @param traffic_signal_state State of the traffic signal to be used
virtual void SetTrafficSignalState(const std::string& traffic_signal_name, const std::string& traffic_signal_state) = 0;
/// @brief Execute a command that is specific for an environment implementation
@@ -126,7 +174,9 @@ public:
/// @param parameters The traffic swarm parameters
virtual void InitTrafficSwarmService(const TrafficSwarmParameters& parameters) = 0;
- /// @brief Returns the traffic swarm service
+ /// @brief Gets the traffic swarm service
+ ///
+ /// @return reference to the traffic swarm service interface
[[nodiscard]] virtual ITrafficSwarmService& GetTrafficSwarmService() = 0;
};
} // namespace mantle_api
diff --git a/include/MantleAPI/Execution/i_scenario_engine.h b/include/MantleAPI/Execution/i_scenario_engine.h
index e5f8090609171124c2fd51e39980743f41d04500..b235ac7ac07d9e4b0f34ab50d2b762b26dc22a33 100644
--- a/include/MantleAPI/Execution/i_scenario_engine.h
+++ b/include/MantleAPI/Execution/i_scenario_engine.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
* Copyright (c) 2022 Ansys, Inc.
*
* This program and the accompanying materials are made
@@ -22,6 +22,8 @@
namespace mantle_api
{
+
+/// Base interface for the scenario
class IScenarioEngine
{
public:
@@ -31,6 +33,7 @@ public:
virtual void Init() = 0;
/// Provide information about the scenario loaded in `Init()`
+ /// @return information about the scenario
[[nodiscard]] virtual ScenarioInfo GetScenarioInfo() const = 0;
/// Calculate the new state of the scenario implementation.
@@ -43,6 +46,7 @@ public:
/// @return `true` if processing the scenario is complete, `false` otherwise.
[[nodiscard]] virtual bool IsFinished() const = 0;
+ /// Activates external controller for the host
virtual void ActivateExternalHostControl() = 0;
/// Check if the scenario and catalog has been parsed correctly
diff --git a/include/MantleAPI/Execution/scenario_info.h b/include/MantleAPI/Execution/scenario_info.h
index 6f5f374f1d312e82de57ba3e56b08bc10a3adbba..2e614b14faa860bb16566320943c1b9ec55e93d3 100644
--- a/include/MantleAPI/Execution/scenario_info.h
+++ b/include/MantleAPI/Execution/scenario_info.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -22,10 +22,14 @@
namespace mantle_api
{
+/// Information about the scenario
struct ScenarioInfo
{
+ /// Duration of the scenario timeout
Time scenario_timeout_duration;
+ /// Specific description of the scenario
std::string description;
+ /// Additional custom information about the scenario
std::map<std::string, std::string> additional_information;
};
diff --git a/include/MantleAPI/Map/i_coord_converter.h b/include/MantleAPI/Map/i_coord_converter.h
index d4850f9921c618820462c9b198fa4d2d61a1c426..53952583dd63170aff83bc114d1f9fd100e3f7d1 100644
--- a/include/MantleAPI/Map/i_coord_converter.h
+++ b/include/MantleAPI/Map/i_coord_converter.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -27,7 +27,11 @@ class ICoordConverter
{
public:
virtual ~ICoordConverter() = default;
+
/// Converts a track position to its corresponding inertial position.
+ ///
+ /// @param position Track position. Coordinate system is implicitly defined by underlying type of Position
+ /// @return Inertial position
[[nodiscard]] virtual Vec3<units::length::meter_t> Convert(Position position) const = 0;
};
diff --git a/include/MantleAPI/Map/i_lane_location_query_service.h b/include/MantleAPI/Map/i_lane_location_query_service.h
index 51d7d32a4d30440962737271ef1225e4653e2a2e..7e34088205672b58eff2f433f539b1573d9e8f1c 100644
--- a/include/MantleAPI/Map/i_lane_location_query_service.h
+++ b/include/MantleAPI/Map/i_lane_location_query_service.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021-2022, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
* Copyright (c) 2022 Ansys, Inc.
*
* This program and the accompanying materials are made
@@ -28,12 +28,16 @@
namespace mantle_api
{
+
+/// Specifiy the direction of the lane relative to the reference pose.
enum class Direction
{
kForward = 0,
kBackwards = 1
};
+/// Definiton of the lateral displacement direction either to the left or right w.r.t the reference pose.
+/// "Any" means that the position calculation to the left is executed first and, in case of an an invalid result, to the right next.
enum class LateralDisplacementDirection
{
kAny = 0,
@@ -157,7 +161,7 @@ public:
/// @brief Calculate the lane id of the relative target lane from a given position
///
/// @param reference_pose_on_lane Starting position. Must be on a lane.
- /// @param relative_target_lane Shift of the target position in number of lanes relative to the lane where the
+ /// @param relative_lane_target Shift of the target position in number of lanes relative to the lane where the
/// reference pose is located. Positive to the left, negative to the right.
/// @return Lane id that is at the given lateral shift (relative_lane_target) from given position
/// (reference_pose_on_lane). No value, if reference pose is not on a lane or if the lane doesn't have a
diff --git a/include/MantleAPI/Map/i_route.h b/include/MantleAPI/Map/i_route.h
index 4f32d9c4eab5bedc92355608ba7e0b690a00ff5a..f52bb147dfb7fef0b15e0aa051171da8611a742d 100644
--- a/include/MantleAPI/Map/i_route.h
+++ b/include/MantleAPI/Map/i_route.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -23,18 +23,56 @@
namespace mantle_api
{
+/// Base interface for route
+/// It represents continuous path throughout the road network, defined by a series of waypoints
class IRoute : public virtual IIdentifiable
{
public:
+ /// Adds a waypoint to the route
+ ///
+ /// @param inert_pos Waypoint to add
+ /// @return created route defined by a series of waypoints
virtual IRoute& AddWaypoint(const Vec3<units::length::meter_t>& inert_pos) = 0;
+
+ /// Adds a waypoint to the route
+ ///
+ /// @param inert_pos Waypoint to add
+ /// @return created route defined by a series of waypoints
virtual IRoute& AddWaypoint(Vec3<units::length::meter_t>&& inert_pos) = 0;
+
+ /// Returns inertial position from track position
+ ///
+ /// @param route_pos s coordinate on lane
+ /// @param lane_id ID of lane
+ /// @param lane_offset t coordinate on lane
+ /// @return position in Cartesian coordinate system
[[nodiscard]] virtual Vec3<units::length::meter_t> GetInertPos(units::length::meter_t route_pos,
LaneId lane_id,
units::length::meter_t lane_offset = units::length::meter_t{
0.0}) const = 0;
+
+ /// Returns interpolated value for the width of the lane at the given position
+ ///
+ /// @param lane_id ID of lane to search in
+ /// @param route_pos s coordinate of search start
+ /// @return width at position
[[nodiscard]] virtual units::length::meter_t GetLaneWidth(units::length::meter_t route_pos, LaneId lane_id) const = 0;
+
+ /// Returns ID of the lane that encloses the passed in position within its shape
+ ///
+ /// @param inert_pos Position to search for the Lane ID
+ /// @return ID of the lane
[[nodiscard]] virtual LaneId GetLaneId(const Vec3<units::length::meter_t>& inert_pos) const = 0;
+
+ /// Returns distance from start to the given position along the set route
+ ///
+ /// @param inert_pos End position
+ /// @return distance from start to the given position
[[nodiscard]] virtual units::length::meter_t GetDistanceFromStartTo(const Vec3<units::length::meter_t>& inert_pos) const = 0;
+
+ /// Returns the length of the route
+ ///
+ /// @return length of the route
[[nodiscard]] virtual units::length::meter_t GetLength() const = 0;
};
diff --git a/include/MantleAPI/Map/map_details.h b/include/MantleAPI/Map/map_details.h
index 64b118bda9e7149e7b5ef184ef64e0dcc4f0d4d9..afb5235ef69e75059a5f866a02f83b04b9f5654c 100644
--- a/include/MantleAPI/Map/map_details.h
+++ b/include/MantleAPI/Map/map_details.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -21,10 +21,12 @@
namespace mantle_api
{
+/// Definition of the map area
struct MapDetails
{
virtual ~MapDetails() = default;
+ /// Area of the map (e.g. GPS latitude, GPS longitude)
std::vector<Position> map_region;
};
diff --git a/include/MantleAPI/Traffic/control_strategy.h b/include/MantleAPI/Traffic/control_strategy.h
index fbe432ec006d569b0899486f4a1b360b9a76f490..c76a152b578c6f8986a74a7f0076f0c1a99f0fdc 100644
--- a/include/MantleAPI/Traffic/control_strategy.h
+++ b/include/MantleAPI/Traffic/control_strategy.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021-2022 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
* Copyright (c) 2022 Ansys, Inc.
*
* This program and the accompanying materials are made
@@ -28,6 +28,7 @@
namespace mantle_api
{
+/// Movement domain of the control strategy, which specifies the desired movement behavior for the entity
enum class MovementDomain
{
kUndefined = 0,
@@ -37,6 +38,7 @@ enum class MovementDomain
kNone
};
+/// Type of the control strategy
enum class ControlStrategyType
{
kUndefined = 0,
@@ -51,26 +53,39 @@ enum class ControlStrategyType
kPerformLaneChange
};
+/// Defintion of all control strategies for a single entity.
+/// The runtime mapping of an private action instance to the simulator core.
struct ControlStrategy
{
virtual ~ControlStrategy() = default;
// TODO: extend by bool use_dynamic_constraints when needed (false assumed at the moment)
- MovementDomain movement_domain{MovementDomain::kUndefined};
- ControlStrategyType type{ControlStrategyType::kUndefined};
+ MovementDomain movement_domain{MovementDomain::kUndefined}; ///< Movement domain of the control strategy
+ ControlStrategyType type{ControlStrategyType::kUndefined}; ///< Type of the control strategy
};
+/// @brief Equality comparison for ControlStrategy.
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs exactly equal to the values of rhs.
constexpr bool operator==(const ControlStrategy& lhs, const ControlStrategy& rhs) noexcept
{
return lhs.movement_domain == rhs.movement_domain && lhs.type == rhs.type;
}
+/// @brief Inequality comparison for ControlStrategy.
+///
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the value of lhs is not almost equal to the value of rhs.
constexpr bool operator!=(const ControlStrategy& lhs, const ControlStrategy& rhs) noexcept
{
return !(lhs == rhs);
}
+/// Controls an entity to keeps current velocity
struct KeepVelocityControlStrategy : public ControlStrategy
{
KeepVelocityControlStrategy()
@@ -81,6 +96,7 @@ struct KeepVelocityControlStrategy : public ControlStrategy
// Doesn't need configuration attributes. Controller keeps current velocity on adding entity or update
};
+/// Controls an entity to keeps current lane offset
struct KeepLaneOffsetControlStrategy : public ControlStrategy
{
KeepLaneOffsetControlStrategy()
@@ -91,6 +107,7 @@ struct KeepLaneOffsetControlStrategy : public ControlStrategy
// Doesn't need configuration attributes. Controller keeps current lane offset on adding entity or update
};
+/// Controls an entity to follow a heading angle from spline
struct FollowHeadingSplineControlStrategy : public ControlStrategy
{
FollowHeadingSplineControlStrategy()
@@ -99,10 +116,13 @@ struct FollowHeadingSplineControlStrategy : public ControlStrategy
type = ControlStrategyType::kFollowHeadingSpline;
}
+ /// List of the heading angles of splines
std::vector<mantle_api::SplineSection<units::angle::radian>> heading_splines;
+ /// The default value of the heading angle
units::angle::radian_t default_value{0};
};
+/// Controls an entity to follow a velocity from spline
struct FollowVelocitySplineControlStrategy : public ControlStrategy
{
FollowVelocitySplineControlStrategy()
@@ -111,22 +131,35 @@ struct FollowVelocitySplineControlStrategy : public ControlStrategy
type = ControlStrategyType::kFollowVelocitySpline;
}
+ /// List of the velocities of splines
std::vector<mantle_api::SplineSection<units::velocity::meters_per_second>> velocity_splines;
+ /// The default value of the velocity
units::velocity::meters_per_second_t default_value{0};
};
+/// @brief Equality comparison for FollowVelocitySplineControlStrategy.
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs exactly equal to the values of rhs.
constexpr bool operator==(const FollowVelocitySplineControlStrategy& lhs,
const FollowVelocitySplineControlStrategy& rhs) noexcept
{
return lhs.default_value == rhs.default_value && lhs.velocity_splines == rhs.velocity_splines;
}
+/// @brief Inequality comparison for FollowVelocitySplineControlStrategy.
+///
+/// @param[in] lhs left-hand side value for the comparison
+/// @param[in] rhs right-hand side value for the comparison
+/// @returns true if the value of lhs is not almost equal to the value of rhs.
constexpr bool operator!=(const FollowVelocitySplineControlStrategy& lhs,
const FollowVelocitySplineControlStrategy& rhs) noexcept
{
return !(lhs == rhs);
}
+/// Controls an entity to follow a lateral offset from spline
struct FollowLateralOffsetSplineControlStrategy : public ControlStrategy
{
FollowLateralOffsetSplineControlStrategy()
@@ -135,9 +168,11 @@ struct FollowLateralOffsetSplineControlStrategy : public ControlStrategy
type = ControlStrategyType::kFollowLateralOffsetSpline;
}
+ /// List of the lateral offsets of splines
std::vector<mantle_api::SplineSection<units::length::meter>> lateral_offset_splines;
};
+/// Defines how a target value will be acquired (with a constant rate, in a defined distance, within a defined time).
enum class Dimension
{
kUndefined = 0,
@@ -146,6 +181,7 @@ enum class Dimension
kTime
};
+/// Function type used to represent the change of a given variable over time or distance.
enum class Shape
{
kUndefined = 0,
@@ -155,13 +191,18 @@ enum class Shape
kSinusoidal
};
+/// Specifies the dynamics of a value transition and defines how the value changes over time or distance.
struct TransitionDynamics
{
+ /// Defines how a target value will be acquired
Dimension dimension{Dimension::kUndefined};
+ /// The shape of the transition function between current and target value
Shape shape{Shape::kUndefined};
+ /// The value for a predefined rate, time or distance to acquire the target value
double value{0.0};
};
+/// Controls the transition to a defined lane offset of an entity
struct AcquireLaneOffsetControlStrategy : public ControlStrategy
{
AcquireLaneOffsetControlStrategy()
@@ -170,10 +211,13 @@ struct AcquireLaneOffsetControlStrategy : public ControlStrategy
type = ControlStrategyType::kAcquireLaneOffset;
}
+ /// Lane offset
units::length::meter_t offset{};
+ /// Specifies the dynamics of a value transition
TransitionDynamics transition_dynamics;
};
+/// Controls the transition of a current light state to the target light state
struct TrafficLightStateControlStrategy : public ControlStrategy
{
TrafficLightStateControlStrategy()
@@ -182,24 +226,34 @@ struct TrafficLightStateControlStrategy : public ControlStrategy
movement_domain = MovementDomain::kNone;
}
+ /// List of specific traffic light phases
std::vector<TrafficLightPhase> traffic_light_phases{};
+ /// The "repeat_states" flag determines, if the light state is repeated or not
bool repeat_states{false};
};
+/// Definition of time value context as either absolute or relative
enum class ReferenceContext
{
kAbsolute = 0,
kRelative
};
+/// Controls an entity to follow a trajectory
struct FollowTrajectoryControlStrategy : public ControlStrategy
{
// TODO: Extend the FollowTrajectoryControlStrategy to support shapes like NURBS and clothoid
+ /// Definition of the time information present in trajectory
struct TrajectoryTimeReference
{
+ /// Specification of the time domain (absolute or relative)
ReferenceContext domainAbsoluteRelative{ReferenceContext::kAbsolute};
+ /// Scaling factor for time values.
+ /// While values smaller than 1.0 represent negative scaling, values larger than 1.0 will result in positive scaling.
+ /// A value of 1.0 means no scaling.
double scale{1.0};
+ /// Global offset for all time values
units::time::second_t offset{0.0};
};
@@ -209,10 +263,14 @@ struct FollowTrajectoryControlStrategy : public ControlStrategy
type = ControlStrategyType::kFollowTrajectory;
}
+ /// Trajectory definition
Trajectory trajectory;
+ /// Time information provided within the trajectory
std::optional<TrajectoryTimeReference> timeReference;
};
+/// Controls an entity to perform a lane change.
+/// Describes the transition between an entity's current lane and its target lane.
struct PerformLaneChangeControlStrategy : public ControlStrategy
{
PerformLaneChangeControlStrategy()
@@ -221,8 +279,11 @@ struct PerformLaneChangeControlStrategy : public ControlStrategy
type = ControlStrategyType::kPerformLaneChange;
}
+ /// ID of the target lane the entity will change to
mantle_api::LaneId target_lane_id{0};
+ /// Lane offset to be reached at the target lane (the action will end there)
units::length::meter_t target_lane_offset{0.0};
+ /// Shape/time of lane change action
TransitionDynamics transition_dynamics{};
};
diff --git a/include/MantleAPI/Traffic/default_routing_behavior.h b/include/MantleAPI/Traffic/default_routing_behavior.h
index fac92b72539d4c71cedb30d9ad43a9ef2a3ad857..137783928c67a1edbc466a016c06c51e86da5ade 100644
--- a/include/MantleAPI/Traffic/default_routing_behavior.h
+++ b/include/MantleAPI/Traffic/default_routing_behavior.h
@@ -13,7 +13,7 @@
namespace mantle_api {
-/// @brief Specifies behavior to end of route
+/// Specify behavior to end of route
enum class DefaultRoutingBehavior
{
kStop, ///< Do nothing
diff --git a/include/MantleAPI/Traffic/entity_properties.h b/include/MantleAPI/Traffic/entity_properties.h
index a855a40787b0fe56b1714e24eb71f1995bf66da3..b93637642e99cddc596c1b189d42cef9e691e80f 100644
--- a/include/MantleAPI/Traffic/entity_properties.h
+++ b/include/MantleAPI/Traffic/entity_properties.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021-2022, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
* Copyright (c) 2022 Ansys, Inc.
*
* This program and the accompanying materials are made
@@ -28,6 +28,7 @@
namespace mantle_api
{
+/// Specify the type of an entity.
enum class EntityType
{
// Other (unspecified but known)
@@ -47,18 +48,29 @@ struct EntityProperties
{
virtual ~EntityProperties() = default;
+ /// The three dimensional bounding box that encloses the entity
BoundingBox bounding_box{Vec3<units::length::meter_t>{}, Dimension3{}};
+ /// Type of the entity object (e.g. vehicle, pedestrian)
EntityType type{EntityType::kOther};
+ /// Definition of the model of the entity
std::string model{};
+ /// Additional properties as name value pairs
std::map<std::string, std::string> properties{};
+ /// The mass of the entity in kg
units::mass::kilogram_t mass{};
};
+/// @brief Equality comparison for EntityProperties.
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs exactly equal to the values of rhs.
constexpr bool operator==(const EntityProperties& lhs, const EntityProperties& rhs) noexcept
{
return lhs.bounding_box == rhs.bounding_box && lhs.type == rhs.type && lhs.model == rhs.model;
}
+/// Specify the class of a vehicle.
enum class VehicleClass
{
kOther = 1, // Other (unspecified but known) type of vehicle.
@@ -99,6 +111,7 @@ enum class VehicleClass
kInvalid = -1
};
+/// Specify the state of the indicators of a vehicle.
enum class IndicatorState
{
// Indicator state is unknown (must not be used in ground truth).
@@ -115,6 +128,7 @@ enum class IndicatorState
kWarning = 5
};
+/// Specify external control of a vehicle.
enum class ExternalControlState
{
kOff = 0,
@@ -123,15 +137,26 @@ enum class ExternalControlState
kLongitudinalOnly = 3
};
+/// This struct represents the performance properties of the vehicle
struct Performance
{
+ /// Maximum speed of the vehicle
units::velocity::meters_per_second_t max_speed{std::numeric_limits<double>::infinity()};
+ /// Maximum acceleration of the vehicle
units::acceleration::meters_per_second_squared_t max_acceleration{std::numeric_limits<double>::infinity()};
- units::acceleration::meters_per_second_squared_t max_deceleration{std::numeric_limits<double>::infinity()};
+ /// Maximum deceleration of the vehicle
+ units::acceleration::meters_per_second_squared_t max_deceleration{std::numeric_limits<double>::infinity()};;
+ /// Maximum acceleration rate of the vehicle. If omitted then infinity is assumed
units::jerk::meters_per_second_cubed_t max_acceleration_rate{std::numeric_limits<double>::infinity()};
+ /// Maximum deceleration rate of the vehicle. If omitted then infinity is assumed
units::jerk::meters_per_second_cubed_t max_deceleration_rate{std::numeric_limits<double>::infinity()};
};
+/// @brief Equality comparison for Performance.
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs almost equal to the values of rhs.
constexpr bool operator==(const Performance& lhs, const Performance& rhs) noexcept
{
return AlmostEqual(lhs.max_speed, rhs.max_speed) &&
@@ -141,14 +166,24 @@ constexpr bool operator==(const Performance& lhs, const Performance& rhs) noexce
AlmostEqual(lhs.max_deceleration_rate, rhs.max_deceleration_rate);
}
+/// This struct represents the definition of vehicle axle
struct Axle
{
+ /// Maximum steering angle which can be performed by the wheels on this axle
units::angle::radian_t max_steering{0.0};
+ /// Diameter of the wheels on this axle
units::length::meter_t wheel_diameter{0.0};
+ /// Distance of the wheels center lines at zero steering
units::length::meter_t track_width{0.0};
+ /// Position of the axle with respect to the center of vehicles bounding box
Vec3<units::length::meter_t> bb_center_to_axle_center{};
};
+/// @brief Equality comparison for Axle.
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs (almost) equal to the values of rhs.
constexpr bool operator==(const Axle& lhs, const Axle& rhs) noexcept
{
return AlmostEqual(lhs.max_steering, rhs.max_steering) &&
@@ -157,20 +192,32 @@ constexpr bool operator==(const Axle& lhs, const Axle& rhs) noexcept
lhs.bb_center_to_axle_center == rhs.bb_center_to_axle_center;
}
+/// Additional properties for entity objects of type vehicle
struct VehicleProperties : public EntityProperties
{
+ /// Category of the vehicle (bicycle, train,...)
VehicleClass classification{VehicleClass::kOther};
+ /// Performance properties of the vehicle
Performance performance{};
+ /// Front axle of the vehicle
Axle front_axle{};
+ /// Rear axle of the vehicle
Axle rear_axle{};
+ /// The "is_host" flag determines, if the vehicle is host or not
bool is_host{false};
// TODO: remove, once external control for traffic is implemented through controllers
+ /// The "is_controlled_externally" flag determines, if the vehicle is controlled externally or not
bool is_controlled_externally{false};
};
+/// @brief Equality comparison for VehicleProperties.
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs exactly equal to the values of rhs.
constexpr bool operator==(const VehicleProperties& lhs, const VehicleProperties& rhs) noexcept
{
return lhs.bounding_box == rhs.bounding_box && lhs.type == rhs.type && lhs.model == rhs.model &&
@@ -183,11 +230,12 @@ struct PedestrianProperties : public EntityProperties
{
};
+/// Additional properties for entity objects of type static
struct StaticObjectProperties : public EntityProperties
{
- // Amount to shift position along lane normal.
- // It allows static objects like traffic signs to be placed at certain amount above the road.
- // It is considered when the position of the entity is set.
+ /// Amount to shift position along lane normal.
+ /// It allows static objects like traffic signs to be placed at certain amount above the road.
+ /// It is considered when the position of the entity is set.
units::length::meter_t vertical_offset{0.0};
};
diff --git a/include/MantleAPI/Traffic/i_controller.h b/include/MantleAPI/Traffic/i_controller.h
index fd93d91c6458f944fff5fc5b6e2881d3b4de1ea7..36ef23fb89c9be0803d7fb31cb7d9056dfb30c95 100644
--- a/include/MantleAPI/Traffic/i_controller.h
+++ b/include/MantleAPI/Traffic/i_controller.h
@@ -45,8 +45,8 @@ public:
};
/// Change the state of a controller
- /// @param parameter lateral New state of the lateral domain
- /// @param parameter longitudinal New state of the longituindal domain
+ /// @param[in] lateral_state New state of the lateral domain
+ /// @param[in] longitudinal_state New state of the longituindal domain
virtual void ChangeState(LateralState lateral_state, LongitudinalState longitudinal_state) = 0;
};
diff --git a/include/MantleAPI/Traffic/i_controller_config.h b/include/MantleAPI/Traffic/i_controller_config.h
index 1f9ab47c0066cf0f2cd898a178fc99464467c7b3..90a3a5602472b80803b2b0d979e675618e5d97d5 100644
--- a/include/MantleAPI/Traffic/i_controller_config.h
+++ b/include/MantleAPI/Traffic/i_controller_config.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -28,18 +28,28 @@
namespace mantle_api
{
+
+/// Base definition for creating a new controller for an entity
struct IControllerConfig
{
+ /// @brief default destructor
virtual ~IControllerConfig() = default;
-
+ /// @brief Name of the controller. Might be ignored by the environment.
std::string name;
- // TODO: Check why map_query_service is part of the interface because it is not set from engine side but only in the
- // environment on calling AddController()
+ /// Pointer to the map query service
+ /// @todo: Check why map_query_service is part of the interface because it is not set from engine side but only in the environment on calling AddController()
ILaneLocationQueryService* map_query_service{nullptr};
+ /// List of active control strategies
std::vector<std::shared_ptr<mantle_api::ControlStrategy>> control_strategies;
+ /// Specifies the route behavior for the control stratgies
RouteDefinition route_definition;
};
+/// @brief Equality comparison for IControllerConfig.
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs and rhs are equal
inline bool operator==(const IControllerConfig& lhs, const IControllerConfig& rhs) noexcept
{
if (&lhs == &rhs)
@@ -90,24 +100,37 @@ inline bool operator==(const IControllerConfig& lhs, const IControllerConfig& rh
compare_route_definition(lhs.route_definition, rhs.route_definition);
}
+/// @brief Check for not equal
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs and rhs are not equal
inline bool operator!=(const IControllerConfig& lhs, const IControllerConfig& rhs) noexcept
{
return !(lhs == rhs);
}
+/// Define a "No Operation" controller
struct NoOpControllerConfig : public IControllerConfig
{
};
+/// Define a default or internal controller (usually one per entity)
struct InternalControllerConfig : public IControllerConfig
{
};
+/// Define an external controller with custom parameters
struct ExternalControllerConfig : public IControllerConfig
{
+ /// Additional parameters as name value pair
std::map<std::string, std::string> parameters;
};
+/// @brief Check for equality
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs and rhs are equal
inline bool operator==(const ExternalControllerConfig& lhs, const ExternalControllerConfig& rhs) noexcept
{
auto compare_base = [](const IControllerConfig& lhs, const IControllerConfig& rhs)
@@ -118,6 +141,11 @@ inline bool operator==(const ExternalControllerConfig& lhs, const ExternalContro
return compare_base(lhs, rhs) && lhs.parameters == rhs.parameters;
}
+/// @brief Check for not equal
+///
+/// @param[in] lhs The left-hand side value for the comparison
+/// @param[in] rhs The right-hand side value for the comparison
+/// @returns true if the values of lhs and rhs are not equal
inline bool operator!=(const ExternalControllerConfig& lhs, const ExternalControllerConfig& rhs) noexcept
{
return !(lhs == rhs);
diff --git a/include/MantleAPI/Traffic/i_controller_repository.h b/include/MantleAPI/Traffic/i_controller_repository.h
index 864e44d034d729aa857e3ca88df0027bef5d91cd..a96187fdb782d2562075e2e0edd5978b9595dad6 100644
--- a/include/MantleAPI/Traffic/i_controller_repository.h
+++ b/include/MantleAPI/Traffic/i_controller_repository.h
@@ -3,6 +3,7 @@
/********************************************************************************
* Copyright (c) 2021 in-tech GmbH
+ * 2023, 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
@@ -23,15 +24,40 @@
namespace mantle_api
{
/// This interface provides CRUD functionality for controllers.
+/// Controller, which is assigned to exactly one entity, controls that one entity by enforcing the behavior prescribed by
+/// the control strategies assigned to that entity.
+/// Multiple controllers can be assigned to an entity, but only one controller can be activated for an entity at a time.
class IControllerRepository
{
public:
+ /// Creates a new controller for the entity
+ ///
+ /// @param config Controller config
+ /// @return newly created controller for the entity
virtual IController& Create(std::unique_ptr<IControllerConfig> config) = 0;
+
+ /// @deprecated Creates a new controller for the entity
+ ///
+ /// @param id Unique ID of the controller
+ /// @param config Controller config
+ /// @return newly created controller for the entity
[[deprecated]] virtual IController& Create(UniqueId id, std::unique_ptr<IControllerConfig> config) = 0; // deprecated
+ /// Gets the controller by the given unique ID
+ ///
+ /// @param id Unique ID of the controller
+ /// @return controller according to the given unique ID
virtual std::optional<std::reference_wrapper<IController>> Get(UniqueId id) = 0;
+
+ /// Checks whether the internal management container contains a controller with the given ID
+ ///
+ /// @param id Unique ID to be searched for
+ /// @return true, if controller with given ID exists, otherwise false
[[nodiscard]] virtual bool Contains(UniqueId id) const = 0;
+ /// Deletes the controller
+ ///
+ /// @param id The Identifier of the controller to be deleted
virtual void Delete(UniqueId id) = 0;
};
diff --git a/include/MantleAPI/Traffic/i_entity.h b/include/MantleAPI/Traffic/i_entity.h
index b8d33bd9a82aa412184e1d21f4bef9c6a9285475..ff2efd487c3880a8eee46d73e806c15a75e1bbb6 100644
--- a/include/MantleAPI/Traffic/i_entity.h
+++ b/include/MantleAPI/Traffic/i_entity.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021-2022, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -26,6 +26,8 @@
namespace mantle_api
{
+
+/// Definition of the visibility of the scenario entity
struct EntityVisibilityConfig
{
/// The "graphics" flag determines, if the entity shall be shown in visualizations of the simulated environment
@@ -50,60 +52,142 @@ struct EntityVisibilityConfig
class IEntity : public IIdentifiable
{
public:
- /// The position of the entity is the geometric center of its bounding box. The origin of the entity coordinate system
- /// can be defined flexibly in relation to the geometric center (see bounding box).
+ /// @brief Sets the position of the scenario entity
+ ///
+ /// @details The position of the entity is the geometric center of its bounding box. The origin of the entity coordinate system
+ /// can be defined flexibly in relation to the geometric center (see bounding box).
+ /// @param inert_pos Position of the scenario entity
virtual void SetPosition(const Vec3<units::length::meter_t>& inert_pos) = 0;
+
+ /// @brief Gets the position of the scenario entity
+ ///
+ /// @return Position of the scenario entity
[[nodiscard]] virtual Vec3<units::length::meter_t> GetPosition() const = 0;
+ /// @brief Sets the velocity of the scenario entity
+ ///
+ /// @param velocity Velocity vector (Forward, Sideward, Upward)
virtual void SetVelocity(const Vec3<units::velocity::meters_per_second_t>& velocity) = 0;
+
+ /// @brief Gets the velocity of the scenario entity
+ ///
+ /// @return Velocity vector (Forward, Sideward, Upward)
[[nodiscard]] virtual Vec3<units::velocity::meters_per_second_t> GetVelocity() const = 0;
+ /// @brief Sets the acceleration of the scenario entity
+ ///
+ /// @param acceleration Acceleration vector (Forward, Sideward, Upward)
virtual void SetAcceleration(const Vec3<units::acceleration::meters_per_second_squared_t>& acceleration) = 0;
+
+ /// @brief Gets the acceleration of the scenario entity
+ ///
+ /// @return Acceleration vector (Forward, Sideward, Upward)
[[nodiscard]] virtual Vec3<units::acceleration::meters_per_second_squared_t> GetAcceleration() const = 0;
+ /// @brief Sets the orientation of the scenario entity
+ ///
+ /// @param orientation 3D representation of orientation using yaw, pitch, and roll angles
virtual void SetOrientation(const Orientation3<units::angle::radian_t>& orientation) = 0;
+
+ /// @brief Gets the orientation of the scenario entity
+ ///
+ /// @return 3D representation of orientation using yaw, pitch, and roll angles
[[nodiscard]] virtual Orientation3<units::angle::radian_t> GetOrientation() const = 0;
+ /// @brief Sets the orientation rate (angular velocity) of the scenario entity
+ ///
+ /// @param orientation_rate Rate of change of a scenario entity's orientation over time
virtual void SetOrientationRate(
const Orientation3<units::angular_velocity::radians_per_second_t>& orientation_rate) = 0;
+
+ /// @brief Gets the orientation rate (angular velocity) of the scenario entity
+ ///
+ /// @return Rate at which yaw, pitch, and roll angles are changing with respect to time
[[nodiscard]] virtual Orientation3<units::angular_velocity::radians_per_second_t> GetOrientationRate() const = 0;
+ /// @brief Sets the orientation acceleration (angular acceleration) of the scenario entity
+ ///
+ /// @param orientation_acceleration Rate of change of a scenario entity's orientation rate with respect to time
virtual void SetOrientationAcceleration(
const Orientation3<units::angular_acceleration::radians_per_second_squared_t>& orientation_acceleration) = 0;
+
+ /// @brief Gets the orientation acceleration (angular acceleration) of the scenario entity
+ ///
+ /// @return Orientation acceleration (angular acceleration)
[[nodiscard]] virtual Orientation3<units::angular_acceleration::radians_per_second_squared_t> GetOrientationAcceleration()
const = 0;
+ /// @brief Sets the properties that describe scenario entity
+ ///
+ /// @param properties Basic properties that describe scenario entity
virtual void SetProperties(std::unique_ptr<mantle_api::EntityProperties> properties) = 0;
+
+ /// @brief Gets the properties that describe scenario entity
+ ///
+ /// @return Basic properties that describe scenario entity
[[nodiscard]] virtual EntityProperties* GetProperties() const = 0;
+ /// @brief Sets the IDs of the lanes that scenario entity is assigned to
+ ///
+ /// @param assigned_lane_ids The IDs of the lanes that scenario entity is assigned to
virtual void SetAssignedLaneIds(const std::vector<std::uint64_t>& assigned_lane_ids) = 0;
+
+ /// @brief Gets the IDs of the lanes that scenario entity is assigned to
+ ///
+ /// @return IDs of the lanes that scenario entity is assigned to
[[nodiscard]] virtual std::vector<std::uint64_t> GetAssignedLaneIds() const = 0;
+ /// @brief Sets the visibility of the scenario entity
+ ///
+ /// @param visibility Visibility of the scenario entity
virtual void SetVisibility(const EntityVisibilityConfig& visibility) = 0;
+
+ /// @brief Gets the visibility of the scenario entity
+ ///
+ /// @return Visibility of the scenario entity
[[nodiscard]] virtual EntityVisibilityConfig GetVisibility() const = 0;
};
+/// Interface for dynamic scenario entities of vehicle type
class IVehicle : public virtual IEntity
{
public:
+ /// @brief Gets the additional properties for entity object of type vehicle
+ ///
+ /// @return Additional properties that describe scenario entity object of type vehicle
[[nodiscard]] VehicleProperties* GetProperties() const override = 0;
+ /// @brief Set the indicator's state
+ ///
+ /// @param state State of the indicator
virtual void SetIndicatorState(IndicatorState state) = 0;
+
+ /// @brief Gets the indicator's state
+ ///
+ /// @return State of the indicator
[[nodiscard]] virtual IndicatorState GetIndicatorState() const = 0;
// virtual bool IsHost() const = 0;
// virtual void SetHost() = 0;
};
+/// Interface for scenario entities of pedestrian type
class IPedestrian : public virtual IEntity
{
public:
+ /// @brief Gets the additional properties for entity object of type pedestrian
+ ///
+ /// @return Additional properties that describe scenario entity object of type pedestrian
[[nodiscard]] PedestrianProperties* GetProperties() const override = 0;
};
+/// Interface for static scenario entities
class IStaticObject : public virtual IEntity
{
public:
+ /// @brief Gets the additional properties for static scenario entity
+ ///
+ /// @return Additional properties that describe static scenario entity
[[nodiscard]] StaticObjectProperties* GetProperties() const override = 0;
};
diff --git a/include/MantleAPI/Traffic/i_entity_repository.h b/include/MantleAPI/Traffic/i_entity_repository.h
index 03cd4f2b93d5da889a06d8bb603559bec4f580b7..4d00bea1a61e65f3fccfc38566d92ceab4a6397e 100644
--- a/include/MantleAPI/Traffic/i_entity_repository.h
+++ b/include/MantleAPI/Traffic/i_entity_repository.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -29,27 +29,114 @@ namespace mantle_api
class IEntityRepository
{
public:
+ /// Creates a new dynamic scenario entity of vehicle type
+ ///
+ /// @param name The name of the entity to be created
+ /// @param properties Vehicle properties
+ /// @return newly created dynamic scenario entity of vehicle type
virtual IVehicle& Create(const std::string& name, const VehicleProperties& properties) = 0;
+
+ /// @deprecated Creates a new dynamic scenario entity of vehicle type
+ ///
+ /// @param id Unique ID of the entity
+ /// @param name The name of the entity to be created
+ /// @param properties Vehicle properties
+ /// @return newly created dynamic scenario entity of vehicle type
[[deprecated]] virtual IVehicle& Create(UniqueId id, const std::string& name, const VehicleProperties& properties) = 0;
+
+ /// Creates a new scenario entity of pedestrian type
+ ///
+ /// @param name The name of the entity to be created
+ /// @param properties Pedestrian properties
+ /// @return newly created scenario entity of pedestrian type
virtual IPedestrian& Create(const std::string& name, const PedestrianProperties& properties) = 0;
+
+ /// @deprecated Creates a new scenario entity of pedestrian type
+ ///
+ /// @param id Unique ID of the entity
+ /// @param name The name of the entity to be created
+ /// @param properties Pedestrian properties
+ /// @return newly created scenario entity of pedestrian type
[[deprecated]] virtual IPedestrian& Create(UniqueId id, const std::string& name, const PedestrianProperties& properties) = 0;
+
+ /// Creates a new scenario entity of static object type
+ ///
+ /// @param name The name of the entity to be created
+ /// @param properties Static object properties
+ /// @return newly created scenario entity of static object type
virtual IStaticObject& Create(const std::string& name, const mantle_api::StaticObjectProperties& properties) = 0;
+
+ /// @deprecated Creates a new scenario entity of static object type
+ ///
+ /// @param id Unique ID of the entity
+ /// @param name The name of the entity to be created
+ /// @param properties Static object properties
+ /// @return newly created scenario entity of static object type
[[deprecated]] virtual IStaticObject& Create(UniqueId id, const std::string& name, const StaticObjectProperties& properties) = 0;
+ /// Gets the host vehicle
+ ///
+ /// @return host vehicle
virtual IVehicle& GetHost() = 0;
+
+ /// Gets the entity by the given name
+ ///
+ /// @param name The name of the entity
+ /// @return entity according to the given name
virtual std::optional<std::reference_wrapper<IEntity>> Get(const std::string& name) = 0;
+
+ /// Gets the const entity by the given name
+ ///
+ /// @param name The name of the entity
+ /// @return const entity according to the given name
[[nodiscard]] virtual std::optional<std::reference_wrapper<const IEntity>> Get(const std::string& name) const = 0;
+
+ /// Gets the entity by the given unique ID
+ ///
+ /// @param id Unique ID of the entity
+ /// @return entity according to the given unique ID
virtual std::optional<std::reference_wrapper<IEntity>> Get(UniqueId id) = 0;
+
+ /// Gets the const entity by the given unique ID
+ ///
+ /// @param id Unique ID of the entity
+ /// @return const entity according to the given unique ID
[[nodiscard]] virtual std::optional<std::reference_wrapper<const IEntity>> Get(UniqueId id) const = 0;
+
+ /// Checks whether the internal management container contains an scenario entity with the given ID
+ ///
+ /// @param id Unique ID to be searched for
+ /// @return true, if scenario entity with given ID exists, otherwise false
[[nodiscard]] virtual bool Contains(UniqueId id) const = 0;
+ /// Deletes the reference entity from the scenario
+ ///
+ /// @param name The name of the entity to be deleted
virtual void Delete(const std::string& name) = 0;
+
+ /// Deletes the reference entity from the scenario
+ ///
+ /// @param id The Identifier of the scenario entity to be deleted
virtual void Delete(UniqueId id) = 0;
+ /// Gets all scenario entities
+ ///
+ /// @returns all scenario entities
[[nodiscard]] virtual const std::vector<std::unique_ptr<mantle_api::IEntity>>& GetEntities() const = 0;
+ /// Allows an external component to react on creation of an entity, such as establishing additional references pointing to it
+ ///
+ /// @param callback Function to be called when creating an entity
virtual void RegisterEntityCreatedCallback(const std::function<void(IEntity&)>& callback) = 0;
+
+ /// Allows an external component to react on deletion of an entity, such as cleaning up invalid references pointing to it
+ ///
+ /// @param callback Function to be called when deleting an entity with string parameter
virtual void RegisterEntityDeletedCallback(const std::function<void(const std::string&)>& callback) = 0;
+
+ /// Allows an external component to react on deletion of an entity, such as cleaning up invalid references pointing to it
+ ///
+ /// @param callback Function to be called when deleting an entity with UniqueId parameter
virtual void RegisterEntityDeletedCallback(const std::function<void(UniqueId)>& callback) = 0;
};
diff --git a/include/MantleAPI/Traffic/i_traffic_swarm_service.h b/include/MantleAPI/Traffic/i_traffic_swarm_service.h
index c879b33c0ce4005821bfafd10d302901a5fa36e5..5325514d69d84ec35b7a0ac0dee407f0da84c0e4 100644
--- a/include/MantleAPI/Traffic/i_traffic_swarm_service.h
+++ b/include/MantleAPI/Traffic/i_traffic_swarm_service.h
@@ -23,38 +23,69 @@
namespace mantle_api
{
+/// This struct represents the parameters of the swarm traffic
struct TrafficSwarmParameters
{
+ /// The range for the lower and upper limit of the entity's starting speeds
struct SpeedRange
{
- units::velocity::meters_per_second_t minimum;
- units::velocity::meters_per_second_t maximum;
+ units::velocity::meters_per_second_t minimum; ///< The lower limit of a speed range
+ units::velocity::meters_per_second_t maximum; ///< The upper limit of a speed range
};
+ /// Name of the central entity the swarm traffic is created around
std::string central_entity_name;
+ /// The maximum number of vehicles surrounding the central entity
size_t maximum_number_of_vehicles;
+ /// The starting speeds of the spawned entities
SpeedRange speed_range;
+ /// Radius of the inner circular area around the central entity
units::length::meter_t exclusion_radius;
+ /// Shape of the swarm traffic distribution area is given as an ellipsis around a central entity.
+ /// semi_minor_spawning_radius defines the half length of the minor axis of this ellipsis.
units::length::meter_t semi_minor_spawning_radius;
+ // Shape of the swarm traffic distribution area is given as an ellipsis around a central entity.
+ /// semi_major_spawning_radius defines the half length of the major axis of this ellipsis.
units::length::meter_t semi_major_spawning_radius;
+ /// Offset in longitudinal direction related to the x-axis of the central entity
units::length::meter_t spawning_area_longitudinal_offset;
};
+/// Base interface for the swarm traffic
class ITrafficSwarmService
{
public:
+
+ /// Specify the relative position of the spawned vehicle to the central entity
enum class RelativePosition
{
kInFront = 0,
kBehind
};
+ /// Specify the position of the spawned vehicle
using SpawningPosition = std::pair<mantle_api::Pose, RelativePosition>;
+ /// Returns available spawning poses
+ ///
+ /// @return list of poses
virtual std::vector<SpawningPosition> GetAvailableSpawningPoses() const = 0;
+
+ /// Returns additional properties for entity objects of type vehicle
+ ///
+ /// @param vehicle_class Category of the vehicle (car, bicycle, train,...)
+ /// @return vehicle properties
virtual mantle_api::VehicleProperties GetVehicleProperties(mantle_api::VehicleClass vehicle_class) const = 0;
+
+ /// Updates parameters for the controller
+ ///
+ /// @param config External controller configuration file
+ /// @param speed The speed of the environment controller
virtual void UpdateControllerConfig(std::unique_ptr<mantle_api::ExternalControllerConfig>& config,
units::velocity::meters_per_second_t speed) = 0;
+ /// Sets the number of swarm entities
+ ///
+ /// @param count number of swarm entities
virtual void SetSwarmEntitiesCount(size_t count) = 0;
};
diff --git a/include/MantleAPI/Traffic/traffic_light_properties.h b/include/MantleAPI/Traffic/traffic_light_properties.h
index a6c13f7a0c945fdd0bbe12e2470b7968e1d134db..03cff3a238da5231389c059c7bb6ff8acd216ef5 100644
--- a/include/MantleAPI/Traffic/traffic_light_properties.h
+++ b/include/MantleAPI/Traffic/traffic_light_properties.h
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2021, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ * Copyright (c) 2021-2023, 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
@@ -20,6 +20,8 @@
namespace mantle_api
{
+
+/// Specify the color of a traffic light bulb.
enum class TrafficLightBulbColor
{
kUnknown = 0,
@@ -31,6 +33,7 @@ enum class TrafficLightBulbColor
kWhite = 6
};
+/// Specify the mode of a traffic light bulb.
enum class TrafficLightBulbMode
{
kUnknown = 0,
@@ -41,16 +44,24 @@ enum class TrafficLightBulbMode
kCounting = 5
};
+/// Definition of the traffic light state
struct TrafficLightBulbState
{
+ /// Color of the traffic light bulb
TrafficLightBulbColor color;
+ /// Indication if a traffic light should be switched on, off or flashing
TrafficLightBulbMode mode;
};
+/// Definition of the specific phase of a traffic light
struct TrafficLightPhase
{
+ /// State of a traffic signal for this phase
+ /// e.g. the visual information "off;off;on" for a vehicle traffic signal
std::vector<TrafficLightBulbState> bulb_states;
+ /// Time specification at the start of the phase
mantle_api::Time start_time{0};
+ /// Time specification at the end of the phase
mantle_api::Time end_time{0};
};
diff --git a/utils/ci/Jenkinsfile b/utils/ci/Jenkinsfile
index 77aa16af7c6defb459b8eab3b2ae027b77d14e4f..8fd81533ec76abdb143718d18b8b0a928bc099bf 100644
--- a/utils/ci/Jenkinsfile
+++ b/utils/ci/Jenkinsfile
@@ -60,6 +60,7 @@ spec:
stage('Linux: Build MantleAPI') {
steps {
container('mantleapi-build') {
+ sh 'bash repo/utils/ci/scripts/25_check_inline_docu.sh'
sh 'bash repo/utils/ci/scripts/30_build.sh'
}
}
@@ -94,6 +95,7 @@ spec:
stage('Windows: Build MantleAPI') {
steps {
dir('M:/') {
+ bat 'C:\\msys64\\usr\\bin\\bash -lc repo/utils/ci/scripts/25_check_inline_docu.sh'
bat 'C:\\msys64\\usr\\bin\\bash -lc repo/utils/ci/scripts/30_build.sh'
}
}
diff --git a/utils/ci/scripts/25_check_inline_docu.sh b/utils/ci/scripts/25_check_inline_docu.sh
new file mode 100755
index 0000000000000000000000000000000000000000..ae0f132d8cdcdce6cc688250f2549862b70a1149
--- /dev/null
+++ b/utils/ci/scripts/25_check_inline_docu.sh
@@ -0,0 +1,64 @@
+#!/bin/bash
+
+################################################################################
+# Copyright (c) 2023 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
+# http://www.eclipse.org/legal/epl-2.0.
+#
+# SPDX-License-Identifier: EPL-2.0
+################################################################################
+
+################################################################################
+# This script checks the inline documentation using doxygen
+################################################################################
+
+MYDIR="$(dirname "$(readlink -f $0)")"
+cd "$MYDIR/../../../../build" || exit 1
+
+make MantleAPI_doc
+
+# version comparison - https://unix.stackexchange.com/a/285928
+# under CC BY-SA 4.0 - https://creativecommons.org/licenses/by-sa/4.0/
+
+# dealing with bugs in Doxygen 1.8.17 (or earlier)
+# bug description - https://github.com/doxygen/doxygen/issues/7411
+# fixed in 1.8.18 - https://github.com/doxygen/doxygen/pull/7483
+if [ "$(printf '%s\n' "1.8.17" "$doxy_version" | sort -V | head -n1)" = "$doxy_version" ]; then
+ echo "Filtering Doxygen warnings \"return type of member ... is not documented\" (see https://github.com/doxygen/doxygen/issues/7411)"
+ sed -i '/warning: return type of member/d' "doc/DoxygenWarningLog.txt"
+fi
+
+# dealing with bugs in Doxygen 1.9.7 (or earlier)
+# bug description - https://github.com/doxygen/doxygen/issues/8091
+if [ "$(printf '%s\n' "1.9.7" "$doxy_version" | sort -V | head -n1)" = "$doxy_version" ]; then
+ echo "Filtering Doxygen warnings \"Member MantleAPI_ ... is not documented\" (see https://github.com/doxygen/doxygen/issues/8091)"
+ sed -i '/warning: Member MantleAPI_.*is not documented/d' "doc/DoxygenWarningLog.txt"
+fi
+
+# dealing with DOT issues bugs in Doxygen 1.9.7 (or earlier)
+# bug description - https://github.com/doxygen/doxygen/issues/8091
+if [ "$(printf '%s\n' "1.9.7" "$doxy_version" | sort -V | head -n1)" = "$doxy_version" ]; then
+ echo "Filtering Doxygen error: Problems running dot: exit code=2, command='dot' (Doxygen 1.9.7)"
+ sed -i "/error: Problems running dot: exit code=2, command='dot'/d" "doc/DoxygenWarningLog.txt"
+ sed -i "/error: Problems running dot: exit code=2, command='dot.exe'/d" "doc/DoxygenWarningLog.txt"
+ # remove blank lines
+ sed -i '/^\s*$/d' "doc/DoxygenWarningLog.txt"
+fi
+
+# filtering warnings not related to in-line documentation
+sed -i "/Detected potential recursive class relation/d" "doc/DoxygenWarningLog.txt"
+
+# remove blank lines
+sed -i '/^\s*$/d' "doc/DoxygenWarningLog.txt"
+
+if [ -s "doc/DoxygenWarningLog.txt" ]
+then
+ echo "ERROR: Doxygen warnings"
+ cat "doc/DoxygenWarningLog.txt"
+ exit 1
+else
+ echo "No Doxygen warnings found"
+ exit 0
+fi
\ No newline at end of file