Package org.opentrafficsim.core.network

Class OTSNetwork

    • Field Detail

      • EXTENT_MARGIN

        public static double EXTENT_MARGIN
        Extra clearance around boundaries of network as fraction of width and height.

    • Constructor Detail

      • OTSNetwork

        public OTSNetwork​(String id,
                  boolean addDefaultTypes,
                  OTSSimulatorInterface simulator)
        Construction of an empty OTSNetwork.
        Parameters:
        id - String; the network id.
        addDefaultTypes - boolean; add the default GTUTypes and LinkTypes, or not
        simulator - OTSSimulatorInterface; the DSOL simulator engine

    • Method Detail

      • getId

        public String getId()
        Get a descriptive Id of this PerceivableContext (useful for debugging purposes).
        Specified by:
        getId in interface Identifiable
        Specified by:
        getId in interface PerceivableContext
        Returns:
        String; the id of this PerceivableContext

      • getNodeMap

        public ImmutableMap<String,​Node> getNodeMap()
        Return an immutable map of node ids to nodes in this Network.
        Specified by:
        getNodeMap in interface Network
        Returns:
        ImmutableMap<String>; an immutable map of nodes

      • addNode

        public void addNode​(Node node)
             throws NetworkException
        Register a node in this Network.
        Specified by:
        addNode in interface Network
        Parameters:
        node - Node; the node to add to this Network.
        Throws:
        NetworkException - if node already exists in this Network, or if name of the node is not unique

      • removeNode

        public void removeNode​(Node node)
                throws NetworkException
        Unregister a node from this Network.
        Specified by:
        removeNode in interface Network
        Parameters:
        node - Node; the node to remove from this Network.
        Throws:
        NetworkException - if node does not exist in this Network.

      • containsNode

        public boolean containsNode​(Node node)
        Test whether a node is present in this Network.
        Specified by:
        containsNode in interface Network
        Parameters:
        node - Node; the node to search for in this Network
        Returns:
        boolean; true if the node is registered in this Network; false if the node is not registered in this Network

      • containsNode

        public boolean containsNode​(String nodeId)
        Test whether a node with a given id is present in this Network.
        Specified by:
        containsNode in interface Network
        Parameters:
        nodeId - String; the id of the node to search for in this Network
        Returns:
        boolean; true if a node with the given id exists in this Network; false if no node with the given id exists in this Network

      • getNode

        public Node getNode​(String nodeId)
        Retrieve a node with a given id from this Network, or null if the id cannot be found.
        Specified by:
        getNode in interface Network
        Parameters:
        nodeId - String; the id of the node to search for in this Network
        Returns:
        Node; the node or null if not present

      • getUnbalancedCentroids

        public List<Node> getUnbalancedCentroids​(GtuType gtuType)
        Return a list of Centroid nodes that have incoming connectors without corresponding outgoing connectors to the same node or vice versa (which can be fully okay, especially when the lanes are a dead end, or when lanes / links only go in a single direction).
        Parameters:
        gtuType - GtuType; the GTU type for which to check the connectors
        Returns:
        List<Node>; a list of Centroid nodes that have incoming connectors without corresponding outgoing connectors to the same node or vice versa.

      • getLinkMap

        public ImmutableMap<String,​Link> getLinkMap()
        Provide an immutable map of link ids to links in this Network.
        Specified by:
        getLinkMap in interface Network
        Returns:
        ImmutableMap<String>; the an immutable map of links

      • addLink

        public void addLink​(Link link)
             throws NetworkException
        Register a link in this Network.
        Specified by:
        addLink in interface Network
        Parameters:
        link - Link; the link to add to this Network
        Throws:
        NetworkException - if link already exists in this Network, if name of the link is not unique, or if the start node or the end node of the link are not registered in this Network.

      • removeLink

        public void removeLink​(Link link)
                throws NetworkException
        Unregister a link from this Network.
        Specified by:
        removeLink in interface Network
        Parameters:
        link - Link; the link to remove from this Network
        Throws:
        NetworkException - if link does not exist in this Network.

      • getLink

        public Link getLink​(Node node1,
                    Node node2)
        Find a link between node1 and node2 and return it if it exists in this Network. If not, return null.
        Specified by:
        getLink in interface Network
        Parameters:
        node1 - Node; first node
        node2 - Node; second node
        Returns:
        Link; the link between node1 and node2 in this Network or null if no such link exists in this Network

      • getLink

        public Link getLink​(String nodeId1,
                    String nodeId2)
             throws NetworkException
        Find a link between node1 and node2 and return it if it exists in this Network. If not, return null.
        Specified by:
        getLink in interface Network
        Parameters:
        nodeId1 - String; id of the first node
        nodeId2 - String; id of the second node
        Returns:
        Link; the link between node1 and node2 in this Network or null if no such link exists in this Network
        Throws:
        NetworkException - if the node(s) cannot be found by their id

      • containsLink

        public boolean containsLink​(Link link)
        Test whether a link is present in this Network.
        Specified by:
        containsLink in interface Network
        Parameters:
        link - Link; the link to search for in this Network
        Returns:
        boolean; true if the link is in this Network; false if the link is not in this Network

      • containsLink

        public boolean containsLink​(String linkId)
        Test whether a link with a given id is present in this Network.
        Specified by:
        containsLink in interface Network
        Parameters:
        linkId - String; the id of the link to search for in this Network
        Returns:
        boolean; true if a link with the given id exists in this Network; false if no link with the given id exists in this Network

      • getLink

        public Link getLink​(String linkId)
        Retrieve a node with a given id from this Network, or null if the id cannot be found.
        Specified by:
        getLink in interface Network
        Parameters:
        linkId - String; the id of the link to search for in this Network
        Returns:
        Link; the link with the given id, or null if no link with the given id exists in this Network

      • getObjectMap

        public ImmutableMap<String,​ObjectInterface> getObjectMap()
        Return an immutable map of all ObjectInterface implementing objects in this Network.
        Specified by:
        getObjectMap in interface Network
        Returns:
        ImmutableMap<String, ObjectInterface>; the immutable map of all ObjectInterface implementing objects in the Network

      • getObjectMap

        public <T extends ObjectInterface> ImmutableMap<String,​T> getObjectMap​(Class<T> objectType)
        Return an immutable map of all ObjectInterface implementing objects in this Network that are of type objectType, or any sub type thereof.
        Specified by:
        getObjectMap in interface Network
        Type Parameters:
        T - type of object
        Parameters:
        objectType - Class<T>; the (sub-)type of ObjectInterface that the returned map is reduced to
        Returns:
        ImmutableMap<String, ObjectInterface>; the immutable map of all ObjectInterface implementing objects in this Network that are of the type objectType, or any sub-type thereof

      • getObject

        public <T extends ObjectInterface> T getObject​(Class<T> objectType,
                                               String objectId)
        Retrieve the object of a specific type with a specific id.
        Specified by:
        getObject in interface Network
        Type Parameters:
        T - object type
        Parameters:
        objectType - Class<T>; object type class
        objectId - String; id of object
        Returns:
        T; the object of given type with given id, null if no such object exists in this Network

      • addObject

        public void addObject​(ObjectInterface object)
               throws NetworkException
        Add an ObjectInterface implementing object to this Network.
        Specified by:
        addObject in interface Network
        Parameters:
        object - ObjectInterface; the object that implements ObjectInterface
        Throws:
        NetworkException - if the object already exists in this Network, or the name of the object is not unique.

      • removeObject

        public void removeObject​(ObjectInterface object)
                  throws NetworkException
        Remove an ObjectInterface implementing object form this Network.
        Specified by:
        removeObject in interface Network
        Parameters:
        object - ObjectInterface; the object that implements ObjectInterface
        Throws:
        NetworkException - if the object does not exist in this Network.

      • findObjects

        public Iterator<ObjectInterface> findObjects​(Bounds3d bounds)
        Construct an Iterator<ObjectInterface> that will yield all ObjectInterface objects with Bounds that intersect the given Bounds3d.
        Parameters:
        bounds - Bounds3d; the 3D search area
        Returns:
        Iterator<ObjectInterface>; that will yield all ObjectInterface objects that intersect the given Bounds3d.

      • getNumberOfObjects

        public long getNumberOfObjects()
        Report how many ObjectInterface objects have been registered (the result includes objects that have subsequently been removed).
        Returns:
        long; the total number of ObjectInterface objects that have been registered

      • containsObject

        public boolean containsObject​(ObjectInterface object)
        Test whether the object is present in this Network.
        Specified by:
        containsObject in interface Network
        Parameters:
        object - ObjectInterface; the object that is tested for presence
        Returns:
        boolean; true if the object is present in this Network; false if the object is not present in this Network

      • containsObject

        public boolean containsObject​(String objectId)
        Test whether an object with the given id is present in this Network. Note that the objectId should be the fullId of the object. E.g., for lanes this means prefixing link id, etc.
        Specified by:
        containsObject in interface Network
        Parameters:
        objectId - String; the id that is tested for presence
        Returns:
        boolean; true if an object with the given id is present in this Network; false if no object with the given id is present in this Network

      • getInvisibleObjectMap

        public ImmutableMap<String,​InvisibleObjectInterface> getInvisibleObjectMap()
        Return an immutable map of all InvisibleObject implementing objects in this Network.
        Specified by:
        getInvisibleObjectMap in interface Network
        Returns:
        ImmutableMap<String, ObjectInterface>; the immutable map of all ObjectInterface implementing objects in the Network

      • getInvisibleObjectMap

        public ImmutableMap<String,​InvisibleObjectInterface> getInvisibleObjectMap​(Class<InvisibleObjectInterface> objectType)
        Return an immutable map of all InvisibleObject implementing objects in this Network that are of type objectType, or any sub type thereof.
        Specified by:
        getInvisibleObjectMap in interface Network
        Parameters:
        objectType - Class<InvisibleObjectInterface>; the (sub-)type of InvisibleObject that the returned map is reduced to
        Returns:
        ImmutableMap<String, InvisibleObject>; the immutable map of all InvisibleObject implementing objects in the Network that are of the type objectType, or any sub type thereof

      • addInvisibleObject

        public void addInvisibleObject​(InvisibleObjectInterface object)
                        throws NetworkException
        Add an ObjectInterface implementing object to this Network.
        Specified by:
        addInvisibleObject in interface Network
        Parameters:
        object - InvisibleObjectInterface; the object that implements ObjectInterface
        Throws:
        NetworkException - if link already exists in this Network, if name of the object is not unique.

      • containsInvisibleObject

        public boolean containsInvisibleObject​(InvisibleObjectInterface object)
        Test whether the invisible object is present in this Network.
        Specified by:
        containsInvisibleObject in interface Network
        Parameters:
        object - InvisibleObjectInterface; the object that is tested for presence
        Returns:
        boolean; whether the invisible object is present in this Network

      • containsInvisibleObject

        public boolean containsInvisibleObject​(String objectId)
        Test whether an invisible object with the given id is present in this Network. Note that the objectId should be the fullId of the object; including lane ids, link ids, etc.
        Specified by:
        containsInvisibleObject in interface Network
        Parameters:
        objectId - String; the id that is tested for presence
        Returns:
        boolean; whether an invisible object with the given id is present in this Network

      • getDefinedRouteMap

        public ImmutableMap<String,​Route> getDefinedRouteMap​(GtuType gtuType)
        Return an immutable map of routes that exist in this Network for the GTUType.
        Specified by:
        getDefinedRouteMap in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to retrieve the defined routes
        Returns:
        ImmutableMap<String, Route>; an immutable map of routes in this Network for the given GTUType, or an empty ImmutableMap if no routes are defined for the given GTUType.

      • addRoute

        public void addRoute​(GtuType gtuType,
                     Route route)
              throws NetworkException
        Add a route to this Network.
        Specified by:
        addRoute in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to add a route
        route - Route; the route to add to this Network.
        Throws:
        NetworkException - if route already exists in this Network, or if name of the route is not unique, or if one of the nodes of the route is not registered in this Network.

      • removeRoute

        public void removeRoute​(GtuType gtuType,
                        Route route)
                 throws NetworkException
        Remove the route from this Network, e.g. because of road maintenance.
        Specified by:
        removeRoute in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to remove a route
        route - Route; the route to remove from this Network.
        Throws:
        NetworkException - if route does not exist in this Network.

      • containsRoute

        public boolean containsRoute​(GtuType gtuType,
                             Route route)
        Determine whether the provided route exists in this Network for the given GTUType.
        Specified by:
        containsRoute in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to check whether the route exists
        route - Route; the route to check for
        Returns:
        boolean; true if the route exists in this Network for the given GTUType, or false if no such route exists in this Network

      • containsRoute

        public boolean containsRoute​(GtuType gtuType,
                             String routeId)
        Determine whether a route with the given id exists in this Network for the given GTUType.
        Specified by:
        containsRoute in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to check whether the route exists
        routeId - String; the id of the route to check for
        Returns:
        boolean; true if a route with the given id exists in this Network for the given GTUType; false if no such route exists in this Network

      • getRoute

        public Route getRoute​(String routeId)
        Retrieve the route with a specific id or null if no such route is known in this OTSNetwork.
        Parameters:
        routeId - String; route id
        Returns:
        Route; route with specified id or null if no such route is known in this OTSNetwork

      • getRoute

        public Route getRoute​(GtuType gtuType,
                      String routeId)
        Return the route with a specific id for a specific GTUType, or null if no route with that id for that GTUType exists in this Network.
        Specified by:
        getRoute in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to retrieve a route based on its id.
        routeId - String; the route to search for in this Network.
        Returns:
        Route; the route or null if no such route exists in this Network

      • getRoutesBetween

        public Set<Route> getRoutesBetween​(GtuType gtuType,
                                   Node nodeFrom,
                                   Node nodeTo)
        Return the the shortest route for a specific GTUType between two nodes in this Network, via a list of intermediate nodes. If no path exists from the start node to the end node via the intermediate nodes in this Network, null is returned.
        Specified by:
        getRoutesBetween in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to retrieve the defined routes
        nodeFrom - Node; the start node.
        nodeTo - Node; the end node.
        Returns:
        Set<Route>; a set with routes from the start Node to the end Node in this Network for the specified GTUType; if no route can be found, an empty set is returned.

      • buildGraph

        public void buildGraph​(GtuType gtuType)
        (Re)build the underlying graph for the given GTUType.
        Specified by:
        buildGraph in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to (re)build the graph

      • getShortestRouteBetween

        public CompleteRoute getShortestRouteBetween​(GtuType gtuType,
                                             Node nodeFrom,
                                             Node nodeTo,
                                             LinkWeight linkWeight)
                                      throws NetworkException
        Calculate the shortest route between two nodes in this Network. If no path exists from the start node to the end node in this Network, null is returned. This method returns a CompleteRoute, which includes all nodes to get from start to end. This method recalculates the graph.
        Specified by:
        getShortestRouteBetween in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to calculate the shortest route
        nodeFrom - Node; the start node
        nodeTo - Node; the end node
        linkWeight - LinkWeight; link weight
        Returns:
        CompleteRoute; the shortest route from nodeFrom to nodeTo in this Network for the specified GTUType. If no path exists in this Network from the start node to the end node for the GTUType, null is returned.
        Throws:
        NetworkException - in case nodes cannot be added to the route, e.g. because they are not directly connected. This can be the case when the links in this Network have changed, but the graph has not been rebuilt. TODO ensure that that NetworkException cannot happen by clearing the graph when the network is changed.

      • getShortestRouteBetween

        public CompleteRoute getShortestRouteBetween​(GtuType gtuType,
                                             Node nodeFrom,
                                             Node nodeTo,
                                             List<Node> nodesVia)
                                      throws NetworkException
        Calculate the shortest route between two nodes in this Network, via a list of intermediate nodes. If no path exists from the start node to the end node via the intermediate nodes in this Network, null is returned. This method returns a CompleteRoute, which includes all nodes to get from start to end. In case the graph for the GTUType has not yet been built, this method will call the buildGraph method.
        Specified by:
        getShortestRouteBetween in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to calculate the shortest route
        nodeFrom - Node; the start node
        nodeTo - Node; the end node
        nodesVia - List<Node>; a number of nodes that the GTU has to pass between nodeFrom and nodeTo in the given order
        Returns:
        CompleteRoute; the shortest route between two nodes in this Network, via the intermediate nodes. If no path exists from nodeFrom to nodeTo via nodesVia in this Network, null is returned.
        Throws:
        NetworkException - in case nodes cannot be added to the route, e.g. because they are not directly connected. This can be the case when the links in this Network have changed, but the graph has not been rebuilt. TODO ensure that that NetworkException cannot happen by clearing the graph when the network is changed.

      • getShortestRouteBetween

        public CompleteRoute getShortestRouteBetween​(GtuType gtuType,
                                             Node nodeFrom,
                                             Node nodeTo,
                                             List<Node> nodesVia,
                                             LinkWeight linkWeight)
                                      throws NetworkException
        Calculate the shortest route between two nodes in this Network, via a list of intermediate nodes. If no path exists from the start node to the end node via the intermediate nodes in this Network, null is returned. This method returns a CompleteRoute, which includes all nodes to get from start to end. This method recalculates the graph.
        Specified by:
        getShortestRouteBetween in interface Network
        Parameters:
        gtuType - GtuType; the GTUType for which to calculate the shortest route
        nodeFrom - Node; the start node
        nodeTo - Node; the end node
        nodesVia - List<Node>; a number of nodes that the GTU has to pass between nodeFrom and nodeTo in the given order
        linkWeight - LinkWeight; link weight
        Returns:
        CompleteRoute; the shortest route between two nodes in this Network, via the intermediate nodes. If no path exists from the start node to the end node via the intermediate nodes in this Network, null is returned.
        Throws:
        NetworkException - in case nodes cannot be added to the route, e.g. because they are not directly connected. This can be the case when the links in this Network have changed, but the graph has not been rebuilt. TODO explain how that is possible if this method recalculates the graph.

      • getRouteMap

        public ImmutableMap<GtuType,​Map<String,​Route>> getRouteMap()
        Get an immutable route map. TODO verify that the internal maps (from String to Route) are also immutable).
        Returns:
        ImmutableMap<GTUType, Map<String, Route>>; immutable route map

      • setRawRouteMap

        public void setRawRouteMap​(Map<GtuType,​Map<String,​Route>> newRouteMap)
        Replace the internal Route Map. Should only be called fro the network package when cloning a network.
        Parameters:
        newRouteMap - Map<GtuType, Map<String, Route>>; the routeMap to set, only to be used in the 'network' package for cloning.

      • getLinkGraphs

        public ImmutableMap<GtuType,​org.jgrapht.graph.SimpleDirectedWeightedGraph<Node,​LinkEdge<Link>>> getLinkGraphs()
        Get an immutable graph map.
        Returns:
        ImmutableHashMap<GTUType, SimpleDirectedWeightedGraph<Node, LinkEdge<Link>>>; only to be used in the 'network' package for cloning.

      • addDefaultLinkTypes

        public void addDefaultLinkTypes()
        Add the default LinkTypes that have been defined in the enum LinkType.DEFAULTS to the network. It is not necessary to call this method on every network; when the LinkTypes are for instance defined in an XML file, adding the default types might not be needed.
        Specified by:
        addDefaultLinkTypes in interface Definitions

      • addLinkType

        public void addLinkType​(LinkType linkType)
        Add a Link type to the map. This method is automatically called from the LinkType constructor.
        Specified by:
        addLinkType in interface Definitions
        Parameters:
        linkType - LinkType; the LinkType to add

      • getLinkType

        public LinkType getLinkType​(String linkId)
        Retrieve a defined LinkType based on its id.
        Specified by:
        getLinkType in interface Definitions
        Parameters:
        linkId - String; the id to search for
        Returns:
        the LinkType or null in case it could not be found

      • getLinkType

        public LinkType getLinkType​(LinkType.DEFAULTS linkEnum)
        Retrieve a defined default LinkType based on its enum.
        Specified by:
        getLinkType in interface Definitions
        Parameters:
        linkEnum - LinkType.DEFAULTS; the enum to search for
        Returns:
        the LinkType or null in case it could not be found

      • addDefaultGtuTypes

        public void addDefaultGtuTypes()
        Add the default GTU Types that have been defined in the enum GTUType.DEFAULTS to the network. It is not necessary to call this method on every network; when the GTUTypes are for instance defined in an XML file, adding the default types might not be needed.
        Specified by:
        addDefaultGtuTypes in interface Definitions

      • addGtuType

        public void addGtuType​(GtuType gtuType)
        Add a GTU type to the map. This method is automatically called from the GTUType constructor.
        Specified by:
        addGtuType in interface Definitions
        Parameters:
        gtuType - GtuType; the GTUType to add

      • getGtuType

        public GtuType getGtuType​(String gtuId)
        Retrieve a defined GTUType based on its id.
        Specified by:
        getGtuType in interface Definitions
        Parameters:
        gtuId - String; the id to search for
        Returns:
        the GTUType or null in case it could not be found

      • getGtuType

        public GtuType getGtuType​(GtuType.DEFAULTS gtuEnum)
        Retrieve a defined default GTUType based on its enum.
        Specified by:
        getGtuType in interface Definitions
        Parameters:
        gtuEnum - GtuType.DEFAULTS; the enum to search for
        Returns:
        the GTUType or null in case it could not be found

      • addGtu

        public void addGtu​(Gtu gtu)
        Add a GTU to this PerceivableContext.
        Specified by:
        addGtu in interface PerceivableContext
        Parameters:
        gtu - Gtu; the GTU to add

      • removeGtu

        public void removeGtu​(Gtu gtu)
        Remove a GTU from this PerceivableContext. TODO should probably throw an exception if the GTU is not in this PerceivableContext.
        Specified by:
        removeGtu in interface PerceivableContext
        Parameters:
        gtu - Gtu; the GTU to remove

      • containsGtu

        public boolean containsGtu​(Gtu gtu)
        Test whether a GTU is registered in this PerceivableContext.
        Specified by:
        containsGtu in interface PerceivableContext
        Parameters:
        gtu - Gtu; the GTU to search for
        Returns:
        boolean; true if the network contains the GTU; false if this PerceivableContext does not contain the GTU

      • getGtu

        public Gtu getGtu​(String gtuId)
        Retrieve a GTU with a specific id from this PerceivableContext.
        Specified by:
        getGtu in interface PerceivableContext
        Parameters:
        gtuId - String; the id of the GTU
        Returns:
        GTU; a GTU as registered in the current model, or null when no GTU with the specified id could be found.

      • getGtus

        public Set<Gtu> getGtus()
        Get an overview of the GTUs in the model. The set returned is a defensive copy that may be modified by the caller.
        Specified by:
        getGtus in interface PerceivableContext
        Returns:
        Set<GTU>; a set of GTUs as registered in the current model.

      • containsGtuId

        public boolean containsGtuId​(String gtuId)
        Test whether a GTU with a specific id is registered in this PerceivableContext.
        Specified by:
        containsGtuId in interface PerceivableContext
        Parameters:
        gtuId - String; the GTU id to search for
        Returns:
        boolean; true if the network contains a GTU with this id; false if this PerceivableContext does not contain a GTU with the specified id

      • getExtent

        public Bounds2d getExtent()
        Calculate the extent of the network based on the network objects' locations and return the dimensions.
        Returns:
        Bounds2d; the extent of the network