Edit on GitHub

States

In this section of the documentation we explain the default vehicle state type provided by AutomotiveSimulator as well as the data types used to represent a driving scene. Most of the underlying structures are defined in Records.jl. The data structures provided in ADM.jl are concrete instances of parametric types defined in Records. It is possible in principle to define your custom state definition and use the interface defined in ADM.jl.

Entity state

Entities are represented by the Entity data type. The Entity data type has three fields: a state, a definition and an id.

AutomotiveSimulator.Entity — Type
Entity{S,D,I}

Immutable data structure to represent entities (vehicle, pedestrian, ...). Entities are defined by a state, a definition, and an id. The state of an entity usually models changing values while the definition and the id should not change.

Constructor

Entity(state, definition, id)

Copy constructor that keeps the definition and id but changes the state (a new object is still created):

Entity(entity::Entity{S,D,I}, s::S)

Fields

  • state::S
  • def::D
  • id::I
source

The state of an entity usually describes physical quantity such as position and velocity.

Two state data structures are provided.

Scenes

Scenes are represented using the Scene object. It is a datastructure to represent a collection of entities.

AutomotiveSimulator.Scene — Type
Scene{E}

Container to store a list of entities. The main difference from a regular array is that its size is defined at construction and is fixed. (push! is O(1))

Constructors

  • Scene(arr::AbstractVector; capacity::Int=length(arr))
  • Scene(::Type{E}, capacity::Int=100) where {E}

Fields

To interact with Scene object it is preferable to use functions rather than accessing the fields directly.

  • entities::Vector{E}
  • n::Int current number of entities in the scene
source

Defining your own state type

You can define your own state type if the provided VehicleState does not contain the right information. There are a of couple functions that need to be defined such that other functions in AutomotiveSimulator can work smoothly with your custom state type.

AutomotiveSimulator.posg — Function
posg(state)

returns the coordinates of the state in the global (world) frame. The return type is expected to be a VecSE2.

source
AutomotiveSimulator.posf — Function
posf(state)

returns the coordinates of the state in the Frenet frame. The return type is expected to be Frenet.

source

Example of a custom state type containing acceleration:


# you can use composition to define your custom state type based on existing ones
struct MyVehicleState
    veh::VehicleState
    acc::Float64
end

# define the functions from the interface 
posg(s::MyVehicleState) = posg(s.veh) # those functions are implemented for the `VehicleState` type
posf(s::MyVehicleState) = posf(s.veh)
velg(s::MyVehicleState) = velg(s.veh)
velf(s::MyVehicleState) = velf(s.veh)
vel(s::MyVehicleState) = vel(s.veh)

Provided State Type and Convenient Functions

Here we list useful functions to interact with vehicle states and retrieve interesting information like the position of the front of the vehicle or the lane to which the vehicle belongs.

AutomotiveSimulator.VehicleState — Type
VehicleState

A default type to represent an agent physical state (position, velocity). It contains the position in the global frame, Frenet frame and the longitudinal velocity

constructors

VehicleState(posG::VecSE2{Float64}, v::Float64) 
VehicleState(posG::VecSE2{Float64}, roadway::Roadway, v::Float64)
VehicleState(posG::VecSE2{Float64}, lane::Lane, roadway::Roadway, v::Float64)
VehicleState(posF::Frenet, roadway::Roadway, v::Float64)

fields

  • posG::VecSE2{Float64} global position
  • posF::Frenet lane relative position
  • v::Float64 longitudinal velocity
source
AutomotiveSimulator.Vec.lerp — Method
Vec.lerp(a::VehicleState, b::VehicleState, t::Float64, roadway::Roadway)

Perform linear interpolation of the two vehicle states. Returns a VehicleState.

source
AutomotiveSimulator.move_along — Method
move_along(vehstate::VehicleState, roadway::Roadway, Δs::Float64;
ϕ₂::Float64=vehstate.posF.ϕ, t₂::Float64=vehstate.posF.t, v₂::Float64=vehstate.v)

returns a vehicle state after moving vehstate of a length Δs along its lane.

source
AutomotiveSimulator.get_lane — Function
get_lane(roadway::Roadway, vehicle::Entity)
get_lane(roadway::Roadway, vehicle::VehicleState)

return the lane where vehicle is in.

source
AutomotiveSimulator.leftlane — Method
leftlane(roadway::Roadway, veh::Entity)

returns the lane to the left of the lane veh is currently in, returns nothing if it does not exists

source
AutomotiveSimulator.rightlane — Method
rightlane(roadway::Roadway, veh::Entity)

returns the lane to the right of the lane veh is currently in, returns nothing if it does not exists

source
Base.convert — Method
Base.convert(::Type{Entity{S, VehicleDef, I}}, veh::Entity{S, D, I}) where {S,D<:AbstractAgentDefinition,I}

Converts the definition of an entity

source