geospatial

geospatial

PyAERMOD Geospatial Utilities

Coordinate transformations (UTM <-> WGS84), GeoDataFrame creation, contour polygon generation, and GIS export (GeoTIFF, Shapefile, GeoPackage).

Requires optional dependencies: pyproj, geopandas, rasterio, shapely. Install with: pip install pyaermod[geo]

CoordinateTransformer dataclass

Bidirectional UTM <-> WGS84 coordinate transformer.

Parameters:

Name	Type	Description	Default
utm_zone	int	UTM zone number (1-60).	required
hemisphere	str	'N' or 'S' for northern/southern hemisphere. Default 'N'.	'N'
datum	str	Datum string: 'WGS84', 'NAD83', or 'NAD27'. Default 'WGS84'.	'WGS84'

utm_crs property

utm_crs

Return the pyproj.CRS for this UTM zone.

geographic_crs property

geographic_crs

Return the WGS84 geographic pyproj.CRS.

from_aermap_domain classmethod

from_aermap_domain(domain) -> CoordinateTransformer

Create transformer from an AERMAPDomain object.

Reads utm_zone and datum from the domain. Hemisphere is inferred as 'N' (AERMOD is predominantly used in the northern hemisphere); override after creation if needed.

from_latlon classmethod

from_latlon(latitude: float, longitude: float, datum: str = 'WGS84') -> CoordinateTransformer

Auto-detect UTM zone from a lat/lon point.

utm_to_latlon

utm_to_latlon(x: float, y: float) -> Tuple[float, float]

Convert UTM easting/northing to (latitude, longitude).

latlon_to_utm

latlon_to_utm(lat: float, lon: float) -> Tuple[float, float]

Convert (latitude, longitude) to UTM (easting, northing).

transform_dataframe

transform_dataframe(df: DataFrame, x_col: str = 'x', y_col: str = 'y', to_latlon: bool = True) -> pd.DataFrame

Add transformed coordinate columns to a DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame.	required
x_col	str	Column names for existing coordinates.	'x'
y_col	str	Column names for existing coordinates.	'x'
to_latlon	bool	If True (default), adds latitude and longitude columns by converting UTM to WGS84. If False, adds utm_x and utm_y columns by converting lat/lon to UTM.	True

Returns:

Type	Description
DataFrame	Copy of df with new columns appended.

GeoDataFrameFactory

Create GeoDataFrames from pyaermod objects.

Parameters:

Name	Type	Description	Default
transformer	CoordinateTransformer	Coordinate transformer for CRS assignment.	required

sources_to_geodataframe

sources_to_geodataframe(sources: list) -> gpd.GeoDataFrame

Convert a list of source objects to a GeoDataFrame.

Returns Point geometries for point/area/volume/circular sources, LineString geometries for line/rline sources, and Polygon geometries for polygonal area sources.

sources_from_results

sources_from_results(results) -> gpd.GeoDataFrame

Convert parsed AERMODResults source summaries to a GeoDataFrame.

receptors_to_geodataframe

receptors_to_geodataframe(receptors) -> gpd.GeoDataFrame

Convert a ReceptorPathway to a GeoDataFrame of receptor points.

Expands CartesianGrid and PolarGrid definitions into individual receptor locations.

concentrations_to_geodataframe

concentrations_to_geodataframe(df: DataFrame, value_col: str = 'concentration', x_col: str = 'x', y_col: str = 'y') -> gpd.GeoDataFrame

Convert a concentration DataFrame to a GeoDataFrame with Point geometries.

postfile_to_geodataframe

postfile_to_geodataframe(result, timestep: Optional[str] = None) -> gpd.GeoDataFrame

Convert a PostfileResult to a GeoDataFrame.

Parameters:

Name	Type	Description	Default
result	PostfileResult	Parsed POSTFILE data.	required
timestep	str	If given, filter to this YYMMDDHH date string.	None

ContourGenerator

Generate contour polygons from concentration data.

Uses scipy.griddata interpolation and matplotlib contourf to compute filled contour paths, then converts them to Shapely Polygons.

Parameters:

Name	Type	Description	Default
transformer	CoordinateTransformer	For CRS assignment on output GeoDataFrames.	required

generate_contours

generate_contours(df: DataFrame, levels: Optional[List[float]] = None, n_levels: int = 10, method: str = 'cubic', grid_resolution: int = 200, x_col: str = 'x', y_col: str = 'y', value_col: str = 'concentration') -> gpd.GeoDataFrame

Generate filled contour polygons as a GeoDataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	Must contain x_col, y_col, and value_col columns.	required
levels	list of float	Explicit contour levels. If None, n_levels equally-spaced levels are computed from the data range.	None
n_levels	int	Number of auto-computed levels when levels is None.	10
method	str	Interpolation method for scipy.interpolate.griddata.	'cubic'
grid_resolution	int	Number of cells in each direction for the interpolation grid.	200
x_col	str	Column names.	'x'
y_col	str	Column names.	'x'
value_col	str	Column names.	'x'

Returns:

Type	Description
GeoDataFrame	Columns: geometry, level_min, level_max, level_label. CRS is set to the UTM CRS of the transformer.

generate_contours_latlon

generate_contours_latlon(df: DataFrame, **kwargs) -> gpd.GeoDataFrame

Same as generate_contours but reprojected to WGS84 (EPSG:4326).

RasterExporter

Export concentration data as georeferenced GeoTIFF rasters.

Parameters:

Name	Type	Description	Default
transformer	CoordinateTransformer	Provides the CRS for the output raster.	required

export_geotiff

export_geotiff(df: DataFrame, output_path: Union[str, Path], resolution: Optional[float] = None, method: str = 'cubic', nodata: float = -9999.0, x_col: str = 'x', y_col: str = 'y', value_col: str = 'concentration') -> Path

Export a concentration DataFrame as a single-band GeoTIFF.

Parameters:

Name	Type	Description	Default
df	DataFrame	Must have x_col, y_col, and value_col columns.	required
output_path	str or Path	Destination .tif file.	required
resolution	float	Pixel size in meters. If None, auto-detected from data spacing.	None
method	str	Interpolation method for scipy.interpolate.griddata.	'cubic'
nodata	float	NoData value written to the raster.	-9999.0

Returns:

Type	Description
Path	The written file path.

VectorExporter

Export pyaermod data as vector GIS files (Shapefile, GeoPackage, GeoJSON).

Parameters:

Name	Type	Description	Default
factory	GeoDataFrameFactory	For creating GeoDataFrames from pyaermod objects.	required

export_sources

export_sources(sources: list, output_path: Union[str, Path], driver: str = 'GPKG') -> Path

Export source objects as a vector file.

export_receptors

export_receptors(receptors, output_path: Union[str, Path], driver: str = 'GPKG') -> Path

Export receptor locations as a point vector file.

export_concentrations

export_concentrations(df: DataFrame, output_path: Union[str, Path], driver: str = 'GPKG', as_contours: bool = False, contour_levels: Optional[List[float]] = None) -> Path

Export concentration data as points or contour polygons.

Parameters:

Name	Type	Description	Default
df	DataFrame	Concentration DataFrame with x, y, concentration columns.	required
output_path	str or Path	Output file path.	required
driver	str	OGR driver name ('GPKG', 'ESRI Shapefile', 'GeoJSON').	'GPKG'
as_contours	bool	If True, generate filled contour polygons instead of points.	False
contour_levels	list of float	Contour levels (only used when as_contours=True).	None

export_all

export_all(project, results=None, output_dir: Union[str, Path] = '.', driver: str = 'GPKG') -> Dict[str, Path]

Export all project components to a directory.

Parameters:

Name	Type	Description	Default
project	AERMODProject	The project to export.	required
results	AERMODResults	Parsed results (required for concentration export).	None
output_dir	str or Path	Output directory.	'.'
driver	str	OGR driver.	'GPKG'

Returns:

Type	Description
dict	Mapping of component name to output file path.

utm_to_latlon

utm_to_latlon(x: float, y: float, utm_zone: int, hemisphere: str = 'N', datum: str = 'WGS84') -> Tuple[float, float]

Quick single-point UTM to (latitude, longitude) conversion.

latlon_to_utm

latlon_to_utm(lat: float, lon: float, datum: str = 'WGS84') -> Tuple[float, float, int, str]

Quick single-point (lat, lon) to UTM conversion.

Returns:

Type	Description
tuple	(easting, northing, utm_zone, hemisphere)

export_concentration_geotiff

export_concentration_geotiff(df: DataFrame, output_path: Union[str, Path], utm_zone: int, hemisphere: str = 'N', datum: str = 'WGS84', **kwargs) -> Path

One-liner GeoTIFF export from a concentration DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	Must have x, y, concentration columns.	required
output_path	str or Path	Destination .tif file.	required
utm_zone	int	UTM zone number.	required
**kwargs		Passed to RasterExporter.export_geotiff.	{}

Returns:

Type	Description
Path	Written file path.

export_concentration_shapefile

export_concentration_shapefile(df: DataFrame, output_path: Union[str, Path], utm_zone: int, hemisphere: str = 'N', datum: str = 'WGS84', as_contours: bool = True, driver: str = 'GPKG', **kwargs) -> Path

One-liner vector export from a concentration DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	Must have x, y, concentration columns.	required
output_path	str or Path	Destination file.	required
utm_zone	int	UTM zone number.	required
as_contours	bool	If True, export filled contour polygons; if False, export points.	True
driver	str	OGR driver name (default 'GPKG').	'GPKG'

Returns:

Type	Description
Path	Written file path.