64-bit hashes¶
aHash, dHash, pHash and wHash, alone or several at once with ph_compute_multi().
| Types | |
|---|---|
ph_ |
Flags selecting which uint64_t hash algorithms to compute in a single ph_compute_multi() call. Bitwise-OR any combination. |
| Constants | |
|---|---|
PH_ |
| The four 64-bit hashes | |
|---|---|
ph_ |
Average hash: one bit per cell of an 8x8 grayscale reduction, set where the cell is at or above the reduction's mean. |
ph_ |
Difference hash: a 9x8 grayscale reduction, one bit per pair of horizontal neighbors, set where the left one is darker. |
ph_ |
Perceptual (DCT) hash: the low-frequency block of the 2-D DCT of a grayscale reduction, thresholded at its median plus 0.1% of the AC range. |
ph_ |
Wavelet hash: the low-frequency Haar band of a grayscale reduction, thresholded at its median. |
| Functions | |
|---|---|
ph_ |
Computes multiple uint64_t hash algorithms for the loaded image in one call. |
Types¶
ph_hash_flags_t¶
Flags selecting which uint64_t hash algorithms to compute in a single ph_compute_multi() call. Bitwise-OR any combination.
| Name | Value | Description |
|---|---|---|
PH_ |
1 << 0 |
|
PH_ |
1 << 1 |
|
PH_ |
1 << 2 |
|
PH_ |
1 << 3 |
|
PH_ |
PH_ |
Not a flag – see "Enum width". |
Constants¶
PH_HASH_FLAGS_COUNT¶
Number of distinct bits defined in ph_hash_flags_t. Sizes ph_compute_multi's out[].
The four 64-bit hashes¶
The four algorithms below share one contract. Each hashes the image loaded into ctx into all 64 bits of out_hash, compared with ph_hamming_distance() or ph_similarity(). The value depends on the decoded pixels and on the context's settings – the grayscale weights, and everything that shapes the pixels at load time (decode scale, auto-orientation, alpha mode) – so hashes are comparable only between contexts configured alike. The cost grows with the source image's pixel count: the reduction to the hash's working size reads every pixel. Return values:
PH_SUCCESS, with the hash inout_hash;PH_ERR_INVALID_ARGUMENTfor a NULLctxorout_hash;PH_ERR_EMPTY_IMAGEif no image is loaded (seeph_is_loaded());PH_ERR_ALLOCATION_FAILEDif the working buffers cannot be allocated.
out_hash is written only on success. ph_compute_multi() computes any combination of the four in one call.
ph_compute_ahash()¶
Average hash: one bit per cell of an 8x8 grayscale reduction, set where the cell is at or above the reduction's mean.
What moves it and what does not, measured: aHash — Average Hash.
Returns PH_SUCCESS, PH_ERR_INVALID_ARGUMENT, PH_ERR_EMPTY_IMAGE or PH_ERR_ALLOCATION_FAILED, as the shared contract above says.
ph_compute_dhash()¶
Difference hash: a 9x8 grayscale reduction, one bit per pair of horizontal neighbors, set where the left one is darker.
What moves it and what does not, measured: dHash — Difference Hash.
Returns PH_SUCCESS, PH_ERR_INVALID_ARGUMENT, PH_ERR_EMPTY_IMAGE or PH_ERR_ALLOCATION_FAILED, as the shared contract above says.
ph_compute_phash()¶
Perceptual (DCT) hash: the low-frequency block of the 2-D DCT of a grayscale reduction, thresholded at its median plus 0.1% of the AC range.
Sizes from ph_context_set_phash_params() (default: a 32x32 reduction, an 8x8 block). With a block smaller than 8x8 only its reduction_size squared low bits are used. The DC coefficient's bit is set for any ordinary image, as in pHash. See pHash — Perceptual Hash.
Returns PH_SUCCESS, PH_ERR_INVALID_ARGUMENT, PH_ERR_EMPTY_IMAGE or PH_ERR_ALLOCATION_FAILED, as the shared contract above says.
ph_compute_whash()¶
Wavelet hash: the low-frequency Haar band of a grayscale reduction, thresholded at its median.
The scale and depth come from ph_context_set_whash_mode(); the coarsest band can be zeroed with ph_context_set_whash_remove_max_haar_ll(). What the band amounts to, and what moves the hash, measured: wHash — Wavelet Hash.
Returns PH_SUCCESS, PH_ERR_INVALID_ARGUMENT, PH_ERR_EMPTY_IMAGE or PH_ERR_ALLOCATION_FAILED, as the shared contract above says.
Functions¶
ph_compute_multi()¶
Computes multiple uint64_t hash algorithms for the loaded image in one call.
Equivalent to calling the individual ph_compute_* functions for each flag set in flags. The work over the full image is cached on the context and done once, whichever algorithms ask for it: the grayscale conversion, and one area-average pass that aHash, pHash (at the default dct_size) and wHash (PH_WHASH_FAST) all reduce from – BMH shares it too. dHash resamples on its own. Results are bit-for-bit identical to calling the equivalent ph_compute_* function directly. What the sharing saves is measured in Performance.
Computation stops at the first algorithm that fails and its error code is returned.
On such a failure out is left partially written: the slots of the algorithms that ran before the failing one hold their correct hashes, and the failing algorithm's slot and every slot after it are untouched — not zeroed. There is no way to tell how far it got from out alone, so a caller that gets a non-PH_SUCCESS return must treat the whole array as unusable, or re-request the algorithms it still wants one at a time. On PH_SUCCESS exactly as many slots as there are bits in flags are written, and nothing beyond them is ever touched.
Parameters
| Parameter | Direction | Description |
|---|---|---|
ctx |
in | The context. Must have an image already loaded, or the call returns PH_ERR_EMPTY_IMAGE. |
flags |
in | Bitwise-OR of ph_hash_flags_t values selecting which hashes to compute. |
out |
out | Array written with one uint64_t per flag that was set, in ascending bit order (e.g. for PH_HASH_DHASH \| PH_HASH_WHASH, out[0] receives the dHash and out[1] the wHash). Must have room for at least as many elements as bits set in flags (at most PH_HASH_FLAGS_COUNT). |
Returns PH_SUCCESS; PH_ERR_INVALID_ARGUMENT for a NULL ctx or out, or flags that are zero or hold a bit no ph_hash_flags_t value defines; PH_ERR_EMPTY_IMAGE if no image is loaded; PH_ERR_ALLOCATION_FAILED from the algorithm that failed.