PICOLA

Présentation fonctionnelle

Le pipeline Picola permet de :

• Automatiser la conversion d’images via Airflow 
• Exécuter des DAGs configurables dans un environnement reproductible 
• Structurer les DAGs et scripts dans un projet modulaireDescription du 
   

DAG principal : `convert_new` (picola_dag.py)

Le DAG `convert_new` est le cœur du pipeline Picola. Il permet d'automatiser la conversion d’images médicales (comme les lames d’anatomopathologie) en fichiers **TIFF pyramidaux** compatibles avec des outils de visualisation ou des traitements en intelligence artificielle.

Fonctionnement du DAG

Le DAG suit les étapes suivantes :

1. **Liste des fichiers** à traiter dans le dossier `input_images/`, en filtrant selon des extensions supportées (`ndpi`, `mrxs`, `svs`, `scn`, `bif`, `tiff`, `tif`, `zip`)
2. **Pour chaque fichier détecté** :
  - S’il s’agit d’un fichier image : il est directement converti au format pyramidal `.tiff` via l’outil `vips`
  - S’il s’agit d’un fichier `.zip` : il est extrait dans un dossier temporaire
3. Tous les fichiers `.mrxs` extraits depuis les `.zip` sont également convertis à leur tour
4. Enfin, un nettoyage automatique supprime les dossiers temporaires utilisés

Technologies utilisées

- `BashOperator` pour exécuter les conversions `vips tiffsave`
- `PythonOperator` pour lister les fichiers, extraire les `.zip`, convertir les fichiers `.mrxs`, et nettoyer
- Pas de déclenchement automatique : le DAG est **lancé manuellement depuis l’interface Airflow**

Répertoires utilisés

- `input_images/` : dossier d’entrée contenant les fichiers à traiter
- `output_images/` : destination des fichiers `.tiff` convertis
- `temp/` : dossier temporaire utilisé pour les extractions de `.zip`

---

Ce DAG est conçu pour s’adapter dynamiquement aux fichiers présents dans `input_images/` au moment de son lancement. Ces 3 dossiers sont automatiquement créés pendant l'installation décrite ci-dessous.

---

Structure des fichiers

| Fichier                   | Description |
|---------------------------|-------------|
| `config.env`                      | Contient toutes les variables de configuration |
| `env_airflow.sh`                  | Active le venv et exporte `AIRFLOW_HOME` |
| `scripts/01_install_deps.sh`      | Installe les dépendances système |
| `scripts/02_setup_postgres.sh`    | Crée la base PostgreSQL et l'utilisateur |
| `scripts/03_setup_airflow.sh`     | Installe Airflow, initialise la DB, copie les DAGs |
| `scripts/04_create_user.py`       | Crée un utilisateur Airflow |
| `scripts/05_start_scheduler.sh`   | Démarre le scheduler |
| `scripts/06_start_webserver.sh`   | Démarre le webserver |
| `scripts/run_all.sh`              | lance tous les scripts de 01 à 04 |
| `dags/`                           | Contient les fichiers DAGs personnalisés |
| `dags/picola_dag.py`              | Le DAG permettant la conversion des images au format tiff pyramidal |
| `Makefile`                        | Point d’entrée principal (`make install`, etc.) pour lancer les installations automatiquement |
 

Il s’agit de la version 1.0 réalisée en Juillet 2025.

Pré-requis

- Ubuntu/Debian avec `sudo`
- Connexion Internet
- Python ≥ 3.10 (installé automatiquement si manquant - recommandé : 3.12.3)
- Airflow testé avec la version 2.10.2

Installation

0. Clonez ce dépôt via Git si besoin

1. Modifiez la configuration dans le fichier `config.env` en remplaçant YOUR_USERNAME par votre nom de user Linux et en définissant les dossiers de travail. Toutes les lignes peuvent être mises à jour :
```bash
nano config.env
```

2. Lancez l’installation complète. Elle n'est à lancer qu'une seule fois. Veillez à bien être au même niveau que le fichier `Makefile` pour lancer l'install sinon ça ne fonctionnera pas :
```bash
make install
```

 Lancement des services Airflow

Une fois l'installation terminée, vous pouvez lancer le scheduler et le webserver pour accéder à l'interface Airflow.

Veillez à bien être au même niveau que le fichier `Makefile` pour lancer le scheduler et le webserver sinon ça ne fonctionnera pas.

Terminal 1 – Scheduler :

Ce make est à lancer à chaque nouvelle ouverture de session. 

```bash

make scheduler

```

Terminal 2 – Webserver :

Ce make est à lancer à chaque nouvelle ouverture de session.

```bash

make webserver

```

Une initialisation de la base peut être demandée automatiquement (répondue par `yes`).

---

 Exécution d’un DAG

1. Un dag pour convertir les formats d'image vers tiff pyramidal est déjà présent dans votre dossier AIRFLOW_HOME tel que configuré dans le `config.env` avant installation (AIRFLOW_HOME/dags/picola_dag.py).

2. Le dag permettant la conversion est automatiquement copié dans le dossier `$AIRFLOW_HOME/dags/` lors du `make install`.

3. Une fois le webserver lancé, accédez à l’interface :

   ```
  http://localhost:8080

   ```
 ou
   ```
   http://{your_IP}:8080
  ```

4. Connectez-vous avec les identifiants (`ADMIN_USERNAME` et `ADMIN_PASSWORD`) définis dans `config.env`.

5. Vérifiez que vous avez bien au moins une image à convertir dans le dossier input_images. Si besoin, par exemple, récupérer une image open source avec : 

   ```bash 

   wget -P "{$BASE_DIR}input_images" https://openslide.cs.cmu.edu/download/openslide-testdata/Mirax/CMU-3.zip

   ```

   `BASE_DIR` correspond au dossier de travail qui est défini dans `config.env`.

6. Activez le DAG dans l’interface et cliquez sur ▶ pour l’exécuter (`convert_new`)

7. Les images converties en TIFF pyramidal se trouvent dans le dossier output_images

Les contributions à ce projet sont les bienvenues ! Veuillez soumettre une pull request avec vos modifications ou suggestions d'amélioration.
 

Support

Pour toute question ou problème, vous pouvez contacter l'auteur à l'adresse suivante : victor.leandre-chevalier@health-data-hub.fr.

Merci à tous les contributeurs et testeurs de ce projet.

Ce projet est sous licence Apache 2.0. Les détails de la licence se trouvent dans le fichier LICENSE.