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
docs/howto/lidar.mdfor a sampling walkthrough.docs/howto/inventory_schema.mdfor the inventory release that plot samples can be joined to.