map.pin module

This module contains pin data structure. Although the properties of a pin are stored as a dictionary, given that different types of pins have different properties, it may be unsafe to directly access the dictionary. These data strcutures or classes provide type-safe access to the properties since the pins are now explicitly casted into the appropriate classes and checked for validity before user access. If a pin dictionary is casted to a wrong pin class, the method is_valid() will return False, and other get methods will not return any sensible value.

The pins and their properties should be treated as immutable for read-only access. For some reason if the data are modified, their new behaviour will be captured by the simulation, but we do not provide any function to write the modified data back to the map file for a permanent change.

To add a new pin type, simply create the corresponding class which inherits the private base class defined in this source file.

All pin types are not encapsulated in a container class, they are defined directly in this module. The recommended way to import the pin classes is:

## use the name `MapPin` to encapsulate all pin types
import map.pin as MapPin 
...
## and access a pin on `my_map` by
my_parking = MapPin.Waypoint(my_map, pin_name="City Parking")
if not my_parking.is_valid:
    print("Error loading `City Parking` pin")

Note

• Created by: CH Foh (2021)

List of Classes

Landmark

It describes a landmark pin.

Waypoint

It describes a waypoint pin. A waypoint location is navigable where it connects to the map graph, and vehicles can be spawned and sunk.

Junction

It describes a road intersection. Like a waypoint, it is also navigable, but it can only be located at a vertex of a road in the map. Unless we need a location precisely at a vertex, otherwise waypoint provides more flexible location.

Building

It describes the shape of a building on the map.

Region

It describes a region defined by the user via map editor.

---

class map.pin.Landmark(map, pin_name)

Bases: map.pin._Pin

This is a landmark pin to be constrcuted by giving pin name of an existing landmark pin.

Parameters

mapmap.mapinfo.MapInfo

A valid mapinfo instance where the pin is on.

pin_namestr

The unique reference name of the pin.

Methods

clear()
copy()
fromkeys(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
get_display_name([default])	This method returns the display name of the pin.
get_xy()	This method returns pin location (x,y).
is_valid()	Use this method to check whether the instance is valid.
items()
keys()
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised
popitem(/)	Remove and return a (key, value) pair as a 2-tuple.
setdefault(key[, default])	Insert key with a value of default if key is not in the dictionary.
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()

__init__(map, pin_name)

Initialize self. See help(type(self)) for accurate signature.

is_valid() → bool

Use this method to check whether the instance is valid. Accessing to an invalid instance may cause run-time error.

Returns

bool

The validity of this pin.

class map.pin.Waypoint(map, pin_name=None)

Bases: map.pin._Pin

This is a waypoint pin to be constrcuted by giving the pin name of an existing waypoint pin. A waypoint pin is navigable, you can use the pin in the mobility module to create or absorb traffic, or to create a mobility waypoint.

Parameters

mapmap.mapinfo.MapInfo

A valid mapinfo instance where the pin is on.

pin_namestr

The unique reference name of the pin.

Methods

clear()
copy()
create(pin_name, road_id, coord_id)	Use this method to create a navigable waypoint.
fromkeys(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
get_display_name([default])	This method returns the display name of the pin.
get_road_id()	It returns road id of this waypoint.
get_xy()	This method returns pin location (x,y).
is_valid()	Use this method to check whether the instance is valid.
items()
keys()
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised
popitem(/)	Remove and return a (key, value) pair as a 2-tuple.
setdefault(key[, default])	Insert key with a value of default if key is not in the dictionary.
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()

__init__(map, pin_name=None)

Initialize self. See help(type(self)) for accurate signature.

is_valid() → bool

Use this method to check whether the instance is valid. Accessing to an invalid instance may cause run-time error.

Returns

bool

The validity of this pin.

create(pin_name, road_id, coord_id) → bool

Use this method to create a navigable waypoint. Usually, waypoint pin is created by placing a pin on the map using the provided map editor, and then load the pin during the simulation runtime using the pin name. However, it is also possible to create a waypoint pin without placing a pin. The pin can be created by directly specifying the road_id and coord_id. However, this is not a recommended approach and may cause unexpected outcome if any id is incorrectly specified.

Parameters

road_idint

The road_id where the waypoint is on.

coord_idint

The coord_id of the waypoint. It is also a road vertex.

Returns

bool

Whether the creation is successful.

get_road_id() → int

It returns road id of this waypoint.

class map.pin.Junction(map, pin_name)

Bases: map.pin._Pin

This is a junction pin to be constrcuted by giving the pin name of an existing junction pin. Junction pin is not navigable, please use waypoint pin for navigation.

Parameters

mapmap.mapinfo.MapInfo

A valid mapinfo instance where the pin is on.

pin_namestr

The unique reference name of the pin.

Methods

clear()
copy()
fromkeys(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
get_display_name([default])	This method returns the display name of the pin.
get_xy()	This method returns pin location (x,y).
is_valid()	Use this method to check whether the instance is valid.
items()
keys()
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised
popitem(/)	Remove and return a (key, value) pair as a 2-tuple.
setdefault(key[, default])	Insert key with a value of default if key is not in the dictionary.
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()

get_junction_id

__init__(map, pin_name)

Initialize self. See help(type(self)) for accurate signature.

is_valid() → bool

Use this method to check whether the instance is valid. Accessing to an invalid instance may cause run-time error.

Returns

bool

The validity of this pin.

get_junction_id() → int

class map.pin.Building(map, pin_name)

Bases: map.pin._Pin

This is a building pin to be constrcuted by giving the dict of an existing building pin. You can use the given method to retrieve the shape of the building.

Parameters

mapmap.mapinfo.MapInfo

A valid mapinfo instance where the pin is on.

pin_namestr

The unique reference name of the pin.

Methods

clear()
copy()
fromkeys(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
get_display_name([default])	This method returns the display name of the pin.
get_xy()	This method returns pin location (x,y).
is_valid()	Use this method to check whether the instance is valid.
items()
keys()
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised
popitem(/)	Remove and return a (key, value) pair as a 2-tuple.
setdefault(key[, default])	Insert key with a value of default if key is not in the dictionary.
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()

get_shape

__init__(map, pin_name)

Initialize self. See help(type(self)) for accurate signature.

is_valid() → bool

Use this method to check whether the instance is valid. Accessing to an invalid instance may cause a run-time error.

Returns

bool

The validity of this pin.

get_shape() → List[Tuple[int, int]]

class map.pin.Region(map, pin_name)

Bases: map.pin._Pin

This is a region pin to be constrcuted by giving the dict of an existing region pin.

Parameters

mapmap.mapinfo.MapInfo

A valid mapinfo instance where the pin is on.

pin_namestr

The unique reference name of the pin.

Methods

clear()
copy()
fromkeys(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
get_display_name([default])	This method returns the display name of the pin.
get_shape()	This method returns the width, height and orientation of the region.
get_vertices()	This method returns a list of four (x,y) points covering the region.
get_xy()	This method returns pin location (x,y).
is_valid()	Use this method to check whether the instance is valid.
items()
keys()
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised
popitem(/)	Remove and return a (key, value) pair as a 2-tuple.
setdefault(key[, default])	Insert key with a value of default if key is not in the dictionary.
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()

__init__(map, pin_name)

Initialize self. See help(type(self)) for accurate signature.

is_valid() → bool

Use this method to check whether the instance is valid. Accessing to an invalid instance may cause run-time error.

Returns

bool

The validity of this pin.

get_vertices() → List[Tuple[int, int]]

This method returns a list of four (x,y) points covering the region.

Returns

List[Tuple[int,int]]

It returns a list of four (x,y) points on the map.

get_shape()

This method returns the width, height and orientation of the region.

Returns

Tuple[int,int,int]

It returns a tuple (width,height,orientation) describing the region. The orientation is given in degree.