Algorithm parameters¶

Grayscale weights, gamma, and each algorithm's own tuning.

Types
`ph_whash_mode_t`	Wavelet Hash operating modes.

Configuration setters
`ph_context_set_gamma()`	Sets the gamma value applied by `ph_compute_radial_hash()`, and by nothing else.
`ph_context_set_gray_weights()`	Sets custom RGB-to-Grayscale weights.
`ph_context_get_gray_weights()`	Reads back the grayscale weights the context actually uses.
`ph_context_set_phash_params()`	Sets pHash parameters.
`ph_context_set_radial_params()`	Sets Radial Hash parameters.
`ph_context_set_block_params()`	Sets the grid resolution for the Block Mean Hash (BMH).
`ph_context_set_mhash_params()`	Sets the Marr-Hildreth hash's kernel scale and normalization size.
`ph_context_set_whash_mode()`	Sets the operating mode for Wavelet Hash (wHash).
`ph_context_set_whash_remove_max_haar_ll()`	Controls wHash's removal of the coarsest LL band (ImageHash's `remove_max_haar_ll`). Off by default.

Types¶

`ph_whash_mode_t`¶

Wavelet Hash operating modes.

Name	Value	Description
`PH_WHASH_FAST`	`0`	A 16x16 reduction and one Haar level (default).
`PH_WHASH_FULL`	`1`	ImageHash's scale: the largest power of two that fits, down to 8x8.
`PH_WHASH_FORCE_INT32_`	`PH_ENUM_FORCE_INT32_VALUE`	Not a mode – see "Enum width".

Configuration setters¶

Every ph_context_set_* function returns ph_error_t, with one contract shared by all of them:

a valid argument (and a non-NULL ctx) returns PH_SUCCESS;
anything else returns PH_ERR_INVALID_ARGUMENT and leaves the configuration completely unchanged — values are never clamped into range, never partially applied, and never replaced by defaults.

An invalid argument is reported rather than ignored, because a silently ignored one would let a caller hash a whole batch with a configuration it never asked for. Each upper bound below is a hard limit of the implementation (digest capacity, hash width, the supported pixel ceiling), not a style preference.

Note

These setters are intentionally not warn_unused_result: they are commonly called with compile-time-constant arguments where the result carries no information. Check the return value whenever the argument comes from outside your code.

Which setting each algorithm reads, when it is read, and which ones change a hash's value: Configuring a context.

`ph_context_set_gamma()`¶

ph_error_t ph_context_set_gamma(ph_context_t *ctx, float gamma);

returns ph_error_t

Sets the gamma value applied by ph_compute_radial_hash(), and by nothing else.

Applied to the blurred grayscale image before the radial projections: out = (in / max)^gamma * max, where max is the brightest value in it, as pHash applies it. The default, 1.0, is the identity, and the step is skipped.

Warning

Despite living on the context, this setting affects only the Radial hash; every other algorithm ignores it. See Radial — Radial Variance Hash.

Parameters

Parameter	Description
`ctx`	The context.
`gamma`	The gamma value (e.g., 1.0). Must be finite and in (0.001, 1000]; NaN and infinities are rejected.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx or an out-of-range gamma.

`ph_context_set_gray_weights()`¶

ph_error_t ph_context_set_gray_weights(ph_context_t *ctx, int r, int g, int b);

returns ph_error_t

Sets custom RGB-to-Grayscale weights.

Input values are automatically normalized to sum to 128 for optimized internal processing. Default is PH_GRAY_R=38, PH_GRAY_G=75, PH_GRAY_B=15 (sum 128).

Note

A zero sum is an error, not a request for the defaults: the configuration is never replaced by something the caller did not ask for.

Parameters

Parameter	Description
`ctx`	The context.
`r`	Relative channel weights. Each must be >= 0, their sum must be > 0 and at most INT_MAX / 255 (8421504), so that the normalization stays inside `int`.
`g`	Relative channel weights. Each must be >= 0, their sum must be > 0 and at most INT_MAX / 255 (8421504), so that the normalization stays inside `int`.
`b`	Relative channel weights. Each must be >= 0, their sum must be > 0 and at most INT_MAX / 255 (8421504), so that the normalization stays inside `int`.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx, a negative weight, or a sum outside the range above.

`ph_context_get_gray_weights()`¶

ph_error_t ph_context_get_gray_weights(const ph_context_t *ctx, int *r, int *g, int *b);

nodiscard · returns ph_error_t

Reads back the grayscale weights the context actually uses.

These are the normalized values, summing to 128, not the ones passed to ph_context_set_gray_weights(): (100, 10, 18) is stored as (100, 10, 18) because it already sums to 128, but (1, 1, 1) is stored as (42, 42, 44). The only configuration getter, because this is the only setter that transforms its input; the others store their value as given, a flag as 0 or 1.

Parameters

Parameter	Direction	Description
`ctx`	in	The context.
`r`	out	Receive the weights. None may be NULL.
`g`	out	Receive the weights. None may be NULL.
`b`	out	Receive the weights. None may be NULL.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for a NULL argument (nothing is written then).

`ph_context_set_phash_params()`¶

ph_error_t ph_context_set_phash_params(
    ph_context_t *ctx,
    int dct_size,
    int reduction_size);

returns ph_error_t

Sets pHash parameters.

Out-of-range values are rejected and the current configuration is left unchanged; they are never clamped. If an out-of-range value reaches ph_compute_phash() by other means, it returns PH_ERR_INVALID_ARGUMENT and leaves the output untouched. See pHash — Perceptual Hash.

Parameters

Parameter	Description
`ctx`	The context.
`dct_size`	The side of the grid the image is reduced to and of its DCT, `reduction_size`..32 (default 32).
`reduction_size`	The side of the low-frequency block of coefficients the hash is made of, 4..8 (default 8): the hash has reduction_size^2 bits, of which the DC coefficient's is always set. Below 4 the hash is degenerate; above 8 it would not fit 64 bits.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx or an out-of-range pair.

`ph_context_set_radial_params()`¶

ph_error_t ph_context_set_radial_params(
    ph_context_t *ctx,
    int projections,
    int samples,
    float sigma);

returns ph_error_t

Sets Radial Hash parameters.

The digest is 40 bytes whatever the settings, so digests computed with different ones cannot be told apart by size; compare only digests computed alike. The cost of the projections is projections * samples, whatever the image size, and the digest converges long before the upper bounds, which keep a configuration from an untrusted source from costing seconds per call. See Radial — Radial Variance Hash.

Parameters

Parameter	Description
`ctx`	The context.
`projections`	Number of lines through the center, spread over [0, pi), 40..4096 (default 180). Fewer than 40 would give fewer than the 40 DCT coefficients the digest holds.
`samples`	Points read on each line, 2..4096 (default 128). One point has no variance, so every image would have no angular structure.
`sigma`	Gaussian blur sigma applied before the projections, in (0, 64/3] (default 3.5, pHash's). Above 64/3 the blur's kernel would be silently narrower than requested.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx or an out-of-range value; the configuration is unchanged on error.

`ph_context_set_block_params()`¶

ph_error_t ph_context_set_block_params(ph_context_t *ctx, int block_size);

returns ph_error_t

Sets the grid resolution for the Block Mean Hash (BMH).

Note

This affects BMH only; mHash has its own parameters, see ph_context_set_mhash_params(). See BMH — Block Mean Hash.

Parameters

Parameter	Description
`ctx`	The context.
`block_size`	Resolution of the grid, 2..32 (default 16): `block_size * block_size` blocks, one bit each. 32 is the largest grid whose bits fit a `ph_digest_t` (1024 bits, PH_DIGEST_MAX_BYTES); at 1 every image would give the same bit. An out-of-range value is refused, not clamped.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx or an out-of-range block_size.

`ph_context_set_mhash_params()`¶

ph_error_t ph_context_set_mhash_params(
    ph_context_t *ctx,
    float alpha,
    float level,
    int size);

returns ph_error_t

Sets the Marr-Hildreth hash's kernel scale and normalization size.

alpha and level set the Laplacian-of-Gaussian kernel: it reaches floor(4 * alpha^level) samples from its center (a 17x17 kernel at the defaults), and a wider kernel describes coarser detail. size is the side the image is normalized to; the grid stays 31x31 blocks of size / 31 pixels, so the digest is always 576 bits. The defaults, 2, 1 and 512, are pHash's. Digests are comparable only when computed with the same values. See mHash — Marr–Hildreth Hash.

Parameters

Parameter	Description
`ctx`	The context.
`alpha`	Scale base, > 1 and finite.
`level`	Scale exponent, >= 0 and finite. `4 * alpha^level` must be at least 1 and must keep the kernel side at 65 or below.
`size`	Normalization side, 62..4096.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx or any value out of range, with the configuration left untouched.

`ph_context_set_whash_mode()`¶

ph_error_t ph_context_set_whash_mode(ph_context_t *ctx, ph_whash_mode_t mode);

returns ph_error_t

Sets the operating mode for Wavelet Hash (wHash).

Parameters

Parameter	Description
`ctx`	The context.
`mode`	PH_WHASH_FAST (0, the default): a fixed 16x16 scale and one Haar level, a cost independent of the image beyond the shared downscale. PH_WHASH_FULL (1): the largest power-of-two scale that fits the image, cascaded down to 8x8 – closer to ImageHash, and its cost grows with the image. The two hashes are not interchangeable. See wHash — Wavelet Hash.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx or a mode that is not one of the declared enumerators.

`ph_context_set_whash_remove_max_haar_ll()`¶

ph_error_t ph_context_set_whash_remove_max_haar_ll(ph_context_t *ctx, int enable);

returns ph_error_t

Controls wHash's removal of the coarsest LL band (ImageHash's remove_max_haar_ll). Off by default.

Zeroing the coarsest LL coefficient and reconstructing subtracts the image mean from every sample, which shifts the working LL band and its median alike: the only bits it can change are those of values that tie with the median, and it decides them by rounding error. Offered for callers who mirror ImageHash's configuration, where it is on. See wHash — Wavelet Hash.

Parameters

Parameter	Description
`ctx`	The context.
`enable`	Non-zero to zero the coarsest LL coefficient before the working decomposition, zero to leave it in place.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx.

Algorithm parameters¶

Types¶

ph_whash_mode_t¶

Configuration setters¶

ph_context_set_gamma()¶

ph_context_set_gray_weights()¶

ph_context_get_gray_weights()¶

ph_context_set_phash_params()¶

ph_context_set_radial_params()¶

ph_context_set_block_params()¶

ph_context_set_mhash_params()¶

ph_context_set_whash_mode()¶

ph_context_set_whash_remove_max_haar_ll()¶

`ph_whash_mode_t`¶

`ph_context_set_gamma()`¶

`ph_context_set_gray_weights()`¶

`ph_context_get_gray_weights()`¶

`ph_context_set_phash_params()`¶

`ph_context_set_radial_params()`¶

`ph_context_set_block_params()`¶

`ph_context_set_mhash_params()`¶

`ph_context_set_whash_mode()`¶

`ph_context_set_whash_remove_max_haar_ll()`¶