414 lines
14 KiB
Markdown
414 lines
14 KiB
Markdown
|
||
#  PlanarianScanner
|
||
|
||
> Système d'imagerie automatisé pour le suivi comportemental de planaires
|
||
|
||
> (C) dd@linuxtarn.org pour le Laboratoire de Biologie, Université Champollion, Albi
|
||
|
||
---
|
||
|
||
## Présentation
|
||
|
||
**PlanarianScanner** est une application web développée pour le suivi de l'activité
|
||
et des mouvements de **planaires** (*Platyhelminthes*) dans le cadre de leur étude
|
||
en laboratoire.
|
||
|
||
Le système pilote un scanner multi-puits motorisé composé d'un bras CNC (GRBL) et
|
||
d'une caméra haute définition ArduCam montée sur Raspberry Pi 4. Il permet
|
||
l'acquisition automatisée d'images sur une grille de **6×4 puits × 4 plaques**,
|
||
le stockage haute performance des captures, et leur export vers des machines
|
||
d'analyse distantes.
|
||
|
||
---
|
||
|
||
## Matériel
|
||
|
||
| Composant | Détail |
|
||
|---|---|
|
||
| Carte | Raspberry Pi 4 |
|
||
| Caméra | ArduCam haute définition |
|
||
| Motorisation | Bras CNC (L2544) piloté en GRBL |
|
||
| Grille de puits | 6×4 × 4 plaques multi-puits |
|
||
| Réseau | LAN local — export Samba/rsync |
|
||
|
||
---
|
||
|
||
## Stack technique
|
||
|
||
| Couche | Technologie |
|
||
|---|---|
|
||
| Backend | Django + Django Channels |
|
||
| Temps réel | Redis (broker + channel layer) |
|
||
| Acquisition | OpenCV + Picamera2 |
|
||
| Stockage | ReductStore (time series haute performance) |
|
||
| Tâches asynchrones | Celery + django-celery-beat |
|
||
| Export | Samba (CIFS), rsync/SSH |
|
||
| Plateforme | Raspberry Pi 4 — Debian Linux |
|
||
|
||
---
|
||
## Fonctionnalités
|
||
|
||
### Application 1: Scanner de tube à essais
|
||
|
||
- Pilotage du bras CNC en GRBL — déplacement automatique puits par puits
|
||
- Calibration des multi-puits avec synchro base de données
|
||
- Acquisition image haute définition via ArduCam (OpenCV + Picamera2)
|
||
- Stockage des frames en base time série ReductStore
|
||
- Sessions de scan paramétrables (grille complète ou sélection de puits)
|
||
- Export asynchrone (Celery) :
|
||
- Archive ZIP d'images JPEG par session
|
||
- Vidéo MP4 générée depuis les frames capturées
|
||
- Transfert automatique des exports vers machines distantes (Linux / Windows)
|
||
- Planification nocturne des exports via django-celery-beat
|
||
- Interface web temps réel (Django Channels / WebSocket)
|
||
- Interface administration Django (sqlite3 ou mariadb ou postgresql)
|
||
- Suivi de progression des tâches longues par polling
|
||
|
||
### Application 2: Détection de planaires et suivi multi-individus dans un tube.
|
||
|
||
|
||
[🎬 Vidéo Simulation planaires](https://youtu.be/pkzClmBp_KM)
|
||
|
||
|
||
- Supporte plusieurs planaires avec paramètres configurables via django ou csv.
|
||
|
||
- Stratégie :
|
||
|
||
- Soustraction de fond MOG2 (léger sur Raspberry Pi 4)
|
||
- Détection de tous les contours valides (surface >= min_area_px)
|
||
- Association frame-à-frame par distance euclidienne minimale
|
||
via algorithme hongrois (scipy.optimize.linear_sum_assignment)
|
||
- Un état inter-frame indépendant par individu (PlanarianState)
|
||
- Retourne une liste de résultats, un par individu suivi
|
||
|
||
- Export CSV par planaire compatible EthoVision XT.
|
||
- Métriques par frame :
|
||
|
||
- Mobilité : velocity, distance, moving, mobility_state
|
||
- Thigmo : dist_to_wall_mm, near_wall
|
||
- Photo : dist_to_light_mm, heading_to_light_deg, fleeing_light
|
||
- Chemo : dist_to_food_mm, heading_to_food_deg, approaching_food, in_food_zone
|
||
- Social : nearest_neighbour_mm, in_avoid_zone, in_aggreg_zone, chem_repulsion_level
|
||
|
||
- Métriques résumé (summary) :
|
||
|
||
- Mobilité : movedCenter_pointTotal_mm, velocity_mean_mm_s, durations par état
|
||
- Thigmo : thigmotaxis_pct_time_near_wall
|
||
- Photo : photo_pct_time_fleeing, photo_mean_dist_mm, photo_latency_s
|
||
- Chemo : chemo_pct_time_approaching, chemo_pct_time_in_zone,
|
||
chemo_latency_s, chemo_mean_dist_mm
|
||
- Social : social_pct_time_avoiding, social_pct_time_aggregating,
|
||
social_mean_nn_mm, social_contact_events
|
||
|
||
- Seuils EthoVision par défaut (configurables via django ou csv)
|
||
|
||
- **Immobile** : déplacement < 0.2 mm/s
|
||
- **Mobile** : 0.2 à 1.5 mm/s
|
||
- **Très mobile** : > 1.5 mm/s
|
||
|
||
| EthoVision | CSV frames | CSV summary |
|
||
|---|---|---|
|
||
| movedCenter-pointTotalmm | total_distance_mm | movedCenter_pointTotal_mm |
|
||
| VelocityCenter-pointMeanmm/s | velocity_mm_s | velocity_mean_mm_s |
|
||
| MovementMoving | moving, duration_moving_s | movement_moving_duration_s |
|
||
| MovementNot Moving | duration_stopped_s | movement_not_moving_duration_s |
|
||
| ImmobileFrequency / Duration | mobility_state | mobility_immobile_frequency/duration_s |
|
||
| MobileFrequency / Duration | mobility_state | mobility_mobile_frequency/duration_s |
|
||
| Highly mobileFrequency / Duration | mobility_state | mobility_highly_mobile_frequency/duration_s |
|
||
|
||
- Comportements
|
||
|
||
- **Thigmotactisme** : attraction vers la paroi (--thigmotaxis)
|
||
- **Phototactisme** : fuite de la lumière (--photo-mode, --photo-strength)
|
||
- **Chimiotactisme** : attraction vers une source de nourriture (--chemo-strength)
|
||
- **Inter-individus** : évitement de contact, agrégation, répulsion chimique
|
||
|
||
### Application 4: Simulation de planaires
|
||
|
||
- planarian_sim.py
|
||
|
||
Espace circulaire de 16mm de diamètre, 500x500px
|
||
Supporte plusieurs planaires avec paramètres configurables via arguments CLI.
|
||
Export CSV par planaire compatible EthoVision XT.
|
||
|
||
Comportements simulés :
|
||
- Thigmotactisme : attraction vers la paroi (--thigmotaxis)
|
||
- Phototactisme : fuite de la lumière (--photo-mode, --photo-strength)
|
||
- Chimiotactisme : attraction vers une source de nourriture (--chemo-strength)
|
||
- Inter-individus : évitement de contact, agrégation, répulsion chimique
|
||
|
||
Usage:
|
||
python3 planarian_sim.py [options]
|
||
|
||
Exemples:
|
||
python3 planarian_sim.py --count 5 --thigmotaxis 0.4
|
||
python3 planaire_sim.py --count 5 --photo-mode fixed --photo-x 0.2 --photo-y 0.2 --photo-strength 0.6
|
||
python3 planarian_sim.py --count 5 --chemo-x 0.7 --chemo-y 0.5 --chemo-strength 0.5
|
||
python3 planarian_sim.py --count 5 --avoid-strength 0.6 --aggreg-strength 0.2
|
||
|
||
- make_videos.sh
|
||
|
||
- Générateur de vidéos paramétrables
|
||
|
||
Usage:
|
||
- ./make_video.sh (génère le fichier par défaut)
|
||
- ./make_video.sh all (génère 24 vidéos pour 24 tubes à essais)
|
||
---
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Raspberry Pi 4
|
||
├── Django (interface web + API)
|
||
│ ├── Django Channels ←→ Redis (WebSocket temps réel)
|
||
│ └── Celery workers
|
||
│ ├── scanning(session_id) — parcours des puits
|
||
│ ├── export_images_zip() — génération ZIP JPEG
|
||
│ ├── export_video_mp4() — génération MP4 (OpenCV)
|
||
│ └── transfer → /mnt/exports — partage Samba
|
||
│
|
||
├── ArduCam ← Picamera2 / OpenCV — capture HD
|
||
├── CNC GRBL ← Serial — déplacement XY
|
||
└── ReductStore — stockage time série frames
|
||
```
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
> Documentation complète à venir.
|
||
|
||
Avec piImager installez PI OS 64-bits Trixie sur le raspberry pi4.<br>
|
||
Personnalisez votre raspberry avec au moins ssh (sshkey ou password)<br>
|
||
Plus tard, par commodité vous installerez VNC server
|
||
|
||
|
||
```bash
|
||
ssh rpi4@ip.du.raspi
|
||
|
||
git clone https://github.com/votre-repo/planarianscanner.git
|
||
git@github.com:deunix-educ/PlanarianScanner.git
|
||
|
||
# modifier les variables d'environnement si besoin
|
||
cp .env.example .env
|
||
# Éditer .env : SECRET_KEY, REDIS_URL, REDUCTSTORE_URL, ...
|
||
|
||
cd PlanarianScanner/etc
|
||
chmod +x *.sh
|
||
|
||
# installation des librairies systèmes
|
||
./1-install-sys.sh
|
||
|
||
# compilation reductstore 15 mn sur le raspberry pi4
|
||
./2-cargo-reductstore-install.sh
|
||
|
||
# installation samba client
|
||
./3-install-samba-client.sh
|
||
|
||
# installation de mariadb
|
||
./4-install_mariadb.sh
|
||
|
||
# installation de adminer
|
||
./5-install_adminer.sh
|
||
|
||
# Configuration des applications Django
|
||
./6-install_django_app.sh
|
||
|
||
# tester
|
||
sudo supervisorctl stop test_tube:*
|
||
./manage.py runserver 0.0.0.0:8000
|
||
|
||
# tester en local
|
||
# http://127.0.0.1:8000
|
||
|
||
# tester en distant
|
||
# http://ip.du.raspi:8000
|
||
|
||
# fin du test
|
||
sudo supervisorctl restart test_tube:*
|
||
|
||
```
|
||
|
||
Démarrage des services :
|
||
|
||
```bash
|
||
Tous les services sont accessibles depuis supervisor
|
||
http://root:toor@ip-du-raspi:9001
|
||
ou
|
||
sudo supervisorctl start|stop|restart reductstore
|
||
sudo supervisorctl start|stop|restart test_tube:*
|
||
|
||
Ajouter scanner.local au fichier hosts des clients web:
|
||
si 10.8.0.100 est l'ip locale du raspberry pi4 le serveur
|
||
|
||
10.8.0.100 scanner.local
|
||
|
||
- linux : /etc/hosts
|
||
- windows: C:\Windows\System32\drivers\etc\hosts
|
||
- mac : /private/etc/hosts"
|
||
|
||
```
|
||
|
||
## Organisation du dépôt
|
||
|
||
```bash
|
||
PlanarianScanner/
|
||
├── assets
|
||
│ ├── calibration-auto.png
|
||
│ └── logo.png
|
||
├── browser.py
|
||
├── etc
|
||
│ ├── 1-install-sys.sh
|
||
│ ├── 2-cargo-reductstore-install.sh
|
||
│ ├── 3-install-samba-client.sh
|
||
│ ├── 4-install_mariadb.sh
|
||
│ ├── 5-install_adminer.sh
|
||
│ ├── 6-install_django_app.sh
|
||
│ ├── db
|
||
│ │ ├── configuration.json
|
||
│ │ ├── multiwell.json
|
||
│ │ └── well.json
|
||
│ ├── install-linux-samba-server.sh
|
||
│ ├── nginx_service.conf
|
||
│ ├── reductstore_service.conf
|
||
│ ├── requirements.txt
|
||
│ ├── scanner_service.conf
|
||
│ └── supervisor-inet_http.conf
|
||
├── LICENSE
|
||
├── README.md
|
||
└── test_tube_scanner
|
||
├── home
|
||
│ ├── apps.py
|
||
│ ├── asgi.py
|
||
│ ├── celerymodule.py
|
||
│ ├── context_processors.py
|
||
│ ├── __init__.py
|
||
│ ├── locale
|
||
│ ├── management
|
||
│ ├── middleware.py
|
||
│ ├── __pycache__
|
||
│ ├── settings.py
|
||
│ ├── static
|
||
│ ├── templates
|
||
│ ├── templatetags
|
||
│ ├── urls.py
|
||
│ ├── views.py
|
||
│ └── wsgi.py
|
||
├── logs
|
||
│ ├── celery.log
|
||
│ └── test_tube.log
|
||
├── manage.py
|
||
├── media
|
||
│ ├── images
|
||
│ └── simulation
|
||
├── modules
|
||
│ ├── capture_interface.py
|
||
│ ├── circular_crop.py
|
||
│ ├── grbl.py
|
||
│ ├── __init__.py
|
||
│ ├── picamera2_capture_basic.py
|
||
│ ├── picamera2_capture.py
|
||
│ ├── planarian_metrics.py
|
||
│ ├── planarian_tracker.py
|
||
│ ├── __pycache__
|
||
│ ├── reductstore.py
|
||
│ ├── system_stats.py
|
||
│ ├── tube_aligner.py
|
||
│ ├── utils.py
|
||
│ ├── videofile_capture.py
|
||
│ └── webcam_capture.py
|
||
├── planarian
|
||
│ ├── admin.py
|
||
│ ├── apps.py
|
||
│ ├── forms.py
|
||
│ ├── __init__.py
|
||
│ ├── migrations
|
||
│ ├── models.py
|
||
│ ├── __pycache__
|
||
│ ├── templates
|
||
│ ├── tests.py
|
||
│ ├── urls.py
|
||
│ └── views.py
|
||
├── run-workers.sh
|
||
├── scanner
|
||
│ ├── admin.py
|
||
│ ├── apps.py
|
||
│ ├── constants.py
|
||
│ ├── consumers.py
|
||
│ ├── export_tasks.py
|
||
│ ├── __init__.py
|
||
│ ├── migrations
|
||
│ ├── models.py
|
||
│ ├── multiwell.py
|
||
│ ├── process.py
|
||
│ ├── __pycache__
|
||
│ ├── routing.py
|
||
│ ├── static
|
||
│ ├── tasks.py
|
||
│ ├── templates
|
||
│ ├── templatetags
|
||
│ ├── tests.py
|
||
│ ├── urls.py
|
||
│ └── views.py
|
||
├── staticfiles
|
||
│ ├── admin
|
||
│ ├── css
|
||
│ ├── img
|
||
│ ├── js
|
||
│ ├── scanner
|
||
│ └── webfonts
|
||
└── templates
|
||
└── admin
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## Procédure de calibration en 4 étapes
|
||
1. Activer "Debug détection" → voir le cercle et les zones sur le stream
|
||
|
||
2. Activer recadrage pour isoler le tube
|
||
|
||
Calibration auto
|
||
|
||
 Calibration auto
|
||
|
||
[🎬 Vidéo Calibration auto](https://youtu.be/6RueJ3onUoY)
|
||
|
||
|
||
|
||
## Contexte scientifique
|
||
|
||
Les **planaires** sont des vers plats dotés de remarquables capacités de
|
||
régénération et d'un système nerveux primitif faisant l'objet de nombreuses
|
||
recherches en neurobiologie et biologie du développement.
|
||
|
||
Ce système d'imagerie automatisé permet d'observer et d'enregistrer leur
|
||
comportement (déplacements, réponses à des stimuli) sur de longues périodes,
|
||
pour un grand nombre d'individus en parallèle, sans intervention humaine.
|
||
|
||
---
|
||
|
||
## Laboratoire
|
||
|
||
Développé par dd@linuxtarn.org pour le **Laboratoire de Biologie de l'Université Champollion**, Albi.
|
||
|
||
---
|
||
|
||
|
||
## Statut
|
||
|
||
> Documentation détaillée et guides d'installation complets à venir prochainement.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## Licence
|
||
|
||
GPL-3.0 — Projet opensource, développé pour le partage et la reproductibilité scientifique.
|