mappymatch.constructs.geofence

Classes

Geofence(crs, geometry)

A geographic boundary polygon with an associated coordinate reference system (CRS).

class mappymatch.constructs.geofence.Geofence(crs: CRS, geometry: Polygon)

A geographic boundary polygon with an associated coordinate reference system (CRS).

A Geofence defines a spatial region used to constrain map data or filter geographic queries. It's commonly used to download only the relevant portion of a road network for map matching by creating a buffer around a GPS trajectory.

Args:

crs: The coordinate reference system of the geofence geometry geometry: A Shapely Polygon defining the geographic boundary

Attributes:

crs: The CRS of the geofence geometry: The Polygon geometry representing the bounded area

Examples:

>>> from mappymatch.constructs.geofence import Geofence
>>>
>>> # Create a geofence from a trace to download relevant map data
>>> trace = Trace.from_gpx('route.gpx')
>>> geofence = Geofence.from_trace(trace, padding=1000)  # 1km buffer
>>>
>>> # Load a geofence from a GeoJSON file
>>> geofence = Geofence.from_geojson('city_boundary.geojson')
>>>
>>> # Export to GeoJSON
>>> geojson_str = geofence.to_geojson()

classmethod from_geojson(file: Path | str) → Geofence

Create a geofence from a GeoJSON file containing a polygon.

The GeoJSON file must contain exactly one polygon feature and must include CRS information. This is typically used to define study areas or regions for downloading map data.

Args:

file: Path to the GeoJSON file (as string or Path object)

Returns:

A new Geofence instance

Raises:

TypeError: If the file contains multiple polygons or lacks CRS information

Examples:

>>> # Load a boundary polygon
>>> geofence = Geofence.from_geojson('study_area.geojson')
>>> print(geofence.crs)  # EPSG:4326

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

Create a geofence by buffering around a GPS trace.

This method creates a polygonal boundary around a trace by converting the trace to a LineString, creating a buffer zone around the line, and transforming to the specified CRS.

This is particularly useful for downloading map data that covers a GPS trajectory, ensuring you get all relevant roads while minimizing unnecessary data.

Args:

trace: The GPS trace to create a boundary around padding: The buffer distance in meters around the trace. Default is 1000m (1km). crs: The target coordinate reference system for the geofence. Default is WGS84 (EPSG:4326). buffer_res: The resolution of the buffer polygon (number of segments per quadrant). Lower values create simpler polygons. Default is 2.

Returns:

A new Geofence encompassing the trace with the specified padding

Examples:

>>> # Create a 500m buffer around a trace for map download
>>> trace = Trace.from_csv('morning_commute.csv')
>>> geofence = Geofence.from_trace(trace, padding=500)
>>>
>>> # Create a larger 2km buffer with higher resolution
>>> geofence = Geofence.from_trace(trace, padding=2000, buffer_res=8)

to_geojson() → str

Convert the geofence to a GeoJSON string.

The geofence is automatically transformed to WGS84 (EPSG:4326) if it's in a different CRS, since GeoJSON uses lat/lon coordinates by convention.

Returns:

A GeoJSON string representation of the geofence polygon

Examples:

>>> geofence = Geofence.from_trace(trace, padding=1000)
>>> geojson_str = geofence.to_geojson()
>>> # Write to file
>>> with open('boundary.geojson', 'w') as f:
...     f.write(geojson_str)