Documentation
¶
Overview ¶
Package pdq implements the PDQ perceptual image hash.
PDQ answers one question: are two pictures essentially the same picture? It is a SYNTACTIC hasher — it compares similarity without extracting meaning — and it is built for media shared with minimum adversariality: recompressed, resized, lightly blurred, JPEG turned into PNG. It is NOT built to survive cropping, border addition or deliberate obfuscation.
The algorithm is Facebook's, published as "The TMK+PDQF video-hashing algorithm and the PDQ image-hashing algorithm" (hashing/hashing.pdf in github.com/facebook/ThreatExchange). This package is a port of the reference C++ in pdq/cpp of the same repository, read at the commit named in testdata/REFERENCE. Every step below cites the source it came from.
⛔ Bit identity with another implementation is NOT the contract. The specification says so itself: the resize down to the hashing resolution is implementation-specific, and hashes from two implementations of the same image are expected to differ by 0, 2, 4 or 6 bits of Hamming distance. What this package promises is the published algorithm, run at full resolution the way the reference does, with the stated bound asserted against the reference's own regression vectors.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrEmpty = errors.New("pdq: empty image")
ErrEmpty is returned for an image with no pixels.
var ErrMalformed = errors.New("pdq: malformed hash")
ErrMalformed is returned for a hash string that is not 64 hex digits.
Functions ¶
Types ¶
type Dihedral ¶
type Dihedral struct {
Original Hash
Rotate90 Hash
Rotate180 Hash
Rotate270 Hash
FlipX Hash
FlipY Hash
FlipPlus1 Hash // transpose, about the main diagonal
FlipMinus1 Hash // about the anti-diagonal
}
Dihedral holds the hashes of the eight symmetries of one image: the original, three rotations and four flips.
They cost almost nothing: all eight come from the SAME 16x16 DCT matrix by transposition and sign flips, so no image is rotated and no second transform is run.
type Hash ¶
type Hash [16]uint16
Hash is a 256-bit PDQ hash.
The bit at row i, column j of the 16x16 transform output is bit j of word i, which is how the reference stores it (pdqBuffer16x16ToBits sets bit i*16+j, and Hash256 keeps 16 words of 16 bits).
func (Hash) Distance ¶
Distance is the Hamming distance between two hashes: 0 when identical, 256 at most.
The specification's guidance on thresholds: distances between unrelated images average 128, and a distance of 30 or less — better 20 or less — has been found to indicate a confident match.
func (Hash) Norm ¶
Norm is the number of 1 bits.
⭐ It is 128 for every non-degenerate image, and that is a real invariant rather than a statistical one: each bit says whether its coefficient exceeds the MEDIAN of the 256 coefficients, so exactly half are set. It only fails when coefficients tie, which happens for degenerate input such as a solid colour — and those are what the quality metric exists to flag.