segrails.client
===============

.. py:module:: segrails.client

.. autoapi-nested-parse::

   Segrails pipeline orchestrator.



Classes
-------

.. autoapisummary::

   segrails.client.SegrailsClient


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

.. py:class:: SegrailsClient(config: altametris.segrails.config.SegrailsConfig | None = None, credentials: altametris.azure_sdk.authentication.credentials.Credentials | None = None, device: str = 'cpu')

   Orchestrate the full Segrails inference pipeline.

   Steps:
       1. **WeightStep** — resolve model weights from Azure Blob or local cache.
       2. **RasterStep** — generate a PNG raster from the input point cloud.
       3. **InferenceStep** — run UNet inference to produce a binary mask.
       4. **PostprocessStep** — detect rail tracks and crossings from the mask.

   The model is loaded on the first call to ``predict()`` and cached for
   subsequent calls.

   :param config: SegrailsConfig instance. When None, built from ``SegrailsConfig()``.
   :param credentials: Pre-built ``Credentials`` instance from ``altametris.azure_sdk``.
                       When None, created with ``auth_mode="default"`` (``az login`` / SP env vars).
   :param device: PyTorch device string. Defaults to ``"cpu"``.

   .. rubric:: Example

   >>> client = SegrailsClient(config=config, credentials=creds)
   >>> result = client.predict(Path("cloud.las"), center=(790490.0, 6878297.0))
   >>> result = client.predict(
   ...     {"path": "https://altametris.xyz/dev/u3d/data/proj/ept.json",
   ...      "headers": {"Bearer": "mytoken"}},
   ...     center=(790490.0, 6878297.0),
   ... )
   >>> print(result.predictions.n_tracks)


   .. py:attribute:: config


   .. py:attribute:: _device
      :value: 'cpu'



   .. py:attribute:: _weight_step


   .. py:attribute:: _raster_step


   .. py:attribute:: _postprocess_step


   .. py:attribute:: _inference_step
      :type:  altametris.segrails.pipeline.inference.InferenceStep | None
      :value: None



   .. py:attribute:: _model_dir
      :type:  pathlib.Path | None
      :value: None



   .. py:attribute:: _tracker


   .. py:method:: predict(point_cloud: altametris.segrails.pipeline.raster.PointCloudSource, center: tuple[float, float], pipeline_name: str | None = None, env: str | None = None) -> altametris.segrails.result.SegrailsResult

      Run the full pipeline on a single point cloud tile.

      :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 centre of the raster tile as ``(X, Y)`` in the
                     same coordinate reference system as the point cloud.
      :param pipeline_name: Optional identifier of the calling pipeline.
      :param env: Optional environment override for this call.

      :returns: SegrailsResult with ``status="success"`` and populated
                ``predictions``, or ``status="failure"`` with a ``SegrailsError``
                describing which step failed and why.