htmx/architecture.md

🏗️ Architecture PointCloud Viewer - Diagramme Mermaid

Vue d'ensemble de l'architecture

flowchart TB
    subgraph "Infrastructure Docker"
        subgraph "Frontend Service:8091"
            FE[FastAPI Frontend]
            FE -- HTMX --> UI[Interface UI]
            UI -- AlpineJS --> FE
        end
        
        subgraph "Backend Service:8000"
            BE[FastAPI Backend]
            BE -- API --> FE
        end
        
        subgraph "External Services"
            POT[Potree Viewer:8090]
            PDAL[PDAL Tool]
            ENT[Entwine Tool]
        end
    end
    
    subgraph "Data Storage"
        UPLOADS[./backend/data/uploads/]
        EPT_DIR[./backend/data/ept/]
        CONFIG[./frontend/config/]
    end
    
    subgraph "Templates & Static"
        TEMPLATES[./frontend/templates/]
        COMPONENTS[./frontend/components/]
        STATIC[./backend/static/potree/]
    end

Flux principal d'upload et conversion

sequenceDiagram
    participant User as Utilisateur
    participant FE as Frontend (8091)
    participant BE as Backend (8000)
    participant ENT as Entwine
    participant FS as Système de Fichiers

    User->>FE: 1. Télécharge fichier LAS/LAZ/PLY
    FE->>FE: 2. Vérifie format supporté
    FE->>BE: 3. POST /upload avec fichier
    BE->>BE: 4. Génère UUID (pc_id)
    BE->>FS: 5. Écrit fichier dans uploads/
    BE->>ENT: 6. LANCE entwine build
    ENT->>FS: 7. Convertit vers format EPT
    ENT->>FS: 8. Crée dossier ept/{pc_id}/
    ENT-->>BE: 9. Retourne résultat
    BE->>BE: 10. Sauvegarde manifest.json
    BE-->>FE: 11. Retourne JSON avec pc_id
    FE->>FE: 12. Affiche résultat HTMX
    FE->>POT: 13. Génère page viewer
    FE-->>User: 14. Affiche visualisation Potree

Flux de visualisation

flowchart LR
    subgraph Frontend
        A[Page /viewer/list] --> B[HTMX Fetch /viewer/list]
        B --> C[cloud_list.html]
    end
    
    subgraph Backend
        D[API /viewer/list] --> E[Lecture EPT_DIR]
        E --> F[manifest.json]
        F --> G[Statistiques]
    end
    
    C -->|Affichage| H[Tableau Nuages]
    
    H -->|Click| I[Page /viewer/{pc_id}]
    I -->|HTMX| J[viewer.html partial]
    J -->|Embed| K[Potree Viewer]
    
    K -->|Chargement| L[/ept_data/{pc_id}/ept.json]
    L --> M[Visualisation 3D]

Flux de crop (réduction du nuage)

sequenceDiagram
    participant User as Utilisateur
    participant FE as Frontend
    participant BE as Backend
    participant PDAL as PDAL
    participant FS as Système Fichiers

    User->>FE: 1. Sélectionne nuage + box 3D
    FE->>BE: 2. POST /admin/crop/{pc_id} avec box
    BE->>PDAL: 3. LANCE pdal filter
    PDAL->>FS: 4. Lit fichier source LAS
    PDAL->>FS: 5. Applique box de filtrage
    PDAL->>FS: 6. Écrit fichier LAS cropped
    PDAL-->>BE: 7. Retourne fichier cropped
    BE->>FS: 8. Lance entwine sur fichier cropped
    ENT->>FS: 9. Convertit vers EPT
    BE->>FS: 10. Sauvegarde nouveau nuage
    BE-->>FE: 11. Retourne nouveau pc_id
    FE->>FE: 12. Affiche nouveau nuage

Architecture des routes

mindmap
  root((Architecture))
    Frontend
      /upload
        GET / - Redirection
        GET /upload - Page upload
        POST /upload - Upload fichier
        GET /health-check - Vérification
      /viewer
        GET /viewer/list - Liste nuages
        GET /viewer/{pc_id} - Visualisation
      /admin
        GET /admin/backend-config
        POST /admin/backend-config
        GET /admin/list
        GET /admin/debug/{pc_id}
        DELETE /admin/delete/{pc_id}
        POST /admin/crop/{pc_id}
    Backend
      /upload
        POST /upload - Conversion entwine
      /viewer
        GET /viewer/list - Liste EPT
        GET /viewer/{pc_id} - Page viewer
        GET /viewer-embed/{pc_id} - Embed
      /admin
        GET /debug/{pc_id} - Debug info
        DELETE /delete/{pc_id} - Suppression
        POST /admin/crop/{pc_id} - Crop PDAL
      /health - Health check
      / - Page HTML
      /ept_data - Serveur statique
      /static - Assets

Structure des dossiers EPT

graph TD
    EPT[EPT Directory]
    EPT --> MANIFEST[manifest.json]
    EPT --> EPT_JSON[ept.json]
    EPT --> EPT_BUILD[ept-build.json]
    EPT --> EPT_DATA[ept-data/]
    EPT_DATA --> TUILES[.las.tileset]
    EPT_DATA --> META[meta.json]
    EPT --> EPT_HIERARCHY[ept-hierarchy/]
    EPT_HIERARCHY --> NOEUDS[.node]
    EPT --> EPT_SOURCES[ept-sources/]
    EPT_SOURCES --> SOURCES[.las]

Diagramme complet des interactions

flowchart TB
    subgraph "Utilisateur"
        U[Utilisateur]
    end
    
    subgraph "Frontend Service [8091]"
        direction TB
        FE[FastAPI<br/>Jinja2 + HTMX + AlpineJS]
        UI[Interface<br/>DaisyUI + Tailwind]
        API_CLIENT[api_client.py<br/>httpx Async]
        CONFIG[config.py<br/>BACKEND_URL + POTREE_URL]
        
        U -->|Navigate| UI
        UI -->|HTMX| FE
        FE -->|Templates| UI
        FE -->|Routes| API_CLIENT
        API_CLIENT -->|HTTP| BE
        FE -->|Config| CONFIG
    end
    
    subgraph "Backend Service [8000]"
        direction TB
        BE[FastAPI<br/>PDAL + Entwine]
        ROUTES[Routes<br/>upload.py<br/>viewer.py<br/>admin.py]
        SERVICES[Services<br/>converter.py<br/>manifest.py<br/>html_generator.py]
        UTILS[Utils<br/>disk.py]
        STATIC[Static Files<br/>Potree Viewer]
        
        BE -->|Include| ROUTES
        ROUTES -->|Call| SERVICES
        SERVICES -->|Read| UTILS
        BE -->|Serve| STATIC
        BE -->|Mount| EPT_DIR[/ept_data/]
    end
    
    subgraph "Outils Externes"
        ENT[Entwine<br/>build EPT]
        PDAL[PDAL<br/>filter/crop LAS]
    end
    
    subgraph "Stockage"
        UPLOADS[uploads/<br/>fichiers LAS/LAZ]
        EPT[ept/<br/>nuages convertis]
        CONFIG_FILE[config/<br/>backend.json]
    end
    
    subgraph "External"
        POT[Potree Viewer<br/>WebGL 3D]
    end
    
    %% Flux Upload
    UI -->|1. Choix fichier| U
    U -->|2. POST /upload| API_CLIENT
    API_CLIENT -->|3. POST /upload| BE
    BE -->|4. Enregistrer| UPLOADS
    BE -->|5. Lancer| ENT
    ENT -->|6. Convertir| EPT
    BE -->|7. Sauvegarder| SERVICES
    SERVICES -->|8. manifest.json| EPT
    
    %% Flux Liste
    UI -->|9. /viewer/list| API_CLIENT
    API_CLIENT -->|10. GET /viewer/list| BE
    BE -->|11. Lire| EPT
    BE -->|12. Retourne| API_CLIENT
    API_CLIENT -->|13. Affiche| UI
    
    %% Flux Visualisation
    UI -->|14. /viewer/{pc_id}| FE
    FE -->|15. Embed| POT
    POT -->|16. Charger| EPT_DIR
    EPT_DIR -->|17. ept.json| POT
    POT -->|18. Visualiser| U
    
    %% Flux Crop
    UI -->|19. /admin/crop| API_CLIENT
    API_CLIENT -->|20. POST /admin/crop| BE
    BE -->|21. Lancer| PDAL
    PDAL -->|22. Filtre| UPLOADS
    BE -->|23. Convertir| ENT
    ENT -->|24. Nouveau EPT| EPT
    BE -->|25. Retourne| API_CLIENT
    API_CLIENT -->|26. Affiche| UI
    
    %% Styles
    classDef user fill:#e1f5ff,stroke:#1890ff,stroke-width:2px
    classDef frontend fill:#fff7e6,stroke:#fa8c16,stroke-width:2px
    classDef backend fill:#f6ffed,stroke:#52c41a,stroke-width:2px
    classDef tools fill:#f0f5ff,stroke:#2f54eb,stroke-width:2px
    classDef storage fill:#fff0f6,stroke:#eb2f96,stroke-width:2px
    classDef external fill:#f9f0ff,stroke:#722ed1,stroke-width:2px
    
    class U user
    class FE,UI,API_CLIENT,CONFIG frontend
    class BE,ROUTES,SERVICES,UTILS,STATIC backend
    class ENT,PDAL tools
    class UPLOADS,EPT,CONFIG_FILE storage
    class POT external

Fonctionnalités de l'application

1. Upload et Conversion

• Téléchargement de fichiers LAS, LAZ, PLY, XYZ, PTS
• Conversion automatique vers format EPT (Entwine Point Tile)
• Génération de manifeste pour chaque nuage
• Suivi du temps de conversion

2. Visualisation 3D

• Intégration Potree Viewer (WebGL)
• Chargement direct des tuiles EPT
• Configuration de la taille de point et forme
• Support des modes embed et standalone

3. Administration

• Liste de tous les nuages de points
• Informations détaillées (taille, nombre de fichiers, date)
• Debug panel pour inspection
• Suppression de nuages

4. Traitement PDAL

• Crop 3D des nuages de points
• Définition de box de sélection
• Conversion du résultat en EPT

5. Configuration Dynamique

• URL du backend configurable
• URL de Potree configurable
• Sauvegarde dans fichier JSON
• Variables d'environnement

6. Monitoring

• Endpoint /health pour vérification
• Indicateur de disponibilité Entwine
• Affichage de l'espace disque libre
• Version de PDAL

7. Relevant Files and Code:

• backend/main.py: Point d'entrée backend, mounting de /ept_data, /static, /potree
• backend/routes/upload.py: POST /upload - conversion entwine avec UUID
• backend/routes/viewer.py: GET /viewer/list, /viewer/{pc_id}, /viewer-embed/{pc_id}
• backend/services/converter.py: run_entwine() - commande entwine build
• backend/services/manifest.py: save_manifest(), read_manifest()
• backend/services/html_generator.py: generate_viewer_html() - template Potree
• frontend/api_client.py: check_health(), upload_file(), get_debug(), delete_pointcloud(), crop_pointcloud()
• frontend/routes/upload.py: POST /upload → api_client.upload_file()
• frontend/routes/crop.py: POST /admin/crop/{pc_id} → api_client.crop_pointcloud()
• frontend/templates/index.html: Interface principale avec HTMX tabs (Upload, Admin)
• docker-compose.yml: 2 services, volumes mount, environment variables