loader.OSMLoader

osm.loader.OSMLoader(
    osm_tags,
    aligner,
    *,
    included_attributes=None,
    include_directional_attributes=False,
)

Loader for OpenStreetMap (OSM) features based on specific tags.

This loader uses the osmnx library to fetch geographical features from OpenStreetMap within a buffered bounding box of the thematic data. It automatically handles Coordinate Reference System (CRS) transformations between the project CRS and the WGS84 system required by OSM.

Parameters

Name	Type	Description	Default
osm_tags	dict	A dictionary of OSM tags used to filter features (e.g., {‘highway’: True} of {‘building’: ‘industrial’}).	required
aligner	Aligner	The aligner object providing the spatial context, target CRS, and logger.	required
included_attributes	Iterable[str] | None	Optional whitelist of OSM attribute names to keep in feature properties. - If None (default), all attributes returned by OSMNX are retained. - If provided, only these attributes are kept (plus optional directional attributes when include_directional_attributes=True).	None
include_directional_attributes	bool	If True, ensure common direction-related OSM attributes are included in feature properties (e.g. oneway, junction, lane/turn-direction fields), even when an included_attributes whitelist is used.	False

Attributes

Name	Type	Description
aligner	Aligner	Reference to the parent aligner object.
osm_tags	dict	The tags used for filtering OSM data.
included_attributes	set[str] | None	Effective attribute whitelist (or None when all attributes are kept).
include_directional_attributes	bool	Flag indicating whether direction-related attributes are always included.
data_dict_source	dict	Metadata dictionary tracking the data source (“OSM”) and version date.
versiondate_info	dict	Dictionary specifying the version date field name and format.

Methods

Name	Description
load_data	Download and process OSM features.

load_data

osm.loader.OSMLoader.load_data()

Download and process OSM features.

The process involves: 1. Buffering the thematic union to define the search area. 2. Transforming the search area to WGS84 (EPSG:4326). 3. Fetching features via osmnx based on the provided tags. 4. Re-projecting the downloaded features back to the Aligner’s CRS. 5. Optionally filtering/stabilizing attribute payload in properties.

Returns

Name	Type	Description
	Any	The result of the parent DictLoader’s load_data method, containing the downloaded geometries and metadata.

Raises

Name	Type	Description
	ValueError	If thematic data has not been loaded into the aligner prior to calling this method.

Notes

The search area is expanded using OSM_MAX_REFERENCE_BUFFER to ensure that reference features partially outside the thematic area are fully captured for alignment.

Attribute handling: - Default behavior keeps all attributes returned by OSMNX. - Use included_attributes to reduce payload and improve downstream performance/memory usage. - Use include_directional_attributes=True for directed-network use cases where one-way and lane direction metadata is relevant.