Tutoriel pas-à-pas

Ce tutoriel guide un nouvel utilisateur pour prendre en main pygroundedweb : - installation - initialisation et authentification - création d’un dataset et upload de photos - création d’une Configuration complète - lancement et suivi d’une Analysis

Prérequis

Assurez-vous d’avoir Python 3.9+ et d’avoir installé le package (ou installé depuis les sources) :

pip install pygroundedweb
# ou pour le développement
# pip install -e .

Initialisation et authentification

from pygroundedweb import GroundedWebClient

# Remplacez par l'URL de votre instance Grounded Web
client = GroundedWebClient(base_url='http://localhost:8000')
client.login(email='admin@example.com', password='password')

Créer un dataset et uploader des photos

Supposons que vous ayez deux listes de fichiers locaux : photos_before et photos_after.

photos_before = ['images/site1_before_01.jpg', 'images/site1_before_02.jpg']
photos_after = ['images/site1_after_01.jpg']

# Création du dataset et upload des photos (upload en parallèle)
dataset = client.dataset.create(
    dataset_name='Site 1 - Inspection',
    photos_before=photos_before,
    photos_after=photos_after,
    max_workers=4,
    progress_callback=lambda done, total: print(f"Uploaded {done}/{total}")
)

print(f"Dataset créé : {dataset.pk} - {dataset.name}")

Remarques : le client gère l’initialisation de la ressource côté API, la création des datasetphotos, l’upload vers les URLs présignées, puis la confirmation finale.

Configuration complète

Voici un exemple illustratif de création d’une configuration en utilisant les modèles fournis (par adaption selon votre setup réel). Nous utilisons : ScaleBar, CCTag, CloudCompare, MicMac.

from pygroundedweb import *

cfg = Configuration(
    name='Standard MicMac + CloudCompare',
    scale_bars=[
        ScaleBar(start=0, end=1, length=0.22),
        ScaleBar(start=2, end=3, length=0.50),
    ],
    detector=CCTag(),
    cloud_processor=CloudCompare(),
    sfm=MicMac(
        distorsion_model=DistortionModel.FRASER_BASIC,
        zoom_final=ZoomFinal.ZOOM_FINAL_MEDIUM,
        tapioca_mode=TapiocaMode.DEFAULT,
        tapioca_resolution=2000,
        tapioca_second_resolution=1000,
    ),
    display_padding=True,
)

# Optionnel: créer la configuration via l'API
cfg_created = client.configuration.create(cfg)
print(f"Configuration créée : {cfg_created.pk} - {cfg_created.name}")

Lancer une analyse

Après avoir une configuration et un dataset, lancez l’analyse :

analysis = client.analysis.create(
    analysis_name='Analyse Site 1',
    configuration=cfg_created,
    dataset=dataset,
    notify_by_email=False,
)

print(f"Analyse créée : ID {analysis.pk}")

Suivi des résultats

Le serveur peut traiter l’analyse en asynchrone. Voici la version la plus simple et lisible pour attendre la fin d’une analyse en utilisant la méthode refresh() de l’objet :

import time

# Récupérer l'analyse une première fois (par ex. après la création)
analysis = client.analysis.retrieve(analysis.pk)

# Boucle simple : on met à jour l'objet en place toutes les X secondes
CHECK_INTERVAL = 15  # secondes

while True:
    # met à jour l'objet `analysis` en interrogeant le serveur
    analysis.refresh()
    print(f"Statut : {analysis.status}")

    # condition de sortie : l'analyse est terminée (succès ou échec)
    if analysis.status in ("COMPLETED", "FAILED"):
        break

    time.sleep(CHECK_INTERVAL)

Remarque : cette approche est propre et lisible lorsque l’instance analysis a été créée via le client (elle a donc un _client attaché). Si vous avez construit l’objet localement sans passer par le client, refresh() lèvera un RuntimeError — dans ce cas, utilisez client.analysis.retrieve(pk) à la place.

Conseils de bons usages

• Testez d’abord votre configuration avec un petit dataset pour valider les paramètres SFM.

• Préférez l’upload depuis un réseau stable ; en cas d’échecs réseau, les uploads sont ré-essayés.

• Pour automatiser massivement, implémentez une logique de retry sur la création des ressources côté client si vous rencontrez des erreurs temporaires côté API.

Support et suites

Si vous avez des problèmes à suivre ce tutoriel, ouvre une Issue sur le dépôt GitHub avec : - logs (niveau debug) s’il y a des erreurs réseau - la configuration utilisée - un petit jeu de données permettant de reproduire