Unified documentation in DataAV. (#199)

tudo-aqua · Jan 14, 2025 · 3242097 · 3242097
1 parent 4dc2191
commit 3242097
Show file tree

Hide file tree

Showing 23 changed files with 55 additions and 70 deletions.
diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Block.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Block.kt
@@ -18,7 +18,7 @@
 package tools.aqua.stars.data.av.dataclasses
 
 /**
- * Data class for road blocks.
+ * Data class for [Road] blocks.
  *
  * @property fileName The filename.
  * @property id Identifier of the road block.

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/ContactArea.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/ContactArea.kt
@@ -18,7 +18,7 @@
 package tools.aqua.stars.data.av.dataclasses
 
 /**
- * Data class for road touching points.
+ * Data class for [Road] touching points.
  *
  * @property id Identifier of the road touching point.
  * @property contactLocation The [Location] of the touching point.

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/LandmarkType.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/LandmarkType.kt
@@ -18,7 +18,7 @@
 package tools.aqua.stars.data.av.dataclasses
 
 /**
- * Data class for landmark types.
+ * Data class for [Landmark] types.
  *
  * @property value Internal json value.
  */

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Lane.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Lane.kt
@@ -38,7 +38,6 @@ package tools.aqua.stars.data.av.dataclasses
  * @property trafficLights List of [StaticTrafficLight]s on this [Lane].
  * @property laneDirection The [LaneDirection] of this [Lane].
  */
-@Suppress("MemberVisibilityCanBePrivate")
 data class Lane(
     val laneId: Int,
     var road: Road,

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/LaneMidpoint.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/LaneMidpoint.kt
@@ -18,7 +18,7 @@
 package tools.aqua.stars.data.av.dataclasses
 
 /**
- * Data class for lane midpoints.
+ * Data class for [Lane] midpoints.
  *
  * @property distanceToStart The distance to the starting point.
  * @property location The [Location] of the midpoint.

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/LaneType.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/LaneType.kt
@@ -18,7 +18,7 @@
 package tools.aqua.stars.data.av.dataclasses
 
 /**
- * Data class for lane types.
+ * Data class for [Lane] types.
  *
  * @property value Internal json value.
  */

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Location.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Location.kt
@@ -26,6 +26,7 @@ import kotlin.math.sqrt
  * @property x The x ordinate.
  * @property y The y ordinate.
  * @property z The z ordinate.
+ * @see Vector3D
  */
 data class Location(val x: Double, val y: Double, val z: Double) {
   companion object {

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Road.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Road.kt
@@ -18,7 +18,7 @@
 package tools.aqua.stars.data.av.dataclasses
 
 /**
- * Json object for roads.
+ * Data class for roads.
  *
  * @property id The identifier of the road.
  * @property isJunction Whether this is a junction.

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Segment.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Segment.kt
@@ -20,7 +20,7 @@ package tools.aqua.stars.data.av.dataclasses
 import tools.aqua.stars.core.types.SegmentType
 
 /**
- * Evaluation segment.
+ * Data class for segments.
  *
  * @property mainInitList [TickData] of the [Segment].
  * @property simulationRunId Identifier of the simulation run.

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/StaticTrafficLight.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/StaticTrafficLight.kt
@@ -24,6 +24,7 @@ package tools.aqua.stars.data.av.dataclasses
  * @property location The [Location] of the traffic light.
  * @property rotation The [Rotation] of the traffic light.
  * @property stopLocations List of stop locations as [Location]s.
+ * @see TrafficLight
  */
 data class StaticTrafficLight(
     var id: Int,

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/TickData.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/TickData.kt
@@ -20,7 +20,7 @@ package tools.aqua.stars.data.av.dataclasses
 import tools.aqua.stars.core.types.TickDataType
 
 /**
- * Json format containing data for current tick.
+ * Data class for tick data.
  *
  * @property currentTick Current tick value.
  * @property entities List of all [Actor]s.

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/TrafficLight.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/TrafficLight.kt
@@ -18,11 +18,12 @@
 package tools.aqua.stars.data.av.dataclasses
 
 /**
- * Json object for traffic lights.
+ * Data class for traffic lights.
  *
  * @property id The identifier of the traffic light.
  * @property state The current state oif the traffic light.
  * @property relatedOpenDriveId The related open drive identifier.
+ * @see StaticTrafficLight
  */
 data class TrafficLight(var id: Int, var state: TrafficLightState, val relatedOpenDriveId: Int) {
   override fun toString(): String = "TrafficLight($id, $state)"

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Vector3D.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/Vector3D.kt
@@ -17,8 +17,10 @@
 
 package tools.aqua.stars.data.av.dataclasses
 
+import kotlin.math.sqrt
+
 /**
- * Data class for 3D vector.
+ * Data class for 3D vectors.
  *
  * @property x The x ordinate.
  * @property y The y ordinate.
@@ -40,7 +42,7 @@ data class Vector3D(val x: Double, val y: Double, val z: Double) {
   /** Negation operator. */
   operator fun unaryMinus(): Vector3D = Vector3D(x = -this.x, y = -this.y, z = -this.z)
 
-  /** Division with scalar operator. */
+  /** Multiplication with scalar operator. */
   operator fun times(scalar: Number): Vector3D =
       Vector3D(
           x = this.x * scalar.toDouble(),
@@ -53,4 +55,20 @@ data class Vector3D(val x: Double, val y: Double, val z: Double) {
           x = this.x / scalar.toDouble(),
           y = this.y / scalar.toDouble(),
           z = this.z / scalar.toDouble())
+
+  /** Dot product with another vector. */
+  fun dot(other: Vector3D): Double = x * other.x + y * other.y + z * other.z
+
+  /** Cross (Vector) product with another vector. */
+  fun cross(other: Vector3D): Vector3D =
+      Vector3D(
+          x = y * other.z - z * other.y,
+          y = z * other.x - x * other.z,
+          z = x * other.y - y * other.x)
+
+  /** Length of the vector. */
+  fun magnitude(): Double = sqrt(x * x + y * y + z * z)
+
+  /** Normalized vector with the same direction and length 1. */
+  fun normalized(): Vector3D = magnitude().let { Vector3D(x / it, y / it, z / it) }
 }
diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/VehicleType.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/VehicleType.kt
@@ -17,7 +17,7 @@
 
 package tools.aqua.stars.data.av.dataclasses
 
-/** Enum class for vehicle types present in CARLA. */
+/** Enum for vehicle types. */
 enum class VehicleType {
   CAR,
   TRUCK,

diff --git a/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/WeatherType.kt b/stars-data-av/src/main/kotlin/tools/aqua/stars/data/av/dataclasses/WeatherType.kt
@@ -17,7 +17,7 @@
 
 package tools.aqua.stars.data.av.dataclasses
 
-/** Data class for weather types. */
+/** Enum for weather types. */
 enum class WeatherType {
   Clear,
   Cloudy,

diff --git a/...er-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonActorPosition.kt b/...er-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonActorPosition.kt
@@ -21,11 +21,11 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * Json object for actor positions.
+ * Json object for [JsonActor] positions.
  *
- * @property positionOnLane Current position on the lane.
- * @property laneId The lane's identifier.
- * @property roadId The road's identifier.
+ * @property positionOnLane Current position on the [JsonLane].
+ * @property laneId The [JsonLane]'s identifier.
+ * @property roadId The [JsonRoad]'s identifier.
  * @property actor The [JsonActor].
  */
 @Serializable

diff --git a/...s-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonBlock.kt b/...s-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonBlock.kt
@@ -21,7 +21,7 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * Json object for road blocks.
+ * Json object for [JsonRoad] blocks.
  *
  * @property id Identifier of the road block.
  * @property roads Roads incorporated in this block.

diff --git a/...rter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactArea.kt b/...rter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactArea.kt
@@ -23,16 +23,16 @@ import kotlinx.serialization.Serializable
 /**
  * Json object for road touching points.
  *
- * @property id Identifier of the road touching point.
+ * @property id Identifier of the [JsonRoad] touching point.
  * @property contactLocation The [JsonLocation] of the touching point.
- * @property lane1RoadId Road identifier of lane 1.
- * @property lane1Id Identifier of lane 1.
- * @property lane1StartPos Start position on lane 1.
- * @property lane1EndPos End position on lane 1.
- * @property lane2RoadId Road identifier of lane 2.
- * @property lane2Id Identifier of lane 2.
- * @property lane2StartPos Start position on lane 2.
- * @property lane2EndPos End position on lane 2.
+ * @property lane1RoadId [JsonRoad] identifier of [JsonLane] 1.
+ * @property lane1Id Identifier of [JsonLane] 1.
+ * @property lane1StartPos Start position on [JsonLane] 1.
+ * @property lane1EndPos End position on [JsonLane] 1.
+ * @property lane2RoadId [JsonRoad] identifier of [JsonLane] 2.
+ * @property lane2Id Identifier of [JsonLane] 2.
+ * @property lane2StartPos Start position on [JsonLane] 2.
+ * @property lane2EndPos End position on [JsonLane] 2.
  */
 @Serializable
 data class JsonContactArea(

diff --git a/...-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactLaneInfo.kt b/...-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactLaneInfo.kt
@@ -23,8 +23,8 @@ import kotlinx.serialization.Serializable
 /**
  * Json object for contact lane info.
  *
- * @property roadId Road identifier of the lane.
- * @property laneId Identifier of the lane.
+ * @property roadId [JsonRoad] identifier of the [JsonLane].
+ * @property laneId Identifier of the [JsonLane].
  */
 @Serializable
 data class JsonContactLaneInfo(

diff --git a/...rter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonCoordinates.kt b/...rter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonCoordinates.kt
diff --git a/...ter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonLaneMidpoint.kt b/...ter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonLaneMidpoint.kt
@@ -22,10 +22,10 @@ import kotlinx.serialization.Serializable
 import tools.aqua.stars.data.av.dataclasses.LaneMidpoint
 
 /**
- * Json object for lane midpoints.
+ * Json object for [JsonLane] midpoints.
  *
- * @property laneId The identifier of the lane.
- * @property roadId The identifier of the road.
+ * @property laneId The identifier of the [JsonLane].
+ * @property roadId The identifier of the [JsonRoad].
  * @property distanceToStart The distance to the starting point.
  * @property location The [JsonLocation] of the midpoint.
  * @property rotation The [JsonRotation] of the midpoint.

diff --git a/...mporter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonTickData.kt b/...mporter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonTickData.kt
@@ -21,7 +21,7 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * Json format containing data for current tick.
+ * Json object for current tick data.
  *
  * @property currentTick Current tick value.
  * @property actorPositions The current [JsonActorPosition]s of all actors.

diff --git a/...mporter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonVector3D.kt b/...mporter-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonVector3D.kt
@@ -27,6 +27,7 @@ import tools.aqua.stars.data.av.dataclasses.Vector3D
  * @property x The x ordinate.
  * @property y The y ordinate.
  * @property z The z ordinate.
+ * @see JsonLocation
  */
 @Serializable
 data class JsonVector3D(