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
Trois modes de capture :
- ArduCam (Picamera2) — caméra haute définition montée sur le bras
- Webcam — via OpenCV (développement / test)
- Vidéo plaque (VideoPlateCapture) — crop dynamique dans une vidéo plaque entière rejouée en boucle ; adapté aux scans sans caméra embarquée
Calibration assistée :
- Détection automatique du centre du puit (Hough + CLAHE, plage rayon adaptable selon le mode)
- Overlay Canny vert pour visualiser les bords en conditions d'éclairage difficile
- Contrôles temps réel : Debug, Overlay annotations, Contours, Recadrage
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

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.
Personnalisez votre raspberry avec au moins ssh (sshkey ou password)
Plus tard, par commodité vous installerez VNC server

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 :

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

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

Mode caméra (ArduCam / Webcam)

Debug → active la détection HoughCircles en continu (cercle + zones affiché)
Overlay → affiche/masque les annotations sans couper la détection
Recadrer → isole le puit et navigue vers la position Base
Calibrage auto → centrage automatique puit par puit avec sauvegarde

Mode vidéo plaque

Note

: ce mode permet de piloter le scanner sans caméra embarquée sur le bras CNC. Une vidéo de la plaque entière est enregistrée une seule fois puis rejouée en boucle ; chaque déplacement GRBL extrait dynamiquement la zone du puit courant dans cette vidéo. Idéal pour les tests sans matériel ou les laboratoires ne disposant pas de caméra ArduCam.

Créer un enregistrement VideoPlate dans l'admin (upload vidéo, px_per_mm, x_origin_mm, y_origin_mm)
Contours → overlay Canny vert pour repérer les bords des puits selon l'éclairage
Debug → détection Hough adaptée (plage rayon élargie pour puit plein cadre)
Recadrer → active le crop + déplace vers la Base
Naviguer puit par puit, sauvegarder les positions

🎬 Vidéo Calibration auto

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.