segrails.pipeline.raster
========================

.. py:module:: segrails.pipeline.raster

.. autoapi-nested-parse::

   Raster generation pipeline step.

   Wraps geo3d.RasterGenerator to produce a PNG raster and its GeoTransform
   from a point cloud file or remote EPT URL, using parameters from SegrailsConfig.



Classes
-------

.. autoapisummary::

   segrails.pipeline.raster.RasterStep


Module Contents
---------------

.. py:class:: RasterStep(config: altametris.segrails.config.SegrailsConfig, reader: str = 'las', height_threshold: float = 4.0, raster_side: int = 35, raster_window_size: float = 2.0, color: bool = True)

   Generate a raster PNG from a point cloud.

   Wraps geo3d.RasterGenerator. The raster cell resolution is read from
   SegrailsConfig. All other generation parameters are fixed at construction
   time and can be overridden per-call via generate().

   :param config: SegrailsConfig instance — provides raster_resolution, cache_dir,
                  raster_above_ground_filter and raster_noise_outlier.
   :param reader: Default point cloud reader. ``"las"`` for local files, ``"ept"``
                  for EPT endpoints. Overridden automatically when a dict filespec is passed.
   :param height_threshold: Height threshold in metres for above-ground filtering.
   :param raster_side: Side length of the output raster in metres.
   :param raster_window_size: PDAL raster window size in metres.
   :param color: Apply default color relief to the output PNG.

   .. rubric:: Example

   >>> step = RasterStep(config, reader="las")

   Local file:

   >>> png_path, gt = step.generate(Path("cloud.las"), center=(448500.0, 6840200.0))

   Remote EPT via U3D API:

   >>> png_path, gt = step.generate(
   ...     {"path": "https://altametris.xyz/dev/u3d/data/proj/ept.json",
   ...      "headers": {"Bearer": "mytoken"}},
   ...     center=(448500.0, 6840200.0),
   ... )


   .. py:attribute:: _config


   .. py:attribute:: _reader
      :value: 'las'



   .. py:attribute:: _height_threshold
      :value: 4.0



   .. py:attribute:: _raster_side
      :value: 35



   .. py:attribute:: _raster_window_size
      :value: 2.0



   .. py:attribute:: _generator


   .. py:method:: generate(point_cloud: PointCloudSource, center: tuple[float, float], output_dir: pathlib.Path | None = None) -> tuple[pathlib.Path, altametris.geo3d.rasters.types.GeoTransform]

      Generate a raster PNG from a point cloud.

      Accepts a local file path or a remote EPT filespec dict.

      :param point_cloud: Point cloud source. Either:

                          - ``str | Path`` — local LAS/LAZ file path.
                          - ``dict`` — remote EPT filespec with keys:

                            - ``"path"`` *(required)*: EPT endpoint URL.
                            - ``"headers"`` *(optional)*: dict of HTTP headers.
                              The ``"Bearer"`` key is forwarded as the EPT token.
      :param center: Geographic center of the raster as ``(X, Y)`` in the
                     point cloud coordinate reference system.
      :param output_dir: Directory for the output PNG. Defaults to
                         ``config.cache_dir / "rasters"``.

      :returns: Tuple of ``(png_path, geotransform)`` where ``png_path`` is the
                path to the generated PNG and ``geotransform`` contains
                georeferencing metadata for the raster.

      :raises FileNotFoundError: If a local path does not exist.
      :raises ValueError: If the filespec dict is missing the ``"path"`` key.
      :raises RuntimeError: If the PDAL pipeline execution fails.