segrails.config
===============

.. py:module:: segrails.config

.. autoapi-nested-parse::

   Segrails library configuration.

   Reads all parameters from environment variables at instantiation time.
   A .env file is loaded automatically when the module is imported (requires python-dotenv).

   To pick up changes to .env: instantiate a new SegrailsConfig().
   To override specific values without env vars: use SegrailsConfig.from_yaml(yaml_path)
   or pass keyword arguments: SegrailsConfig(model_name="my-model").

   Environment variables:
       Model:
           SEGRAILS_MODEL_NAME         Model name              (default: "segrails-unet").
           SEGRAILS_MODEL_VERSION      Model version           (default: "latest").
           SEGRAILS_WEIGHTS_SOURCE     Weights URI             (azure://... or https://...).

       Storage:
           DS_WEIGHTS_CONTAINER        Azure Blob container name (default: "weights").
           DS_WEIGHTS_PREFIX           Container prefix        (default: "segrails").
           DS_API_BASE_URL             APIM base URL. When set and SEGRAILS_WEIGHTS_SOURCE is absent,
                                       weights_source is derived as {DS_API_BASE_URL}/{SEGRAILS_ENV}/weights/
                                       {DS_WEIGHTS_PREFIX}/{SEGRAILS_MODEL_NAME}.

       Processing:
           SEGRAILS_RASTER_RESOLUTION              Raster resolution in m/px (default: 0.06).
           SEGRAILS_RASTER_ABOVE_GROUND_FILTER     Remove ground points before rasterization (default: true).
           SEGRAILS_RASTER_NOISE_OUTLIER           Remove statistical noise outliers before rasterization (default: false).
           SEGRAILS_POSTPROCESS_DEBUG              Save debug PNG visualisations after postprocessing (default: false).

       Cache:
           SEGRAILS_CACHE_DIR          Local cache directory   (default: ~/.cache/segrails).
           SEGRAILS_CACHE_TTL_SECONDS  Cache TTL in seconds    (default: 86400).

       Monitoring:
           MLFLOW_TRACKING_URI             MLflow tracking URI (disabled if absent).
           AZURE_TABLES_CONNECTION_STRING  Azure Storage connection string for Table tracking.
           AZURE_TABLES_ACCOUNT_URL        Azure Storage table endpoint URL (used with DefaultAzureCredential).
           AZURE_TABLES_TABLE_NAME         Azure Table name (default: "SegrailsInferences").

       Environment:
           SEGRAILS_ENV                Target environment: dev / test / beta / prod (default: "dev").

   .. rubric:: Example

   >>> config = SegrailsConfig()
   >>> config.env
   'dev'

   >>> config = SegrailsConfig.from_yaml("segrails.yml")
   >>> config.model_name
   'U-Net-segrails'



Classes
-------

.. autoapisummary::

   segrails.config.SegrailsConfig


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

.. py:class:: SegrailsConfig

   Immutable configuration for the Segrails library.

   All fields are read from environment variables at instantiation time.
   A .env file is loaded automatically if python-dotenv is installed.

   To override values: use from_yaml(yaml_path) for file-based config, or pass
   keyword arguments directly: SegrailsConfig(model_name="my-model").

   .. rubric:: Example

   >>> import os
   >>> os.environ["SEGRAILS_ENV"] = "prod"
   >>> config = SegrailsConfig()
   >>> config.env
   'prod'

   >>> config = SegrailsConfig.from_yaml("segrails.yml")
   >>> config.model_name
   'U-Net-segrails'


   .. py:attribute:: model_name
      :type:  str


   .. py:attribute:: model_version
      :type:  str


   .. py:attribute:: weights_source
      :type:  str


   .. py:attribute:: weights_container
      :type:  str


   .. py:attribute:: weights_prefix
      :type:  str


   .. py:attribute:: api_base_url
      :type:  str


   .. py:attribute:: api_weights_endpoint
      :type:  str
      :value: 'weights'



   .. py:attribute:: raster_resolution
      :type:  float


   .. py:attribute:: raster_above_ground_filter
      :type:  bool


   .. py:attribute:: raster_noise_outlier
      :type:  bool


   .. py:attribute:: inference_image_size
      :type:  tuple[int, int]
      :value: (512, 512)



   .. py:attribute:: model_encoder
      :type:  str


   .. py:attribute:: model_classes
      :type:  int


   .. py:attribute:: model_mean
      :type:  tuple[float, float, float]
      :value: (93.8652, 72.2728, 14.3507)



   .. py:attribute:: model_std
      :type:  tuple[float, float, float]
      :value: (72.8819, 76.9462, 25.7942)



   .. py:attribute:: detection_area_min
      :type:  float


   .. py:attribute:: detection_area_max
      :type:  float


   .. py:attribute:: detection_distance_min
      :type:  float


   .. py:attribute:: detection_distance_max
      :type:  float


   .. py:attribute:: detection_dilation_size
      :type:  float


   .. py:attribute:: detection_canny_low
      :type:  float


   .. py:attribute:: detection_canny_high
      :type:  float


   .. py:attribute:: detection_hough_threshold
      :type:  float


   .. py:attribute:: detection_hough_min_line
      :type:  float


   .. py:attribute:: detection_hough_max_gap
      :type:  float


   .. py:attribute:: detection_origin_distance
      :type:  float


   .. py:attribute:: detection_box_splits
      :type:  int


   .. py:attribute:: detection_iou_threshold
      :type:  float


   .. py:attribute:: postprocess_debug
      :type:  bool


   .. py:attribute:: cache_dir
      :type:  str


   .. py:attribute:: cache_ttl_seconds
      :type:  int | None


   .. py:attribute:: mlflow_tracking_uri
      :type:  str


   .. py:attribute:: azure_tables_connection_string
      :type:  str


   .. py:attribute:: azure_tables_account_url
      :type:  str


   .. py:attribute:: azure_tables_table_name
      :type:  str


   .. py:attribute:: env
      :type:  str


   .. py:method:: from_yaml(path: str | pathlib.Path) -> SegrailsConfig
      :classmethod:


      Load configuration from a YAML file with environment variable overrides.

      YAML values serve as base defaults. Environment variables always take
      priority and override the corresponding YAML values.

      :param path: Path to the YAML configuration file (see ``segrails.yml.example``).

      :returns: Merged configuration (YAML base + env var overrides).
      :rtype: SegrailsConfig

      :raises FileNotFoundError: If the YAML file does not exist.
      :raises ValueError: If the YAML file is invalid or malformed.

      .. rubric:: Example

      >>> config = SegrailsConfig.from_yaml("segrails.yml")
      >>> config.model_name
      'U-Net-segrails'