InfrastructurePerception.java

  1. package org.opentrafficsim.road.gtu.lane.perception.categories;

  2. import java.util.SortedSet;

  3. import org.djunits.value.vdouble.scalar.Length;
  4. import org.opentrafficsim.base.parameters.ParameterException;
  5. import org.opentrafficsim.core.gtu.GTUException;
  6. import org.opentrafficsim.core.network.LateralDirectionality;
  7. import org.opentrafficsim.road.gtu.lane.perception.InfrastructureLaneChangeInfo;
  8. import org.opentrafficsim.road.gtu.lane.perception.RelativeLane;
  9. import org.opentrafficsim.road.network.speed.SpeedLimitProspect;

  10. /**
  11.  * <p>
  12.  * Copyright (c) 2013-2018 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
  13.  * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
  14.  * <p>
  15.  * @version $Revision$, $LastChangedDate$, by $Author$, initial version 14 feb. 2017 <br>
  16.  * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
  17.  * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
  18.  * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
  19.  */
  20. public interface InfrastructurePerception extends LaneBasedPerceptionCategory
  21. {

  22.     /**
  23.      * Updates the infrastructural lane change info. It starts at the given lane and moves downstream over the network. Whenever
  24.      * a point is encountered where lane changes are required, this information is saved.
  25.      * @param lane relative lateral lane
  26.      * @throws GTUException if the GTU was not initialized or if the lane is not in the cross section
  27.      * @throws ParameterException if a parameter is not defined
  28.      */
  29.     void updateInfrastructureLaneChangeInfo(RelativeLane lane) throws GTUException, ParameterException;

  30.     /**
  31.      * Updates the speed limit prospect.
  32.      * @param lane relative lateral lane
  33.      * @throws GTUException if the GTU was not initialized or if the lane is not in the cross section
  34.      * @throws ParameterException if a parameter is not defined
  35.      */
  36.     void updateSpeedLimitProspect(RelativeLane lane) throws GTUException, ParameterException;

  37.     /**
  38.      * Updates the distance over which lane changes remains legally possible.
  39.      * @param lane lane from which the lane change possibility is requested
  40.      * @param lat LEFT or RIGHT, null not allowed
  41.      * @throws GTUException if the GTU was not initialized or if the lane is not in the cross section
  42.      * @throws ParameterException if a parameter is not defined
  43.      */
  44.     void updateLegalLaneChangePossibility(RelativeLane lane, LateralDirectionality lat) throws GTUException, ParameterException;

  45.     /**
  46.      * Updates the distance over which lane changes remains physically possible.
  47.      * @param lane lane from which the lane change possibility is requested
  48.      * @param lat LEFT or RIGHT, null not allowed
  49.      * @throws GTUException if the GTU was not initialized or if the lane is not in the cross section
  50.      * @throws ParameterException if a parameter is not defined
  51.      */
  52.     void updatePhysicalLaneChangePossibility(RelativeLane lane, LateralDirectionality lat)
  53.             throws GTUException, ParameterException;

  54.     /**
  55.      * Updates a set of relative lanes representing the cross section. This set consists of all lanes on the current link, and
  56.      * an additional lane on the left and/or right side in case of a merge that is sufficiently nearby.
  57.      * @throws GTUException if the GTU was not initialized
  58.      * @throws ParameterException if a parameter is not defined
  59.      */
  60.     void updateCrossSection() throws GTUException, ParameterException;

  61.     /**
  62.      * Returns infrastructure lane change info of a lane. A set is returned as multiple points may force lane changes. Which
  63.      * point is considered most critical is a matter of driver interpretation and may change over time. This is shown below.
  64.      * Suppose vehicle A needs to take the off-ramp, and that behavior is that the minimum distance per required lane change
  65.      * determines how critical it is. First, 400m before the lane-drop, the off-ramp is critical. 300m downstream, the lane-drop
  66.      * is critical. Info is sorted by distance, closest first.
  67.      *
  68.      * <pre>
  69.      * _______
  70.      * _ _A_ _\_________
  71.      * _ _ _ _ _ _ _ _ _
  72.      * _________ _ _ ___
  73.      *          \_______
  74.      *     (-)        Lane-drop: 1 lane change  in 400m (400m per lane change)
  75.      *     (--------) Off-ramp:  3 lane changes in 900m (300m per lane change, critical)
  76.      *    
  77.      *     (-)        Lane-drop: 1 lane change  in 100m (100m per lane change, critical)
  78.      *     (--------) Off-ramp:  3 lane changes in 600m (200m per lane change)
  79.      * </pre>
  80.      *
  81.      * @param lane relative lateral lane
  82.      * @return infrastructure lane change info of a lane
  83.      */
  84.     SortedSet<InfrastructureLaneChangeInfo> getInfrastructureLaneChangeInfo(RelativeLane lane);

  85.     /**
  86.      * Returns the prospect for speed limits on a lane (dynamic speed limits may vary between lanes).
  87.      * @param lane relative lateral lane
  88.      * @return prospect for speed limits on a lane
  89.      */
  90.     SpeedLimitProspect getSpeedLimitProspect(RelativeLane lane);

  91.     /**
  92.      * Returns the distance over which a lane change remains legally possible. Negative values indicate the distance over which
  93.      * a lane change is legally not possible.
  94.      * @param fromLane lane from which the lane change possibility is requested
  95.      * @param lat LEFT or RIGHT, null not allowed
  96.      * @return distance over which a lane change remains possible
  97.      * @throws NullPointerException if {@code lat == null}
  98.      */
  99.     Length getLegalLaneChangePossibility(RelativeLane fromLane, LateralDirectionality lat);

  100.     /**
  101.      * Returns the distance over which a lane change remains physically possible. Negative values indicate the distance over
  102.      * which a lane change is physically not possible.
  103.      * @param fromLane lane from which the lane change possibility is requested
  104.      * @param lat LEFT or RIGHT, null not allowed
  105.      * @return distance over which a lane change remains possible
  106.      * @throws NullPointerException if {@code lat == null}
  107.      */
  108.     Length getPhysicalLaneChangePossibility(RelativeLane fromLane, LateralDirectionality lat);

  109.     /**
  110.      * Returns a set of relative lanes representing the cross section. Lanes are sorted left to right.
  111.      * @return set of relative lanes representing the cross section
  112.      */
  113.     SortedSet<RelativeLane> getCrossSection();

  114.     /** {@inheritDoc} */
  115.     @Override
  116.     default void updateAll() throws GTUException, ParameterException
  117.     {
  118.         updateCrossSection();
  119.         for (RelativeLane lane : getCrossSection())
  120.         {
  121.             updateInfrastructureLaneChangeInfo(lane);
  122.             updateSpeedLimitProspect(lane);
  123.             updateLegalLaneChangePossibility(lane, LateralDirectionality.LEFT);
  124.             updateLegalLaneChangePossibility(lane, LateralDirectionality.RIGHT);
  125.             updatePhysicalLaneChangePossibility(lane, LateralDirectionality.LEFT);
  126.             updatePhysicalLaneChangePossibility(lane, LateralDirectionality.RIGHT);
  127.         }
  128.     }

  129. }