map.mapinfo module

Module mapdata is the module interfacing with a digital map. It contains MapInfo class that specifies interfaces to access the map during the simulation. The class contains several key information for simulation to use: (i) the bitmap of a map, (ii) the user defined pins on the map, (iii) path-finding between two pins. Internally, the class also contains the graph data structure corresponding to the map, which is needed for path finding. The path-finding algorithm used in the class is the A*STAR algorithm.

To construct and make it ready to use, it provides convenient load_file() functions which can load an image file for the map, and the corresponding JSON file descrbing the graph data structure and the user defined pin locations. These two files can be generated and downloaded online from our website (still under development). Then users can use editpins.jar to locally edit the pins in the map.

In the simulation, a user scenario can set a background using the provided bitmap as well as use this class to access to pin information and perform path-finding between two pins.

There are some methods created specifically for map editor. The method names start with editor_. They should not be used in the simulation. All these methods will soon be removed.

Note

• Created by: CH Foh (2021)

class map.mapinfo.MapInfo

Bases: object

This is a class to provide access to information of a map during the simulation. A map generally contains the following:

• a bitmap image for display

• a graph data structure, including:

  • graph vertices, also called coords, containing (id,x,y). In OSM, this is called a node.

  • graph links, describing how a vertex connects to its neighbouring vertices in a straight line.

• information on the map:

  • map objects, a group of connected vertices forming either a polyline or polygon. Polylines are used for roads, rivers, railways, etc, and polygons are used for areas, buildings, train platforms, etc. In OSM, a map object is called a way (open-way for polyline, closed-way for polygon).

• pins for user defined locations.

Internally, this class contains a list of objects:

• self._bitmap: bitmap of the map as wx.Bitmap

• self._info: dictionary containing map info (see below, under “info”)

• self._coords: dictionary lookup table from id to (x,y)

• self._objs: dictionary lookup table from id to dict containing the object info

• self._neighbour_of: graph data structure of the map for path finding

• self._pins: pin database in dictionary (see the JSON below, under “pins”)

• self._intersection: a set (in dict) of data struct (in class) describing an intersection

The above information is constructed from the map data JSON file:

{
    "info": {                     # dict
        "width": width,           # integer, pixels
        "height": height,         # integer, pixels
        "resolution": resolution  # integer, pixels per km
        "minlat": min_latitude    # float
        "maxlat": max_latitude    # float
        "minlon": min_longitude   # float
        "maxlon": max_longitude   # float
        "version": map_version    # str, in "Major.Minor.Build"
    },
    "graph.vertices": { 
        vertex_id1: [x1,y1],  # a list of two integers for (x,y)
        vertex_id2: [x2,y2],
        ...
    },
    "graph.links": { 
        vertex_id5: [          # a list of neighbouring vertex_id (as integer)
            [neighbour_vertex1,obj_id1],
            [neighbour_vertex2,obj_id2],
            ...
        ] 
        vertex_id6: [...],
        ...
    },
    "map.objects": { 
        obj_id1: {
            "id": id,         # integer
            "coords": [...],  # a list of vertex_id (as integer)
            "any other key": any_value
            ...
        },
        obj_id2: {...},
        ...
    },
    "pins": [
        {                       # each pin is a dict
            "id": pin_id,       #<--must have
            "coords": [         #<--must have
                coord_id1,
                coord_id2,
                ...
            ],
            ".coord1": coord_id1,   #<--must have for waypoing & junction
            ".coord2": coord_id2,   #<--must have for waypoint
            ".obj_id": obj_id,      #<--must have for waypoint
            ".width": width,        #<--must have for region
            ".height": height,      #<--must have for region
            ".orientation": angle,  #<--must have for region
            "x": x,                 #<--x,y location of the pin, must have
            "y": y,
            "type": pin_type_str,   #<--must have
            "unique": unique_name_str, # the reference name, should be unique
            "name": any_non_unique_display_name_str,
            "user define key": any_value,
            "more user define key": any_value,
            ...
        },
        ...
    ]
}

For each pin type:

• landmark: id is a negative integer, coords contains only id.

• waypoint: id is a negative integer, coords contains three coords, which are [.coord1, id, .coord2]. It’s linked into the graph, so it’s navigable.

• junction: id is an existing map coord_id, coords contains only id.

• building: id is a negative integer, coords contains only id. .obj_id contains the id of the building on the map.

• region: id is a negative integer, coords contains only id. .width, .height and .orientation contain the region layout.

Methods

add_new_waypoint_pin(new_pin)	Use this method to manually add a waypoint pin to the map structure.
editor_assign_coord_dict(coords)	Do not use.
editor_assign_info_dict(info)	Do not use.
editor_assign_map(bitmap)	Do not use.
editor_assign_navigation_dict(navigation)	Do not use.
editor_assign_obj_dict(objs)	Do not use.
editor_assign_pin_dict(pins)	Do not use.
editor_get_pin_dict()	Do not use.
editor_load_pins(filename)	This method will load pin dictionary from the file.
editor_save_file(image_file, data_file)	Do not use.
find_path(from_pin, to_pin)	Perform path finding using A*Star algorithm.
get_all_pins([pin_type])	This method returns all pin objects (in dict) in a list.
get_bitmap()	This method returns the bitmap object of the map.
get_err_str()	Return the error message string for this class.
get_info(info)	This method returns high level information of the map.
get_intersection(coord_id)	This method checks whether a vertex of a road is an intersection.
get_obj(obj_id)	This method is a map object lookup using obj_id to retrieve the full object info.
get_pin(pin_name)	This method is a pin lookup using the unique reference pin_name to retrieve full info of the pin in dict.
get_pin_xy(pin_name)	This method returns the (x,y) location of the given pin.
get_xy(coord_id)	This method is a coordinate lookup using coord_id to retrieve the (x,y) pixel location of the coord_id on the map image.
is_ready()	Test if the instance has a valid map to enable other methods in this class.
km(length_in_kilometer)	It returns the number of pixels given a length in kilometers.
kph(speed[, speed_up_factor])	It translates the input parameter speed specified in km/h to the number of pixels per second that an object should move on the map.
load_file(image_file, data_file)	Load external files to initialize this class.
num_pixels(len_in_meter)	It returns the number of pixels given a length in meter.

min_version = (0, 8, 6)

Minimum map version supported by this simulator.

__init__()

This is the default constructor.

get_err_str()

Return the error message string for this class.

Returns

str

It returns None if there is no error, or the error message string. Use this method to find out the error related to loading the map data and constructing this map instance.

is_ready()

Test if the instance has a valid map to enable other methods in this class. It is important to test before accessing to other methods.

Returns

bool

It returns whether this instance is ready to use.

load_file(image_file, data_file) → bool

Load external files to initialize this class. The method will load an image file of the map and its corresponding digital information.

Parameters

image_filestr

The image filename to load.

data_filestr

The json data filename to load.

editor_load_pins(filename)

This method will load pin dictionary from the file. This should be sufficient for the editor since the editor has all other information from the StreetMap object.

editor_save_file(image_file, data_file)

Do not use.

editor_assign_map(bitmap)

Do not use.

editor_assign_info_dict(info)

Do not use.

editor_assign_coord_dict(coords)

Do not use.

editor_assign_obj_dict(objs)

Do not use.

editor_assign_navigation_dict(navigation)

Do not use.

editor_assign_pin_dict(pins)

Do not use.

editor_get_pin_dict()

Do not use.

find_path(from_pin: str, to_pin: str) → List[Tuple[int, int, int]]

Perform path finding using A*Star algorithm.

Parameters

from_pinstr

The unique name of the pin as the start location.

to_pinstr

The unique name of the pin as the end location.

add_new_waypoint_pin(new_pin)

Use this method to manually add a waypoint pin to the map structure. Instead of using this method, user simulation should just place a waypoint pin using the provided map editor directly. A placed waypoint pin will automatically be loaded to the memory.

This method shall be used only when waypoint pins are to be manually created in the code (which is not a recommended approach). The reason to manually create waypoint pins can be either that there are too many pins to create and using coding is more convenient, or the pins to be created are of temporary use so that there is no incentive to add them into the map.

Parameters

new_pindict

A dictionary containing pin information to add to the map.

get_bitmap()

This method returns the bitmap object of the map.

get_xy(coord_id) → Tuple[int, int]

This method is a coordinate lookup using coord_id to retrieve the (x,y) pixel location of the coord_id on the map image.

Note

If coord_id is not found in the lookup table, the method throws a KeyError exception.

Parameters

coord_idint

The input coordinate id.

Returns

Tuple[int,int]

The (x,y) coordiate of the input coordinate id.

get_intersection(coord_id) → List[Tuple[int, int]]

This method checks whether a vertex of a road is an intersection.

Parameters

coord_idint

The input coordinate id of the road vertex.

Returns

List[Tuple[int,int]]

A list of tuples (coord_id, obj_id), each of which is the arm of the intersection connecting to the neighbouring vertex specified by the coord_id. If the input vertex is not an intersection, the method returns None.

get_obj(obj_id) → Dict

This method is a map object lookup using obj_id to retrieve the full object info. Only navigable map object is available. The information contains whatever given in the map source specified by the map provider. The returning dictionary contains two standard keys: id and coords where id is just obj_id and coords is a list of coord_id (i.e. a list of waypoints specified by their coord_id).

Note

If the map obj_id is not found in the lookup table, the method throws a KeyError exception.

Parameters

obj_idint

The map object id to lookup for.

Returns

dict

A dictionary containing all raw information about the map object.

get_pin(pin_name) → Dict

This method is a pin lookup using the unique reference pin_name to retrieve full info of the pin in dict.

Parameters

pin_namestr

The unique reference name of the pin.

Returns

dict or None

The dictionary of the pin, or None if the pin is invalid or not found.

get_info(info: str)

This method returns high level information of the map. The information can be retrieved includes: - “width”: integer, the width of the map in pixels - “height”: integer, the height of the map in pixels - “resolution”: integer, the resolution of the map in pixels per km - “version”: str, the version of the map info format

Note

If the info is not recognized, the method throws a KeyError exception.

Parameters

infostr

The information specified in string to retrieve.

Returns

any

The retrieved information.

get_pin_xy(pin_name) → Tuple[int, int]

This method returns the (x,y) location of the given pin.

Parameters

pin_namestr

The unique reference name of the pin.

Returns

tuple (x:int,y:int) or None

The (x,y) location of the pin on the map. If no valid pin is found on the map, it returns None.

get_all_pins(pin_type=None) → List

This method returns all pin objects (in dict) in a list. See the module description for the pin dict structure. If no pin_type is given, all pins will be included in the list.

Parameters

pin_typestr, optional, default=None

The type of pins to retrieve.

Returns

List

It returns a list of pin objects. If a non-existing pin type is specified in pin_type, it returns None.

km(length_in_kilometer)

It returns the number of pixels given a length in kilometers. The number of pixels depends on the resolution of the map measured in pixels per km.

num_pixels(len_in_meter)

It returns the number of pixels given a length in meter.

Parameters

len_in_meterfloat

The length to be converted to pixels based on the map resolution.

Returns

float

The number of pixels equivalent to the length in meters.

kph(speed, speed_up_factor=1)

It translates the input parameter speed specified in km/h to the number of pixels per second that an object should move on the map. The number of pixels per second is the speed unit used in all mobility modules in the simulation, and therefore a translation is needed.

The speed_up_factor parameter is used to speed up the animation by increasing the movement. This can be useful to make a node hopping a longer range in each simulation step to speed up the simulation, by artificially increasing the speed of movement by a factor. Controlling the speed via speed_up_factor may be more convenient than simultaneously adjusting the playback speed and simulation time step.

Parameters

int

It returns the rounded number of pixels for a kilometer.