Skip to content

Aimsun Next API Vehicle Tracking

Modify the Speed of a Tracked Vehicle

In C++ and Python

Explanation

Modify the speed of a tracked vehicle for the next simulation step, if it's lower than the speed calculated using the car-following model.

Format
int AKIVehTrackedModifySpeed (int aidVeh, double newSpeed);
Parameters
  • aidVeh: Tracked vehicle Identifier.
  • newSpeed: New Speed (Km/h or Mph depending the units defined in the network).
Output
  • = 0: No Error
  • < 0: Error

Force the Speed of a Tracked Vehicle

In C++ and Python

Explanation

Force the speed of a tracked vehicle for the next simulation step without considering restrictions of the car-following model.

Format
int AKIVehTrackedForceSpeed (int aidVeh, double newSpeed);
Parameters
  • aidVeh: Tracked vehicle Identifier.
  • newSpeed: New Speed (Km/h or Mph depending the units defined in the network).
Output
  • = 0: No Error
  • < 0: Error

Modify the Lane of a Tracked Vehicle

In C++ and Python

Explanation

Modify the target lane of a tracked vehicle until it has performed the lane change.

There are conditions that must be satisfied when using side lanes to merge into a section. If the tracked vehicle is in a side lane, and the new target lane is the adjacent lane of the road section, then the instruction from the AKIVehTrackedModifyLane function is subject to the presence of a virtual lane solid line set by the merge distance and the FIFO option for ramp merging. See the section on Ramp Merges for details.

Note that in the case where the instruction from the API function is over-ruled by the merge parameters, the API function would have returned 0 (No error) as it would have set the target lane successfully, before the application of the merge rules.

The modeler can either ensure that the API call is never overridden by setting the merge distance to be equal to the length of the merge lane and deselecting the FIFO option. This will however modify the behavior of all vehicles in the simulation and hence should be used with care.

Format
int AKIVehTrackedModifyLane (int aidVeh, int nextLane);
Parameters
  • aidVeh: Tracked vehicle identifier.
  • newLane: -1 next right lane or 1 next left lane. 0 do not change lane. -2 reset, gives back the control of the target lane to the default simulation model.
Output
  • = 0: No Error
  • < 0: Error

Modify the Next Section of a Tracked Vehicle

In C++ and Python

Explanation

Modify the next section of a tracked vehicle in order to force a turn, for the next simulation step.

Format
int AKIVehTrackedModifyNextSection (int aidVeh, int nextSection);
Parameters
  • aidVeh: Tracked vehicle identifier.
  • nextSection: Next section.
Output
  • = 0: No Error
  • < 0: Error

Modify the Next Sections of a Tracked Vehicle

In C++ only

Explanation

Modify the next sections of a tracked vehicle in order to force a subpath, for the next simulation step. The first section given should be a section immediately downstream of the vehicle’s current section. The list of sections does not reach the vehicle’s destination centroid. Once it leaves the last section of the given subpath, the vehicle will calculate a route from its location to its destination.

Format
int AKIVehTrackedModifyNextSections (int aidVeh, int sizeNextSections, const int *nextSections);
Parameters
  • aidVeh: Tracked vehicle identifier.
  • sizeNextSections: Number of sections in the subpath
  • nextSections: Array with the IDs of the next sections. As much sections as sizeNextSections must be provided
Output
  • = 0: No Error
  • < 0: Error

Usage example in C:

int * pathArray = (int *) calloc( pathSize, sizeof(int) );
for( int i = 0; i < pathSize; i++ ){
    pathArray[i] = sectionID[i];
}
int err = AKIVehTrackedModifyNextSections( vehId, pathSize, pathArray );
free( pathArray );

Modify the Entrance Lane in the Next Section of a Tracked Vehicle

In C++ and Python

Explanation

Sets the desired lane the tracked vehicle should choose when entering the next section. The desired lane should be connected to the current lane. If not, the vehicle will not consider the desired lane as its target lane.

Format
int AKIVehTrackedModifyNextTargetLaneInNextSection(int aidVeh, int nextSection, int nextlane);
Parameters
  • *aidVeh: Tracked vehicle identifier.
  • nextSection: Next section identifier.
  • nextlane: Lane position of the desired lane where 1 is the rightmost lane and N the leftmost lane where N is the number of lanes in next section.
Output
  • = 0: No Error

Remove a Tracked Vehicle

In C++ and Python

Explanation

Remove a tracked vehicle.

Format
int AKIVehTrackedRemove (int aidVeh);
int AKIVehTrackedDelete (int aidVeh);  //Old function, kept for compatibility
Parameters
  • aidVeh: Tracked vehicle identifier.
Output
  • = 0: No Error
  • < 0: Error

Set a Vehicle as Tracked / Not Tracked

In C++ and Python

Explanation

Set a vehicle as tracked/ Set a Vehicle as not tracked

Format
int AKIVehSetAsTracked (int aidVeh);
int AKIVehSetAsNoTracked (int aidVeh);
Parameters
  • aidVeh: Vehicle identifier.
Output
  • = 0: No Error
  • < 0: Error

Read the information of a Tracked Vehicle

In C++ and Python

Explanation

Read the information of a tracked vehicle

Format
InfVeh AKIVehTrackedGetInf(int aidVeh)
Parameters
  • aidVeh: Tracked vehicle identifier.
Output
struct InfVeh{
    int report;
    int idVeh;
    int type;
    // Information in Vehicle when it is in a section
    int idSection;
    int segment;
    int numberLane;

    // Information in Vehicle when it is in a node
    int idJunction;
    int idSectionFrom;
    int idLaneFrom;
    int idSectionTo;
    int idLaneTo;

    double CurrentPos; 
    double distance2End;
    double xCurrentPos, yCurrentPos, zCurrentPos;
    double xCurrentPosBack, yCurrentPosBack, zCurrentPosBack; 
    double CurrentSpeed, PreviousSpeed;
    double TotalDistance;
    double SystemGenerationT;
    double SystemEntranceT;
    double SectionEntranceT;
    double CurrentStopTime;
    bool stopped;
    uint mNbLostTurnings;
    double energyState;
};

where:

  • report: 0, OK, otherwise is an error code
  • idVeh: The vehicle identifier
  • type: The vehicle type (car, bus, truck, etc.).
  • idSection: The section identifier.
  • segment: Segment number of the section where the vehicle is located (from 0 to n-1)
  • numberLane: Lane number in the segment (from 1, the rightmost lane, to N, the leftmost lane).
  • idSectionFrom: Origin section identifier.
  • idLaneFrom: Origin section's lane where the vehicle enters the junction from. 1 being the rightmost lane and N the leftmost lane, being N the number of lanes in the origin section.
  • idSectionTo: Destination section identifier.
  • idLaneTo: Destination section's lane where the vehicle exits the junction to. 1 being the rightmost lane and N the leftmost lane, being N the number of lanes in the destination section.
  • CurrentPos: Position inside the section. The distance (meters or feet, depending on the units defined in the network) from the beginning of the section or position inside the junction given as the distance from the entrance to the junction.
  • distance2End: Distance to end of the section (meters or feet, depending on the units defined in the network) when the vehicle is located in a section or the distance to the end of the turn when the vehicle is in a junction.
  • xCurrentPos, yCurrentPos, zCurrentPos: World coordinates of the middle point of the front bumper of the vehicle.
  • xCurrentPosBack, yCurrentPosBack, zCurrentPosBack: World coordinates of the middle point of the rear bumper of the vehicle.
  • CurrentSpeed: Current speed (in km/h or mph, depending on the units defined in the network.
  • PreviousSpeed: Speed in the previous simulation step (in km/h or mph, depending on the units defined in the network.
  • TotalDistance: Total distance traveled (meters or feet).
  • SystemGenerationT: The absolute generation time of the vehicle into the system. If no virtual queue found in its entrance section it will be the same as the SystemEntranceT.
  • SystemEntranceT: The absolute entrance time of the vehicle into the system, that is into its entrance section. If no virtual queue found in its entrance section it will be the same as the SystemGenerationT.
  • SectionEntranceT: The absolute entrance time of the vehicle into the current section.
  • CurrentStopTime: The current stop time.
  • stopped: True if the vehicle remains stopped.
  • mNbLostTurnings The number of lost turnings.
  • energyState Current fuel tank level in combustion vehicles (l) or current battery State of Charge in electric vehicles (kW)

Read the Static Information of a Tracked Vehicle

In C++ and Python

Explanation

Read the static information of the tracked vehicle. Static information is the characteristics of the vehicle which were set when the vehicle entered the system.

Format
StaticInfVeh AKIVehTrackedGetStaticInf (int aidVeh)
Parameters
  • aidVeh: Tracked vehicle identifier.
Output:
struct StaticInfVeh{
    int report;
    int idVeh;
    int type;
    double length;
    double width;
    double maxDesiredSpeed;
    double maxAcceleration;
    double normalDeceleration;
    double maxDeceleration;
    double speedAcceptance;
    double minDistanceVeh;
    double giveWayTime;
    double guidanceAcceptance;
    int enrouted;
    int equipped;
    int tracked;
    bool  keepfastLane;
    double safetyMarginFactor;
    double headwayMin;
    double sensitivityFactor;
    double reactionTime;
    double reactionTimeAtStop;
    double reactionTimeAtTrafficLight;
    bool laneChangingCooperation;
    double laneChangingAggressivenessLevel;
    double distanceZoneFactor;
    int centroidOrigin;
    int centroidDest;
    int idsectionExit;
    int idLine;
    void * internalInfo;
    int engineTypeId;
    int vehicleSegmentId;
    int EUEmissionId;
    double energyCapacity;
};

where:

  • report: 0, OK, else error code
  • idVeh: Vehicle identifier
  • type: Vehicle type (car, bus, truck, etc.)
  • length: Vehicle length (m or feet, depending on the units defined in the network).
  • width: Vehicle width (m or feet, depending on the units defined in the network).
  • maxDesiredSpeed: Maximum desired speed of the vehicle (km/h or mph, depending on the units defined in the network).
  • maxAcceleration: Maximum acceleration of the vehicle (m/s2 or ft/ s2, depending on the units defined in the network).
  • normalDeceleration: Maximum deceleration of the vehicle that can apply under normal conditions (m/s2 or ft/ s2, depending the units defined in the network).
  • maxDeceleration: Maximum deceleration of the vehicle that can apply under special conditions (m/s2 or ft/ s2, depending the units defined in the network).
  • speedAcceptance: Degree of acceptance of the speed limits.
  • minDistanceVeh: Distance that the vehicle keeps between itself and the preceding vehicle (meters or feet, depending on the units defined in the network).
  • giveWayTime: Time after which the vehicle becomes more aggressive in yield situations (seconds).
  • guidanceAcceptance: Level of compliance of the vehicle to guidance indications.
  • enrouted: 0 means vehicle will not update path en route, 1 means vehicle will change path en route depending on the defined percentage of vehicles that update path en route.
  • equipped: 0 means vehicle not equipped, 1 means vehicle equipped.
  • tracked: 0 means vehicle not tracked, 1 means vehicle tracked.
  • keepfastLane: True means the vehicle keeps fast lane during overtaking
  • safetyMarginFactor: Safety margin factor
  • headwayMin: Minimum headway to the leader
  • sensitivityFactor: Estimation of the acceleration of the leader
  • reactionTime: Reaction time of the vehicle
  • reactionTimeAtStop: Reaction time at stop of the vehicle
  • reactionTimeAtTrafficLight: Reaction time of the vehicle when stopped the first one of the queue in a traffic light.
  • laneChangingCooperation:
  • laneChangingAggressivenessLevel:
  • distanceZoneFactor:
  • centroidOrigin: Identifier of centroid origin of the vehicle, when the traffic conditions are defined by an OD matrix.
  • centroidDest: : Identifier of centroid destination of the vehicle, when the traffic conditions are defined by an OD matrix.
  • idsectionExit: : Identifier of exit section destination of the vehicle, when the destination centroid uses percentages as destination (otherwise is –1) and the traffic conditions are defined by an OD matrix.
  • idLine: Identifier of Transit Line, when the vehicle has been generated as a transit vehicle.
  • internalInfo: For internal use
  • engineTypeId: Identifier of the engine type of the vehicle (emission, consumption, MFC acceleration models)
  • vehicleSegmentId: Identifier of the Euro Car Segment of the vehicle for the MFC acceleration model/Battery Consumption model: None = 0, A = 1, B = 2, C = 3, D = 4, E = 5, F = 6, J = 7, NM = 8.
  • EUEmissionId: Identifier Standard Emission for LEM. Null= 0, Zero = 1, Euro 0 = 2, Euro 1 = 3, Euro 2 = 4, Euro 3= 5, Euro 4 = 6, Euro 5 = 7, Euro 6 = 8, Euro 6c = 9 (Light Duty vehicles (car, taxi, van) ), Euro I = 10, Euro II = 11, Euro III = 12, Euro IV = 13, Euro IV EGR = 14, Euro V = 15, Euro V EGR = 16, Euro V SCR = 17, Euro VI = 18 (Heavy Duty vehicles (LGV, HGV, Bus, Coach) ).
  • energyCapacity: Total Capacity of the tank (l) or battery (kW)

Modify the Static Information of a Tracked Vehicle

In C++ and Python

Explanation

Modify some of the static parameters of a tracked vehicle. Static parameters are the characteristics of the vehicle that were set as the vehicle entered the system. The static parameters that it is possible to change are: type, length, width, maxDesiredSpeed, maxAcceleration, normalDeceleration, maxDeceleration, speedAcceptance, minDistanceVeh, giveWayTime, guidanceAcceptance, enrouted, equipped, tracked, keepfastLane, safetyMarginFactor, headwayMin, sensitivityFactor, reactionTime, reactionTimeAtStop, reactionTimeAtTrafficLight, centroidOrigin, centroidDest and idsectionExit (the exit section has sense when the destination centroid uses percentages as destination; if the identifier of the section is invalid or –1 then Aimsun Next will determine the exit section according to criteria defined in the centroid). Aimsun Next does not store the previous values, therefore it cannot recover them.

Format
int AKIVehTrackedSetStaticInf (int aidVeh, StaticInfVeh staticinfVeh)
Parameters
  • aidVeh: the tracked vehicle Identifier.
  • staticinfVeh: the new static parameters to be assigned.
Output:
  • = 0: No Error
  • < 0: Error

Read the Adaptive Cruise Control Information of a Tracked Vehicle

In C++ and Python

Explanation

Read the Adaptive Cruise Control information of the tracked vehicle. ACC Parameters establish the capabilities and influence the behavior of Adaptive Cruise Control of the vehicle. These parameters were set when the vehicle entered the system.

Format
StaticInfVehACCParams AKIVehTrackedGetStaticInfACCParams( int aidVeh )
Parameters
  • aidVeh: Tracked vehicle identifier.
Output:
struct StaticInfVehACCParams {
    int report;                     
    int idVeh;
    int accType;

    double minClearanceDistance;
    double maxClearanceDistance;
    double speedGainFreeFlow;
    double distanceGain;
    double speedGainPrec;
    double desiredTimeGap;

    double connectedDistanceGain;
    double connectedSpeedGain;
    double minTimeGapThreshold;
    double maxTimeGapThreshold;
    double followerTimeGap;
    double leaderTimeGap;
};

where:

Parameters common to all simulated vehicles:

  • report: Error code returned (0 means success).
  • idVeh: The simulated vehicle's ID.
  • accType: The simulated vehicle's ACC module (0: None, 1: ACC, 2: CACC).

ACC Model Parameters:

(All these parameters will be -1 when the module is disabled)

  • minClearanceDistance: The lower threshold for the space between the rear bumper of a vehicle and the front bumper of the following (m).
  • maxClearanceDistance: The upper threshold for the space between the rear bumper of a vehicle and the front bumper of the following (m).
  • speedGainFreeFlow: The gain on the speed difference between the free flow speed and the subject vehicle’s current speed (s-1).
  • distanceGain: The gain on the position difference between the preceding vehicle and the subject vehicle (s-2).
  • speedGainPrec: The gain on the speed difference between the preceding vehicle and the subject vehicle (s-1).
  • desiredTimeGap: The desired time gap of the ACC controller (s).

CACC Model Parameters:

(All these parameters will be -1 when the module is disabled)

  • connectedDistanceGain: The gain on the position difference between the preceding connected vehicle and the subject CACC vehicle (s-1).
  • connectedSpeedGain: The gain on the speed difference between the preceding connected vehicle and the subject CACC vehicle.
  • minTimeGapThreshold: The lower threshold for the time gap (s).
  • maxTimeGapThreshold: The upper threshold for the time gap (s).
  • followerTimeGap: The constant time gap between the last vehicle of the preceding connected string and the subject CACC vehicle (s).
  • leaderTimeGap: The constant time gap between the last vehicle of the preceding connected string and the subject CACC vehicle (s).

Modify the Adaptive Cruise Control Information of a Tracked Vehicle

In C++ and Python

Explanation

Modify the ACC parameters of a tracked vehicle. ACC Parameters establish the capabilities and influence the behavior of Adaptive Cruise Control of the vehicle. These parameters were set when the vehicle entered the system. All parameters can be changed except idVeh and report. Aimsun Next does not store the previous values, so it cannot recover them.

Format
int AKIVehTrackedSetStaticInfACCParams( int aidVeh, StaticInfVehACCParams staticinfVehACC )
Parameters
  • aidVeh: the tracked vehicle Identifier.
  • staticinfVehACC: the new ACC parameters to be assigned.
Output:
  • = 0: No Error
  • < 0: Error

Read the position(s) of a Tracked Vehicle

In C++ and Python

Explanation

Read the coordinates of the tracked vehicle during the last simulation step.

Format
InfVehPos AKIVehTrackedGetPos( int anIdVeh, int nbPos )
Parameters
  • aidVeh: Tracked vehicle identifier.
  • nbPos: Number of positions of the tracked vehicle. If this parameter is greater than 1 then the function gives the "between-simulating-step" positions for this vehicle. The last position always corresponds to the position at the end of the simulation step.
Output:
struct InfVehPos{
    int report;
    int idVeh;
    int Npos;
    VehPos *vehiclePos;
};

struct VehPos{
    double xPos, yPos, zPos;
    double xPosBack, yPosBack, zPosBack;
};

where:

  • report: 0, OK, otherwise an error code.
  • idVeh: The vehicle identifier.
  • Npos: Number of positions during last simulation step (input parameter).
  • vehiclePos: Array with the positions during last simulation step. After using this function, this array must be deallocated using “free” function.
  • xPos, yPos, zPos: World coordinates of the middle point of a vehicle front bumper for the current position.
  • xPosBack, yPosBack, zPosBack: World coordinates of the middle point of the vehicle rear bumper for the current position.
Usage in Python

The VehPos * structure is mapped as a VehPosArray. In order to access it correctly the VehPosArray needs to be built from the vehiclePos structure. See the following code as an example:

currentState = AKIVehTrackedGetPos(1, 4)
if currentState.report == 0:
    vehiclePos = VehPosArray.frompointer(currentState.vehiclePos)
    for i in range(currentState.Npos):
        print (time,vehiclePos[i].xPos, vehiclePos[i].yPos, vehiclePos[i].zPos)

Modify the position of a Tracked Vehicle

In C++ and Python

Explanation

Modify the position of the tracked vehicle during the last simulation step, considering the world coordinates on the middle point of the vehicle front and rear bumpers.

Format
int AKIVehSetVehicleTrackedDynInf( int anIdVeh, DynInfVeh dynInfVeh)
Parameters
  • aidVeh: Tracked vehicle Identifier.
  • dynInfVeh: The dynamic information during the last simulation step where:

    struct dynInfVeh{ double xCurrentPos, yCurrentPos; double xCurrentPosBack, yCurrentPosBack; double currentSpeed; int turning; }; - xCurrentPos, yCurrentPos: World coordinates of the middle point of the vehicle front bumper for the current position - xCurrentPosBack, yCurrentPosBack: World coordinates of the middle point of the vehicle rear bumper for the current position - currentSpeed: Current speed (km/h or mph, depending the units defined in the network). - turning: Next turn selected by the vehicle (-1 right turn, 1 left turn, 0 other cases)

Output:
  • = 0: No Error
  • < 0: Error

Read relative position to the leader of a Tracked Vehicle

In C++ and Python

Explanation

Read relative position to the leader

Format
LeaderInfVeh AKIVehTrackedGetLeaderVehInf(int aidVeh);
Parameters
  • aidVeh: Vehicle Identifier
Output
struct LeaderInfVeh{
    int report;
    int idVeh;
    int idLeaderVeh; 
    double headway;
    double gap;
    double spacing;
    double clearance;
};

where:

  • report: 0, OK, else error code
  • idVeh: vehicle identifier
  • idLeaderVeh: leader vehicle identifier, 0 if no leader.
  • headway: time between the front bumper of a vehicle and the front bumper of the following vehicle (s).
  • gap: time between the rear bumper of a vehicle and the front bumper of the following vehicle (s).
  • spacing: space between the front bumper of a vehicle and the front bumper of the following vehicle (m).
  • clearance: space between the rear bumper of a vehicle and the front bumper of the following (m).

Read the Graphical Information of a Tracked Vehicle

In C++ and Python

Explanation

Read the graphical information of the tracked vehicle during the last simulation step.

Format
GraphicInfVeh AKIVehTrackedGetGraphicInf ( int anIdVeh)
Parameters
  • aidVeh: Tracked vehicle Identifier.
Output:
struct GraphicInfVeh{
    int report;
    int idVeh;
    bool leftTurnSignal;
    bool rightTurnSignal;
    bool brakeLight;
}

Read Vehicle Category identifier

In C++ and Python

Explanation

Read the static vehicle category identifier: Used for classifying the vehicle category.

Format
int AKIVehTrackedGetVehicleCategoryId ( int anIdVeh )
Parameters
  • aidVeh: Tracked vehicle Identifier.
Output:

int vehicleCategory{ 0 = Car 1 = CommercialVehicle 2 = Bus 3 = Motorbike 4 = NonMotorized };

Read Vehicle emission type identifier for the London Emission Model (LEM).

In C++ and Python

Explanation

Read the static vehicle emission identifier: Used for classifying the emission vehicle type (subtype from vehicle category).

Format
int AKIVehTrackedGetLEMEmissionVehicleTypeId ( int anIdVeh )
Parameters
  • aidVeh: Tracked vehicle Identifier.
Output:

int SSLEMVehicleTypeID{ 0 = Car 1 = Taxi 2 = eLGV 3 = eHGV 4 = eSingleDeckerBus 5 = eDoubleDeckerBus 6 = eCoach };

Read the number of sections to reach destination

In C++ and Python

Explanation

Read the number of sections to reach destination of a tracked vehicle path. Valid for OD and transit vehicles, otherwise returns 0.

Format
int AKIVehTrackedGetNbSectionsVehiclePath( int idveh )
Parameters
  • idveh: The tracked vehicle Identifier.
Output:
  • ≥ 0: Number of sections to reach destination.
  • AKIVehNotTracked: Error

Read the Identifiers of the Sections used to reach the Destination

In C++ and Python

Explanation

Read the identifier of section elem-th of the tracked vehicle path to reach destination. Valid for OD and transit vehicles, otherwise returns 0. AKIVehTrackedGetNbSectionsVehiclePath must be called before call this function.

Format
int AKIVehTrackedGetIdSectionVehiclePath( int idveh, int indexsection )
Parameters
  • idveh: The tracked vehicle Identifier.
  • indexsection: Section index ( 0 ≤ indexsection < Number of sections )
Output:
  • > 0: Section Identifier.
  • AKIVehNotTracked: Error

Set Vehicle trajectory based on lanes

In C++ and Python

Explanation

Function to assign a trajectory based on specific lanes in sections.

Format
int AKIVehTrackedSetLanesTrajectory(int idVehicle, int nbSegmentsInTrajectory, int * sectIds, int * lanes, int idLastSection)
Parameters
  • idVehicle: Vehicle Identifier.
  • nbSegmentsInTrajectory: Number of different section id + lane id pairs that will be part of the trajectory based on lanes.
  • sectIds: vector of nbSegmentsInTrajectory of section identifiers.
  • lanes: vector of nbSegmentsInTrajectory of lane identifiers in the same position as the section they reference to. Lane ids go from 1...N being 1 the rightmost lane and N the leftmost one.
  • idLastSection: id of the last section identifierin the trajectory.
Output
  • 0: No error

Sample code in Python

sectIds = intArray( 3 )
sectIds[0] = 182
sectIds[1] = 183
sectIds[2] = 184
laneIds = intArray( 3 )
laneIds[0] = 1
laneIds[1] = 2
laneIds[2] = 1
AKIVehTrackedSetLanesTrajectory(idVehicle, 3, sectIds, laneIds, 184)