pydsstools.core.gridinfo.albers

Albers grid type implementation and SHG utilities.

This module provides the AlbersInfo class and utilities for Standard Hydrologic Grid (SHG) commonly used in HEC-HMS modeling. SHG uses Albers Equal Area Conic projection with NAD83 datum.

Functions

`build_shg_gridinfo`(shape, cell_size, min_xy, ...)	Create a Standard Hydrologic Grid (SHG) with default parameters.
`update_albers_from_crs`(gridinfo, crs_wkt)	Update Albers projection parameters from CRS WKT string.

Classes

AlbersInfo(**data)

Metadata for Albers Equal Area Conic projection grid.

class pydsstools.core.gridinfo.albers.AlbersInfo(**data)[source]

Bases: GridInfo

Metadata for Albers Equal Area Conic projection grid.

Albers grids are commonly used for the Standard Hydrologic Grid (SHG) in HEC-HMS, typically using NAD83 datum with CONUS Albers parameters (EPSG:5070).

In addition to the parameters inherited from GridInfo, this class adds projection parameters for Albers Equal Area Conic projection.

Examples

Create standard SHG grid:

>>> from pydsstools.core.gridinfo import build_shg_gridinfo, DataType
>>> info = build_shg_gridinfo(
...     shape=(500, 700),
...     cell_size=2000.0,  # 2 km cells
...     min_xy=(-1500000, 500000),  # SW corner in EPSG:5070
...     data_type=DataType.inst_val,
...     data_units="M"
... )

Create custom Albers grid:

>>> from pydsstools.core.gridinfo import AlbersInfo, Datum
>>> info = AlbersInfo(
...     grid_type=GridType.albers,
...     data_type=DataType.per_aver,
...     shape=(300, 400),
...     cell_size=5000.0,
...     proj_datum=Datum.nad83,
...     lat_0=37.0,
...     lat_1=34.0,
...     lat_2=40.5,
...     lon_0=-120.0,
...     data_units="MM"
... )

Update from CRS WKT:

>>> wkt = "PROJCS[...]"  # Full WKT string
>>> info = AlbersInfo(...)
>>> update_albers_from_crs(info, wkt)

Notes

Albers Projection Properties:

Equal-area conic projection
Preserves area (important for hydrologic modeling)
Minimizes distortion along standard parallels
Suitable for east-west oriented regions (e.g., CONUS)

Standard Hydrologic Grid (SHG) Default Parameters (EPSG:5070):

Datum: NAD83
Units: meter
Origin latitude: 23.0°N
First parallel: 29.5°N
Second parallel: 45.5°N
Central meridian: -96.0°W
False easting/northing: 0, 0

Grid Coordinate Concepts:

For Albers/SHG grids, two coordinate pairs are critical:

coords_cell0: Coordinates of cell (0,0) in the global grid system. Usually equals (false_easting, false_northing) = (0, 0) for SHG. Defines the projection origin.
lower_left_cell: Cell indices of your grid’s lower-left corner. Calculated as: (floor((xmin - x_0) / cellsize), floor((ymin - y_0) / cellsize)). Indicates which cell in the global SHG grid corresponds to your grid origin.

This allows multiple grid datasets to be spatially referenced in the same coordinate system.

Typical Users:

HEC-HMS for watershed modeling
HEC-RAS for floodplain mapping
Hydrologic modeling in the United States

References

[albers1]

HEC-HMS Technical Reference Manual https://www.hec.usace.army.mil/confluence/hmsdocs/

[albers2]

Standard Hydrologic Grid (SHG) https://www.hec.usace.army.mil/confluence/hmsdocs/hmsum/4.8/geographic-information/coordinate-reference-systems

grid_type

Type of grid projection. Only albers and albers_time are valid. Default GridType.albers_time.

Type:: GridType

proj_datum

Datum for the projection. Default Datum.nad83.

Type:: Datum

proj_units

Linear units of the projection. Default "meter".

Type:: str

lat_0

Latitude of projection origin (degrees). Default 23.0.

Type:: float

lat_1

Latitude of first standard parallel (degrees). Default 29.5.

Type:: float

lat_2

Latitude of second standard parallel (degrees). Default 45.5.

Type:: float

lon_0

Longitude of central meridian (degrees). Default -96.0.

Type:: float

x_0

False easting (projection units). Default 0.0.

Type:: float

y_0

False northing (projection units). Default 0.0.

Type:: float

coords_cell0

(easting, northing) of southwest corner of cell (0,0). Default (0.0, 0.0).

Type:: tuple[float, float] or None

update_lower_left_cell_from_minxy()[source]

Update lower_left_cell indices from min_xy coordinates.

Calculates the cell indices for the lower-left corner of the grid based on min_xy and the projection origin (coords_cell0).

Raises:: ValueError – If min_xy is not set.

Notes

Modifies lower_left_cell in-place.

update_lower_left_cell_from_transform(transform)[source]

Update lower_left_cell indices from affine transform.

Parameters:: transform (Affine) – 6-element affine transform: (dx, 0, xmin, 0, dy, ymax).
Raises:: ValueError – If cell size in transform doesn’t match gridinfo cell_size.

Notes

Modifies lower_left_cell in-place.

update_crs_params(crs_wkt)[source]

normalize(transform=None)[source]

Normalize coords_cell0 and/or lower_left_cell based on grid_type.

This is implemented in the concrete classes.

Parameters:: transform (Affine or None, optional) – Affine transform of grid or raster data. Default is None.

pydsstools.core.gridinfo.albers.build_shg_gridinfo(shape, cell_size, min_xy, data_type, data_units='', **kwargs)[source]

Create a Standard Hydrologic Grid (SHG) with default parameters.

This is a convenience function that creates an AlbersInfo with standard SHG parameters (NAD83 / Conus Albers, EPSG:5070).

Parameters:

shape (tuple[int, int]) – Grid dimensions as (rows, columns).
cell_size (float) – Cell size in meters.
min_xy (tuple[float, float]) – Minimum (x, y) coordinates in EPSG:5070 (meters).
data_type (DataType) – Temporal data type.
data_units (str, optional) – Physical units of data (e.g., “MM”, “M”).
**kwargs – Additional parameters passed to AlbersInfo constructor.

Returns:

Configured SHG grid info with lower_left_cell calculated.

Return type:

AlbersInfo

Examples

>>> from pydsstools.core.gridinfo import build_shg_gridinfo, DataType
>>> info = build_shg_gridinfo(
...     shape=(500, 700),
...     cell_size=2000.0,
...     min_xy=(-1500000, 500000),
...     data_type=DataType.inst_val,
...     data_units="M"
... )
>>> print(info.lower_left_cell)
(-750, 250)