trombinoscope 0.1.0__tar.gz

trombinoscope-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Photographies : le dépôt n'en contient aucune, et ne doit jamais en contenir.
+# Les tests d'intégration les téléchargent via scripts/fetch_samples.py.
+tests/data/portraits/
+*.jpg
+*.jpeg
+*.heic
+*.heif
+# Exception : la silhouette de remplacement, dessinée par scripts/make_placeholder.py
+!src/trombinoscope/assets/placeholder.png
+
+# Sorties de travail
+artifacts/
+portraits/
+detections/
+*.pdf
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Outils
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Systèmes
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

trombinoscope-0.1.0/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Journal des modifications
+
+Le format suit [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/) et le
+versionnage sémantique.
+
+## [Non publié]
+
+## [0.1.0]
+
+Première version publique. C'est la réécriture d'un module personnel de 2020,
+jamais publié, qui produisait les trombinoscopes d'une classe préparatoire.
+
+### Ajouté
+
+- Interface en ligne de commande `trombinoscope` avec trois sous-commandes :
+  `build`, `inspect` et `template`.
+- `BatchColorHarmonizer` : harmonisation colorimétrique **à l'échelle du lot**,
+  en deux passes, vers l'illuminant et la luminance médians de la séance. C'est
+  la seule fonction que les bibliothèques de correction couleur existantes ne
+  fournissent pas — elles travaillent toutes image par image. Sur une séance
+  simulée, la dispersion chromatique chute de 78 %.
+- Estimateurs d'illuminant `GrayWorldEstimator`, `ShadesOfGrayEstimator`
+  (défaut, `p = 6`) et `WhitePatchEstimator`, calculés **en lumière linéaire**.
+- `LuminanceMatcher` : normalisation d'exposition par correction gamma, mesurée
+  sur le visage et non sur l'image entière.
+- Paramètre `strength` pour atténuer la correction de teinte.
+- `PortraitFramer` : recadrage à proportion de visage constante, et redressement
+  optionnel de la ligne des yeux (`align_eyes`).
+- Détection par YuNet, avec les cinq points caractéristiques. Le détecteur est un
+  protocole injectable.
+- `RosterLoader` : lecture CSV et JSON, séparateur détecté, en-têtes reconnus
+  sans tenir compte de la casse ni des accents, colonnes inconnues ignorées.
+- `load_sqlite` : liste chargée depuis une requête SQLite libre, base ouverte en
+  lecture seule, colonnes nommées avec `AS` pour traduire un schéma métier.
+- `GridConfig.title_top` et `title_skip` se comptent en **hauteurs de ligne**
+  (multiples de `font_size`) et non en millimètres, de sorte que l'espacement du
+  titre suive sa taille. `PdfCanvas.draw_paragraph` tient désormais compte des
+  `spaceBefore` / `spaceAfter` du style, comme un flowable ReportLab.
+- `GridConfig.annotation_layout`, `badge_corner`, `badge_inset`, `logo_position`,
+  `logo_width`, `logo_margin` et `logo_offset` : placement des annotations
+  pivotées, de l'étoile et du logo. Le logo se pose par défaut en haut à droite,
+  et l'étoile est centrée sur le coin de la photo.
+- `examples/trombi_mp_sqlite.py` : reproduction d'un trombinoscope de classe
+  préparatoire depuis sa base SQLite, avec la mise en page historique.
+- `BuildReport` : rapport structuré des personnes sans photo, photos sans
+  personne, photos sans visage et photos à plusieurs visages.
+- `GridPaginator` : pagination testable indépendamment de ReportLab.
+- Lecture des fichiers HEIC via l'extra `[heic]`.
+- 322 tests, dont l'essentiel tourne sur des images synthétiques et un détecteur
+  bouchon : ni réseau, ni modèle, ni photographie. Intégration continue sur
+  Linux, macOS et Windows, en Python 3.11 à 3.14.
+- Documentation : [étude colorimétrique](docs/color.md), [état de l'art et étude
+  d'originalité](docs/prior-art.md), [pistes d'amélioration](docs/improvements.md),
+  [revue du module de 2020](docs/legacy-review.md).
+
+### Corrigé
+
+Défauts de la version 2020. L'analyse détaillée, extraits de code à l'appui, est
+dans [docs/legacy-review.md](docs/legacy-review.md) ; le code source, lui, ne
+commente que ce qu'il fait.
+
+- **La correction colorimétrique était inopérante.**
+  `cv2.convertScaleAbs(image, alpha, beta)` place `alpha` en position `dst` et
+  `beta` en position `alpha` — la signature réelle est
+  `convertScaleAbs(src, dst, alpha, beta)`. Le gain calculé n'était jamais
+  appliqué et les images ressortaient saturées. Un test de non-régression
+  verrouille l'appel nommé. Détail dans [docs/color.md](docs/color.md).
+- **L'appariement se décalait silencieusement.** Une photo sur laquelle aucun
+  visage n'était trouvé faisait `continue` sans avancer l'indice de la personne :
+  toutes les suivantes changeaient de photo. L'appariement est désormais résolu
+  avant toute détection.
+- **Les annotations se retrouvaient sous les mauvaises photos** quand la dernière
+  ligne était centrée : placement et annotations recalculaient l'indice de la
+  personne de deux façons incompatibles. Une `IndexError` était même possible sur
+  une dernière ligne incomplète.
+- **`UnboundLocalError`** lorsque les groupes étaient affichés sans étiquettes :
+  la coordonnée `x` n'était calculée que dans la branche des étiquettes.
+- **Exception sur les cadrages débordant** de la photo source, par recollage
+  manuel de tranches de tableau.
+- **Division par zéro** de l'étalement d'histogramme sur une image uniforme.
+- **Étalement calculé sur l'image entière**, donc sur le fond plutôt que sur le
+  sujet.
+- **Chemins non-ASCII** : `cv2.imread` et `cv2.imwrite` échouent silencieusement
+  sous Windows ; la lecture et l'écriture passent par `imdecode` / `imencode`.
+- **`os.system` avec un chemin concaténé** dans l'ouverture du PDF : un espace ou
+  une apostrophe cassait la commande.
+- **Sensibilité à la casse du système de fichiers** devinée en écrivant un
+  fichier temporaire dans le dossier de l'utilisateur, avec un cache partagé
+  entre tous les dossiers.
+- **Déduplication en O(n²)** par `os.path.samefile`.
+
+### Modifié
+
+- **Modèle de détection** : SSD ResNet-10 Caffe (10 Mo) remplacé par YuNet ONNX
+  (227 Ko), qui fournit en plus les points caractéristiques. L'arborescence
+  d'origine transportait 142 Mo de modèles, dont 132 Mo jamais chargés par le
+  code — le prédicteur 68 points de dlib et un fichier PyTorch. `readNetFromCaffe`
+  a par ailleurs disparu d'OpenCV 5 : l'ancienne approche n'était plus viable.
+- **`Eleve` devient `Person`.** Les champs de prépa française (`cube`, `LV1`,
+  `LV2`, `option`, `groupe`, `groupecolle`) laissent place à deux listes libres
+  d'étiquettes, qui couvrent le cas d'origine sans imposer son vocabulaire. Table
+  de correspondance dans [docs/DOC.md](docs/DOC.md), section 10.
+- **`trombinoscope/logging.py` devient `trombinoscope/log.py`** et s'appuie sur
+  la bibliothèque standard. L'ancien nom masquait `logging` pour tout import
+  absolu depuis l'intérieur du paquet.
+- **`warning()` ne bloque plus sur `input()`.** La pause interactive devient un
+  choix explicite de l'appelant, désactivé par défaut.
+- **Aucun modèle n'est chargé à l'import.** Le réseau était construit au niveau
+  module : un simple `import trombinoscope` le payait, et échouait si le fichier
+  manquait, même pour n'utiliser que la mise en page.
+- **`pkg_resources` remplacé par `importlib.resources`** — le premier a disparu
+  de Python 3.12.
+- **Le module local `pdf_maker` (412 lignes, non publié) est réduit** à ce dont
+  le trombinoscope a besoin. La grille est dessinée directement sur le canevas
+  plutôt qu'avec des tableaux ReportLab imbriqués, ce qui rend la position des
+  annotations traçable.
+- **Dépendance `opencv-python-headless`** plutôt que `opencv-python` : aucune
+  bibliothèque graphique système requise.
+- **L'étalement d'histogramme est désactivé par défaut.** Une fois son bug
+  corrigé, la mesure montre qu'il dégrade la cohérence du lot.
+- **La rotation de redressement des yeux** utilisait l'opposé de l'inclinaison,
+  ce qui l'aurait doublée au lieu de la corriger. Détecté par un test lors de la
+  réécriture ; la fonctionnalité n'avait jamais été branchée dans la version
+  d'origine.
+
+### Supprimé
+
+- Toutes les photographies personnelles : portraits d'élèves, PDF de
+  trombinoscopes nominatifs, logo d'établissement. Le dépôt ne contient plus
+  aucune image de personne, et la CI vérifie qu'il n'en apparaît ni dans le dépôt
+  ni dans la roue. Les tests d'intégration téléchargent à la demande des
+  portraits sous licence libre — voir [CREDITS.md](CREDITS.md).
+- `FaceAligner` et le prédicteur 68 points de dlib (95 Mo), jamais utilisés : le
+  redressement se fait maintenant avec les points de YuNet, dans la même
+  transformation affine que le recadrage.
+- Le fichier `HR18-300W.pth` (37 Mo), auquel aucun code ne faisait référence.
+- Le cache `photos.pkl` écrit dans le dossier de l'utilisateur.
+- Le guide ReportLab en PDF (548 Ko) versionné dans l'arborescence.
+
+[Non publié]: https://github.com/antnardo/trombinoscope/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/antnardo/trombinoscope/releases/tag/v0.1.0

trombinoscope-0.1.0/CREDITS.md

@@ -0,0 +1,99 @@
+# Crédits et licences des composants tiers
+
+## Embarqué dans la distribution
+
+### Modèle de détection YuNet
+
+`src/trombinoscope/assets/models/face_detection_yunet_2023mar.onnx` — 227 Ko.
+
+- Source : [OpenCV Zoo](https://github.com/opencv/opencv_zoo/tree/main/models/face_detection_yunet)
+- Auteurs : Wei Wu, Weiyuan Peng, Shiqi Yu
+- Licence : MIT
+- Empreinte SHA-256 : `8f2383e4dd3cfbb4553ea8718107fc0423210dc964f9f4280604804ed2552fa4`
+
+La licence MIT du dépôt OpenCV Zoo couvre les poids comme le code, ce qui autorise
+la redistribution dans une roue PyPI — contrairement, par exemple, aux poids
+d'InsightFace ou de MODNet, réservés à un usage non commercial. Voir
+[docs/improvements.md](docs/improvements.md), section 1.2.
+
+### Silhouette de remplacement
+
+`src/trombinoscope/assets/placeholder.png` est **dessinée par
+`scripts/make_placeholder.py`**, pas téléchargée. C'est la seule façon d'être
+certain qu'aucune œuvre tierce — et surtout aucun portrait de personne réelle —
+ne se retrouve dans la distribution. Pour la régénérer :
+
+```bash
+uv run python scripts/make_placeholder.py
+```
+
+## Dépendances d'exécution
+
+| Paquet | Licence |
+| --- | --- |
+| [NumPy](https://numpy.org/) | BSD-3-Clause |
+| [opencv-python-headless](https://github.com/opencv/opencv-python) | Apache-2.0 (OpenCV), MIT (l'empaquetage) |
+| [Pillow](https://python-pillow.org/) | MIT-CMU |
+| [ReportLab](https://www.reportlab.com/) | BSD-3-Clause |
+| [pillow-heif](https://github.com/bigcat88/pillow_heif) *(extra `heic`)* | BSD-3-Clause / LGPL-3.0 pour libheif |
+
+## Images de test
+
+**Aucune de ces images n'est versionnée ni distribuée.** Elles sont téléchargées
+à la demande par `scripts/fetch_samples.py`, dans `tests/data/portraits/`, un
+dossier ignoré par git. Les tests unitaires — l'essentiel de la couverture —
+n'en ont pas besoin et fonctionnent sur des images synthétiques.
+
+Toutes proviennent de [Wikimedia Commons](https://commons.wikimedia.org/) et sont
+sous licence libre. L'attribution ci-dessous est fournie parce que c'est correct
+de le faire, et parce que trois d'entre elles l'exigent.
+
+| Fichier local | Sujet | Licence | Auteur |
+| --- | --- | --- | --- |
+| `01-hopper.jpg` | Grace Hopper | Domaine public | James S. Davis, U.S. Navy |
+| `02-johnson.jpg` | Katherine Johnson | Domaine public | NASA |
+| `03-perlman.jpg` | Radia Perlman | Domaine public | Scientist-100 (Wikipédia anglophone) |
+| `04-hamilton.jpg` | Margaret Hamilton | CC BY-SA 3.0 | Daphne Weld Nichols |
+| `05-liskov.jpg` | Barbara Liskov | CC BY-SA 3.0 | Kenneth C. Zirkel |
+| `06-vanrossum.jpg` | Guido van Rossum | CC BY-SA 4.0 | Daniel Stroud |
+| `07-knuth.jpg` | Donald Knuth | CC BY-SA 2.5 | Jacob Appelbaum |
+| `08-kay.jpg` | Alan Kay | CC BY 2.0 | Marcin Wichary |
+
+Le manifeste écrit à côté des fichiers (`MANIFEST.json`) reprend ces informations
+avec l'URL de la page Commons et l'empreinte SHA-256 de chaque téléchargement.
+
+Note sur le partage à l'identique : les clauses SA des licences CC BY-SA
+s'appliquent à la **distribution** d'œuvres dérivées. Les portraits recadrés
+produits par les tests vivent dans un dossier temporaire et ne sont jamais
+publiés ; aucune obligation de partage n'est donc déclenchée. Si vous
+redistribuez ces images ou des dérivés, les clauses s'appliquent pleinement.
+
+## Travaux antérieurs
+
+Le paquet ne reprend le code d'aucun projet tiers, mais il s'appuie sur des idées
+et des algorithmes publiés. L'[étude d'originalité](docs/prior-art.md) est
+détaillée ; les dettes principales :
+
+- **Shades of Gray** — G. Finlayson et E. Trezzi, *Shades of Gray and Colour
+  Constancy*, Color Imaging Conference, 2004. L'estimateur d'illuminant par
+  défaut est une implémentation directe de cet article.
+- **Correction de von Kries** — J. von Kries, 1902, pour la correction diagonale
+  par gains indépendants par canal.
+- **Retinex / white patch** — E. Land, *The Retinex Theory of Color Vision*,
+  Scientific American, 1977.
+- **YuNet** — W. Wu, W. Peng, S. Yu, *YuNet: A Tiny Millisecond-level Face
+  Detector*, Machine Intelligence Research, 2023.
+- **[autocrop](https://github.com/leblancfg/autocrop)** (MIT) — le recadrage à
+  proportion de visage constante (`--facePercent`) y préexiste. Aucun code n'en
+  est repris, mais l'idée n'est pas de nous.
+- **[WhosWho](https://framagit.org/Yvan-Masson/WhosWho)** (GPL-3.0) — le
+  concurrent libre le plus abouti, et une référence utile pour ce qu'un
+  générateur de trombinoscope doit savoir faire.
+
+## Historique
+
+Ce paquet est la réécriture d'un module personnel non publié, écrit en 2020 pour
+produire les trombinoscopes d'une classe préparatoire. La structure du pipeline,
+la logique de dernière ligne centrée et les annotations pivotées en viennent
+directement. Le reste — modèle de détection, module colorimétrique, découpage en
+modules, tests, CLI — a été refait. Voir [CHANGELOG.md](CHANGELOG.md).

trombinoscope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 antnardo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trombinoscope-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: trombinoscope
+Version: 0.1.0
+Summary: Génère un trombinoscope PDF prêt à imprimer depuis un dossier de photos brutes et une liste de personnes.
+Project-URL: Homepage, https://github.com/antnardo/trombinoscope
+Project-URL: Documentation, https://github.com/antnardo/trombinoscope/blob/main/docs/DOC.md
+Project-URL: Repository, https://github.com/antnardo/trombinoscope
+Project-URL: Issues, https://github.com/antnardo/trombinoscope/issues
+Project-URL: Changelog, https://github.com/antnardo/trombinoscope/blob/main/CHANGELOG.md
+Author-email: antnardo <antnardo@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: face-detection,opencv,pdf,portrait,reportlab,trombinoscope,white-balance,yearbook
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: French
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: Capture
+Classifier: Topic :: Printing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: pillow>=10.0
+Requires-Dist: reportlab>=4.0
+Provides-Extra: heic
+Requires-Dist: pillow-heif>=0.15; extra == 'heic'
+Description-Content-Type: text/markdown
+
+# trombinoscope
+
+[![CI](https://github.com/antnardo/trombinoscope/actions/workflows/ci.yml/badge.svg)](https://github.com/antnardo/trombinoscope/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/trombinoscope.svg)](https://pypi.org/project/trombinoscope/)
+[![Python](https://img.shields.io/pypi/pyversions/trombinoscope.svg)](https://pypi.org/project/trombinoscope/)
+[![Licence MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+
+Un dossier de photos brutes, une liste CSV, un PDF prêt à imprimer.
+
+```bash
+pip install trombinoscope
+trombinoscope build photos/ classe.csv -o trombinoscope.pdf
+```
+
+Le paquet détecte le visage sur chaque photo, recadre au même endroit et à la
+même taille pour tout le monde, homogénéise les couleurs **à l'échelle du lot**,
+puis compose une grille paginée.
+
+## Ce qu'il fait
+
+- **Recadrage à proportion de visage constante.** Que la photo ait été prise à
+  deux mètres ou à cinquante centimètres, le visage occupe la même fraction du
+  cadre. C'est ce qui rend une planche regardable.
+- **Homogénéisation colorimétrique du lot.** Chaque portrait est ramené vers
+  l'illuminant et la luminance *médians de la séance*, pas vers un gris neutre
+  arbitraire. Sur une séance dont la balance des blancs dérive, la dispersion
+  chromatique chute de 78 %. C'est la seule chose que ce paquet fait et que les
+  bibliothèques de correction couleur existantes ne font pas — elles travaillent
+  toutes image par image. Voir [docs/color.md](docs/color.md).
+- **Appariement positionnel.** Les photos triées par nom de fichier suivent
+  l'ordre de la liste. Aucun renommage manuel.
+- **Mise en page soignée.** Pagination automatique, dernière ligne centrée,
+  étiquettes pivotées dans les gouttières, silhouette de remplacement pour les
+  absents.
+- **Aucune dépendance système.** Ni LaTeX, ni LibreOffice, ni ImageMagick : que
+  des roues Python. Installable en conteneur et en CI.
+- **Détecteur léger et remplaçable.** YuNet en ONNX, 227 Ko, embarqué dans la
+  roue. Le détecteur est un protocole : branchez le vôtre si vous préférez.
+
+## Ce qu'il ne fait pas
+
+Il ne fait **pas de reconnaissance faciale**. Il détecte qu'il y a un visage et
+où, jamais qui c'est. C'est une frontière volontaire.
+
+Il ne ramène **pas les carnations vers une teinte de référence** : cela
+reviendrait à modifier la couleur de peau des personnes photographiées. Seul
+l'illuminant — une propriété de l'éclairage — est estimé.
+
+## Démarrage
+
+```bash
+# 1. Un modèle de liste, pour voir le format attendu
+trombinoscope template classe.csv
+
+# 2. Vérifier la détection avant de tout lancer
+trombinoscope inspect photos/ -o detections/
+
+# 3. Produire le PDF
+trombinoscope build photos/ classe.csv -o trombi.pdf \
+    --title "MP2 — 2026-2027" --columns 6 --align-eyes
+```
+
+Le fichier de liste :
+
+```csv
+nom,prenom,tags,groupes,badge
+HOPPER,Grace,Maths;LV2 ALL,Gr1;Tr3,1
+JOHNSON,Katherine,Info,Gr2;Tr1,
+```
+
+Seule la colonne `nom` est obligatoire. `tags` s'affiche dans la gouttière
+gauche, `groupes` dans la gouttière droite, `badge` place une étoile en coin.
+Les en-têtes sont reconnus sans tenir compte de la casse ni des accents, et les
+colonnes inconnues sont ignorées : donnez directement votre export d'ENT.
+
+### Depuis Python
+
+```python
+from trombinoscope import BuildOptions, TrombinoscopeBuilder, FramingConfig, GridConfig
+
+options = BuildOptions(
+    title="Promotion 2026",
+    absent=("DUPONT",),                       # dans la liste, mais pas photographié
+    face_choice={"MARTIN": 1},                # deux visages sur sa photo : prendre le second
+    framing=FramingConfig(face_ratio=0.5, align_eyes=True),
+    grid=GridConfig(columns=6, landscape=True),
+)
+
+report = TrombinoscopeBuilder(options).build("photos/", "classe.csv", "trombi.pdf")
+print(report.summary())
+```
+
+`build` renvoie toujours un `BuildReport` : personnes sans photo, photos sans
+personne, photos sans visage détecté, photos à plusieurs visages. Rien n'est
+avalé silencieusement.
+
+Les briques s'utilisent aussi séparément — `PortraitFramer` pour recadrer sans
+produire de PDF, `BatchColorHarmonizer` pour harmoniser un lot d'images
+quelconques, `GridPaginator` pour la mise en page seule.
+
+La liste peut aussi venir d'une base SQLite, via une requête libre dont les
+colonnes sont nommées avec `AS` :
+
+```python
+from trombinoscope import load_sqlite
+
+people = load_sqlite("base.db", "SELECT nom, prenom, redoublant AS badge FROM eleves ORDER BY nom")
+```
+
+Voir [`examples/`](examples/) pour un script complet branché sur une base réelle.
+
+## Quand utiliser autre chose
+
+Ce paquet occupe une case étroite. L'[étude d'originalité](docs/prior-art.md) est
+détaillée et n'édulcore rien ; en résumé :
+
+| Votre besoin | Préférez |
+| --- | --- |
+| Une interface graphique, sans écrire de code | [WhosWho](https://framagit.org/Yvan-Masson/WhosWho) |
+| Vos photos sont déjà dans PRONOTE | Le trombinoscope de PRONOTE |
+| Seulement recadrer des portraits sur le visage | [autocrop](https://github.com/leblancfg/autocrop) |
+| Des photos d'identité aux normes, fond détouré | [HivisionIDPhotos](https://github.com/Zeyi-Lin/HivisionIDPhotos) |
+| Une planche image en une ligne de shell | `montage` d'ImageMagick |
+| **Un PDF reproductible depuis un script ou une CI** | **`trombinoscope`** |
+
+[WhosWho](https://framagit.org/Yvan-Masson/WhosWho) mérite d'être mentionné
+d'emblée : c'est un logiciel libre, vivant, qui couvre l'essentiel du même
+besoin. Si une application de bureau vous convient, utilisez-la. Les différences
+réelles sont l'absence d'harmonisation colorimétrique inter-photos de son côté,
+et l'absence d'interface graphique du nôtre.
+
+## Documentation
+
+- [DOC.md](docs/DOC.md) — référence complète : options, API, formats, recettes
+- [color.md](docs/color.md) — l'étude colorimétrique, mesures à l'appui
+- [prior-art.md](docs/prior-art.md) — état de l'art et étude d'originalité
+- [improvements.md](docs/improvements.md) — pistes examinées et décisions
+- [legacy-review.md](docs/legacy-review.md) — revue du module de 2020 dont ce
+  paquet est issu, et ce que la réécriture en a tiré
+- [CREDITS.md](CREDITS.md) — modèles, images et travaux réutilisés
+
+## Installation
+
+```bash
+pip install trombinoscope           # cœur
+pip install 'trombinoscope[heic]'   # + lecture des .heic de l'iPhone
+```
+
+Python 3.11 et suivants, testé sur Linux, macOS et Windows.
+
+La dépendance OpenCV est `opencv-python-headless` : aucune bibliothèque
+graphique système n'est requise. Si votre environnement contient déjà
+`opencv-python`, installez avec `--no-deps` pour éviter que les deux
+distributions ne se disputent le module `cv2`.
+
+## Développement
+
+```bash
+git clone https://github.com/antnardo/trombinoscope
+cd trombinoscope
+uv sync --group dev
+
+uv run pytest -m "not integration"    # rapide, sans réseau
+uv run ruff format src tests scripts
+uv run ruff check src tests scripts
+
+uv run python scripts/fetch_samples.py   # portraits d'exemple, non versionnés
+uv run pytest -m integration
+uv run python scripts/color_bench.py --output artifacts
+```
+
+Le dépôt ne contient **aucune photographie**. Les portraits utilisés par les
+tests d'intégration sont téléchargés à la demande depuis Wikimedia Commons et la
+CI vérifie qu'aucun fichier image n'apparaît ni dans le dépôt ni dans la roue.
+
+## Licence
+
+MIT — voir [LICENSE](LICENSE). Les composants tiers embarqués ou téléchargés ont
+leurs propres licences, toutes recensées dans [CREDITS.md](CREDITS.md).