Loading images¶

From a file, a memory buffer or raw pixels, and the settings that shape the pixels at load time: grayscale, transparency, orientation, size limit, decode scale.

Types
`ph_decode_scale_t`	JPEG decode resolution hint — see `ph_context_set_decode_scale()`.
`ph_alpha_mode_t`	What becomes of an image's alpha channel before it is hashed — see `ph_context_set_alpha_mode()`.

Configuration setters
`ph_context_set_load_grayscale()`	Controls whether `ph_load_from_file()` and `ph_load_from_memory()` ask the decoder for one grayscale channel instead of color. Off by default.
`ph_context_set_alpha_mode()`	Chooses what an image's alpha channel does to the hash.
`ph_context_set_auto_orient()`	Controls whether the EXIF orientation is applied right after decoding. On by default.
`ph_context_set_max_pixels()`	Sets the most pixels, width * height, an image may have. Checked against the dimensions a file declares, before any pixel buffer is allocated, so that a small file declaring an enormous image is refused cheaply.
`ph_context_set_decode_scale()`	Requests that JPEG be decoded at a reduced resolution instead of natively, trading accuracy for decode speed. Full resolution by default.

Functions
`ph_load_from_file()`	Loads an image from a file path.
`ph_load_from_memory()`	Loads an image from an encoded file held in memory.
`ph_load_from_pixels()`	Loads an image from an already-decoded pixel buffer.

Types¶

`ph_decode_scale_t`¶

JPEG decode resolution hint — see ph_context_set_decode_scale().

Name	Value	Description
`PH_DECODE_SCALE_FULL`	`0`	Decode at the image's native resolution (default).
`PH_DECODE_SCALE_HALF`	`1`	Decode at ½ linear resolution (¼ the pixels).
`PH_DECODE_SCALE_QUARTER`	`2`	Decode at ¼ linear resolution (1/16 the pixels).
`PH_DECODE_SCALE_EIGHTH`	`3`	Decode at ⅛ linear resolution (1/64 the pixels).
`PH_DECODE_SCALE_FORCE_INT32_`	`PH_ENUM_FORCE_INT32_VALUE`	Not a scale – see "Enum width".

`ph_alpha_mode_t`¶

What becomes of an image's alpha channel before it is hashed — see ph_context_set_alpha_mode().

Name	Value	Description
`PH_ALPHA_BLEND_GREY`	`0`	Composite onto mid-gray (128, 128, 128) (default).
`PH_ALPHA_BLEND_WHITE`	`1`	Composite onto white.
`PH_ALPHA_BLEND_BLACK`	`2`	Composite onto black.
`PH_ALPHA_IGNORE`	`3`	Drop alpha and hash the color stored under it, as ImageHash does.
`PH_ALPHA_FORCE_INT32_`	`PH_ENUM_FORCE_INT32_VALUE`	Not a mode – see "Enum width".

Configuration setters¶

These functions follow the rules given under Configuration setters.

`ph_context_set_load_grayscale()`¶

ph_error_t ph_context_set_load_grayscale(ph_context_t *ctx, int enable);

returns ph_error_t

Controls whether ph_load_from_file() and ph_load_from_memory() ask the decoder for one grayscale channel instead of color. Off by default.

A grayscale load skips the library's color-to-gray conversion, and for JPEG the decoder's color conversion as well; a JPEG's grayscale is then the luma the file stores, which can differ from the library's conversion by a level. Every other format's gray is the library's default weights (ph_context_set_gray_weights() does not reach it). The setting applies from the next load.

Note

A single-channel image has no color statistics: on one, ph_compute_color_hash() and ph_compute_color_moments_hash(), and ph_compute_digest() for either, fail with PH_ERR_REQUIRES_COLOR. Load in color if you need them.

When it pays, and what it changes in a hash: Loading images.

Parameters

Parameter	Description
`ctx`	The context.
`enable`	1 to enable grayscale loading, 0 to disable (load native channels). Any non-zero value enables it.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT only for a NULL ctx — every int is a valid flag value.

`ph_context_set_alpha_mode()`¶

ph_error_t ph_context_set_alpha_mode(ph_context_t *ctx, ph_alpha_mode_t mode);

returns ph_error_t

Chooses what an image's alpha channel does to the hash.

A transparent pixel looks like whatever is behind it, and the color stored under alpha 0 is invisible and differs from encoder to encoder. By default every image with alpha — a PNG or WebP with an alpha channel or a tRNS chunk, or a 4-channel buffer given to ph_load_from_pixels() — is composited onto mid-gray before anything else happens, per channel (c * a + bg * (255 - a) + 127) / 255, so the hash follows the visible image only. What ignoring alpha costs, and which background suits which algorithm, is measured in Image preparation.

The mode applies at load time: set it before ph_load_from_file(), ph_load_from_memory() or ph_load_from_pixels(). A loaded image never has an alpha channel, so ph_context_get_dimensions() reports 3 channels (1 when loaded as grayscale) for an image that had one.

Parameters

Parameter	Description
`ctx`	The context.
`mode`	`PH_ALPHA_BLEND_GREY` (default), `PH_ALPHA_BLEND_WHITE`, `PH_ALPHA_BLEND_BLACK`, or `PH_ALPHA_IGNORE` to hash the stored color whatever its alpha, which is what ImageHash (and PIL's `convert("L")`) does.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for NULL ctx or a mode that is not one of the enumerators above (configuration unchanged).

`ph_context_set_auto_orient()`¶

ph_error_t ph_context_set_auto_orient(ph_context_t *ctx, int enable);

returns ph_error_t

Controls whether the EXIF orientation is applied right after decoding. On by default.

When enabled, the Orientation tag (values 1-8) of a JPEG's Exif segment, a WebP's EXIF chunk or a PNG's eXIf chunk is applied, turning or mirroring the image before any hash, so that a hash describes the picture as a viewer shows it. When disabled, the pixels are hashed as stored. ph_load_from_pixels() carries no orientation. The setting applies from the next load. See Image preparation.

Note

A missing or malformed tag reads as 1, no transform; it never fails a load.

Note

Applying an orientation of 2-8 takes a second buffer the size of the decoded image. If it cannot be allocated, the load returns PH_ERR_ALLOCATION_FAILED and no image is loaded, rather than an image in an orientation you did not ask for.

Parameters

Parameter	Description
`ctx`	The context.
`enable`	1 to auto-orient using EXIF metadata (default), 0 to hash the raw decoded buffer as-is. Any non-zero value enables it.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT only for a NULL ctx — every int is a valid flag value.

`ph_context_set_max_pixels()`¶

ph_error_t ph_context_set_max_pixels(ph_context_t *ctx, uint64_t max_pixels);

returns ph_error_t

Sets the most pixels, width * height, an image may have. Checked against the dimensions a file declares, before any pixel buffer is allocated, so that a small file declaring an enormous image is refused cheaply.

An image over the limit fails to load with PH_ERR_IMAGE_TOO_LARGE. Two fixed limits apply whatever is set here: INT_MAX (2147483647) pixels, as the library indexes pixels in int; and, for ph_load_from_file() and ph_load_from_memory() only, 1000000 pixels on either side, so that an image of one enormous row cannot pass the area limit. ph_load_from_pixels() is held to the pixel count only. See Loading images.

Parameters

Parameter	Description
`ctx`	The context.
`max_pixels`	The limit; 256 * 1024 * 1024 by default. 0 removes it, leaving the fixed limits.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT only for a NULL ctx. Every uint64_t is accepted, including values above the implementation ceiling: the ceiling is applied when an image is loaded, not when the limit is set.

`ph_context_set_decode_scale()`¶

ph_error_t ph_context_set_decode_scale(ph_context_t *ctx, ph_decode_scale_t scale);

returns ph_error_t

Requests that JPEG be decoded at a reduced resolution instead of natively, trading accuracy for decode speed. Full resolution by default.

libjpeg-turbo decodes at ½, ¼ or ⅛ of the width and height by scaling in the DCT domain, rounding a side that does not divide evenly up. The decode itself gets somewhat cheaper, and everything after it – the grayscale conversion, and each hash's reduction, blur or histogram – reads four times fewer pixels at each step. Every hash then describes the smaller image, so its value changes; by how much depends on the algorithm and on the decoded size. Both the saving and the change are measured in Image preparation.

Note

Only the JPEG backend honors this. A PNG, a WebP, or a JPEG in a build whose JPEG decoder is stb_image is decoded at full resolution whatever the setting, and ph_load_from_pixels() has no decoder at all. The max_pixels limit is judged by a JPEG's full dimensions.

Parameters

Parameter	Description
`ctx`	The context.
`scale`	The requested decode resolution. `PH_DECODE_SCALE_FULL` is the default.

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

Functions¶

`ph_load_from_file()`¶

ph_error_t ph_load_from_file(ph_context_t *ctx, const char *filepath);

nodiscard · returns ph_error_t

Loads an image from a file path.

The file is opened once and its whole content handed to the decoder, memory-mapped where the platform supports it and read into a buffer otherwise; from there the call behaves exactly like ph_load_from_memory() on the same bytes. Peak memory includes the encoded file as well as the decoded image. Any image already loaded is dropped before the file is opened, so a load that fails on the file or its contents leaves the context empty. See Loading images.

Parameters

Parameter	Description
`ctx`	The context.
`filepath`	Path to the image file.

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for a NULL argument; PH_ERR_IO if the path cannot be opened or is not a readable, non-empty regular file; PH_ERR_ALLOCATION_FAILED if the file cannot be read into memory; otherwise the decoding errors of ph_load_from_memory(): PH_ERR_UNSUPPORTED_FORMAT, PH_ERR_CORRUPT_DATA, PH_ERR_DECODER_UNAVAILABLE, PH_ERR_IMAGE_TOO_LARGE and PH_ERR_ALLOCATION_FAILED.

`ph_load_from_memory()`¶

ph_error_t ph_load_from_memory(ph_context_t *ctx, const uint8_t *buffer, size_t length);

nodiscard · returns ph_error_t

Loads an image from an encoded file held in memory.

The first bytes choose the decoder. Any image already loaded is dropped before the bytes are decoded, so a load that fails on them leaves the context empty. The formats each build reads are listed in Loading images.

Note

An animated GIF loads as its first frame. An animated WebP fails with PH_ERR_CORRUPT_DATA: libwebp's simple decode API, which the library uses, cannot read a frame out of an animation.

Note

A truncated JPEG, PNG or WebP fails with PH_ERR_CORRUPT_DATA in every build: the data must reach the file's own end (the JPEG end-of-image marker, the PNG IEND chunk, the size its WebP RIFF header states). Bytes after that end are ignored.

Note

The encoded data may be at most INT_MAX bytes (2 GiB - 1).

Parameters

Parameter	Description
`ctx`	The context.
`buffer`	Pointer to the raw file data (e.g., JPEG bytes).
`length`	Size of the buffer.

Returns PH_SUCCESS, or:

PH_ERR_INVALID_ARGUMENT for a NULL ctx or buffer, or a zero length;
PH_ERR_UNSUPPORTED_FORMAT if the bytes are in no format the library recognizes;
PH_ERR_CORRUPT_DATA if the format is recognized but the data is malformed or truncated;
PH_ERR_DECODER_UNAVAILABLE if the format is recognized but this build has no decoder for it;
PH_ERR_IMAGE_TOO_LARGE if the image exceeds the context's max_pixels or a fixed limit, or length exceeds INT_MAX;
PH_ERR_ALLOCATION_FAILED if the decoded image, or its EXIF orientation, does not fit in memory.

`ph_load_from_pixels()`¶

ph_error_t ph_load_from_pixels(
    ph_context_t *ctx,
    const uint8_t *pixels,
    int width,
    int height,
    int channels,
    int stride);

nodiscard · returns ph_error_t

Loads an image from an already-decoded pixel buffer.

Copies pixels that already live in memory, a frame another library decoded, without an encode and decode in between. The channels are read in the order R, G, B (and A); a buffer in BGR order hashes as a different image. An alpha channel is resolved as ph_context_set_alpha_mode() says, and no orientation is applied. See Loading images.

Parameters

Parameter	Description
`ctx`	The context.
`pixels`	Pointer to the raw pixel data, `height` rows of `channels`-interleaved bytes.
`width`	Image width in pixels. Must be > 0.
`height`	Image height in pixels. Must be > 0.
`channels`	Number of channels per pixel. Must be 1, 3, or 4; 4 is RGBA, with straight (not premultiplied) alpha, resolved as `ph_context_set_alpha_mode()` says.
`stride`	Number of bytes between the start of consecutive rows. Pass 0 for tightly packed rows (stride = width * channels).

Returns PH_SUCCESS; PH_ERR_INVALID_ARGUMENT for a NULL argument, a value outside the ranges above, or a stride that is negative or shorter than a row; PH_ERR_IMAGE_TOO_LARGE if the image exceeds the context's max_pixels; PH_ERR_ALLOCATION_FAILED if the copy does not fit in memory. On any error the previously loaded image stays loaded.

Loading images¶

Types¶

ph_decode_scale_t¶

ph_alpha_mode_t¶

Configuration setters¶

ph_context_set_load_grayscale()¶

ph_context_set_alpha_mode()¶

ph_context_set_auto_orient()¶

ph_context_set_max_pixels()¶

ph_context_set_decode_scale()¶

Functions¶

ph_load_from_file()¶

ph_load_from_memory()¶

ph_load_from_pixels()¶

`ph_decode_scale_t`¶

`ph_alpha_mode_t`¶

`ph_context_set_load_grayscale()`¶

`ph_context_set_alpha_mode()`¶

`ph_context_set_auto_orient()`¶

`ph_context_set_max_pixels()`¶

`ph_context_set_decode_scale()`¶

`ph_load_from_file()`¶

`ph_load_from_memory()`¶

`ph_load_from_pixels()`¶