Car API

All cars operating in a Road Traffic Library flowchart provide the functions listed below.

Car dimensions

Function	Description
double getLength()	Returns the length of the car, in meters.
double getLength(LengthUnits units)	Returns the length of the car, in specified length units. For instance, getLength(FOOT) returns the car length in feet. units — the length units.
void setLength(double length)	Sets the length of the car, in meters. The new length value must be must be greater than 0. The length can be set only to a car that is not in the road network. length — the new length of the car.
void setLength(double length, LengthUnits units)	Sets the length of the car, in specified length units. For instance, setLength(4.5, METER) sets the car length to 4.5 meters. The new length value must be must be greater than 0. The length can be set only to a car that is not in the road network. length — the new length of the car. units — the length units.
double getWidth()	Returns the width of the car, in meters.
double getWidth(LengthUnits units)	Returns the width of the car, in specified length units. For instance, getWidth(METER) returns the car width in meters. units — the length units.

Speed

Function	Description
double getSpeed()	Returns the current speed of the car, in meters per second.
double getSpeed(SpeedUnits units)	Returns the current speed of the car, in specified speed units. For instance, getSpeed(KPH) returns the current car speed in kilometers per hour. units — the speed units.
double getAverageSpeed()	Returns the average speed of the car, in meters per second. If the car has not moved yet, the function returns 0.
double getAverageSpeed(SpeedUnits units)	Returns the average speed of the car, in specified speed units. For instance, getAverageSpeed(KPH) returns the preferred speed in kilometers per hour. If the car has not moved yet, the function returns 0. units — the speed units.
double getPreferredSpeed()	Returns the preferred speed of the car, in meters per second.
double getPreferredSpeed(SpeedUnits units)	Returns the preferred speed of the car, in specified speed units. For instance, getPreferredSpeed(KPH) returns the preferred speed in kilometers per hour. units — the speed units.
void setPreferredSpeed(double speed)	Sets the new preferred speed for the car, in meters per second. speed — the new preferred speed for the car.
void setPreferredSpeed(double speed, SpeedUnits units)	Sets the new preferred speed for the car, in specified speed units. For instance, setPreferredSpeed(70, KPH) sets the preferred speed to 70 kilometers per hour. speed — the new preferred speed. units — the speed units.

Acceleration and deceleration

Function	Description
boolean isAccelerating()	Tests if the car is accelerating. Returns true if the car is accelerating (that is, its acceleration is greater than 0), otherwise false.
boolean isDecelerating()	Tests if the car is decelerating. Returns true if the car is decelerating (that is, its acceleration is less than 0), otherwise false.
double getAcceleration()	Returns the current acceleration of the car, in meters per second².
double getAcceleration(AccelerationUnits units)	Returns the current acceleration of the car, in specified acceleration units. For instance, getAcceleration(FPS_SQ) returns the current car acceleration in feet per second². units — the acceleration units.
double getMaxAcceleration()	Returns the maximum possible acceleration of the car, in meters per second².
double getMaxAcceleration(AccelerationUnits units)	Returns the maximum possible acceleration of the car, in specified acceleration units. For instance, getMaxAcceleration(FPS_SQ) returns the maximum possible acceleration in feet per second². units — the acceleration units.
double getMaxDeceleration()	Returns the maximum possible deceleration of the car, in meters per second².
double getMaxDeceleration(AccelerationUnits units)	Returns the maximum possible deceleration of the car, in specified acceleration units. For instance, getMaxDeceleration(FPS_SQ) returns the maximum possible deceleration in feet per second².
void setMaxAcceleration(double maxAcceleration)	Sets the new maximum possible acceleration of the car, in meters per second². The value must be greater than 0. maxAcceleration — the new maximum acceleration.
void setMaxAcceleration(double maxAcceleration, AccelerationUnits units)	Sets the new maximum possible acceleration of the car, in specified acceleration units. For instance, setMaxAcceleration(3, FPS_SQ) sets the maximum possible acceleration to 3 feet per second². maxAcceleration must be greater than 0. maxAcceleration — the new maximum acceleration.
void setMaxDeceleration(double maxDeceleration)	Sets the new maximum possible deceleration of the car, in meters per second². The value must be greater than 0. maxDeceleration — the new maximum deceleration.
void setMaxDeceleration(double maxDeceleration, AccelerationUnits units)	Sets the new maximum possible deceleration of the car, in specified acceleration units. For instance, setMaxDeceleration(3, FPS_SQ) sets the maximum possible deceleration to 3 feet per second². maxDeceleration must be greater than 0. maxDeceleration — the new maximum deceleration. units — the acceleration units.

Distance driven

Function	Description
double getDistanceDriven()	Returns the distance driven from the creation of the car or from the last call of the resetDistanceDriven() function, in meters.
double getDistanceDriven(LengthUnits units)	Returns the distance driven from the creation of the car or from the last call of the resetDistanceDriven() function, in specified units. units — the length units.
void resetDistanceDriven()	Resets the accumulation of the distance driven to 0.

Car location

Function	Description
Road getRoad()	Returns the road where this car is located, if any, or null if the car is not on a road.
int getLaneIndex()	Returns the index of the lane that the car is currently in. Lanes are numbered from the outermost (that has the index 0) to innermost. If the car is currently changing lane or car is not on a road (for example, it is at an intersection), the function returns -1.
double getRoadOffset()	Returns the offset (measured along the road axis, that is, the middle of the road’s median strip) from the beginning of the road in the XY-projection. If the car is not on the road (for example, it is at an intersection), returns -1. The offset value is returned in meters.
Intersection getIntersection()	Returns the intersection where this car is located, if any, or null if the car is not at an intersection currently.
ParkingLot getParkingLot()	Returns the parking lot where this car is located, if any, or null if the car is not at a parking lot currently.
BusStop getBusStop()	Returns the bus stop where this car is located, if any, or null if the car is not at a bus stop currently.
boolean isCarOn(Object roadNetworkPart)	Checks if the car is now on the specified part of the road network (a road, intersection, parking lot, or bus stop). Returns true if the car is now on the specified part of the road network, false otherwise. roadNetworkPart — the specified part of the road network (a road, intersection, parking lot, or bus stop)
boolean isOnForwardSide()	Checks if the car is on the forward lane of the road. The returned value is only applicable if the car is on the road. Returns true if the car is on the forward lane of the road, returns false if the car is on the backward lane of the road. It also returns false if the car is not on the road.
RoadNetwork getRoadNetwork()	Returns the road network where the car is currently in, or null if the car is not in a road network.

Other

Function	Description
RoadNetworkDescriptor getRoadNetworkDescriptor()	Returns the RoadNetworkDescriptor block that configures the road network where the car is currently in. Returns null if the car is not in a road network.
boolean isChangingLane()	Checks if the car is currently changing lane. Returns true if the car is currently changing lane, otherwise false.
Agent getCarInFront()	Returns the car that is located in front of this car within this car’s attention range. Returns null if there is no such car. The car’s attention range changes dynamically and depends on the car’s speed.
void highlight(boolean yes)	Toggles the highlighting of the car depending on the function’s argument value. A red circle is drawn around a highlighted car. yes — If true, highlight the car, otherwise remove the highlight.

How can we improve this article?