$ show thorn-oss/perception
Perception is a Python library for perceptual image and video hashing, developed by Thorn. It provides a unified interface for multiple hashing algorithms (e.g., pHash, dHash, PDQ, TMK), approximate nearest neighbor search via FAISS with graph-based clustering, and a benchmarking framework for evaluating hasher robustness under various transformations. The library is designed for production use cases like near-duplicate detection, content matching, and CSAM detection via integration with Thorn's Safer service. The codebase demonstrates strong engineering practices: clean abstractions, Cython acceleration, optional dependency management, and extensive test coverage. While primarily an application/library, it includes research-oriented benchmarking pipelines and evaluation datasets, making it a hybrid of production tooling and research infrastructure.
The LLM identified 5 files worth highlighting for reuse:
Defines the abstract base class `Hasher` and concrete `ImageHasher` with a consistent interface for computing hashes, converting between vectors and strings, computing distances, and parallel processing. This pattern allows any new hasher to be plugged in by implementing `_compute`. The design is reusable across projects needing a family of hashing algorithms.
Wraps FAISS index operations (building, training, adding, saving, loading) into an `ApproximateNearestNeighbors` class with tunable parameters and integration with a database backend. This is a reusable component for any project requiring large-scale similarity search with HNSW or IVFPQ indices.
Provides Cython-accelerated functions for computing pairwise duplicate pairs and distance matrices. The Python fallback ensures compatibility, but the Cython version offers significant speedup for hash comparisons. Reusable in any system needing fast pairwise comparison of fixed-length vectors.
Contains `BenchmarkImageDataset` and `BenchmarkImageTransforms` classes that load image datasets, apply transformations (via albumentations), and compute hashes. The pipeline pattern (load -> transform -> compute -> evaluate) is reusable for evaluating any image hasher or similarity metric.
Implements `FramewiseHasher` that processes video frames sequentially using a stateful `process_frame` method, then produces a final hash via `hash_from_final_state`. This pattern is reusable for any video analysis that requires per-frame updates and aggregated output, and supports multi-hasher synchronization.