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) mappymatch.constructs.coordinate.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) mappymatch.constructs.coordinate.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: pyproj.crs.crs.CRS, geometry: shapely.geometry.polygon.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: Union[pathlib.Path, str]) mappymatch.constructs.geofence.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) mappymatch.constructs.geofence.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.
Match
- class Match(road: Optional[mappymatch.constructs.road.Road], coordinate: mappymatch.constructs.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
Optional[mappymatch.constructs.road.Road]
- coordinate
The original coordinate that was matched;
- distance
The distance to the matched road; If no road was found, this is infinite
- Type
float
- set_coordinate(c: mappymatch.constructs.coordinate.Coordinate)[source]
Set the coordinate of this match
- Parameters
c – The new coordinate
- Returns
The match with the new coordinate
Road
- class Road(road_id: RoadId, geom: LineString, metadata: Optional[dict] = None)[source]
Represents a road that can be matched to;
- road_id
The unique identifier for this road
- 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
Optional[dict]
Trace
- class Trace(frame: geopandas.geodataframe.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[mappymatch.constructs.coordinate.Coordinate]
Get coordinates as Coordinate objects.
- property crs: pyproj.crs.crs.CRS
Get Coordinate Reference System(CRS) to underlying GeoDataFrame.
- downsample(npoints: int) mappymatch.constructs.trace.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) mappymatch.constructs.trace.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: Union[str, pathlib.Path], xy: bool = True, lat_column: str = 'latitude', lon_column: str = 'longitude') mappymatch.constructs.trace.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: pandas.core.frame.DataFrame, xy: bool = True, lat_column: str = 'latitude', lon_column: str = 'longitude') mappymatch.constructs.trace.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: geopandas.geodataframe.GeoDataFrame, xy: bool = True) mappymatch.constructs.trace.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: Union[str, pathlib.Path], index_property: Optional[str] = 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: Union[str, pathlib.Path], xy: bool = True) mappymatch.constructs.trace.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: Union[str, pathlib.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: pandas.core.indexes.base.Index
Get index to underlying GeoDataFrame.
- to_crs(new_crs: pyproj.crs.crs.CRS) mappymatch.constructs.trace.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