Altametris - segrails

Welcome to segrails’s documentation

Note

For a complete documentation, please visit the repository segrails.

Owner altametris.

Project Description

A Python package for doing inference with segrails

Steps

  1. Install the package following the Installation

  2. Learn how to use it following the Usage

Contents

Contributors

README

segrails

Bibliothèque Python pour la détection de voies ferrées sur nuages de points LiDAR.

Introduction

alta-segrails orchestre un pipeline complet : téléchargement des poids modèle, génération de raster depuis un nuage de points LAS/EPT, inférence UNet, et post-traitement (détection de rails et croisements).

Installation

Les dépendances natives (GDAL, PDAL) doivent être installées via conda avant pip :

conda create -n segrails python=3.11
conda activate segrails
conda install -c conda-forge gdal python-pdal libjpeg-turbo
pip install alta-segrails

Usage

Fichier .env minimal
SEGRAILS_ENV=dev
SEGRAILS_MODEL_NAME=U-Net_segrails_
DS_WEIGHTS_PREFIX=segrails

# Blob SDK — le storage account suit la convention deployment4{env}
AZURE_STORAGE_ACCOUNT_NAME=deployment4dev
AZURE_TENANT_ID=...
AZURE_CLIENT_ID=...
AZURE_CLIENT_SECRET=...

# APIM — décommenter DS_API_BASE_URL pour activer la dérivation APIM
# DS_API_BASE_URL=https://am-ds-apiman-dev.azure-api.net
# DS_API_SCOPE=https://api.altametris.xyz/datascience/dev/.default

weights_source est dérivé automatiquement depuis SEGRAILS_ENV, DS_WEIGHTS_PREFIX et SEGRAILS_MODEL_NAME : changer SEGRAILS_ENV suffit pour pointer sur le bon backend.

Monitoring

Chaque appel predict() écrit une ligne dans Azure Table Storage (SegrailsMonitoring par défaut). Le tracking est no-op si azure-data-tables n’est pas installé ou si aucune connexion n’est configurée.

Variable

Défaut

Description

AZURE_TABLES_CONNECTION_STRING

—

Connection string du compte Storage (dev/CI)

AZURE_TABLES_ACCOUNT_URL

https://data4ds.table.core.windows.net/

URL Table Storage (prod, Managed Identity)

AZURE_TABLES_TABLE_NAME

SegrailsMonitoring

Nom de la table (créée automatiquement)

Passer le contexte pipeline à chaque appel :

result = client.predict(
    point_cloud,
    center=(X, Y),
    pipeline_name="u3d-rail-prod",  # identifiant du pipeline appelant
    env="prod",                      # override de SEGRAILS_ENV pour cette ligne
)

Schema de la table :

Colonne

Description

PartitionKey

Hostname de la machine

RowKey

{Start_time}_{uuid8}

Env

Environnement (dev / test / beta / prod)

Start_time

Début de predict() (ISO 8601)

End_time

Fin de predict() (ISO 8601)

Status

success ou failure

Duration

Durée totale pipeline (ms)

pipeline_name

Identifiant du pipeline appelant (optionnel)

model_name / model_version

Modèle utilisé

n_tracks / valid_tracks / crossings

Résultats de détection

point_cloud_url

Source nuage de points

error_message

Message d’erreur (si failure)
Notes

  • Auth requise sur le compte storage : rôle Storage Table Data Contributor (le rôle Owner seul ne suffit pas pour le data plane Azure Table Storage).

Cache

Les poids sont mis en cache localement après le premier téléchargement.

Variable

Défaut

Description

SEGRAILS_CACHE_DIR

~/.cache/segrails

Répertoire de cache local

SEGRAILS_CACHE_TTL_SECONDS

non définie (infini)

Durée de validité du cache en secondes. Ne pas définir ou None = pas d’expiration.

Surcharge programmatique :

config = SegrailsConfig(cache_ttl_seconds=3600)   # expire après 1h
client = SegrailsClient(config=config)

Ou via YAML (segrails.yml) :

cache_ttl_seconds: 3600
Pipeline
from altametris.segrails import SegrailsClient, SegrailsConfig
from pathlib import Path

config = SegrailsConfig()
client = SegrailsClient(config=config)

# Fichier local LAS/LAZ
result = client.predict(Path("cloud.las"), center=(790490.0, 6878297.0))

# Source EPT distante (U3D API)
result = client.predict(
    {"path": "https://altametris.xyz/dev/u3d/data/proj/ept.json",
     "headers": {"Bearer": "mytoken"}},
    center=(790490.0, 6878297.0),
    pipeline_name="u3d-rail-prod",  # optionnel — identifiant du pipeline appelant (monitoring)
    env="prod",                      # optionnel — surcharge SEGRAILS_ENV pour cette ligne
)

print(result.predictions.n_tracks)

Modèles

U-Net-segrails

Paramètre

Valeur

Encodeur

ResNet-34

Classes

1 (rail)

Résolution raster

0.06 m/px

Version PyTorch

2.5.1+cu118

Installation GPU (conda) :

conda install pytorch==2.5.1 torchvision==0.20.1 pytorch-cuda=11.8 -c pytorch -c nvidia

Note — warning MLflow attendu

Si la version CUDA de PyTorch installée diffère de celle du checkpoint (ex. cu124 vs cu118), MLflow affiche au chargement du modèle :

WARNING mlflow.pytorch: Stored model version '2.5.1+cu118' does not match installed PyTorch version '2.5.1+cu124'

Ce warning est normal et sans impact : les poids sont indépendants de la version CUDA. Il disparaît uniquement si la build CUDA correspond exactement.

Note — installation pip (CPU uniquement)

pip install alta-segrails installe PyTorch sans support GPU. Pour utiliser le GPU, installer torch via conda (commande ci-dessus) avant pip install alta-segrails.

Connu : conflit libjpeg sur Linux (GDAL + PyTorch)

Symptôme
ImportError: libtiff.so.6: undefined symbol: jpeg12_write_raw_data, version LIBJPEG_8.0
ModuleNotFoundError: No module named '_gdal'
Cause

libtiff (conda-forge) est compilée avec le support JPEG-12 bits et attend jpeg12_write_raw_data depuis libjpeg-turbo. PyTorch charge sa propre version de libjpeg au démarrage, et le linker Linux cache la première version chargée par soname. Quand GDAL est importé ensuite, il tombe sur la version de torch qui n’a pas le symbole JPEG-12.

Solution permanente

Forcer le chargement de libjpeg-turbo conda avant PyTorch via les scripts d’activation de l’env :

# Script d'activation
mkdir -p $CONDA_PREFIX/etc/conda/activate.d
echo 'export LD_PRELOAD=$CONDA_PREFIX/lib/libjpeg.so.8' \
  > $CONDA_PREFIX/etc/conda/activate.d/fix_libjpeg.sh
chmod +x $CONDA_PREFIX/etc/conda/activate.d/fix_libjpeg.sh

# Script de désactivation (évite de polluer les autres envs)
mkdir -p $CONDA_PREFIX/etc/conda/deactivate.d
echo 'unset LD_PRELOAD' \
  > $CONDA_PREFIX/etc/conda/deactivate.d/fix_libjpeg.sh
chmod +x $CONDA_PREFIX/etc/conda/deactivate.d/fix_libjpeg.sh

Après conda deactivate && conda activate segrails, LD_PRELOAD est positionné automatiquement.

Fix rapide (session courante uniquement)
export LD_PRELOAD=$CONDA_PREFIX/lib/libjpeg.so.8

Indices and tables