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.

.. code-block:: python

   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
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 15 25 60

   * - 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:

.. list-table::
   :header-rows: 1
   :widths: 20 80

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

Examples
^^^^^^^^

Python:

.. code-block:: python

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

CLI:

.. code-block:: console

   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
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 15 25 60

   * - 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:

.. list-table::
   :header-rows: 1
   :widths: 20 80

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

Examples
^^^^^^^^

Python:

.. code-block:: python

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

CLI:

.. code-block:: console

   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
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 15 25 60

   * - 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:

.. list-table::
   :header-rows: 1
   :widths: 20 80

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

Examples
^^^^^^^^

Python:

.. code-block:: python

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

CLI:

.. code-block:: console

   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.