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