Constructs

Constructs are the fundamental data structures shared between all matching implementations. For readability, the full path is listed below and not used in other parts of the documentation.

Available Constructs

For readability, the full path is listed below and not used in other parts of the documentation.

Coordinate

class Coordinate(coordinate_id: Any, geom: Point, crs: CRS)[source]

Represents a single coordinate with a CRS and a geometry

coordinate_id

The unique identifier for this coordinate

Type:

Any

geom

The geometry of this coordinate

Type:

shapely.geometry.point.Point

crs

The CRS of this coordinate

Type:

pyproj.crs.crs.CRS

x

The x value of this coordinate

y

The y value of this coordinate

classmethod from_lat_lon(lat: float, lon: float) → Coordinate[source]

Build a coordinate from a latitude/longitude

Parameters:

  • lat – The latitude

  • lon – The longitude

Returns:

A new coordinate

to_crs(new_crs: Any) → Coordinate[source]

Convert this coordinate to a new CRS

Parameters:

new_crs – The new CRS to convert to

Returns:

A new coordinate with the new CRS

Raises:

A ValueError if it fails to convert the coordinate –

Geofence

class Geofence(crs: CRS, geometry: Polygon)[source]

A geofence is basically a shapely polygon with a CRS

Parameters:

  • geom – The polygon geometry of the geofence

  • crs – The CRS of the geofence

classmethod from_geojson(file: Path | str) → Geofence[source]

Creates a new geofence from a geojson file.

Parameters:

file – The path to the geojson file

Returns:

A new geofence

classmethod from_trace(trace: ~mappymatch.constructs.trace.Trace, padding: float = 1000.0, crs: ~pyproj.crs.crs.CRS = <Geographic 2D CRS: EPSG:4326> Name: WGS 84 Axis Info [ellipsoidal]: - Lat[north]: Geodetic latitude (degree) - Lon[east]: Geodetic longitude (degree) Area of Use: - name: World. - bounds: (-180.0, -90.0, 180.0, 90.0) Datum: World Geodetic System 1984 ensemble - Ellipsoid: WGS 84 - Prime Meridian: Greenwich, buffer_res: int = 2) → Geofence[source]

Create a new geofence from a trace.

This is done by computing a radial buffer around the entire trace (as a line).

Parameters:

  • trace – The trace to compute the bounding polygon for.

  • padding – The padding (in meters) around the trace line.

  • crs – The coordinate reference system to use.

  • buffer_res – The resolution of the surrounding buffer.

Returns:

The computed bounding polygon.

to_geojson() → str[source]

Converts the geofence to a geojson string.

Match

class Match(road: Road | None, coordinate: Coordinate, distance: float)[source]

Represents a match made by a Matcher

road

The road that was matched; None if no road was found;

Type:

mappymatch.constructs.road.Road | None

coordinate

The original coordinate that was matched;

Type:

mappymatch.constructs.coordinate.Coordinate

distance

The distance to the matched road; If no road was found, this is infinite

Type:

float

set_coordinate(c: Coordinate)[source]

Set the coordinate of this match

Parameters:

c – The new coordinate

Returns:

The match with the new coordinate

to_flat_dict() → dict[source]

Convert this match to a flat dictionary

Returns:

A flat dictionary with all match information

Road

class Road(road_id: RoadId, geom: LineString, metadata: dict | None = None)[source]

Represents a road that can be matched to;

road_id

The unique identifier for this road

Type:

mappymatch.constructs.road.RoadId

geom

The geometry of this road

Type:

shapely.geometry.linestring.LineString

origin_junction_id

The unique identifier of the origin junction of this road

destination_junction_id

The unique identifier of the destination junction of this road

metadata

an optional dictionary for storing additional metadata

Type:

dict | None

to_dict() → Dict[str, Any][source]

Convert the road to a dictionary

to_flat_dict() → Dict[str, Any][source]

Convert the road to a flat dictionary

class RoadId(start, end, key)[source]

Trace

class Trace(frame: GeoDataFrame)[source]

A Trace is a collection of coordinates that represents a trajectory to be matched.

coords

A list of all the coordinates

crs

The CRS of the trace

index

The index of the trace

property coords: List[Coordinate]

Get coordinates as Coordinate objects.

property crs: CRS

Get Coordinate Reference System(CRS) to underlying GeoDataFrame.

downsample(npoints: int) → Trace[source]

Downsample the trace to a given number of points

Parameters:

npoints – the number of points to downsample to

Returns:

The downsampled trace

drop(index=typing.List) → Trace[source]

Remove points from the trace specified by the index parameter

Parameters:

index – the index of the points to drop (0 based index)

Returns:

The trace with the points removed

classmethod from_csv(file: str | Path, xy: bool = True, lat_column: str = 'latitude', lon_column: str = 'longitude') → Trace[source]

Builds a trace from a csv file.

Expects the file to have latitude / longitude information in the epsg 4326 format

Parameters:

  • file – the csv file

  • xy – should the trace be projected to epsg 3857?

  • lat_column – the name of the latitude column

  • lon_column – the name of the longitude column

Returns:

The trace built from the csv file

classmethod from_dataframe(dataframe: DataFrame, xy: bool = True, lat_column: str = 'latitude', lon_column: str = 'longitude') → Trace[source]

Builds a trace from a pandas dataframe

Expects the dataframe to have latitude / longitude information in the epsg 4326 format

Parameters:

  • dataframe – pandas dataframe with _one_ trace

  • xy – should the trace be projected to epsg 3857?

  • lat_column – the name of the latitude column

  • lon_column – the name of the longitude column

Returns:

The trace built from the pandas dataframe

classmethod from_geo_dataframe(frame: GeoDataFrame, xy: bool = True) → Trace[source]

Builds a trace from a geopandas dataframe

Expects the dataframe to have geometry column

Parameters:

  • frame – geopandas dataframe with _one_ trace

  • xy – should the trace be projected to epsg 3857?

Returns:

The trace built from the geopandas dataframe

classmethod from_geojson(file: str | Path, index_property: str | None = None, xy: bool = True)[source]

Reads a trace from a geojson file; If index_property is not specified, this will set any property columns as the index.

Parameters:

  • file – the geojson file

  • index_property – the name of the property to use as the index

  • xy – should the trace be projected to epsg 3857?

Returns:

The trace built from the geojson file

classmethod from_gpx(file: str | Path, xy: bool = True) → Trace[source]

Builds a trace from a gpx file.

Expects the file to have simple gpx structure: a sequence of lat, lon pairs

Parameters:

  • file – the gpx file

  • xy – should the trace be projected to epsg 3857?

Returns:

The trace built from the gpx file

classmethod from_parquet(file: str | Path, xy: bool = True)[source]

Read a trace from a parquet file

Parameters:

  • file – the parquet file

  • xy – should the trace be projected to epsg 3857?

Returns:

The trace built from the parquet file

property index: Index

Get index to underlying GeoDataFrame.

to_crs(new_crs: CRS) → Trace[source]

Converts the crs of a trace to a new crs

Parameters:

new_crs – the new crs to convert to

Returns:

A new trace with the new crs

to_geojson(file: str | Path)[source]

Write the trace to a geojson file

Parameters:

file – the file to write to