nemora.lidar

nemora.lidar is an optional observation layer for prepared canopy or terrain rasters. It samples rasters in their native CRS and computes canopy summaries for inventory validation and synthetic-stand comparison.

It does not discover LiDAR tiles, download or materialize products, classify point clouds, derive a CHM/DTM, or detect individual trees. Those producer responsibilities remain in FEMIC/WS4. See ADR 0001 for the boundary.

Install the optional dependency:

pip install "nemora[lidar]"

Importing the package works without rasterio. Calling read_raster without the extra raises LidarDependencyError with installation guidance.

API

.. py:module:: nemora.lidar

Optional LiDAR observation and raster metric helpers.

This package does not produce LiDAR products. It samples existing rasters and summarizes canopy structure for inventory validation and synthetic-stand comparison. See notes/adr/0001-plot-lidar-boundaries.md for the boundary.

.. py:class:: CanopyMetrics(valid_pixels, cover_fraction, cover_threshold_m, height_mean_m, height_min_m, height_max_m, height_p50_m, height_p95_m) :module: nemora.lidar :canonical: nemora.lidar.raster.CanopyMetrics

Bases: :py:class:object

Summary of canopy-height values from a valid raster footprint.

.. py:attribute:: CanopyMetrics.cover_fraction :module: nemora.lidar :type: float

.. py:attribute:: CanopyMetrics.cover_threshold_m :module: nemora.lidar :type: float

.. py:attribute:: CanopyMetrics.height_max_m :module: nemora.lidar :type: float

.. py:attribute:: CanopyMetrics.height_mean_m :module: nemora.lidar :type: float

.. py:attribute:: CanopyMetrics.height_min_m :module: nemora.lidar :type: float

.. py:attribute:: CanopyMetrics.height_p50_m :module: nemora.lidar :type: float

.. py:attribute:: CanopyMetrics.height_p95_m :module: nemora.lidar :type: float

.. py:method:: CanopyMetrics.to_dict() :module: nemora.lidar

  Return the metrics as a JSON-serializable mapping.


  :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`float\` \| \:py\:class\:\`int\`\]`

.. py:attribute:: CanopyMetrics.valid_pixels :module: nemora.lidar :type: int

.. py:exception:: LidarDependencyError :module: nemora.lidar :canonical: nemora.lidar.raster.LidarDependencyError

Bases: :py:class:ImportError

Raised when an optional LiDAR dependency is not installed.

.. py:class:: RasterGrid(values, transform, crs, nodata, resolution, width, height) :module: nemora.lidar :canonical: nemora.lidar.raster.RasterGrid

Bases: :py:class:object

A single-band raster in its native CRS.

:type values: :sphinx_autodoc_typehints_type:\:py\:class\:\~numpy.ndarray`    :param values: Two-dimensional array with ``height`` rows and ``width`` columns.                   Nodata and masked pixels are represented by ``NaN``.    :type transform: :sphinx_autodoc_typehints_type::py:class:`tuple`\ \[:py:class:`float`, :py:class:`float`, :py:class:`float`, :py:class:`float`, :py:class:`float`, :py:class:`float`]    :param transform: Affine coefficients ``(a, b, c, d, e, f)`` in the rasterio convention:                      ``x = a * col + b * row + c`` and ``y = d * col + e * row + f``.    :type crs: :sphinx_autodoc_typehints_type::py:class:`str` | :py:obj:`None`    :param crs: Native CRS string, or ``None`` when the source has no CRS.    :type nodata: :sphinx_autodoc_typehints_type::py:class:`float` | :py:obj:`None`    :param nodata: Source nodata value, when declared.    :type resolution: :sphinx_autodoc_typehints_type::py:class:`tuple`\ \[:py:class:`float`, :py:class:`float`]    :param resolution: Pixel size as ``(x_resolution, y_resolution)`` in CRS units.    :type width: :sphinx_autodoc_typehints_type::py:class:`int`    :param width: Number of columns.    :type height: :sphinx_autodoc_typehints_type::py:class:`int`` :param height: Number of rows.

.. py:attribute:: RasterGrid.crs :module: nemora.lidar :type: str | None

.. py:attribute:: RasterGrid.height :module: nemora.lidar :type: int

.. py:attribute:: RasterGrid.nodata :module: nemora.lidar :type: float | None

.. py:attribute:: RasterGrid.resolution :module: nemora.lidar :type: tuple[float, float]

.. py:attribute:: RasterGrid.transform :module: nemora.lidar :type: tuple[float, float, float, float, float, float]

.. py:attribute:: RasterGrid.values :module: nemora.lidar :type: ~numpy.ndarray

.. py:attribute:: RasterGrid.width :module: nemora.lidar :type: int

.. py:function:: canopy_metrics(values, *, cover_threshold_m=2.0) :module: nemora.lidar

Summarize canopy-height values.

Finite, non-negative values are treated as valid canopy heights. Negative values and NaN are ignored. Cover is the fraction of valid pixels at or above cover_threshold_m.

:type values: :sphinx_autodoc_typehints_type:\:py\:class\:\~numpy.ndarray` | :py:class:`~collections.abc.Sequence`\ \[:py:class:`float`]    :param values: Scalar array or sequence of canopy heights in metres.    :type cover_threshold_m: :sphinx_autodoc_typehints_type::py:class:`float`` :param cover_threshold_m: Height threshold for the cover fraction.

:returns: Valid-pixel count, cover fraction, and height summary. :rtype: CanopyMetrics

:raises ValueError: If no finite, non-negative values are available.

.. py:function:: read_raster(path, *, band=1) :module: nemora.lidar

Read one band of a raster as a :class:RasterGrid.

:type path: :sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`~pathlib.Path`    :param path: Path to a raster readable by rasterio.    :type band: :sphinx_autodoc_typehints_type::py:class:`int`` :param band: One-based band index.

:raises LidarDependencyError: If rasterio is not installed. :raises ValueError: If the band index is invalid or the raster has no two-dimensional band.

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.lidar.raster.RasterGrid``

.. py:function:: sample_raster_at_points(grid, x, y) :module: nemora.lidar

Sample a raster at native-CRS point locations.

Points are assigned to the pixel containing them. Points outside the grid, pixels with NaN, and non-finite coordinates return NaN.

:type grid: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.lidar.raster.RasterGrid`    :param grid: Raster to sample.    :type x: :sphinx_autodoc_typehints_type::py:class:`~numpy.ndarray` | :py:class:`~collections.abc.Sequence`\ \[:py:class:`float`]    :param x: Coordinate arrays in the raster's native CRS. They must have the same              shape.    :type y: :sphinx_autodoc_typehints_type::py:class:`~numpy.ndarray` | :py:class:`~collections.abc.Sequence`\ \[:py:class:`float`]` :param y: Coordinate arrays in the raster’s native CRS. They must have the same shape.

:returns: An array with the same shape as x and y. :rtype: numpy.ndarray

.. py:function:: summarize_canopy_grid(grid, *, cover_threshold_m=2.0) :module: nemora.lidar

Compute :func:canopy_metrics over all valid cells in a raster.

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.lidar.raster.CanopyMetrics``

.. py:module:: nemora.lidar.raster

Raster sampling and canopy metrics for existing LiDAR products.

The module deliberately consumes prepared rasters in their native CRS. It does not download tiles, classify point clouds, derive a CHM, reproject, or resample. Install the optional lidar extra to read GeoTIFFs with rasterio.

.. py:class:: CanopyMetrics(valid_pixels, cover_fraction, cover_threshold_m, height_mean_m, height_min_m, height_max_m, height_p50_m, height_p95_m) :module: nemora.lidar.raster

Bases: :py:class:object

Summary of canopy-height values from a valid raster footprint.

.. py:attribute:: CanopyMetrics.cover_fraction :module: nemora.lidar.raster :type: float

.. py:attribute:: CanopyMetrics.cover_threshold_m :module: nemora.lidar.raster :type: float

.. py:attribute:: CanopyMetrics.height_max_m :module: nemora.lidar.raster :type: float

.. py:attribute:: CanopyMetrics.height_mean_m :module: nemora.lidar.raster :type: float

.. py:attribute:: CanopyMetrics.height_min_m :module: nemora.lidar.raster :type: float

.. py:attribute:: CanopyMetrics.height_p50_m :module: nemora.lidar.raster :type: float

.. py:attribute:: CanopyMetrics.height_p95_m :module: nemora.lidar.raster :type: float

.. py:method:: CanopyMetrics.to_dict() :module: nemora.lidar.raster

  Return the metrics as a JSON-serializable mapping.


  :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`float\` \| \:py\:class\:\`int\`\]`

.. py:attribute:: CanopyMetrics.valid_pixels :module: nemora.lidar.raster :type: int

.. py:exception:: LidarDependencyError :module: nemora.lidar.raster

Bases: :py:class:ImportError

Raised when an optional LiDAR dependency is not installed.

.. py:class:: RasterGrid(values, transform, crs, nodata, resolution, width, height) :module: nemora.lidar.raster

Bases: :py:class:object

A single-band raster in its native CRS.

:type values: :sphinx_autodoc_typehints_type:\:py\:class\:\~numpy.ndarray`    :param values: Two-dimensional array with ``height`` rows and ``width`` columns.                   Nodata and masked pixels are represented by ``NaN``.    :type transform: :sphinx_autodoc_typehints_type::py:class:`tuple`\ \[:py:class:`float`, :py:class:`float`, :py:class:`float`, :py:class:`float`, :py:class:`float`, :py:class:`float`]    :param transform: Affine coefficients ``(a, b, c, d, e, f)`` in the rasterio convention:                      ``x = a * col + b * row + c`` and ``y = d * col + e * row + f``.    :type crs: :sphinx_autodoc_typehints_type::py:class:`str` | :py:obj:`None`    :param crs: Native CRS string, or ``None`` when the source has no CRS.    :type nodata: :sphinx_autodoc_typehints_type::py:class:`float` | :py:obj:`None`    :param nodata: Source nodata value, when declared.    :type resolution: :sphinx_autodoc_typehints_type::py:class:`tuple`\ \[:py:class:`float`, :py:class:`float`]    :param resolution: Pixel size as ``(x_resolution, y_resolution)`` in CRS units.    :type width: :sphinx_autodoc_typehints_type::py:class:`int`    :param width: Number of columns.    :type height: :sphinx_autodoc_typehints_type::py:class:`int`` :param height: Number of rows.

.. py:attribute:: RasterGrid.crs :module: nemora.lidar.raster :type: str | None

.. py:attribute:: RasterGrid.height :module: nemora.lidar.raster :type: int

.. py:attribute:: RasterGrid.nodata :module: nemora.lidar.raster :type: float | None

.. py:attribute:: RasterGrid.resolution :module: nemora.lidar.raster :type: tuple[float, float]

.. py:attribute:: RasterGrid.transform :module: nemora.lidar.raster :type: tuple[float, float, float, float, float, float]

.. py:attribute:: RasterGrid.values :module: nemora.lidar.raster :type: ~numpy.ndarray

.. py:attribute:: RasterGrid.width :module: nemora.lidar.raster :type: int

.. py:function:: canopy_metrics(values, *, cover_threshold_m=2.0) :module: nemora.lidar.raster

Summarize canopy-height values.

Finite, non-negative values are treated as valid canopy heights. Negative values and NaN are ignored. Cover is the fraction of valid pixels at or above cover_threshold_m.

:type values: :sphinx_autodoc_typehints_type:\:py\:class\:\~numpy.ndarray` | :py:class:`~collections.abc.Sequence`\ \[:py:class:`float`]    :param values: Scalar array or sequence of canopy heights in metres.    :type cover_threshold_m: :sphinx_autodoc_typehints_type::py:class:`float`` :param cover_threshold_m: Height threshold for the cover fraction.

:returns: Valid-pixel count, cover fraction, and height summary. :rtype: CanopyMetrics

:raises ValueError: If no finite, non-negative values are available.

.. py:function:: read_raster(path, *, band=1) :module: nemora.lidar.raster

Read one band of a raster as a :class:RasterGrid.

:type path: :sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`~pathlib.Path`    :param path: Path to a raster readable by rasterio.    :type band: :sphinx_autodoc_typehints_type::py:class:`int`` :param band: One-based band index.

:raises LidarDependencyError: If rasterio is not installed. :raises ValueError: If the band index is invalid or the raster has no two-dimensional band.

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.lidar.raster.RasterGrid``

.. py:function:: sample_raster_at_points(grid, x, y) :module: nemora.lidar.raster

Sample a raster at native-CRS point locations.

Points are assigned to the pixel containing them. Points outside the grid, pixels with NaN, and non-finite coordinates return NaN.

:type grid: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.lidar.raster.RasterGrid`    :param grid: Raster to sample.    :type x: :sphinx_autodoc_typehints_type::py:class:`~numpy.ndarray` | :py:class:`~collections.abc.Sequence`\ \[:py:class:`float`]    :param x: Coordinate arrays in the raster's native CRS. They must have the same              shape.    :type y: :sphinx_autodoc_typehints_type::py:class:`~numpy.ndarray` | :py:class:`~collections.abc.Sequence`\ \[:py:class:`float`]` :param y: Coordinate arrays in the raster’s native CRS. They must have the same shape.

:returns: An array with the same shape as x and y. :rtype: numpy.ndarray

.. py:function:: summarize_canopy_grid(grid, *, cover_threshold_m=2.0) :module: nemora.lidar.raster

Compute :func:canopy_metrics over all valid cells in a raster.

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.lidar.raster.CanopyMetrics``

See also