lardon3d/docs/concepts/visual_index.md

Visual Index

Définition

Un visual index (ou index visuel) est une structure de données compacte qui encode les caractéristiques visuelles distinctives de chaque image d'un scan set. Il permet de retrouver rapidement les paires d'images susceptibles de se chevaucher, sans comparaison exhaustive de toutes les combinaisons possibles.

L'index visuel transforme chaque image en un vecteur de descripteurs (features) invariantes à la rotation, à l'échelle et partiellement à l'illumination. Ces descripteurs forment une empreinte numérique qui identifie le contenu visuel de l'image.

Statut

IMPLEMENTED v1 — Lardon3D utilise un LSH binaire déterministe en segments persistants. Une image ajoutée lors d'une campagne ultérieure peut retrouver une ancienne image par contenu, même dans un autre ScanSet et loin d'elle dans le dossier. Le score indique une priorité de comparaison, jamais une validité géométrique.

Les tests de retrieval passent par l'import, l'extraction ORB et l'index réel : crop significatif, rotation modérée et recherche inter-ScanSets. Un asset image partagé est signalé par same_image_asset et peut être explicitement exclu. Les buckets trop communs sont ignorés afin qu'un motif répétitif banal ne domine pas des détails distincts.

Place dans le pipeline

Scan Set (images brutes)
    ↓
Feature Extraction (descripteurs par image)
    ↓
Visual Index (indexation compacte)
    ↓
Candidate Selection (paires candidats)
    ↓
Matching & Tracks (appariement détaillé)

L'index visuel se situe entre l'extraction de features et la sélection de paires candidates. Il réduit drastiquement l'espace de recherche pour l'appariement.

Le futur index consommera exclusivement un feature_set_id et les descripteurs obtenus par plages bornées du Feature Reader. Il ne dépendra ni des chemins source, ni d'OpenCV, ni du runtime de la tâche productrice. Un chemin d'asset ou un nom source n'est pas une clé d'index durable.

Concepts clés

Descripteurs visuels

Type	Caractéristiques	Usage
SIFT	Invariant à l'échelle et rotation, 128 dimensions	Référence académique, lent
SURF	Plus rapide que SIFT, bonne invariance	Compromis vitesse/qualité
ORB	Binaire, très rapide, Open source	Usage temps réel
AKAZE	Non-linéaire, préservation des contours	Bon pour les textures

Structure de l'index

Image → [Feature 1, Feature 2, ..., Feature N]
                    ↓
         Visual Index (KD-Tree / LSH / PQ)
                    ↓
         Requête : top-K voisins les plus proches

Techniques d'indexation

• KD-Tree : arbre binaire de partitionnement spatial, efficace pour KNN en basse dimension
• Locality-Sensitive Hashing (LSH) : hashing probabiliste, efficace en haute dimension
• Product Quantization (PQ) : quantification par produit, compression agressive des descripteurs
• IVF (Inverted File) : indexation par clusters, bon compromis mémoire/recherche

Paramètres clés

Paramètre	Description	Impact
n_features_per_image	Nombre de descripteurs extraits par image	Plus = meilleure couverture, plus de mémoire
index_type	Type de structure d'index (KD-Tree, LSH, PQ)	Compromis précision/vitesse
search_radius	Rayon de recherche pour les voisins	Plus grand = plus de candidats, plus lent
min_match_count	Seuil minimum d'appariements validés	Filtre les faux positifs

Relations avec les autres modules

Module	Relation
Image Catalog	Le catalogue fournit les métadonnées nécessaires à l'indexation (dimensions, modèle caméra).
Image View	Les vues peuvent filtrer les images avant indexation (par zone, par qualité).
Resource Governor	Le gouverneur alloue la mémoire pour la structure d'index et contrôle la taille des lots d'indexation.
Task	L'indexation visuelle est une tâche candidate pour le runtime/Queue. Elle est CPU-intensive mais parallélisable.
Hardware Profile	Le profil matériel détermine le type d'index optimal (KD-Tree pour peu de features, LSH pour beaucoup).

Contraintes de conception

• L'index doit tenir en mémoire pour un scan set complet typique (100-1000 images).
• La construction de l'index ne doit pas bloquer la TUI : tâche asynchrone avec progression.
• L'index et ses memberships sont persistants ; seuls les buffers de requête sont transitoires.
• La taille maximale de l'index est bornée par le budget RAM du Resource Governor.
• Les descripteurs doivent être calculés de manière déterministe (même image → même index).

Terminologie

Terme	Définition
Feature	Point d'intérêt local avec descripteur associé
Keypoint	Position spatiale (x, y) d'un point d'intérêt
Descriptor	Vecteur numérique décruant l'apparence locale autour d'un keypoint
KNN	K-Nearest Neighbors, recherche des K voisins les plus proches
Vocabulary visuel	Dictionnaire de descripteurs typiques pour la bag-of-words
BoW (Bag of Words)	Représentation histogrammique des features d'une image