terrain¶
terrain ¶
PyAERMOD Terrain Processing Pipeline
Downloads DEM data from USGS, runs AERMAP terrain preprocessor, parses output, and updates receptor/source elevations.
Requires: pip install pyaermod[terrain]
DEMTileInfo
dataclass
¶
Metadata for a single DEM tile from USGS.
DEMDownloader ¶
Downloads USGS 3DEP (1/3 arc-second NED) elevation data.
Uses the USGS TNM (The National Map) API to find and download DEM tiles covering a bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cache_dir
|
Path or str
|
Directory to cache downloaded tiles. Defaults to ~/.pyaermod/dem_cache. |
None
|
dataset
|
str
|
USGS dataset name. |
'National Elevation Dataset (NED) 1/3 arc-second'
|
find_tiles ¶
Find DEM tiles covering a bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bounds
|
tuple
|
(west, south, east, north) in decimal degrees (WGS84). |
required |
Returns:
| Type | Description |
|---|---|
list of DEMTileInfo
|
|
download_tile ¶
Download a single DEM tile.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tile
|
DEMTileInfo
|
Tile to download. |
required |
output_dir
|
Path
|
Where to save. Defaults to cache_dir. |
None
|
Returns:
| Type | Description |
|---|---|
Path to downloaded file.
|
|
download_dem ¶
download_dem(bounds: Tuple[float, float, float, float], output_dir: Optional[Union[str, Path]] = None) -> List[Path]
Download all DEM tiles covering a bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bounds
|
tuple
|
(west, south, east, north) in decimal degrees (WGS84). |
required |
output_dir
|
Path or str
|
Directory to save tiles. Defaults to cache_dir. |
None
|
Returns:
| Type | Description |
|---|---|
list of Path
|
|
AERMAPRunResult
dataclass
¶
Result from an AERMAP execution.
AERMAPRunner ¶
Execute AERMAP terrain preprocessor from Python.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
executable_path
|
Path or str
|
Path to AERMAP executable. If None, searches PATH. |
None
|
log_level
|
str
|
Logging level. |
'INFO'
|
run ¶
run(input_file: Union[str, Path], working_dir: Optional[Union[str, Path]] = None, timeout: int = 3600, capture_output: bool = True) -> AERMAPRunResult
Execute AERMAP with given input file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_file
|
Path or str
|
Path to AERMAP input file. |
required |
working_dir
|
Path or str
|
Working directory. Defaults to input file's parent. |
None
|
timeout
|
int
|
Maximum execution time in seconds. |
3600
|
capture_output
|
bool
|
Whether to capture stdout/stderr. |
True
|
Returns:
| Type | Description |
|---|---|
AERMAPRunResult
|
|
AERMAPOutputParser ¶
Parse AERMAP receptor and source output files.
Output format verified against AERMAP Fortran source code (v24142).
parse_receptor_output
staticmethod
¶
Parse AERMAP receptor output to extract elevations and hill heights.
Handles both discrete (DISCCART) and grid (GRIDCART ELEV/HILL) formats.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filepath
|
Path or str
|
Path to AERMAP receptor output file. |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
Columns: x, y, zelev, zhill |
parse_source_output
staticmethod
¶
Parse AERMAP source output to extract base elevations.
Format: "SO LOCATION srcid(A12) type(A8) x(F12.2) y(F12.2) zelev(F12.2)"
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filepath
|
Path or str
|
Path to AERMAP source output file. |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
Columns: source_id, source_type, x, y, zelev |
TerrainProcessor ¶
High-level terrain processing pipeline.
Coordinates DEM download, AERMAP input generation, execution, and elevation updates for an AERMOD project.
create_aermap_project_from_aermod ¶
create_aermap_project_from_aermod(aermod_project, dem_files: List[str], utm_zone: int = 16, datum: str = 'NAD83')
Create an AERMAPProject from an AERMODProject.
Extracts source and receptor locations from the AERMOD project and builds corresponding AERMAP input.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
aermod_project
|
AERMODProject
|
|
required |
dem_files
|
list of str
|
|
required |
utm_zone
|
int
|
|
16
|
datum
|
str
|
|
'NAD83'
|
Returns:
| Type | Description |
|---|---|
AERMAPProject
|
|
process ¶
process(project, bounds: Tuple[float, float, float, float], aermap_exe: Optional[Union[str, Path]] = None, working_dir: Optional[Union[str, Path]] = None, utm_zone: int = 16, datum: str = 'NAD83', skip_download: bool = False, dem_files: Optional[List[str]] = None, timeout: int = 3600)
Run the full terrain processing pipeline.
Steps: 1. Download DEM tiles (or use provided files) 2. Generate AERMAP input from AERMOD project 3. Run AERMAP 4. Parse output and update project elevations
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project
|
AERMODProject
|
|
required |
bounds
|
tuple
|
(west, south, east, north) in decimal degrees. |
required |
aermap_exe
|
Path or str
|
|
None
|
working_dir
|
Path or str
|
|
None
|
utm_zone
|
int
|
|
16
|
datum
|
str
|
|
'NAD83'
|
skip_download
|
bool
|
Skip DEM download (use dem_files instead). |
False
|
dem_files
|
list of str
|
Pre-existing DEM files. |
None
|
timeout
|
int
|
AERMAP execution timeout in seconds. |
3600
|
Returns:
| Type | Description |
|---|---|
AERMODProject
|
Updated project with receptor elevations. |
run_aermap ¶
run_aermap(input_file: Union[str, Path], executable_path: Optional[Union[str, Path]] = None, timeout: int = 3600) -> AERMAPRunResult
Quick function to run AERMAP.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_file
|
Path or str
|
|
required |
executable_path
|
Path or str
|
|
None
|
timeout
|
int
|
|
3600
|
Returns:
| Type | Description |
|---|---|
AERMAPRunResult
|
|