gps-denied-onboard/docs/02_components/helpers/h04_faiss_index_manager_spec.md

Faiss Index Manager Helper

Interface Definition

Interface Name: IFaissIndexManager

Interface Methods

class IFaissIndexManager(ABC):
    @abstractmethod
    def build_index(self, descriptors: np.ndarray, index_type: str) -> FaissIndex:
        pass
    
    @abstractmethod
    def add_descriptors(self, index: FaissIndex, descriptors: np.ndarray) -> bool:
        pass
    
    @abstractmethod
    def search(self, index: FaissIndex, query: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]:
        pass
    
    @abstractmethod
    def save_index(self, index: FaissIndex, path: str) -> bool:
        pass
    
    @abstractmethod
    def load_index(self, path: str) -> FaissIndex:
        pass
    
    @abstractmethod
    def is_gpu_available(self) -> bool:
        pass
    
    @abstractmethod
    def set_device(self, device: str) -> bool:
        """Set device: 'gpu' or 'cpu'."""
        pass

Component Description

Manages Faiss indices for DINOv2 descriptor similarity search. H04 builds indexes from UAV image descriptors for:

1. Loop closure detection: Find when UAV revisits previously seen areas within the same flight
2. Chunk-to-chunk matching: Match disconnected chunks to each other
3. Flight-to-flight matching: Match current flight to previous flights in same area

Index Source: Descriptors are computed from UAV images using F08's DINOv2 encoder, NOT from satellite images. The index enables finding similar UAV viewpoints.

API Methods

build_index(descriptors: np.ndarray, index_type: str) -> FaissIndex

Description: Builds Faiss index from descriptors.

Index Types:

• "IVF": Inverted File (fast for large databases)
• "HNSW": Hierarchical Navigable Small World (best accuracy/speed trade-off)
• "Flat": Brute force (exact, slow for large datasets)

Input: (N, D) descriptors array

---

add_descriptors(index: FaissIndex, descriptors: np.ndarray) -> bool

Description: Adds more descriptors to existing index.

---

search(index: FaissIndex, query: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]

Description: Searches for k nearest neighbors.

Output: (distances, indices) - shape (k,)

---

save_index(index: FaissIndex, path: str) -> bool

Description: Saves index to disk for fast startup.

---

load_index(path: str) -> FaissIndex

Description: Loads pre-built index from disk.

Dependencies

External: faiss-gpu or faiss-cpu

GPU/CPU Fallback

H04 supports automatic fallback from GPU to CPU:

• is_gpu_available(): Returns True if faiss-gpu is available and CUDA works
• set_device("gpu"): Use GPU acceleration (faster for large indexes)
• set_device("cpu"): Use CPU (fallback when GPU unavailable)

Test Cases

1. Build index with 10,000 UAV image descriptors → succeeds
2. Search query UAV descriptor → returns top-k similar UAV frames
3. Save/load index → index restored correctly
4. GPU unavailable → automatically falls back to CPU
5. Add descriptors incrementally → index grows correctly