From 569621e0bd0eb655a5eb401f0e1ff1fb1328a10e Mon Sep 17 00:00:00 2001 From: Dominik Schmid Date: Wed, 11 Dec 2024 10:51:41 +0100 Subject: [PATCH] Unified documentation in DataAV. --- .../aqua/stars/data/av/dataclasses/Block.kt | 2 +- .../stars/data/av/dataclasses/ContactArea.kt | 2 +- .../stars/data/av/dataclasses/LandmarkType.kt | 2 +- .../aqua/stars/data/av/dataclasses/Lane.kt | 1 - .../stars/data/av/dataclasses/LaneMidpoint.kt | 2 +- .../stars/data/av/dataclasses/LaneType.kt | 2 +- .../stars/data/av/dataclasses/Location.kt | 1 + .../aqua/stars/data/av/dataclasses/Road.kt | 2 +- .../aqua/stars/data/av/dataclasses/Segment.kt | 2 +- .../data/av/dataclasses/StaticTrafficLight.kt | 1 + .../stars/data/av/dataclasses/TickData.kt | 2 +- .../stars/data/av/dataclasses/TrafficLight.kt | 3 +- .../stars/data/av/dataclasses/Vector3D.kt | 10 +++++- .../stars/data/av/dataclasses/VehicleType.kt | 2 +- .../stars/data/av/dataclasses/WeatherType.kt | 2 +- .../carla/dataclasses/JsonActorPosition.kt | 8 ++--- .../importer/carla/dataclasses/JsonBlock.kt | 2 +- .../carla/dataclasses/JsonContactArea.kt | 18 +++++----- .../carla/dataclasses/JsonContactLaneInfo.kt | 4 +-- .../carla/dataclasses/JsonCoordinates.kt | 36 ------------------- .../carla/dataclasses/JsonLaneMidpoint.kt | 6 ++-- .../carla/dataclasses/JsonTickData.kt | 2 +- .../carla/dataclasses/JsonVector3D.kt | 1 + 23 files changed, 44 insertions(+), 69 deletions(-) delete mode 100644 stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonCoordinates.kt 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 index 9b6676a5..dcbc6dca 100644 --- 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 index 73130de2..a95e6184 100644 --- 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 index 36b63f14..66d54662 100644 --- 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 index 299b1bfa..980af2af 100644 --- 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 index c5345689..ecd4d6b1 100644 --- 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 index ddd61ca9..0f1768c3 100644 --- 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 index 3f40731c..389feeb2 100644 --- 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 index 8a7b8edd..1195044a 100644 --- 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 index 7c8139fe..4a9597d0 100644 --- 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 index a96647b2..906fb53f 100644 --- 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 index 13b284c1..f15c3211 100644 --- 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 index cd86cf8c..0b6400d5 100644 --- 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 index 0f8e0009..fc405625 100644 --- 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. @@ -53,4 +55,10 @@ 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()) + + fun dot(other: Vector3D): Double = x * other.x + y * other.y + z * other.z + + fun magnitude(): Double = sqrt(x * x + y * y + z * z) + + fun normalize(): 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 index 61405ed5..273780e1 100644 --- 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 index bfcbc6be..4e0fdafd 100644 --- 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/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonActorPosition.kt b/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonActorPosition.kt index 89a0d13e..a2c017e2 100644 --- a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonActorPosition.kt +++ b/stars-importer-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/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonBlock.kt b/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonBlock.kt index a029b11f..e17ee29b 100644 --- a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonBlock.kt +++ b/stars-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/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactArea.kt b/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactArea.kt index 0b3b0b5e..64c3fec3 100644 --- a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactArea.kt +++ b/stars-importer-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/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactLaneInfo.kt b/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactLaneInfo.kt index a240aa25..2920d94b 100644 --- a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonContactLaneInfo.kt +++ b/stars-importer-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/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonCoordinates.kt b/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonCoordinates.kt deleted file mode 100644 index 32cca094..00000000 --- a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonCoordinates.kt +++ /dev/null @@ -1,36 +0,0 @@ -/* - * Copyright 2023-2024 The STARS Project Authors - * SPDX-License-Identifier: Apache-2.0 - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package tools.aqua.stars.importer.carla.dataclasses - -import kotlinx.serialization.SerialName -import kotlinx.serialization.Serializable - -/** - * Json object for 3D coordinates. - * - * @property x The x ordinate. - * @property y The y ordinate. - * @property z The z ordinate. - */ -@Suppress("unused") -@Serializable -data class JsonCoordinates( - @SerialName("x") val x: Double, - @SerialName("y") val y: Double, - @SerialName("z") val z: Double, -) diff --git a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonLaneMidpoint.kt b/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonLaneMidpoint.kt index b9aff6a0..a70b774f 100644 --- a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonLaneMidpoint.kt +++ b/stars-importer-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/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonTickData.kt b/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonTickData.kt index 0771afff..5fc1e623 100644 --- a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonTickData.kt +++ b/stars-importer-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/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonVector3D.kt b/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonVector3D.kt index 2c3daa53..8917ac57 100644 --- a/stars-importer-carla/src/main/kotlin/tools/aqua/stars/importer/carla/dataclasses/JsonVector3D.kt +++ b/stars-importer-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(