Disim Highway Simulator/The LUA API

Getting Started

Disim allows one to control the individual car behavior and the infrastructure using scripts made in LUA. These scripts have to provide specific functions to Disim (as seen here and here), but Disim also provides functions to them in the form of an object-oriented API.

LuaCar

This object describes a car running inside the simulator. It has 9 associated functions.

function LuaCar:getPosition()

This function returns a number. This number is the position of the vehicle in its current lane. This position is given in meters if the current segment is a straight segment or in radians if it is circular.

function LuaCar:getLane()

This function returns a pointer to a LuaLane object representing the current lane of the vehicle.

function LuaCar:getSpeed()

This function returns a number giving the current speed of the vehicle in meters per second (m/s).

function LuaCar:setSpeed(speed)

This function sets the current speed of the vehicle in meters per second (m/s) and sets its acceleration to zero.

function LuaCar:setAccleration(acceleration)

This function sets the current acceleration of the vehicle in meters per second squared (m/s^2).

function LuaCar:setLaneChange(offset)

This function sets the next lane to change to. If offset is negative the car will change to the left lane, if it is positive it will change to the right lane, otherwise it will stay on the current lane. A lane change may fail if there is no space on the destination lane.

function LuaCar:getType()

This function return either the value CAR or TRUCK depending on whether the vehicle is a car or a truck.

function LuaCar:getGeometry()

This function returns 4 numbers. The first number is the distance from the center of the rear axle to the front bumper, the second is the distance to the rear bumper, the third is the distance to the left-most side and the fourth is the height of the vehicle.

function LuaCar:isTracked()

This function returns true if the vehicle is being followed by the camera in the graphical interface (useful to debug). It returns false otherwise.

function LuaCar:isLeftAllowed()

This function returns true if it is legal to change lanes to the left (this function checks the lane markings on the left side of the current position).

function LuaCar:isRightAllowed()

This function returns true if it is legal to change lanes to the right (this function checks the lane markings on the right side of the current position).

function LuaCar:getDestination()

This function returns the preferred destination lane as LuaLane object. It returns nil if no destination lane is preferred.

function LuaCar:nextTrafficLight()

This function returns a pointer to the next LuaRoadActuator with the type equal to TRAFFICLIGHT.

LuaInfrastructure

This object describes the infrastructure and gives access to all sensors and actuators of the network. It provides 7 functions.

function LuaInfrastructure:getName()

This function returns the name of the current map.

function LuaInfrastructure:getLane(name)

This function returns one pointer to a LuaLane with the name name. If multiple lanes are declared with the same name, just one lane is returned (which one is returned is not specified).

function LuaInfrastructure:getLanes(name)

This function returns an array of pointers to all LuaLanes with the name name.

function LuaInfrastructure:getEntryLanes()

This function returns an array of pointers to all LuaLanes with that are entries of the network.

function LuaInfrastructure:getRoadSensor(name)

This function returns one pointer to a LuaRoadSensor with the name name. If multiple sensors are declared with the same name, just one sensor is returned (which one is returned is not specified).

function LuaInfrastructure:getRoadActuator(name)

This function returns one pointer to a LuaRoadActuator with the name name. If multiple actuators are declared with the same name, just one actuator is returned (which one is returned is not specified).

function LuaInfrastructure:getTimeOfDay(t)

This function returns a string in the HH:MM 24-hours format. It takes as input the total time elapsed since the beginning of the simulation.

LuaLane

This object describes a lane of the highway. Each segment of the highway contains a given number of lane. Each lane provides 17 functions.

function LuaLane:getNext()

This function returns a pointer to the LuaLane object representing the lane directly following the current lane. If there is no such lane, the value nil is returned.

function LuaLane:getPrev()

This function returns a pointer to the LuaLane object representing the lane directly preceding the current lane. If there is no such lane, the value nil is returned.

function LuaLane:getLeft()

This function returns a pointer to the LuaLane object representing the lane directly on the left the current lane. If there is no such lane, the value nil is returned.

function LuaLane:getRight()

This function returns a pointer to the LuaLane object representing the lane directly on the right the current lane. If there is no such lane, the value nil is returned.

function LuaLane:getMergeDirection()

This function returns 1 if the cars on this lane need to merge on the right lane by the end of that lane. This means that there are no next lane and that the cars either need to stop or merge. This function return -1 when merging on the left is needed and 0 otherwise.

function LuaLane:getType()

This function returns either ENTRY, EXIT or NONE depending on whether the current lane is an entry, an exit or neither respectively.

function LuaLane:getGeometry()

This function returns either STRAIGHT or CIRCULAR if the current lane is part of a straight segment or a circular segment.

function LuaLane:getLength()

If this lane is straight (getGeometry() == STRAIGHT), this function returns the length in meters of that lane. If this lane is not straight, the return value is not defined.

function LuaLane:getRadius()

If this lane is circular (getGeometry() == CIRCULAR), this function returns the radius of curvature of that lane in meters. If this lane is not circular, the return value is not defined.

function LuaLane:getAngleSpan()

If this lane is circular (getGeometry() == CIRCULAR), this function returns the angle spanned by that lane in radians. If this returned value is negative the lane is turning to the left and if it is positive, it is turning to the right. If this lane is not circular, the return value is not defined.

function LuaLane:getSpeedLimit()

This function returns the maximal speed limit allowed on this lane in meters per second (m/s).

function LuaLane:getName()

This function returns the name of that lane. If no names was specified for that lane, it returns an empty string.

function LuaLane:getIndex()

This function returns the index of that lane on its segment. 0 is the index of the left-most lane, 1 is the index of the lane to the right of the left-most lane, and so on.

function LuaLane:getEntryRate()

This function returns the entry rate specified for that lane in vehicles per hour (veh/h).

function LuaLane:setEntryRate(entryRate)

This function sets the entry rate of that lane in vehicles per hour (veh/h).

function LuaLane:getEntrySpeed()

This function returns the entry speed specified for that lane in kilometers per hour (km/h).

function LuaLane:setEntrySpeed(entrySpeed)

This function sets the entry speed of that lane in kilometers per hour (km/h). If we do not care about the entry speed of the vehicles we can set this to a negative value.

function LuaLane:getVehicleCount()

This function returns the number of vehicle present on that lane.

LuaRoadSensor

This object represents a sensor in the network. It provides 5 functions.

function LuaRoadSensor:getValue()

This function returns the current value computed by this sensor. If this sensor is set to measure flow, it returns a value in vehicles per hour (veh/h); if it is set the measure speed, it returns a value in kilometers per hour (km/h); if it is set to measure density, it returns a value in vehicles per kilometer (veh/km).

function LuaRoadSensor:isOccupied()

This function returns true if there is a car present on the sensor at that moment. It returns false otherwise.

function LuaRoadSensor:getVehicleCount()

If this sensor is a density sensor (getType() == DENSITY), this function returns the number of vehicles present in the detectable area. Otherwise this function returns nothing.

function LuaRoadSensor:getType()

This function returns either FLOW, SPEED or DENSITY depending on the kind of measure it computes.

function LuaRoadSensor:getName()

This function returns the name of that sensor. If no name was specified the empty string is returned.

function LuaRoadSensor:getLane()

This function returns a pointer to the Lane to which this sensor belongs.

LuaRoadActuator

This object represents an actuator in the network. It provides 8 functions.

function LuaRoadActuator:getColor()

If the current actuator is a traffic light (getType() == TRAFFICLIGHT), this function returns returns either GREEN or RED depending on the current light color of this actuator. A red color means that the cars should not pass. If this actuator is not a traffic light, this function does nothing.

function LuaRoadActuator:red()

If the current actuator is a traffic light (getType() == TRAFFICLIGHT), this function sets the color of the traffic light to be red. If this actuator is not a traffic light, this function does nothing.

function LuaRoadActuator:green()

If the current actuator is a traffic light (getType() == TRAFFICLIGHT), this function sets the color of the traffic light to be green. If this actuator is not a traffic light, this function does nothing.

function LuaRoadActuator:setSpeedLimit(speedLimit)

If the current actuator is a variable speed limit (getType() == SPEEDLIMIT), this function sets the speed limit in kilometers per hour (km/h). If this actuator is not a speed limit, this function does nothing.

function LuaRoadActuator:getType()

This function returns either TRAFFICLIGHT or SPEEDLIMIT depending on whether the current actuator is a traffic light or a variable speed sign.

function LuaRoadActuator:getName()

This function returns the name of this actuator. If no name was specified this function returns the empty string.

function LuaRoadActuator:getLane()

This function returns a pointer to the LuaLane on which this actuator is present.

function LuaRoadActuator:getPosition()

This function returns the position of this actuator on its lane in meters if the lane is straight on in radians if the lane is circular.

function LuaRoadActuator:getAverageQueueLength()

If the current actuator is a a traffic light (getType() == TRAFFICLIGHT), this function returns the average queue length up to the traffic light in seconds (one minute aggregates). If this actuator is not a traffic light, this function does nothing.

function LuaRoadActuator:getInstantQueueLength()

If the current actuator is a a traffic light (getType() == TRAFFICLIGHT), this function returns the latest queue length up to the traffic light in seconds (the queue duration experienced by the latest car that passed by). If this actuator is not a traffic light, this function does nothing.

function LuaRoadActuator:getVehicleCount()

If the current actuator is a a traffic light (getType() == TRAFFICLIGHT), this function returns the latest vehicle count (number of vehicles that passed through the light). If this actuator is not a traffic light, this function does nothing.

Additional values and global variables

LEAD        -- Index of the leading car
TRAIL       -- Trailing car
LEFT_LEAD   -- Leading car on the left lane
LEFT_TRAIL  -- Trailing car on the left lane
RIGHT_LEAD  -- Leading car on the right lane
RIGHT_TRAIL -- Trailing car on the right lane
REMOTE      -- RESERVED

These variables represent indices in the neighbors array given as an argument to the think function provided by the LUA script controlling the behaviors of the cars (neighbors[LEAD].car refers to the car leading the car being controlled, neighbors[RIGHT_TRAIL].distance is the longitudinal distance from the center of the rear axle of the controlled car to the center of the rear axle of the vehicle on the right lane directly behind the current car).

CAR   -- The vehicle is a car
TRUCK -- The vehicle is a truck

These variables represent the type of a vehicle as returned by the LuaCar:getType() function.

ENTRY -- This lane is an entry to the highway
EXIT  -- This lane is an exit
NONE  -- This is neither an entry nor an exit

These variables represent the type of a lane as returned by the LuaLane:getType() function.

STRAIGHT -- This lane is part of a straight segment
CIRCULAR -- This lane is part of a circular segment

These variables represent the geometry of a lane as returned by the LuaLane:getGeometry() function.

TRAFFICLIGHT -- This actuator is a traffic light
SPEEDLIMIT   -- This actuator is a variable speed limit sign

These variables represent the type of an actuator as returned by the LuaRoadActuator:getType() function.

DENSITY -- This sensor measures average densities
SPEED   -- This sensor measures average speeds
FLOW    -- This sensor measures average flows

These variables represent the type of a sensor as returned by the LuaRoadSensor:getType() function.

GREEN -- The light is green
RED   -- The light is red

These variables represent the current light color of a traffic light actuator as returned by the LuaRoadActuator:getColor() function.