traci._vehicle

   1# -*- coding: utf-8 -*-
   2# Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
   3# Copyright (C) 2011-2026 German Aerospace Center (DLR) and others.
   4# This program and the accompanying materials are made available under the
   5# terms of the Eclipse Public License 2.0 which is available at
   6# https://www.eclipse.org/legal/epl-2.0/
   7# This Source Code may also be made available under the following Secondary
   8# Licenses when the conditions for such availability set forth in the Eclipse
   9# Public License 2.0 are satisfied: GNU General Public License, version 2
  10# or later which is available at
  11# https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html
  12# SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
  13
  14# @file    _vehicle.py
  15# @author  Michael Behrisch
  16# @author  Lena Kalleske
  17# @author  Mario Krumnow
  18# @author  Lena Kalleske
  19# @author  Jakob Erdmann
  20# @author  Laura Bieker
  21# @author  Daniel Krajzewicz
  22# @author  Leonhard Luecken
  23# @author  Mirko Barthauer
  24# @date    2011-03-09
  25
  26from __future__ import absolute_import
  27import warnings
  28from ._vehicletype import VTypeDomain
  29from . import constants as tc
  30from .exceptions import TraCIException, deprecated, alias_param
  31from ._lane import _readLinks
  32
  33
  34_legacyGetLeader = True
  35
  36
  37class StopData(object):
  38
  39    def __init__(self,
  40                 lane="",
  41                 startPos=-1,
  42                 endPos=-1,
  43                 stoppingPlaceID="",
  44                 stopFlags=0,
  45                 duration=-1,
  46                 until=-1,
  47                 intendedArrival=-1,
  48                 arrival=-1,
  49                 depart=-1,
  50                 split="",
  51                 join="",
  52                 actType="",
  53                 tripId="",
  54                 line="",
  55                 speed=0):
  56        self.lane = lane
  57        self.startPos = startPos
  58        self.endPos = endPos
  59        self.stoppingPlaceID = stoppingPlaceID
  60        self.stopFlags = stopFlags
  61        self.duration = duration
  62        self.until = until
  63        self.intendedArrival = intendedArrival
  64        self.arrival = arrival
  65        self.depart = depart
  66        self.split = split
  67        self.join = join
  68        self.actType = actType
  69        self.tripId = tripId
  70        self.line = line
  71        self.speed = speed
  72
  73    def __attr_repr__(self, attrname, default=""):
  74        if getattr(self, attrname) == default:
  75            return ""
  76        else:
  77            val = getattr(self, attrname)
  78            if val == tc.INVALID_DOUBLE_VALUE:
  79                val = "INVALID"
  80            return "%s=%s" % (attrname, val)
  81
  82    def __repr__(self):
  83        return "StopData(%s)" % ', '.join([v for v in [
  84            self.__attr_repr__("lane"),
  85            self.__attr_repr__("startPos"),
  86            self.__attr_repr__("endPos"),
  87            self.__attr_repr__("stoppingPlaceID"),
  88            self.__attr_repr__("stopFlags"),
  89            self.__attr_repr__("duration", tc.INVALID_DOUBLE_VALUE),
  90            self.__attr_repr__("until", tc.INVALID_DOUBLE_VALUE),
  91            self.__attr_repr__("intendedArrival", tc.INVALID_DOUBLE_VALUE),
  92            self.__attr_repr__("arrival", tc.INVALID_DOUBLE_VALUE),
  93            self.__attr_repr__("depart", tc.INVALID_DOUBLE_VALUE),
  94            self.__attr_repr__("split"),
  95            self.__attr_repr__("join"),
  96            self.__attr_repr__("actType"),
  97            self.__attr_repr__("tripId"),
  98            self.__attr_repr__("line"),
  99            self.__attr_repr__("speed", 0),
 100        ] if v != ""])
 101
 102
 103def _readStopData(result):
 104    result.read("!iB")  # numCompounds, TYPE_INT
 105    numStops = result.read("!i")[0]
 106    nextStops = []
 107    for _ in range(numStops):
 108        lane = result.readTypedString()
 109        endPos = result.readTypedDouble()
 110        stoppingPlaceID = result.readTypedString()
 111        stopFlags = result.readTypedInt()
 112        duration = result.readTypedDouble()
 113        until = result.readTypedDouble()
 114        startPos = result.readTypedDouble()
 115        intendedArrival = result.readTypedDouble()
 116        arrival = result.readTypedDouble()
 117        depart = result.readTypedDouble()
 118        split = result.readTypedString()
 119        join = result.readTypedString()
 120        actType = result.readTypedString()
 121        tripId = result.readTypedString()
 122        line = result.readTypedString()
 123        speed = result.readTypedDouble()
 124        nextStops.append(StopData(lane, startPos, endPos, stoppingPlaceID,
 125                                  stopFlags, duration, until, intendedArrival, arrival, depart, split, join,
 126                                  actType, tripId, line, speed))
 127    return tuple(nextStops)
 128
 129
 130def _readBestLanes(result):
 131    result.read("!iB")
 132    nbLanes = result.read("!i")[0]  # Length
 133    lanes = []
 134    for _ in range(nbLanes):
 135        laneID = result.readTypedString()
 136        length, occupation, offset = result.read("!BdBdBb")[1::2]
 137        allowsContinuation = bool(result.read("!BB")[1])
 138        numNextLanes = result.read("!Bi")[1]
 139        nextLanes = [result.readString() for __ in range(numNextLanes)]
 140        lanes.append((laneID, length, occupation, offset, allowsContinuation, tuple(nextLanes)))
 141    return tuple(lanes)
 142
 143
 144def _readLeader(result):
 145    assert result.read("!i")[0] == 2  # compound size
 146    vehicleID = result.readTypedString()
 147    dist = result.readTypedDouble()
 148    if vehicleID == "" and _legacyGetLeader:
 149        return None
 150    return vehicleID, dist
 151
 152
 153def _readFollower(result):
 154    # note: merge this with _readLeader once the default of _legacyGetLeader has
 155    # been changed to False
 156    assert result.read("!i")[0] == 2  # compound size
 157    vehicleID = result.readTypedString()
 158    dist = result.readTypedDouble()
 159    return vehicleID, dist
 160
 161
 162def _readNeighbors(result):
 163    """ result has structure:
 164    byte(TYPE_COMPOUND) | length(neighList) | Per list entry: string(vehID) | double(dist)
 165    """
 166    num = result.readInt()  # length of the vehicle list
 167    neighs = []
 168    for _ in range(num):
 169        vehID = result.readString()
 170        dist = result.readDouble()
 171        neighs.append((vehID, dist))
 172    return tuple(neighs)
 173
 174
 175def _readNextTLS(result):
 176    result.read("!iB")  # numCompounds, TYPE_INT
 177    numTLS = result.read("!i")[0]
 178    nextTLS = []
 179    for _ in range(numTLS):
 180        result.read("!B")
 181        tlsID = result.readString()
 182        tlsIndex, dist, state = result.read("!BiBdBB")[1::2]
 183        nextTLS.append((tlsID, tlsIndex, dist, chr(state)))
 184    return tuple(nextTLS)
 185
 186
 187def _readNextStops(result):
 188    result.read("!iB")  # numCompounds, TYPE_INT
 189    numStops = result.read("!i")[0]
 190    nextStop = []
 191    for _ in range(numStops):
 192        result.read("!B")
 193        lane = result.readString()
 194        result.read("!B")
 195        endPos = result.readDouble()
 196        result.read("!B")
 197        stoppingPlaceID = result.readString()
 198        result.read("!B")
 199        stopFlags = result.readInt()
 200        result.read("!B")
 201        duration = result.readDouble()
 202        result.read("!B")
 203        until = result.readDouble()
 204        nextStop.append((lane, endPos, stoppingPlaceID, stopFlags, duration, until))
 205    return tuple(nextStop)
 206
 207
 208def _readJunctionFoes(result):
 209    result.read("!Bi")
 210    nbJunctionFoes = result.readInt()
 211    junctionFoes = []
 212    for _ in range(nbJunctionFoes):
 213        result.read("!B")
 214        foeId = result.readString()
 215        result.read("!B")
 216        egoDist = result.readDouble()
 217        result.read("!B")
 218        foeDist = result.readDouble()
 219        result.read("!B")
 220        egoExitDist = result.readDouble()
 221        result.read("!B")
 222        foeExitDist = result.readDouble()
 223        result.read("!B")
 224        egoLane = result.readString()
 225        result.read("!B")
 226        foeLane = result.readString()
 227        result.read("!B")
 228        egoResponse = bool(result.read("!B")[0])
 229        result.read("!B")
 230        foeResponse = bool(result.read("!B")[0])
 231        junctionFoes.append((foeId, egoDist, foeDist, egoExitDist, foeExitDist,
 232                             egoLane, foeLane, egoResponse, foeResponse))
 233    return tuple(junctionFoes)
 234
 235
 236_RETURN_VALUE_FUNC = {tc.VAR_ROUTE_VALID: lambda result: bool(result.read("!i")[0]),
 237                      tc.VAR_BEST_LANES: _readBestLanes,
 238                      tc.VAR_LEADER: _readLeader,
 239                      tc.VAR_FOLLOWER: _readFollower,
 240                      tc.VAR_NEIGHBORS: _readNeighbors,
 241                      tc.VAR_NEXT_TLS: _readNextTLS,
 242                      tc.VAR_NEXT_STOPS: _readNextStops,
 243                      tc.VAR_NEXT_LINKS: _readLinks,
 244                      tc.VAR_NEXT_STOPS2: _readStopData,
 245                      tc.VAR_FOES: _readJunctionFoes,
 246                      # ignore num compounds and type int
 247                      tc.CMD_CHANGELANE: lambda result: result.read("!iBiBi")[2::2]}
 248
 249
 250class VehicleDomain(VTypeDomain):
 251    # imported for backwards compatibility
 252    STOP_DEFAULT = tc.STOP_DEFAULT
 253    STOP_PARKING = tc.STOP_PARKING
 254    STOP_TRIGGERED = tc.STOP_TRIGGERED
 255    STOP_CONTAINER_TRIGGERED = tc.STOP_CONTAINER_TRIGGERED
 256    STOP_BUS_STOP = tc.STOP_BUS_STOP
 257    STOP_CONTAINER_STOP = tc.STOP_CONTAINER_STOP
 258    STOP_CHARGING_STATION = tc.STOP_CHARGING_STATION
 259    STOP_PARKING_AREA = tc.STOP_PARKING_AREA
 260    DEPART_TRIGGERED = tc.DEPARTFLAG_TRIGGERED
 261    DEPART_CONTAINER_TRIGGERED = tc.DEPARTFLAG_CONTAINER_TRIGGERED
 262    DEPART_NOW = tc.DEPARTFLAG_NOW
 263    DEPART_SPEED_RANDOM = tc.DEPARTFLAG_SPEED_RANDOM
 264    DEPART_SPEED_MAX = tc.DEPARTFLAG_SPEED_MAX
 265    DEPART_LANE_RANDOM = tc.DEPARTFLAG_LANE_RANDOM
 266    DEPART_LANE_FREE = tc.DEPARTFLAG_LANE_FREE
 267    DEPART_LANE_ALLOWED_FREE = tc.DEPARTFLAG_LANE_ALLOWED_FREE
 268    DEPART_LANE_BEST_FREE = tc.DEPARTFLAG_LANE_BEST_FREE
 269    DEPART_LANE_FIRST_ALLOWED = tc.DEPARTFLAG_LANE_FIRST_ALLOWED
 270
 271    def __init__(self):
 272        VTypeDomain.__init__(self, "vehicle", tc.CMD_GET_VEHICLE_VARIABLE, tc.CMD_SET_VEHICLE_VARIABLE,
 273                             tc.CMD_SUBSCRIBE_VEHICLE_VARIABLE, tc.RESPONSE_SUBSCRIBE_VEHICLE_VARIABLE,
 274                             tc.CMD_SUBSCRIBE_VEHICLE_CONTEXT, tc.RESPONSE_SUBSCRIBE_VEHICLE_CONTEXT,
 275                             _RETURN_VALUE_FUNC, subscriptionDefault=(tc.VAR_ROAD_ID, tc.VAR_LANEPOSITION))
 276
 277    def getSpeed(self, vehID):
 278        """getSpeed(string) -> double
 279
 280        Returns the (longitudinal) speed in m/s of the named vehicle within the last step.
 281        """
 282        return self._getUniversal(tc.VAR_SPEED, vehID)
 283
 284    def getLateralSpeed(self, vehID):
 285        """getLateralSpeed(string) -> double
 286
 287        Returns the lateral speed in m/s of the named vehicle within the last step.
 288        """
 289        return self._getUniversal(tc.VAR_SPEED_LAT, vehID)
 290
 291    def getAcceleration(self, vehID):
 292        """getAcceleration(string) -> double
 293
 294        Returns the acceleration in m/s^2 of the named vehicle within the last step.
 295        """
 296        return self._getUniversal(tc.VAR_ACCELERATION, vehID)
 297
 298    def getSpeedWithoutTraCI(self, vehID):
 299        """getSpeedWithoutTraCI(string) -> double
 300        Returns the speed that the vehicle would drive if no speed-influencing
 301        command such as setSpeed or slowDown was given.
 302        """
 303        return self._getUniversal(tc.VAR_SPEED_WITHOUT_TRACI, vehID)
 304
 305    def getPosition(self, vehID):
 306        """getPosition(string) -> (double, double)
 307
 308        Returns the position of the named vehicle within the last step [m,m].
 309        """
 310        return self._getUniversal(tc.VAR_POSITION, vehID)
 311
 312    def getPosition3D(self, vehID):
 313        """getPosition3D(string) -> (double, double, double)
 314
 315        Returns the position of the named vehicle within the last step [m,m,m].
 316        """
 317        return self._getUniversal(tc.VAR_POSITION3D, vehID)
 318
 319    def getAngle(self, vehID):
 320        """getAngle(string) -> double
 321
 322        Returns the angle in degrees of the named vehicle within the last step.
 323        """
 324        return self._getUniversal(tc.VAR_ANGLE, vehID)
 325
 326    def getRoadID(self, vehID):
 327        """getRoadID(string) -> string
 328
 329        Returns the id of the edge the named vehicle was at within the last step.
 330        """
 331        return self._getUniversal(tc.VAR_ROAD_ID, vehID)
 332
 333    def getDeparture(self, vehID):
 334        """getDeparture(string) -> double
 335
 336        Returns the actual departure time in seconds
 337        """
 338        return self._getUniversal(tc.VAR_DEPARTURE, vehID)
 339
 340    def getDepartDelay(self, vehID):
 341        """getDepartDelay(string) -> double
 342
 343        Returns the delay between intended and actual departure in seconds
 344        """
 345        return self._getUniversal(tc.VAR_DEPART_DELAY, vehID)
 346
 347    def getLaneID(self, vehID):
 348        """getLaneID(string) -> string
 349
 350        Returns the id of the lane the named vehicle was at within the last step.
 351        """
 352        return self._getUniversal(tc.VAR_LANE_ID, vehID)
 353
 354    def getLaneIndex(self, vehID):
 355        """getLaneIndex(string) -> integer
 356
 357        Returns the index of the lane the named vehicle was at within the last step.
 358        """
 359        return self._getUniversal(tc.VAR_LANE_INDEX, vehID)
 360
 361    def getSegmentID(self, vehID):
 362        """getSegmentID(string) -> string
 363
 364        Returns the id of the segment the named vehicle was at within the last step (mesosim).
 365        """
 366        return self._getUniversal(tc.VAR_SEGMENT_ID, vehID)
 367
 368    def getSegmentIndex(self, vehID):
 369        """getSegmentIndex(string) -> integer
 370
 371        Returns the index of the segment the named vehicle was at within the last step (mesosim).
 372        """
 373        return self._getUniversal(tc.VAR_SEGMENT_INDEX, vehID)
 374
 375    def getTypeID(self, vehID):
 376        """getTypeID(string) -> string
 377
 378        Returns the id of the type of the named vehicle.
 379        """
 380        return self._getUniversal(tc.VAR_TYPE, vehID)
 381
 382    def getRouteID(self, vehID):
 383        """getRouteID(string) -> string
 384
 385        Returns the id of the route of the named vehicle.
 386        """
 387        return self._getUniversal(tc.VAR_ROUTE_ID, vehID)
 388
 389    def getRouteIndex(self, vehID):
 390        """getRouteIndex(string) -> int
 391
 392        Returns the index of the current edge within the vehicles route or -1 if the
 393        vehicle has not yet departed
 394        """
 395        return self._getUniversal(tc.VAR_ROUTE_INDEX, vehID)
 396
 397    def getRoute(self, vehID):
 398        """getRoute(string) -> tuple(string)
 399
 400        Returns the ids of the edges the vehicle's route is made of.
 401        """
 402        return self._getUniversal(tc.VAR_EDGES, vehID)
 403
 404    def getLanePosition(self, vehID):
 405        """getLanePosition(string) -> double
 406
 407        The position of the vehicle along the lane measured in m.
 408        """
 409        return self._getUniversal(tc.VAR_LANEPOSITION, vehID)
 410
 411    def getCO2Emission(self, vehID):
 412        """getCO2Emission(string) -> double
 413
 414        Returns the CO2 emission in mg/s for the last time step.
 415        Multiply by the step length to get the value for one step.
 416        """
 417        return self._getUniversal(tc.VAR_CO2EMISSION, vehID)
 418
 419    def getCOEmission(self, vehID):
 420        """getCOEmission(string) -> double
 421
 422        Returns the CO emission in mg/s for the last time step.
 423        Multiply by the step length to get the value for one step.
 424        """
 425        return self._getUniversal(tc.VAR_COEMISSION, vehID)
 426
 427    def getHCEmission(self, vehID):
 428        """getHCEmission(string) -> double
 429
 430        Returns the HC emission in mg/s for the last time step.
 431        Multiply by the step length to get the value for one step.
 432        """
 433        return self._getUniversal(tc.VAR_HCEMISSION, vehID)
 434
 435    def getPMxEmission(self, vehID):
 436        """getPMxEmission(string) -> double
 437
 438        Returns the particular matter emission in mg/s for the last time step.
 439        Multiply by the step length to get the value for one step.
 440        """
 441        return self._getUniversal(tc.VAR_PMXEMISSION, vehID)
 442
 443    def getNOxEmission(self, vehID):
 444        """getNOxEmission(string) -> double
 445
 446        Returns the NOx emission in mg/s for the last time step.
 447        Multiply by the step length to get the value for one step.
 448        """
 449        return self._getUniversal(tc.VAR_NOXEMISSION, vehID)
 450
 451    def getFuelConsumption(self, vehID):
 452        """getFuelConsumption(string) -> double
 453
 454        Returns the fuel consumption in mg/s for the last time step.
 455        Multiply by the step length to get the value for one step.
 456        """
 457        return self._getUniversal(tc.VAR_FUELCONSUMPTION, vehID)
 458
 459    def getNoiseEmission(self, vehID):
 460        """getNoiseEmission(string) -> double
 461
 462        Returns the noise emission in db for the last time step.
 463        """
 464        return self._getUniversal(tc.VAR_NOISEEMISSION, vehID)
 465
 466    def getElectricityConsumption(self, vehID):
 467        """getElectricityConsumption(string) -> double
 468
 469        Returns the electricity consumption in Wh/s for the last time step.
 470        Multiply by the step length to get the value for one step.
 471        """
 472        return self._getUniversal(tc.VAR_ELECTRICITYCONSUMPTION, vehID)
 473
 474    def getPersonNumber(self, vehID):
 475        """getPersonNumber(string) -> integer
 476        Returns the total number of persons which includes those defined
 477        using attribute 'personNumber' as well as <person>-objects who are riding in
 478        this vehicle.
 479        """
 480        return self._getUniversal(tc.VAR_PERSON_NUMBER, vehID)
 481
 482    def getPersonIDList(self, vehID):
 483        """getPersonIDList(string) -> tuple(string)
 484        Returns the tuple of persons who are riding in this vehicle.
 485        """
 486        return self._getUniversal(tc.LAST_STEP_PERSON_ID_LIST, vehID)
 487
 488    def getAdaptedTraveltime(self, vehID, time, edgeID):
 489        """getAdaptedTraveltime(string, double, string) -> double
 490
 491        Returns the information about the travel time of edge "edgeID" valid
 492        for the given time from the vehicle's internal edge weights
 493        container (see setAdaptedTraveltime).
 494        If there is no individual travel time set, INVALID_DOUBLE_VALUE is returned.
 495        """
 496        return self._getUniversal(tc.VAR_EDGE_TRAVELTIME, vehID, "tds", 2, time, edgeID)
 497
 498    def getEffort(self, vehID, time, edgeID):
 499        """getEffort(string, double, string) -> double
 500
 501        Returns the information about the effort needed for edge "edgeID" valid
 502        for the given time from the vehicle's internal effort
 503        container (see setEffort).
 504        If there is no individual travel time set, INVALID_DOUBLE_VALUE is returned.
 505        """
 506        return self._getUniversal(tc.VAR_EDGE_EFFORT, vehID, "tds", 2, time, edgeID)
 507
 508    def isRouteValid(self, vehID):
 509        """isRouteValid(string) -> bool
 510        Returns whether the current vehicle route is connected for the vehicle
 511        class of the given vehicle.
 512        """
 513        return self._getUniversal(tc.VAR_ROUTE_VALID, vehID)
 514
 515    def getSignals(self, vehID):
 516        """getSignals(string) -> integer
 517
 518        Returns an integer encoding the state of a vehicle's signals.
 519        """
 520        return self._getUniversal(tc.VAR_SIGNALS, vehID)
 521
 522    def getLateralLanePosition(self, vehID):
 523        """getLateralLanePosition(string) -> double
 524
 525        Returns the lateral position of the vehicle on its current lane measured in m.
 526        """
 527        return self._getUniversal(tc.VAR_LANEPOSITION_LAT, vehID)
 528
 529    def getAllowedSpeed(self, vehID):
 530        """getAllowedSpeed(string) -> double
 531
 532        Returns the maximum allowed speed on the current lane regarding speed factor in m/s for this vehicle.
 533        """
 534        return self._getUniversal(tc.VAR_ALLOWED_SPEED, vehID)
 535
 536    def getWaitingTime(self, vehID):
 537        """getWaitingTime(string) -> double
 538        The waiting time of a vehicle is defined as the time (in seconds) spent with a
 539        speed below 0.1m/s since the last time it was faster than 0.1m/s.
 540        (basically, the waiting time of a vehicle is reset to 0 every time it moves).
 541        A vehicle that is stopping intentionally with a <stop> does not accumulate waiting time.
 542        """
 543        return self._getUniversal(tc.VAR_WAITING_TIME, vehID)
 544
 545    def getAccumulatedWaitingTime(self, vehID):
 546        """getAccumulatedWaitingTime(string) -> double
 547        The accumulated waiting time of a vehicle collects the vehicle's waiting time
 548        over a certain time interval (interval length is set per option '--waiting-time-memory')
 549        """
 550        return self._getUniversal(tc.VAR_ACCUMULATED_WAITING_TIME, vehID)
 551
 552    def getLaneChangeMode(self, vehID):
 553        """getLaneChangeMode(string) -> integer
 554
 555        Gets the vehicle's lane change mode as a bitset.
 556        """
 557        return self._getUniversal(tc.VAR_LANECHANGE_MODE, vehID)
 558
 559    def getSpeedMode(self, vehID):
 560        """getSpeedMode(string) -> int
 561        The speed mode of a vehicle
 562        """
 563        return self._getUniversal(tc.VAR_SPEEDSETMODE, vehID)
 564
 565    def getSlope(self, vehID):
 566        """getSlope(string) -> double
 567        The slope at the current position of the vehicle in degrees
 568        """
 569        return self._getUniversal(tc.VAR_SLOPE, vehID)
 570
 571    def getLine(self, vehID):
 572        """getLine(string) -> string
 573
 574        Returns the line information of this vehicle.
 575        """
 576        return self._getUniversal(tc.VAR_LINE, vehID)
 577
 578    def getVia(self, vehID):
 579        """getVia(string) -> tuple(string)
 580
 581        Returns the ids of via edges for this vehicle
 582        """
 583        return self._getUniversal(tc.VAR_VIA, vehID)
 584
 585    def getLastActionTime(self, vehID):
 586        """getLastActionTime(string) -> double
 587
 588        Returns the time in s of last action point for this vehicle.
 589        """
 590        return self._getUniversal(tc.VAR_LASTACTIONTIME, vehID)
 591
 592    def getBestLanes(self, vehID):
 593        """getBestLanes(string) -> tuple(data)
 594        where data is a tuple of (laneID, length, occupation, offset, allowsContinuation, tuple(nextLanes))
 595
 596        For each lane of the current edge a data tuple is returned where the
 597        entries have the following meaning:
 598        - laneID: the id of that lane on the current edge
 599        - the length that can be driven without lane change (measured from the start of that lane)
 600        - the occupation on the future lanes (brutto vehicle lengths)
 601        - the offset of that lane from the lane that would be strategically
 602          preferred (this is the lane that requires the least future lane
 603          changes or a lane that needs to be used for stopping)
 604        - whether that lane allows continuing the route (for at least one more edge)
 605        - the sequence of lanes that would be driven starting at laneID if no
 606          lane change were to take place
 607        """
 608        return self._getUniversal(tc.VAR_BEST_LANES, vehID)
 609
 610    def getLeader(self, vehID, dist=100.):
 611        """getLeader(string, double) -> (string, double)
 612
 613        Return the leading vehicle id together with the distance. The distance
 614        is measured from the front + minGap to the back of the leader, so it does not include the
 615        minGap of the vehicle.
 616        The dist parameter defines the minimum lookahead, 0 calculates a lookahead from the brake gap.
 617        Note that the returned leader may be further away than the given dist and that the vehicle
 618        will only look on its current best lanes and not look beyond the end of its final route edge.
 619
 620        In the case where no leader is found, the function returns 'None'.
 621        This special case is deprecated. The future behavior is to return the
 622        pair ("", -1) when no leader is found.
 623        The function 'traci.setLegacyGetLeader(bool) can be used to switch
 624        between both behaviors.
 625        """
 626        return self._getUniversal(tc.VAR_LEADER, vehID, "d", dist)
 627
 628    def getFollower(self, vehID, dist=0.):
 629        """getFollower(string, double) -> (string, double)
 630
 631        Return the following vehicle id together with the distance. The distance
 632        is measured from the front + minGap of the follower to the back of vehID, so it does not include the
 633        minGap of the follower.
 634        The dist parameter defines the minimum lookback, 0 calculates the
 635        lookback distance from the braking distance at 4.5m/s^2 at 2*roadSpeedLimit.
 636        Due to junctions and lane merges, there may be multiple followers.
 637        In this case, the "critical" follower is returned. This is the follower
 638        where the value of (getSecureGap - gap) is maximal.
 639        Note that the returned follower may be further away than the given dist.
 640        """
 641        return self._getUniversal(tc.VAR_FOLLOWER, vehID, "d", dist)
 642
 643    def getRightFollowers(self, vehID, blockingOnly=False):
 644        """ getRightFollowers(string, bool) -> tuple(tuple(string, double))
 645        Convenience method, see getNeighbors()
 646        """
 647        if blockingOnly:
 648            mode = 5
 649        else:
 650            mode = 1
 651        return self.getNeighbors(vehID, mode)
 652
 653    def getRightLeaders(self, vehID, blockingOnly=False):
 654        """ getRightLeaders(string, bool) -> tuple(tuple(string, double))
 655        Convenience method, see getNeighbors()
 656        """
 657        if blockingOnly:
 658            mode = 7
 659        else:
 660            mode = 3
 661        return self.getNeighbors(vehID, mode)
 662
 663    def getLeftFollowers(self, vehID, blockingOnly=False):
 664        """ getLeftFollowers(string, bool) -> tuple(tuple(string, double))
 665        Convenience method, see getNeighbors()
 666        """
 667        if blockingOnly:
 668            mode = 4
 669        else:
 670            mode = 0
 671        return self.getNeighbors(vehID, mode)
 672
 673    def getLeftLeaders(self, vehID, blockingOnly=False):
 674        """ getLeftLeaders(string, bool) -> tuple(tuple(string, double))
 675        Convenience method, see getNeighbors()
 676        """
 677        if blockingOnly:
 678            mode = 6
 679        else:
 680            mode = 2
 681        return self.getNeighbors(vehID, mode)
 682
 683    def getNeighbors(self, vehID, mode):
 684        """ getNeighbors(string, byte) -> tuple(tuple(string, double))
 685
 686        The parameter mode is a bitset (UBYTE), specifying the following:
 687        bit 1: query lateral direction (left:0, right:1)
 688        bit 2: query longitudinal direction (followers:0, leaders:1)
 689        bit 3: blocking (return all:0, return only blockers:1)
 690
 691        The returned tuple contains pairs (ID, dist) for all lane change relevant neighboring leaders, resp. followers,
 692        along with their longitudinal distance to the ego vehicle (egoFront - egoMinGap to leaderBack, resp.
 693        followerFront - followerMinGap to egoBack. The value can be negative for overlapping neighs).
 694        For the non-sublane case, the lists will contain at most one entry.
 695
 696        Note: The exact set of blockers in case blocking==1 is not determined for the sublane model,
 697        but either all neighboring vehicles are returned (in case LCA_BLOCKED) or
 698        none is returned (in case !LCA_BLOCKED).
 699        """
 700        return self._getUniversal(tc.VAR_NEIGHBORS, vehID, "B", mode)
 701
 702    def getFollowSpeed(self, vehID, speed, gap, leaderSpeed, leaderMaxDecel, leaderID=""):
 703        """getFollowSpeed(string, double, double, double, double, string) -> double
 704        Return the follow speed computed by the carFollowModel of vehID
 705        """
 706        return self._getUniversal(tc.VAR_FOLLOW_SPEED, vehID, "tdddds", 5,
 707                                  speed, gap, leaderSpeed, leaderMaxDecel, leaderID)
 708
 709    def getSecureGap(self, vehID, speed, leaderSpeed, leaderMaxDecel, leaderID=""):
 710        """getSecureGap(string, double, double, double, string) -> double
 711        Return the secure gap computed by the carFollowModel of vehID
 712        """
 713        return self._getUniversal(tc.VAR_SECURE_GAP, vehID, "tddds", 4,
 714                                  speed, leaderSpeed, leaderMaxDecel, leaderID)
 715
 716    def getStopSpeed(self, vehID, speed, gap):
 717        """getStopSpeed(string, double, double) -> double
 718        Return the speed for stopping at gap computed by the carFollowModel of vehID
 719        """
 720        return self._getUniversal(tc.VAR_STOP_SPEED, vehID, "tdd", 2, speed, gap)
 721
 722    def getStopDelay(self, vehID):
 723        """getStopDelay(string) -> double
 724        Returns the expected depart delay at the next stop (if that stop defines the
 725        until-attribute) in seconds. Returns -1 if the next stop is not applicable
 726        """
 727        return self._getUniversal(tc.VAR_STOP_DELAY, vehID)
 728
 729    def getStopArrivalDelay(self, vehID):
 730        """getStopArrivalDelay(string) -> double
 731        Returns the expected arrival delay at the next stop (if that stop defines the
 732        arrival-attribute) in seconds. The returned value may be negative to
 733        indicate early arrival.  Returns INVALID_DOUBLE if the next stop is not applicable
 734        """
 735        return self._getUniversal(tc.VAR_STOP_ARRIVALDELAY, vehID)
 736
 737    def getTimeLoss(self, vehID):
 738        """getTimeLoss(string) -> double
 739        Returns the time loss since departure
 740        """
 741        return self._getUniversal(tc.VAR_TIMELOSS, vehID)
 742
 743    def getNextTLS(self, vehID):
 744        """getNextTLS(string) -> tuple(tuple(string, int, double, string))
 745
 746        Return tuple of upcoming traffic lights [(tlsID, tlsIndex, distance, state), ...]
 747        """
 748        return self._getUniversal(tc.VAR_NEXT_TLS, vehID)
 749
 750    @alias_param("dist", "distance")
 751    def getJunctionFoes(self, vehID, dist=0.):
 752        """getJunctionFoes(string, double) -> complex
 753
 754        Return tuple of junction foes [(foeId, egoDist, foeDist, egoExitDist, foeExitDist,
 755        egoLane, foeLane, egoResponse, foeResponse), ...] within the given distance to the given vehicle.
 756        """
 757        return self._getUniversal(tc.VAR_FOES, vehID, "d", dist)
 758
 759    @deprecated()
 760    def getNextStops(self, vehID):
 761        """getNextStops(string) -> tuple(tuple(string, double, string, int, double, double))
 762
 763        Return tuple of upcoming stops ((lane, endPos, stoppingPlaceID, stopFlags, duration, until), ...)
 764        where integer stopFlag is defined as:
 765               1 * stopped +
 766               2 * parking +
 767               4 * personTriggered +
 768               8 * containerTriggered +
 769              16 * isBusStop +
 770              32 * isContainerStop +
 771              64 * chargingStation +
 772             128 * parkingarea
 773        with each of these flags defined as 0 or 1.
 774        """
 775        return self._getUniversal(tc.VAR_NEXT_STOPS, vehID)
 776
 777    def getNextLinks(self, vehID):
 778        """getNextLinks(string) -> tuple(tuple(string, string, bool, bool, bool, string, string, double))
 779
 780        Return tuple of upcoming links along the route ((lane, via, priority, opened, foe,
 781         state, direction, length), ...)
 782        """
 783        return self._getUniversal(tc.VAR_NEXT_LINKS, vehID)
 784
 785    def getStops(self, vehID, limit=0):
 786        """getStops(string, int) -> tuple(StopData)
 787
 788        Return a tuple of StopData object. The flags are the same as for setStop and
 789        replaceStop (and different from getNextStops(!) for backward compatibility):
 790               1 * parking +
 791               2 * personTriggered +
 792               4 * containerTriggered +
 793               8 * isBusStop +
 794              16 * isContainerStop +
 795              32 * chargingStation +
 796              64 * parkingarea
 797        with each of these flags defined as 0 or 1.
 798
 799        The optional argument limit can be used to limit the returned stops to
 800        the next INT number (i.e. limit=1 if only the next stop is required).
 801        Setting a negative limit returns up to 'limit' previous stops (or fewer
 802        if the vehicle stopped fewer times previously)
 803        """
 804        return self._getUniversal(tc.VAR_NEXT_STOPS2, vehID, "i", limit)
 805
 806    def subscribeLeader(self, vehID, dist=0., begin=0, end=2**31 - 1):
 807        """subscribeLeader(string, double, double, double) -> None
 808
 809        Subscribe for the leading vehicle id together with the distance.
 810        The dist parameter defines the maximum lookahead, 0 calculates a lookahead from the brake gap.
 811        """
 812        self.subscribe(vehID, (tc.VAR_LEADER,), begin, end, {tc.VAR_LEADER: ("d", dist)})
 813
 814    def getDrivingDistance(self, vehID, edgeID, pos, laneIndex=0):
 815        """getDrivingDistance(string, string, double, integer) -> double
 816
 817        For an edge along the remaining route of vehID, return the distance from the current vehicle position
 818        to the given edge and position along the vehicles route.
 819        Otherwise, return INVALID_DOUBLE_VALUE
 820        """
 821        return self._getUniversal(tc.DISTANCE_REQUEST, vehID, "tru", 2,
 822                                  (edgeID, pos, laneIndex), tc.REQUEST_DRIVINGDIST)
 823
 824    def getDrivingDistance2D(self, vehID, x, y):
 825        """getDrivingDistance2D(string, double, double) -> integer
 826
 827        Return the distance to the given network position along the vehicles route.
 828        """
 829        return self._getUniversal(tc.DISTANCE_REQUEST, vehID, "tou", 2, (x, y), tc.REQUEST_DRIVINGDIST)
 830
 831    def getDistance(self, vehID):
 832        """getDistance(string) -> double
 833
 834        Returns the distance to the starting point like an odometer.
 835        """
 836        return self._getUniversal(tc.VAR_DISTANCE, vehID)
 837
 838    def getReferenceDistance(self, vehID):
 839        """getReferenceDistance(string) -> double
 840        Returns the distance along the linear reference system
 841        in which the current edge takes part (i.e. kilometrage/mile markers)
 842        """
 843        return self._getUniversal(tc.VAR_REFERENCE_DISTANCE, vehID)
 844
 845    def getStopParameter(self, vehID, nextStopIndex, param, customParam=False):
 846        """getStopParameter(string, int, string) -> string
 847        Gets the value of the given parameter for the stop at the given index
 848        Negative indices permit access to past stops.
 849        Supported params correspond to all legal stop xml-attributes
 850        If customParam is set to True, the user defined stop parameter with the
 851        specified param name will be returned instead (or "" if undefined)
 852        """
 853        return self._getUniversal(tc.VAR_STOP_PARAMETER, vehID, "tisb", 3, nextStopIndex, param, customParam)
 854
 855    def getStopState(self, vehID):
 856        """getStopState(string) -> integer
 857
 858        Returns information in regard to stopping:
 859        The returned integer is defined as 1 * stopped + 2 * parking
 860        + 4 * personTriggered + 8 * containerTriggered + 16 * isBusStop
 861        + 32 * isContainerStop
 862        with each of these flags defined as 0 or 1
 863        """
 864        return self._getUniversal(tc.VAR_STOPSTATE, vehID)
 865
 866    def isStopped(self, vehID):
 867        """isStopped(string) -> bool
 868        Return whether the vehicle is stopped
 869        """
 870        return (self.getStopState(vehID) & 1) == 1
 871
 872    def isStoppedParking(self, vehID):
 873        """isStoppedParking(string) -> bool
 874        Return whether the vehicle is parking (implies stopped)
 875        """
 876        return (self.getStopState(vehID) & 2) == 2
 877
 878    def isStoppedTriggered(self, vehID):
 879        """isStoppedTriggered(string) -> bool
 880        Return whether the vehicle is stopped and waiting for a person or container
 881        """
 882        return (self.getStopState(vehID) & 12) > 0
 883
 884    def isAtBusStop(self, vehID):
 885        """isAtBusStop(string) -> bool
 886        Return whether the vehicle is stopped at a bus stop
 887        """
 888        return (self.getStopState(vehID) & 16) == 16
 889
 890    def isAtContainerStop(self, vehID):
 891        """isAtContainerStop(string) -> bool
 892        Return whether the vehicle is stopped at a container stop
 893        """
 894        return (self.getStopState(vehID) & 32) == 32
 895
 896    def getLaneChangeState(self, vehID, direction):
 897        """getLaneChangeState(string, int) -> (int, int)
 898        Return the lane change state for the vehicle. The first value returns
 899        the state as computed by the lane change model and the second value
 900        returns the state after incorporation TraCI requests.
 901        See getLaneChangeStatePretty for an interpretation of the integer/bitset
 902        results
 903        """
 904        return self._getUniversal(tc.CMD_CHANGELANE, vehID, "i", direction)
 905
 906    def getLaneChangeStatePretty(self, vehID, direction):
 907        """getLaneChangeStatePretty(string, int) -> ([string, ...], [string, ...])
 908        Return the lane change state for the vehicle as two lists of string
 909        constants. The first tuple returns the state as computed by the lane change
 910        model and the second tuple returns the state after incorporation TraCI requests.
 911        """
 912        constants = {
 913            0: 'stay',
 914            1: 'left',
 915            2: 'right',
 916            3: 'strategic',
 917            4: 'cooperative',
 918            5: 'speedGain',
 919            6: 'keepRight',
 920            7: 'TraCI',
 921            8: 'urgent',
 922            9: 'blocked by left leader',
 923            10: 'blocked by left follower',
 924            11: 'blocked by right leader',
 925            12: 'blocked by right follower',
 926            13: 'overlapping',
 927            14: 'insufficient space',
 928            15: 'sublane',
 929        }
 930
 931        def prettifyBitstring(intval):
 932            return tuple([v for k, v in constants.items() if (intval & 2**k)])
 933
 934        state, stateTraCI = self.getLaneChangeState(vehID, direction)
 935        return prettifyBitstring(state), prettifyBitstring(stateTraCI)
 936
 937    def couldChangeLane(self, vehID, direction, state=None):
 938        """couldChangeLane(string, int) -> bool
 939        Return whether the vehicle could change lanes in the specified direction.
 940        This reflects the state after the last try to change lanes.
 941        If you want to execute changeLane as a result of the evaluation of this function
 942        it is not guaranteed to work because vehicle movements occur first.
 943        """
 944        if state is None:
 945            state, stateTraCI = self.getLaneChangeState(vehID, direction)
 946            if self.wantsAndCouldChangeLane(vehID, direction, stateTraCI):
 947                # vehicle changed in the last step. state is no longer applicable
 948                return False
 949        return state != tc.LCA_UNKNOWN and (state & tc.LCA_BLOCKED == 0)
 950
 951    def wantsAndCouldChangeLane(self, vehID, direction, state=None):
 952        """wantsAndCouldChangeLane(string, int) -> bool
 953        Return whether the vehicle wants to and could change lanes in the specified direction
 954        This reflects the state after the last try to change lanes.
 955        If you want to execute changeLane as a result of the evaluation of this function
 956        it is not guaranteed to work because vehicle movements occur first.
 957        """
 958        if state is None:
 959            state, stateTraCI = self.getLaneChangeState(vehID, direction)
 960            if self.wantsAndCouldChangeLane(vehID, direction, stateTraCI):
 961                # vehicle changed in the last step. state is no longer applicable
 962                return False
 963        if state & tc.LCA_BLOCKED == 0:
 964            if direction == -1:
 965                return state & tc.LCA_RIGHT != 0
 966            if direction == 1:
 967                return state & tc.LCA_LEFT != 0
 968        return False
 969
 970    def getRoutingMode(self, vehID):
 971        """getRoutingMode(string)
 972        returns the current routing mode:
 973        tc.ROUTING_MODE_DEFAULT    : use weight storages and fall-back to edge speeds (default)
 974        tc.ROUTING_MODE_AGGREGATED : use global smoothed travel times from device.rerouting
 975        """
 976        return self._getUniversal(tc.VAR_ROUTING_MODE, vehID)
 977
 978    @alias_param("taxiState", "flag")
 979    def getTaxiFleet(self, taxiState=0):
 980        """getTaxiFleet(int) -> tuple(string)
 981        Return the tuple of all taxis with the given taxiState:
 982        0 : empty
 983        1 : pickup
 984        2 : occupied
 985        """
 986        return self._getUniversal(tc.VAR_TAXI_FLEET, "", "i", taxiState)
 987
 988    def getLoadedIDList(self):
 989        """getLoadedIDList() -> tuple(string)
 990        returns all loaded vehicles that have not yet left the simulation
 991        """
 992        return self._getUniversal(tc.VAR_LOADED_LIST, "")
 993
 994    def getTeleportingIDList(self):
 995        """getTeleportingIDList() -> tuple(string)
 996        returns all teleporting or jumping vehicles
 997        """
 998        return self._getUniversal(tc.VAR_TELEPORTING_LIST, "")
 999
1000    def rerouteParkingArea(self, vehID, parkingAreaID):
1001        """rerouteParkingArea(string, string)
1002
1003        Changes the next parking area in parkingAreaID, updates the vehicle route,
1004        and preserve consistency in case of passengers/containers on board.
1005        """
1006        self._setCmd(tc.CMD_REROUTE_TO_PARKING, vehID, "ts", 1, parkingAreaID)
1007
1008    def setStop(self, vehID, edgeID, pos=1., laneIndex=0, duration=tc.INVALID_DOUBLE_VALUE,
1009                flags=tc.STOP_DEFAULT, startPos=tc.INVALID_DOUBLE_VALUE, until=tc.INVALID_DOUBLE_VALUE):
1010        """setStop(string, string, double, integer, double, integer, double, double) -> None
1011
1012        Adds or modifies a stop with the given parameters. The duration and the until attribute are
1013        in seconds.
1014        """
1015        if type(duration) is int and duration >= 1000 and duration % 1000 == 0:
1016            warnings.warn("API change now handles duration as floating point seconds", stacklevel=2)
1017        self._setCmd(tc.CMD_STOP, vehID, "tsdbdbdd", 7, edgeID, pos, laneIndex, duration, flags, startPos, until)
1018
1019    def setBusStop(self, vehID, stopID, duration=tc.INVALID_DOUBLE_VALUE,
1020                   until=tc.INVALID_DOUBLE_VALUE, flags=tc.STOP_DEFAULT):
1021        """setBusStop(string, string, double, double, integer) -> None
1022
1023        Adds or modifies a bus stop with the given parameters. The duration and the until attribute are
1024        in seconds.
1025        """
1026        self.setStop(vehID, stopID, duration=duration, until=until, flags=flags | tc.STOP_BUS_STOP)
1027
1028    def setContainerStop(self, vehID, stopID, duration=tc.INVALID_DOUBLE_VALUE,
1029                         until=tc.INVALID_DOUBLE_VALUE, flags=tc.STOP_DEFAULT):
1030        """setContainerStop(string, string, double, double, integer) -> None
1031
1032        Adds or modifies a container stop with the given parameters. The duration and the until attribute are
1033        in seconds.
1034        """
1035        self.setStop(vehID, stopID, duration=duration, until=until, flags=flags | tc.STOP_CONTAINER_STOP)
1036
1037    def setChargingStationStop(self, vehID, stopID, duration=tc.INVALID_DOUBLE_VALUE,
1038                               until=tc.INVALID_DOUBLE_VALUE, flags=tc.STOP_DEFAULT):
1039        """setChargingStationStop(string, string, double, double, integer) -> None
1040
1041        Adds or modifies a stop at a chargingStation with the given parameters. The duration and the until attribute are
1042        in seconds.
1043        """
1044        self.setStop(vehID, stopID, duration=duration, until=until, flags=flags | tc.STOP_CHARGING_STATION)
1045
1046    def setParkingAreaStop(self, vehID, stopID, duration=tc.INVALID_DOUBLE_VALUE,
1047                           until=tc.INVALID_DOUBLE_VALUE, flags=tc.STOP_PARKING):
1048        """setParkingAreaStop(string, string, double, double, integer) -> None
1049
1050        Adds or modifies a stop at a parkingArea with the given parameters. The duration and the until attribute are
1051        in seconds.
1052        """
1053        self.setStop(vehID, stopID, duration=duration, until=until, flags=flags | tc.STOP_PARKING_AREA)
1054
1055    def replaceStop(self, vehID, nextStopIndex, edgeID, pos=1., laneIndex=0, duration=tc.INVALID_DOUBLE_VALUE,
1056                    flags=tc.STOP_DEFAULT, startPos=tc.INVALID_DOUBLE_VALUE,
1057                    until=tc.INVALID_DOUBLE_VALUE, teleport=0):
1058        """replaceStop(string, int, string, double, integer, double, integer, double, double) -> None
1059
1060        Replaces stop at the given index (within the list of all stops) with a new stop.
1061        Automatically modifies the route if the replacement stop is at another location.
1062        For edgeID a stopping place id may be given if the flag marks this
1063        stop as stopping on busStop, parkingArea, containerStop etc.
1064        If edgeID is "", the stop at the given index will be removed without
1065        replacement and the route will not be modified (unless setting
1066        teleport=2 which will trigger rerouting between the prior and next stop)
1067        If teleport is set to 1, the route to the replacement stop will be
1068        disconnected (forcing a teleport).
1069        If stopIndex is 0 the gap will be between the current
1070        edge and the new stop. Otherwise the gap will be between the stop edge for
1071        nextStopIndex - 1 and the new stop.
1072        """
1073        self._setCmd(tc.CMD_REPLACE_STOP, vehID, "tsdbdiddib", 9, edgeID, pos,
1074                     laneIndex, duration, flags, startPos, until, nextStopIndex, teleport)
1075
1076    def insertStop(self, vehID, nextStopIndex, edgeID, pos=1., laneIndex=0, duration=tc.INVALID_DOUBLE_VALUE,
1077                   flags=tc.STOP_DEFAULT, startPos=tc.INVALID_DOUBLE_VALUE,
1078                   until=tc.INVALID_DOUBLE_VALUE, teleport=0):
1079        """insertStop(string, int, string, double, integer, double, integer, double, double) -> None
1080
1081        Insert stop at the given index (within the list of all existing stops).
1082        Automatically modifies the route if the new stop is not along the route between the preceeding
1083        and succeeding stops (or start / end).
1084        For edgeID a stopping place id may be given if the flag marks this
1085        stop as stopping on busStop, parkingArea, containerStop etc.
1086        If teleport is set to 1, the route to the new stop will be
1087        disconnected (forcing a teleport).
1088        If stopIndex is 0 the gap will be between the current
1089        edge and the new stop. Otherwise the gap will be between the stop edge for
1090        nextStopIndex - 1 and the new stop.
1091        """
1092        self._setCmd(tc.CMD_INSERT_STOP, vehID, "tsdbdiddib", 9, edgeID, pos,
1093                     laneIndex, duration, flags, startPos, until, nextStopIndex, teleport)
1094
1095    def setStopParameter(self, vehID, nextStopIndex, param, value, customParam=False):
1096        """setStopParameter(string, int, string, string) -> None
1097        Sets the value of the given parameter for the (upcoming) stop at the
1098        given index (within the list of all stops).
1099        Supported params correspond to (almost) all legal stop xml-attributes
1100        and their value semantics
1101        If customParam is set to True, the user defined stop parameter with the
1102        specified param name will be set instead
1103        """
1104        self._setCmd(tc.VAR_STOP_PARAMETER, vehID, "tissb", 4, nextStopIndex, param, value, customParam)
1105
1106    def resume(self, vehID):
1107        """resume(string) -> None
1108
1109        Resumes the vehicle from the current stop (throws an error if the vehicle is not stopped).
1110        """
1111        self._setCmd(tc.CMD_RESUME, vehID, "t", 0)
1112
1113    def changeLane(self, vehID, laneIndex, duration):
1114        """changeLane(string, int, double) -> None
1115        Forces a lane change to the lane with the given index; The lane change
1116        will be attempted for the given duration (in s) and if it succeeds,
1117        the vehicle will stay on that lane for the remaining duration.
1118        """
1119        if type(duration) is int and duration >= 1000:
1120            warnings.warn("API change now handles duration as floating point seconds", stacklevel=2)
1121        self._setCmd(tc.CMD_CHANGELANE, vehID, "tbd", 2, laneIndex, duration)
1122
1123    def changeLaneRelative(self, vehID, indexOffset, duration):
1124        """changeLaneRelative(string, int, double) -> None
1125
1126        Forces a relative lane change; if successful,
1127        the lane will be chosen for the given amount of time (in s).
1128        The indexOffset specifies the target lane relative to the vehicles current lane
1129        """
1130        if type(duration) is int and duration >= 1000:
1131            warnings.warn("API change now handles duration as floating point seconds", stacklevel=2)
1132        self._setCmd(tc.CMD_CHANGELANE, vehID, "tbdb", 3, indexOffset, duration, 1)
1133
1134    def changeSublane(self, vehID, latDist):
1135        """changeSublane(string, double) -> None
1136        Forces a lateral change by the given amount (negative values indicate changing to the right, positive
1137        to the left). This will override any other lane change motivations but conform to
1138        safety-constraints as configured by laneChangeMode.
1139        """
1140        self._setCmd(tc.CMD_CHANGESUBLANE, vehID, "d", latDist)
1141
1142    def slowDown(self, vehID, speed, duration):
1143        """slowDown(string, double, double) -> None
1144
1145        Changes the speed smoothly to the given value over the given amount
1146        of time in seconds (can also be used to increase speed).
1147        """
1148        if type(duration) is int and duration >= 1000:
1149            warnings.warn("API change now handles duration as floating point seconds", stacklevel=2)
1150        self._setCmd(tc.CMD_SLOWDOWN, vehID, "tdd", 2, speed, duration)
1151
1152    def openGap(self, vehID, newTimeHeadway, newSpaceHeadway, duration, changeRate, maxDecel=-1, referenceVehID=None):
1153        """openGap(string, double, double, double, double, double, string) -> None
1154
1155        Changes the vehicle's desired time headway (cf-parameter tau) smoothly to the given new value
1156        using the given change rate. Similarly, the given space headway is applied gradually
1157        to achieve a minimal spatial gap.
1158        The vehicle is commanded to keep the increased headway for
1159        the given duration once its target value is attained. The maximal value for the
1160        deceleration can be given to prevent harsh braking due to the change of tau. If maxDecel=-1,
1161        the limit determined by the CF model is used.
1162        A vehicle ID for a reference vehicle can optionally be given, otherwise, the gap is created with
1163        respect to the current leader on the ego vehicle's current lane.
1164        Note that this does only affect the following behavior regarding the current leader and does
1165        not influence the gap acceptance during lane change, etc.
1166        """
1167        if type(duration) is int and duration >= 1000:
1168            warnings.warn("API change now handles duration as floating point seconds", stacklevel=2)
1169        if referenceVehID is None:
1170            self._setCmd(tc.CMD_OPENGAP, vehID, "tddddd", 5,
1171                         newTimeHeadway, newSpaceHeadway, duration, changeRate, maxDecel)
1172        else:
1173            self._setCmd(tc.CMD_OPENGAP, vehID, "tddddds", 6,
1174                         newTimeHeadway, newSpaceHeadway, duration, changeRate, maxDecel, referenceVehID)
1175
1176    def deactivateGapControl(self, vehID):
1177        """deactivateGapControl(string) -> None
1178
1179        Deactivate the vehicle's gap control
1180        """
1181        self.openGap(vehID, -1, -1, -1, -1)
1182
1183    def requestToC(self, vehID, leadTime):
1184        """ requestToC(string, double) -> None
1185
1186        Interface for triggering a transition of control for a vehicle equipped with a ToC device.
1187        """
1188        self.setParameter(vehID, "device.toc.requestToC", str(leadTime))
1189
1190    def changeTarget(self, vehID, edgeID):
1191        """changeTarget(string, string) -> None
1192
1193        The vehicle's destination edge is set to the given edge id. The route is rebuilt.
1194        """
1195        self._setCmd(tc.CMD_CHANGETARGET, vehID, "s", edgeID)
1196
1197    def setType(self, vehID, typeID):
1198        """setType(string, string) -> None
1199
1200        Sets the id of the type for the named vehicle.
1201        """
1202        self._setCmd(tc.VAR_TYPE, vehID, "s", typeID)
1203
1204    def setRouteID(self, vehID, routeID):
1205        """setRouteID(string, string) -> None
1206
1207        Changes the vehicles route to the route with the given id.
1208        """
1209        self._setCmd(tc.VAR_ROUTE_ID, vehID, "s", routeID)
1210
1211    def setRoute(self, vehID, edgeList):
1212        """
1213        setRoute(string, list) ->  None
1214
1215        changes the vehicle route to given edges list.
1216        The first edge in the list has to be the one that the vehicle is at the moment.
1217
1218        example usage:
1219        setRoute('1', ['1', '2', '4', '6', '7'])
1220
1221        this changes route for vehicle id 1 to edges 1-2-4-6-7
1222        """
1223        if isinstance(edgeList, str):
1224            edgeList = [edgeList]
1225        self._setCmd(tc.VAR_ROUTE, vehID, "l", edgeList)
1226
1227    def setLateralLanePosition(self, vehID, posLat):
1228        """setLateralLanePosition(string, double) -> None
1229
1230        Sets the lateral vehicle position relative to the center line of the
1231        lane in m (negative values are to the right in right-hand networks).
1232        The vehicle may adapt this position in the same step unless this is
1233        disabled via setLaneChangeMode.
1234        """
1235        self._setCmd(tc.VAR_LANEPOSITION_LAT, vehID, "d", posLat)
1236
1237    def updateBestLanes(self, vehID):
1238        """ updateBestLanes(string) -> None
1239        Triggers an update of the vehicle's bestLanes (structure determining the lane preferences used by LC models)
1240        It may be called after modifying the vClass for instance.
1241        """
1242        self._setCmd(tc.VAR_UPDATE_BESTLANES, vehID)
1243
1244    def setAdaptedTraveltime(self, vehID, edgeID, time=None, begTime=None, endTime=None):
1245        """setAdaptedTraveltime(string, string, double, double, double) -> None
1246        Inserts the information about the travel time of edge "edgeID" valid
1247        from begin time to end time into the vehicle's internal edge weights
1248        container.
1249        If the time is not specified, any previously set values for that edge
1250        are removed.
1251        If begTime or endTime are not specified the value is set for the whole
1252        simulation duration.
1253        """
1254        if not isinstance(edgeID, str) and isinstance(begTime, str):
1255            # legacy handling
1256            warnings.warn(
1257                "Parameter order has changed for setAdaptedTraveltime(). Attempting legacy ordering. " +
1258                "Please update your code.", stacklevel=2)
1259            return self.setAdaptedTraveltime(vehID, begTime, endTime, edgeID, time)
1260        if time is None:
1261            # reset
1262            self._setCmd(tc.VAR_EDGE_TRAVELTIME, vehID, "ts", 1, edgeID)
1263        elif begTime is None:
1264            # set value for the whole simulation
1265            self._setCmd(tc.VAR_EDGE_TRAVELTIME, vehID, "tsd", 2, edgeID, time)
1266        else:
1267            self._setCmd(tc.VAR_EDGE_TRAVELTIME, vehID, "tddsd", 4, begTime, endTime, edgeID, time)
1268
1269    def setEffort(self, vehID, edgeID, effort=None, begTime=None, endTime=None):
1270        """setEffort(string, string, double, double, double) -> None
1271        Inserts the information about the effort of edge "edgeID" valid from
1272        begin time to end time into the vehicle's internal edge weights
1273        container.
1274        If the time is not specified, any previously set values for that edge
1275        are removed.
1276        If begTime or endTime are not specified the value is set for the whole
1277        simulation duration.
1278        """
1279        if not isinstance(edgeID, str) and isinstance(begTime, str):
1280            # legacy handling
1281            warnings.warn(
1282                "Parameter order has changed for setEffort(). Attempting legacy ordering. Please update your code.",
1283                stacklevel=2)
1284            return self.setEffort(vehID, begTime, endTime, edgeID, effort)
1285        if effort is None:
1286            # reset
1287            self._setCmd(tc.VAR_EDGE_EFFORT, vehID, "ts", 1, edgeID)
1288        elif begTime is None:
1289            # set value for the whole simulation
1290            self._setCmd(tc.VAR_EDGE_EFFORT, vehID, "tsd", 2, edgeID, effort)
1291        else:
1292            self._setCmd(tc.VAR_EDGE_EFFORT, vehID, "tddsd", 4, begTime, endTime, edgeID, effort)
1293
1294    LAST_TRAVEL_TIME_UPDATE = -1
1295
1296    def setRoutingMode(self, vehID, routingMode):
1297        """setRoutingMode(string, int) -> None
1298        Sets the current routing mode:
1299        tc.ROUTING_MODE_DEFAULT    : use weight storages and fall-back to edge speeds (default)
1300        tc.ROUTING_MODE_AGGREGATED : use global smoothed travel times from device.rerouting
1301        tc.ROUTING_MODE_AGGREGATED_CUSTOM : use weight storages and fall-back to smoothed travel times
1302        """
1303        self._setCmd(tc.VAR_ROUTING_MODE, vehID, "i", routingMode)
1304
1305    def rerouteTraveltime(self, vehID, currentTravelTimes=True):
1306        """rerouteTraveltime(string, bool) -> None
1307        Reroutes a vehicle.
1308        If currentTravelTimes is True (default) and the routing mode is still ROUTING_MODE_DEFAULT
1309        then the ROUTING_MODE_AGGREGATED_CUSTOM gets activated temporarily
1310        and used for rerouting. The various functions and options for
1311        customizing travel times are described at https://sumo.dlr.de/wiki/Simulation/Routing
1312
1313        When rerouteTraveltime has been called once with an aggregated routing mode,
1314        edge weight storage and update gets activated which might slow down the simulation.
1315        """
1316        if currentTravelTimes:
1317            routingMode = self.getRoutingMode(vehID)
1318            if routingMode == tc.ROUTING_MODE_DEFAULT:
1319                self.setRoutingMode(vehID, tc.ROUTING_MODE_AGGREGATED_CUSTOM)
1320        self._setCmd(tc.CMD_REROUTE_TRAVELTIME, vehID, "t", 0)
1321        if currentTravelTimes and routingMode == tc.ROUTING_MODE_DEFAULT:
1322            self.setRoutingMode(vehID, routingMode)
1323
1324    def rerouteEffort(self, vehID):
1325        """rerouteEffort(string) -> None
1326        Reroutes a vehicle according to the effort values.
1327        """
1328        self._setCmd(tc.CMD_REROUTE_EFFORT, vehID, "t", 0)
1329
1330    def setSignals(self, vehID, signals):
1331        """setSignals(string, integer) -> None
1332
1333        Sets an integer encoding the state of the vehicle's signals.
1334        """
1335        self._setCmd(tc.VAR_SIGNALS, vehID, "i", signals)
1336
1337    def moveTo(self, vehID, laneID, pos, reason=tc.MOVE_AUTOMATIC):
1338        """moveTo(string, string, double, integer) -> None
1339
1340        Move a vehicle to a new position along its current route.
1341        """
1342        self._setCmd(tc.VAR_MOVE_TO, vehID, "tsdi", 3, laneID, pos, reason)
1343
1344    def setSpeed(self, vehID, speed):
1345        """setSpeed(string, double) -> None
1346
1347        Sets the speed in m/s for the named vehicle within the last step.
1348        Calling with speed=-1 hands the vehicle control back to SUMO.
1349        """
1350        self._setCmd(tc.VAR_SPEED, vehID, "d", speed)
1351
1352    def setAcceleration(self, vehID, acceleration, duration):
1353        """setAcceleration(string, double, double) -> None
1354
1355        Sets the acceleration in m/s^2 for the named vehicle and the given duration.
1356        """
1357        self._setCmd(tc.VAR_ACCELERATION, vehID, "tdd", 2, acceleration, duration)
1358
1359    def setPreviousSpeed(self, vehID, speed, acceleration=tc.INVALID_DOUBLE_VALUE):
1360        """setPreviousSpeed(string, double, double) -> None
1361
1362        Sets the previous speed in m/s for the named vehicle wich will be used for
1363        calculations in the current step. Optionally, the acceleration for the
1364        previous step (in m/s^2) can be set as well.
1365        """
1366        self._setCmd(tc.VAR_PREV_SPEED, vehID, "tdd", 2, speed, acceleration)
1367
1368    def setLine(self, vehID, line):
1369        """setLine(string, string) -> None
1370
1371        Sets the line information for this vehicle.
1372        """
1373        self._setCmd(tc.VAR_LINE, vehID, "s", line)
1374
1375    def setVia(self, vehID, edgeList):
1376        """
1377        setVia(string, list) ->  None
1378
1379        changes the via edges to the given edges list (to be used during
1380        subsequent rerouting calls).
1381
1382        Note: a single edgeId as argument is allowed as shorthand for a list of length 1
1383        """
1384        if isinstance(edgeList, str):
1385            edgeList = [edgeList]
1386        self._setCmd(tc.VAR_VIA, vehID, "l", edgeList)
1387
1388    def highlight(self, vehID, color=(255, 0, 0, 255), size=-1, alphaMax=-1, duration=-1, type=0):
1389        """ highlight(string, color, float, ubyte, float, ubyte) -> None
1390            Adds a circle of the given color tracking the vehicle.
1391            If a positive size [in m] is given the size of the highlight is chosen accordingly,
1392            otherwise the length of the vehicle is used as reference.
1393            If alphaMax and duration are positive, the circle fades in and out within the given duration,
1394            otherwise it permanently follows the vehicle.
1395        """
1396        if type > 255:
1397            raise TraCIException("vehicle.highlight(): maximal value for type is 255")
1398        if alphaMax > 255:
1399            raise TraCIException("vehicle.highlight(): maximal value for alphaMax is 255")
1400        if alphaMax <= 0 and duration > 0:
1401            raise TraCIException("vehicle.highlight(): duration>0 requires alphaMax>0")
1402        if alphaMax > 0 and duration <= 0:
1403            raise TraCIException("vehicle.highlight(): alphaMax>0 requires duration>0")
1404
1405        if alphaMax > 0:
1406            self._setCmd(tc.VAR_HIGHLIGHT, vehID, "tcdBdB", 5, color, size, alphaMax, duration, type)
1407        else:
1408            self._setCmd(tc.VAR_HIGHLIGHT, vehID, "tcd", 2, color, size)
1409
1410    @alias_param("laneChangeMode", "lcm")
1411    def setLaneChangeMode(self, vehID, laneChangeMode):
1412        """setLaneChangeMode(string, integer) -> None
1413
1414        Sets the vehicle's lane change mode as a bitset.
1415        """
1416        self._setCmd(tc.VAR_LANECHANGE_MODE, vehID, "i", laneChangeMode)
1417
1418    @alias_param("speedMode", "sm")
1419    def setSpeedMode(self, vehID, speedMode):
1420        """setSpeedMode(string, integer) -> None
1421
1422        Sets the vehicle's speed mode as a bitset.
1423        """
1424        self._setCmd(tc.VAR_SPEEDSETMODE, vehID, "i", speedMode)
1425
1426    def addLegacy(self, vehID, routeID, depart=tc.DEPARTFLAG_NOW, pos=0, speed=0,
1427                  lane=tc.DEPARTFLAG_LANE_FIRST_ALLOWED, typeID="DEFAULT_VEHTYPE"):
1428        """
1429        Add a new vehicle (old style)
1430        """
1431        if depart == tc.DEPARTFLAG_NOW:
1432            depart = "now"
1433        elif depart == tc.DEPARTFLAG_TRIGGERED:
1434            depart = "triggered"
1435        else:
1436            depart = str(depart)
1437        if pos < 0:
1438            print("Invalid departure position.")
1439            return
1440        if lane == tc.DEPARTFLAG_LANE_FIRST_ALLOWED:
1441            lane = "first"
1442        elif lane == tc.DEPARTFLAG_LANE_FREE:
1443            lane = "free"
1444        else:
1445            lane = str(lane)
1446        self.addFull(vehID, routeID, typeID, depart, lane, str(pos), str(speed))
1447
1448    def add(self, vehID, routeID, typeID="DEFAULT_VEHTYPE", depart="now",
1449            departLane="first", departPos="base", departSpeed="0",
1450            arrivalLane="current", arrivalPos="max", arrivalSpeed="current",
1451            fromTaz="", toTaz="", line="", personCapacity=0, personNumber=0):
1452        """
1453        Add a new vehicle (new style with all possible parameters)
1454        If routeID is "", the vehicle will be inserted on a random network edge
1455        if route consists of two disconnected edges, the vehicle will be treated
1456        like a <trip> and use the fastest route between the two edges.
1457        """
1458        if depart is None:
1459            # legacy compatibility
1460            depart = str(self._connection.simulation.getTime())
1461        self._setCmd(tc.ADD_FULL, vehID, "t" + (12 * "s") + "ii", 14,
1462                     routeID, typeID, depart, departLane, departPos, departSpeed,
1463                     arrivalLane, arrivalPos, arrivalSpeed, fromTaz, toTaz, line, personCapacity, personNumber)
1464
1465    addFull = add
1466
1467    def dispatchTaxi(self, vehID, reservations):
1468        """dispatchTaxi(string, list(string)) -> None
1469        dispatches the taxi with the given id to service the given reservations.
1470        If only a single reservation is given, this implies pickup and drop-off
1471        If multiple reservations are given, each reservation id must occur twice
1472        (once for pickup and once for drop-off) and the list encodes ride
1473        sharing of passengers (in pickup and drop-off order)
1474        """
1475        if isinstance(reservations, str):
1476            reservations = [reservations]
1477        self._setCmd(tc.CMD_TAXI_DISPATCH, vehID, "l", reservations)
1478
1479    def remove(self, vehID, reason=tc.REMOVE_VAPORIZED):
1480        '''Remove vehicle with the given ID for the give reason.
1481           Reasons are defined in module constants and start with REMOVE_'''
1482        self._setCmd(tc.REMOVE, vehID, "b", reason)
1483
1484    @alias_param("laneIndex", "lane")
1485    def moveToXY(self, vehID, edgeID, laneIndex, x, y, angle=tc.INVALID_DOUBLE_VALUE, keepRoute=1, matchThreshold=100):
1486        '''Place vehicle at the given x,y coordinates and force its angle to
1487        the given value (for drawing).
1488        If the angle is set to INVALID_DOUBLE_VALUE, the vehicle assumes the
1489        natural angle of the edge on which it is driving.
1490        If keepRoute is set to 1, the closest position
1491        within the existing route is taken. If keepRoute is set to 0, the vehicle may move to
1492        any edge in the network but its route then only consists of that edge.
1493        If keepRoute is set to 2 the vehicle has all the freedom of keepRoute=0
1494        but in addition to that may even move outside the road network.
1495        edgeID and lane are optional placement hints to resolve ambiguities.
1496        The command fails if no suitable target position is found within the
1497        distance given by matchThreshold.
1498        '''
1499        self._setCmd(tc.MOVE_TO_XY, vehID, "tsidddbd", 7, edgeID, laneIndex, x, y, angle, keepRoute, matchThreshold)
1500
1501    def addSubscriptionFilterLanes(self, lanes, noOpposite=False, downstreamDist=None, upstreamDist=None):
1502        """addSubscriptionFilterLanes(list(integer), bool, double, double) -> None
1503
1504        Adds a lane-filter to the last modified vehicle context subscription (call it just after subscribing).
1505        lanes is a list of relative lane indices (-1 -> right neighboring lane of the ego, 0 -> ego lane, etc.)
1506        noOpposite specifies whether vehicles on opposite direction lanes shall be returned
1507        downstreamDist and upstreamDist specify the range of the search for surrounding vehicles along the road net.
1508        """
1509        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_LANES, lanes)
1510        if noOpposite:
1511            self.addSubscriptionFilterNoOpposite()
1512        if downstreamDist is not None:
1513            self.addSubscriptionFilterDownstreamDistance(downstreamDist)
1514        if upstreamDist is not None:
1515            self.addSubscriptionFilterUpstreamDistance(upstreamDist)
1516
1517    def addSubscriptionFilterNoOpposite(self):
1518        """addSubscriptionFilterNoOpposite() -> None
1519
1520        Omits vehicles on other edges than the ego's for the last modified vehicle context subscription
1521        (call it just after subscribing).
1522        """
1523        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_NOOPPOSITE)
1524
1525    def addSubscriptionFilterDownstreamDistance(self, dist):
1526        """addSubscriptionFilterDownstreamDist(float) -> None
1527
1528        Sets the downstream distance along the network for vehicles to be returned by the last modified
1529        vehicle context subscription (call it just after subscribing).
1530        """
1531        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_DOWNSTREAM_DIST, dist)
1532
1533    def addSubscriptionFilterUpstreamDistance(self, dist):
1534        """addSubscriptionFilterUpstreamDist(float) -> None
1535
1536        Sets the upstream distance along the network for vehicles to be returned by the last modified
1537        vehicle context subscription (call it just after subscribing).
1538        """
1539        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_UPSTREAM_DIST, dist)
1540
1541    def addSubscriptionFilterCFManeuver(self, downstreamDist=None, upstreamDist=None):
1542        """addSubscriptionFilterCFManeuver() -> None
1543
1544        Restricts vehicles returned by the last modified vehicle context subscription to leader and follower of the ego.
1545        downstreamDist and upstreamDist specify the range of the search for leader and follower along the road net.
1546        """
1547        self.addSubscriptionFilterLeadFollow([0])
1548        if downstreamDist is not None:
1549            self.addSubscriptionFilterDownstreamDistance(downstreamDist)
1550        if upstreamDist is not None:
1551            self.addSubscriptionFilterUpstreamDistance(upstreamDist)
1552
1553    def addSubscriptionFilterLCManeuver(self, direction=None, noOpposite=False, downstreamDist=None, upstreamDist=None):
1554        """addSubscriptionFilterLCManeuver(int) -> None
1555
1556        Restricts vehicles returned by the last modified vehicle context subscription to neighbor and ego-lane leader
1557        and follower of the ego.
1558        direction - lane change direction (in {-1=right, 1=left})
1559        noOpposite specifies whether vehicles on opposite direction lanes shall be returned
1560        downstreamDist and upstreamDist specify the range of the search for leader and follower along the road net.
1561        Combine with: distance filters; vClass/vType filter.
1562        """
1563        if direction is None:
1564            # Using default: both directions
1565            lanes = [-1, 0, 1]
1566        elif not (direction == -1 or direction == 1):
1567            warnings.warn("Ignoring lane change subscription filter " +
1568                          "with non-neighboring lane offset direction=%s." % direction)
1569            return
1570        else:
1571            lanes = [0, direction]
1572        self.addSubscriptionFilterLeadFollow(lanes)
1573        if noOpposite:
1574            self.addSubscriptionFilterNoOpposite()
1575        if downstreamDist is not None:
1576            self.addSubscriptionFilterDownstreamDistance(downstreamDist)
1577        if upstreamDist is not None:
1578            self.addSubscriptionFilterUpstreamDistance(upstreamDist)
1579
1580    def addSubscriptionFilterLeadFollow(self, lanes):
1581        """addSubscriptionFilterLCManeuver(lanes) -> None
1582
1583        Restricts vehicles returned by the last modified vehicle context subscription to neighbor and ego-lane leader
1584        and follower of the ego.
1585        Combine with: lanes-filter to restrict to one direction; distance filters; vClass/vType filter.
1586        """
1587        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_LEAD_FOLLOW)
1588        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_LANES, lanes)
1589
1590    def addSubscriptionFilterTurn(self, downstreamDist=None, foeDistToJunction=None):
1591        """addSubscriptionFilterTurn(double, double) -> None
1592
1593        Restricts vehicles returned by the last modified vehicle context subscription to foes on upcoming junctions
1594        """
1595        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_TURN, foeDistToJunction)
1596        if downstreamDist is not None:
1597            self.addSubscriptionFilterDownstreamDistance(downstreamDist)
1598
1599    def addSubscriptionFilterVClass(self, vClasses):
1600        """addSubscriptionFilterVClass(list(String)) -> None
1601
1602        Restricts vehicles returned by the last modified vehicle context subscription to vehicles of the given classes
1603        """
1604        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_VCLASS, vClasses)
1605
1606    def addSubscriptionFilterVType(self, vTypes):
1607        """addSubscriptionFilterVType(list(String)) -> None
1608
1609        Restricts vehicles returned by the last modified vehicle context subscription to vehicles of the given types
1610        """
1611        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_VTYPE, vTypes)
1612
1613    def addSubscriptionFilterFieldOfVision(self, openingAngle):
1614        """addSubscriptionFilterFieldOfVision(float) -> None
1615
1616        Restricts vehicles returned by the last modified vehicle context subscription
1617        to vehicles within field of vision with given opening angle
1618        """
1619        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_FIELD_OF_VISION, openingAngle)
1620
1621    def addSubscriptionFilterLateralDistance(self, lateralDist, downstreamDist=None, upstreamDist=None):
1622        """addSubscriptionFilterLateralDist(double, double, double) -> None
1623
1624        Adds a lateral distance filter to the last modified vehicle context subscription
1625        (call it just after subscribing).
1626        downstreamDist and upstreamDist specify the longitudinal range of the search
1627        for surrounding vehicles along the ego vehicle's route.
1628        """
1629        self._connection._addSubscriptionFilter(tc.FILTER_TYPE_LATERAL_DIST, lateralDist)
1630        if downstreamDist is not None:
1631            self.addSubscriptionFilterDownstreamDistance(downstreamDist)
1632        if upstreamDist is not None:
1633            self.addSubscriptionFilterUpstreamDistance(upstreamDist)