Documentation complète – REST API Python pour la visualisation et l’analyse de maillages 3D du cortex
- Introduction
- Architecture générale
- Installation et démarrage rapide
- Endpoints de l’API REST
- Détails des modules et des fonctions
- Cas d’usage / tutoriels
- Tests
- CI / CD
- Contribution
- Roadmap
- Références
Une API REST (Representational State Transfer) est une interface qui permet à différents systèmes informatiques de communiquer via le protocole HTTP, en respectant un ensemble de contraintes architecturales.
| Méthode | Usage |
|---|---|
GET |
Lire une ressource |
POST |
Créer une ressource ou envoyer une action |
PUT |
Mettre à jour une ressource existante |
DELETE |
Supprimer une ressource |
Les réponses sont généralement renvoyées au format JSON, ce qui simplifie l’intégration côté client (navigateur, application mobile, etc.).
Dans ce projet, l’API REST permet :
- de charger des fichiers 3D ;
- de déclencher des traitements scientifiques en Python ;
- de visualiser les résultats de manière interactive.
À compléter – description du problème résolu, motivations et cas d’utilisation principaux.
- Visualiser des maillages 3D du cortex directement depuis le navigateur
- Lancer des analyses quantitatives (épaisseur corticale, régions ROI, etc.)
- API REST conforme OpenAPI / Swagger
- Extensible par plugins d’analyse
| Couche | Rôle | Dossiers clés | Technologies |
|---|---|---|---|
| Back-end (API) | Expose les routes HTTP pour charger, analyser et servir maillages & métadonnées | routes/, tools/, launch_app.py |
FastAPI, NumPy, SciPy, PyVista / VTK |
| Front-end Web 3D | Interface utilisateur (visualisation temps réel : colormap, wireframe, edges) | src/app/ (sous-dossiers ui/, viewer/, utils/) |
JavaScript (ES6), Three.js |
| Scripts CLI | Automatisation hors-ligne (conversion, analyse, base) | tools/ |
Python |
| Données | Maillages, textures, ressources statiques | asset/, data/, uploads/ |
OBJ, GIfTI, CSV, PNG |
CORTEXVISU/
├─ asset/
├─ data/
├─ dist/
├─ node_modules/
├─ public/
├─ routes/
│ ├─ mesh.py
│ ├─ texture.py
│ ├─ normals.py
│ └─ import_package.py
├─ src/app/
│ ├─ ui/
│ ├─ viewer/
│ ├─ utils/
│ ├─ services/
│ ├─ main.js
│ └─ style.css
├─ tools/
├─ uploads/
├─ tests/
├─ launch_app.py
└─ README.md
git clone https://github.com/<user>/<repo>.git
cd <repo>
pip install -r requirements.txt
uvicorn app.main:app --reloadUn endpoint est une URL exposée par le serveur qui représente une action ou une ressource spécifique.
| Méthode | Route | Description |
|---|---|---|
POST |
/api/load-mesh-from-path |
Charge un maillage depuis son chemin |
POST |
/api/upload-texture |
Associe une texture scalaire à un maillage |
POST |
/api/import-package |
Importe dynamiquement un module Python |
POST |
/api/run-function |
Lance une fonction d’analyse sur le maillage courant |
Exemple : l’endpoint /api/load-mesh-from-path permet de charger un fichier de maillage à partir de son chemin et de le rendre disponible côté front-end.
À compléter selon les fichiers routes/ et tools/.
Ce module gère la modale d’import de fichiers .csv contenant des vecteurs de normales à associer à un ou plusieurs maillages existants.
| Élément DOM | ID | Description |
|---|---|---|
| Bouton ouvrir | #open-normal-modal |
Affiche la modale |
| Bouton fermer | #cancel-normal-load |
Ferme la modale |
| Input chemin dossier | #normal-folder-path |
Spécifie le dossier contenant les CSV |
| Bouton dossier | #browse-normal-folder |
Envoie la requête /api/list-folder-files |
| Input filtre | #normal-folder-filter |
Mot-clé de filtrage |
| Bouton filtre | #filter-normal-folder |
Applique le filtre |
| Liste fichiers du dossier | #normal-folder-list |
Fichiers CSV détectés, avec cases à cocher |
| Bouton ajout à base | #add-normal-to-db |
Copie les fichiers cochés dans la base temporaire normalDB[] |
| Liste DB internes | #normal-db-list |
Affiche les fichiers prêts à être associés |
| Bouton tout cocher | #select-all-normals |
Coche tous les fichiers visibles |
| Liste maillages | #loaded-mesh-list-normals |
Affiche les maillages disponibles à associer |
| Bouton supprimer | #delete-selected-normals |
Supprime des entrées de normalDB[] |
| Bouton associer | #load-normals-button |
Associe les fichiers cochés aux maillages cochés |
Fonctionnement :
- L’utilisateur ouvre la modale et charge un dossier de
.csvde normales. - Il peut filtrer, cocher certains fichiers, et les ajouter à la DB.
- Il coche un ou plusieurs maillages et fichiers CSV.
- Le bouton Associer ajoute les objets
{ name, path }aux propriétésnormals[]des maillages sélectionnés. - Si un des maillages affectés est actuellement affiché, un callback met à jour dynamiquement la liste
#normal-listdans l’UI principale.
Utilisé par : modals.js (appel initNormalModal(meshes, updateNormalListForSelectedMesh))
À compléter.
À compléter.
À compléter.
À compléter.
À compléter.
À compléter.
CortexVisu est une application de visualisation interactive de maillages 3D du cortex cérébral (format GIfTI .gii) avec :
- Colorimétrie dynamique (colormaps, plage personnalisée)
- Histogramme interactif des valeurs scalaires
- Options d’affichage (arêtes, wireframe, fond)
- Outils de dessin de texture manuelle
- Interface utilisateur simple et personnalisable
git clone {ton fork}
cd cortexvisuconda env create -f environment.yml
conda activate cortexvisupip install -r requirements.txtSi npm ou node ne sont pas installés : Télécharger depuis https://nodejs.org
Ensuite, dans le dossier du projet :
npm installEn local (tout-en-un)
python launch_app.pyCela :
- Compile le frontend (vite build)
- Lance le backend FastAPI (uvicorn)
- Ouvre automatiquement le navigateur à http://localhost:8000
window : double clic sur dev.bat puis aller a l'adresse http://localhost:5173/ linux : lancer dev.sh (apres avoir ajouter les droit d'execution chmod x...)
npm run dev
python -m uvicorn tools.api:app --reload --port 8000D:/Callisto/repo/cortexvisu/.conda/python.exe d:/Callisto/repo/cortexvisu/launch_app.py --rebuild