segrails.pipeline.postprocess
=============================

.. py:module:: segrails.pipeline.postprocess

.. autoapi-nested-parse::

   Post-processing pipeline step.

   Wraps _PostProcessor to convert an inference mask into structured track detections
   (center points, directions, IoU scores) using Hough lines and contour analysis.



Classes
-------

.. autoapisummary::

   segrails.pipeline.postprocess.PostprocessStep


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

.. py:class:: PostprocessStep(config: altametris.segrails.config.SegrailsConfig)

   Run post-processing on a segmentation mask to extract rail track detections.

   Wraps _PostProcessor. All detection parameters are read from SegrailsConfig.

   :param config: SegrailsConfig instance — provides inference_image_size and all
                  detection_* parameters.

   .. rubric:: Example

   >>> step = PostprocessStep(config)
   >>> result = step.run(image_np, mask, geotransform, filename="tile_001")
   >>> print(result.n_tracks)


   .. py:attribute:: _config


   .. py:attribute:: _postprocessor


   .. py:method:: run(image: numpy.typing.NDArray[numpy.uint8], mask: numpy.typing.NDArray[numpy.uint8], geotransform: altametris.geo3d.rasters.types.GeoTransform, output_dir: pathlib.Path | None = None, filename: str = 'detection') -> altametris.segrails.result.SegrailsPrediction

      Extract rail detections from a segmentation mask.

      :param image: RGB raster image as uint8 ndarray of shape ``(H, W, 3)``,
                    already resized to ``inference_image_size`` (as returned by
                    ``InferenceStep.predict()``). Passed directly to avoid re-reading
                    the raster file that was already opened during inference.
      :param mask: Binary segmentation mask of shape (H, W) with dtype uint8,
                   as returned by InferenceStep.predict().
      :param geotransform: GeoTransform from RasterStep.generate(), used to map
                           pixel coordinates to geographic coordinates.
      :param output_dir: Optional directory for saving the detection JSON and debug
                         images. Created if it does not exist.
      :param filename: Base name for output files (no extension). Defaults to
                       ``"detection"``.

      :returns: SegrailsPrediction with n_tracks, valid_tracks, crossings,
                total_missed_detections, total_low_detections and enriched tracks list.



   .. py:method:: _format_predictions(raw: dict) -> altametris.segrails.result.SegrailsPrediction

      Build SegrailsPrediction from raw _PostProcessor output in a single pass.

      Enriches each track dict with ``low_detections``, ``missed_detections``
      and ``overall_iou``. Uses ``detection_iou_threshold`` from config.

      :param raw: Raw dict from _PostProcessor.run() with a ``"tracks"`` key.

      :returns: SegrailsPrediction with all counters populated.