Usage

NLDI XSTools provides three tools for generating topographic cross-sections: Cross-Section at Point for stream-snapped sections, Cross-Section at Endpoints for user-defined transects, and Cross-Section at Path for multi-point paths. All accept WGS 84 longitude/latitude coordinates and return GeoDataFrames.

from nldi_xstool.nldi_xstool import getxsatpoint, getxsatendpts, getxsatpathpts

Tip

3DEP does not specifically include bathymetry. Elevation values represent the land surface. The DEM resolution parameter (res) specifies the interpolation resolution, not the native resolution of the source data. Use nldi_xstool.ancillary.query_dems to discover available native resolutions at your area of interest.

Cross-Section at Point

Snaps a point to the nearest NHD stream segment via the NLDI, then generates a perpendicular topographic cross-section using 3DEP elevation data.

Parameters

Name	Type	Description
`point`	Tuple[float, float]	Longitude and latitude in WGS 84 decimal degrees, e.g. `(-103.8011, 40.2684)`.
`numpoints`	int	Number of points to interpolate along the cross-section.
`width`	float	Width of the cross-section in meters.
`file`	Optional[str]	Path to write GeoJSON output. If `None`, returns a GeoDataFrame.
`res`	float	3DEP DEM resolution in meters. One of: `1`, `3`, `5`, `10`, `30`, `60`. Defaults to `10`.

Returns

A GeoDataFrame with columns:

Column	Description
`geometry`	Point geometries of the cross-section in WGS 84.
`distance`	Distance in meters from the first point (EPSG:5071).

Examples

Python:

xs = getxsatpoint(point=(-103.8011, 40.2684), numpoints=100, width=1000.0)

CLI:

nldi-xstool xsatpoint -ll -103.8011 40.2684 -w 1000 -n 100 -r 10m
nldi-xstool xsatpoint -ll -103.8011 40.2684 -w 1000 -n 100 -r 10m -f output.json

Cross-Section at Endpoints

Generates a topographic cross-section between two user-defined endpoints using 3DEP elevation data. No stream snapping is performed.

Parameters

Name	Type	Description
`path`	List[Tuple[float, float]]	Two coordinate pairs defining the start and end points, ordered river-left to river-right, e.g. `[(-103.801134, 40.267335), (-103.800787, 40.272798)]`.
`numpts`	int	Number of points to interpolate along the cross-section.
`crs`	Optional[str]	CRS of input coordinates. Defaults to `"epsg:4326"`.
`file`	Optional[str]	Path to write GeoJSON output. If `None`, returns a GeoDataFrame.
`res`	float	3DEP DEM resolution in meters. Defaults to `10`.

Returns

A GeoDataFrame with columns:

Column	Description
`geometry`	Point geometries of the cross-section in WGS 84.
`distance`	Distance in meters from the first point (EPSG:5071).

Examples

Python:

xs = getxsatendpts(
    path=[(-103.801134, 40.267335), (-103.800787, 40.272798)],
    numpts=100,
    res=10,
)

CLI:

nldi-xstool xsatendpts -s -103.801134 40.267335 -e -103.800787 40.272798 -n 100 -r 10m
nldi-xstool xsatendpts -s -103.801134 40.267335 -e -103.800787 40.272798 -n 100 -r 10m -f output.json

Cross-Section at Path

Generates a topographic cross-section along a user-defined path of coordinate pairs using 3DEP elevation data.

Parameters

Name	Type	Description
`path`	List[Tuple[float, float]]	List of coordinate pairs defining the path, e.g. `[(-103.801, 40.267), (-103.800, 40.270), (-103.799, 40.273)]`.
`numpts`	int	Number of points to interpolate along the path.
`crs`	Optional[str]	CRS of input coordinates. Defaults to `"epsg:4326"`.
`file`	Optional[str]	Path to write GeoJSON output. If `None`, returns a GeoDataFrame.
`res`	float	3DEP DEM resolution in meters. Defaults to `10`.

Returns

A GeoDataFrame with columns:

Column	Description
`geometry`	Point geometries along the path in WGS 84.
`distance`	Cumulative distance between consecutive points in meters (EPSG:5071).

Examples

Python:

xs = getxsatpathpts(
    path=[(-103.801, 40.267), (-103.800, 40.270), (-103.799, 40.273)],
    numpts=100,
    res=10,
)

CLI:

nldi-xstool xsatpathpts "[(-103.801,40.267),(-103.800,40.270),(-103.799,40.273)]" -n 100 -r 10m

Notes

The res parameter controls the interpolation resolution of the 3DEP query, not the native resolution of the source DEM. Use nldi_xstool.ancillary.query_dems to check which native resolutions are available at your location.
Available DEM resolutions: 1m, 3m, 5m, 10m, 30m, 60m. The 10m resolution is available throughout CONUS.
All CLI commands support --outcrs to set the output CRS (default: epsg:4326), -v for verbose output, and -f to write results to a JSON file.