ISCC - Image Processing

Image handling module.

image_normalize(img, **options)

Normalize image for hash calculation.

Parameters:

Name	Type	Description	Default
img		Pillow Image Object	required
options		Keyword arguments forwarded to sdk_opts: image_exif_transpose - Transpose image according to EXIF Orientation tag. Default: True; image_fill_transparency - Add white background to transparent images. Default: True; image_trim_border - Crop uniform colored borders. Default: True; image_trim_tolerant - Repeated tolerant crop of near-uniform borders (instead of the exact crop). Default: True	{}

Returns:

Type	Description
	Normalized and flattened image as 1024-pixel array (from 32x32 gray pixels)

image_exif_transpose(img)

Transpose image according to EXIF Orientation tag

Parameters:

Name	Type	Description	Default
img		Pillow Image Object	required

Returns:

Type	Description
	EXIF transposed image

image_fill_transparency(img)

Add white background to image if it has alpha transparency.

Parameters:

Name	Type	Description	Default
img		Pillow Image Object	required

Returns:

Type	Description
	RGB Image with transparency replaced by a white background

image_trim_border(img)

Trim uniform colored (empty) border.

Takes the upper left pixel as reference for border color.

Parameters:

Name	Type	Description	Default
img		Pillow Image Object	required

Returns:

Type	Description
	Image with uniform colored (empty) border removed.

image_trim_tolerant(img, tolerance=16)

Trim near-uniform colored borders repeatedly until stable.

Each pass takes the upper left pixel as reference for border color and crops to the bounding box of all pixels where any RGB channel differs from the reference by more than tolerance. A pass that cuts only one side must remove a flat band (no pixel differs from the reference by more than half the tolerance), otherwise trimming stops, so smooth gradients such as skies are kept. Passes repeat until a pass crops nothing (no pixel differs, the bounding box covers the whole image or a one-sided band is not flat), or at most TRIM_MAX_PASSES times.

Parameters:

Name	Type	Description	Default
img		Pillow Image Object	required
tolerance		Maximum per-channel difference (0-255) of a border pixel to the reference	16

Returns:

Type	Description
	Image with near-uniform colored borders removed.

image_border_bbox(img, tolerance)

Bounding box of pixels that differ from the upper left pixel by more than tolerance.

A pixel counts as different if any of its channels differs by more than tolerance.

Parameters:

Name	Type	Description	Default
img		Pillow Image Object in mode "RGB" or "L"	required
tolerance		Maximum per-channel difference (0-255) of a border pixel to the reference	required

Returns:

Type	Description
	Bounding box (left, upper, right, lower) or None if no pixel differs.

is_featureless_image_code(iscc)

Check if an ISCC holds a featureless Image-Code.

Featureless images (uniform colors, one-axis brightness gradients, plain stripes, some symmetric graphics) get nearly identical Image-Codes that match each other regardless of content. Code generation is unaffected; applications such as matching services use this check to skip them, like the quality score of Meta's PDQ lets applications discard featureless images.

Rule: An Image-Code is featureless if any complete 64-bit segment of its body has fewer than 8 bits set to 1. Segments are consecutive 64-bit big-endian words from the start of the body. Trailing bits of a body whose length is not a multiple of 64 are not checked. A regular segment has 32 one-bits (median split of 64 DCT coefficients), fewer than 8 means at least 26 ties.

• Image-Code unit (MainType CONTENT, SubType IMAGE): checked by the rule.
• ISCC-CODE: its Image-Code unit is checked, False if it has none.
• Any other ISCC unit: False.

Parameters:

Name	Type	Description	Default
iscc		ISCC string (with or without "ISCC:" prefix)	required

Returns:

Type	Description
	True if the ISCC holds a featureless Image-Code

Raises:

Type	Description
ValueError	If the Image-Code is shorter than 64 bits and cannot be judged.

image_meta_extract(fp, file_name=None)

Extract metadata from image using native exiv2 bindings.

Parameters:

Name	Type	Description	Default
fp		Filepath to image file.	required
file_name		Custom filename for MIME type guessing (overrides actual filename).	None

Returns:

Type	Description
	Metadata mapped to IsccMeta schema

image_meta_embed(fp, meta)

Embed metadata into a copy of the image file.

Parameters:

Name	Type	Description	Default
fp		Filepath to source image file	required
meta		Metadata to embed into image	required

Returns:

Type	Description
	Filepath to the new image file with updated metadata

image_meta_delete(fp)

Delete all metadata from image.

Parameters:

Name	Type	Description	Default
fp		Filepath to image file.	required

image_thumbnail(fp, **options)

Create a thumbnail for an image.

Parameters:

Name	Type	Description	Default
fp		Filepath to image file.	required
options		Keyword arguments forwarded to sdk_opts: image_thumbnail_size - Size of the larger side of the thumbnail in pixels. Default: 128	{}

Returns:

Type	Description
	Thumbnail image as PIL Image object

image_strip_metadata(img)

Strip all metadata from Pillow Image object.

Parameters:

Name	Type	Description	Default
img		PIL Image object to strip metadata from.	required

Returns:

Type	Description
	Image.Image

image_to_data_url(img, **options)

Convert PIL Image object to a Data-URL in the thumbnail image format.

Parameters:

Name	Type	Description	Default
img		PIL Image object to encode as Data-URL.	required
options		Keyword arguments forwarded to sdk_opts: image_thumbnail_format - Image format (JPEG, WEBP or AVIF). Default: WEBP; image_thumbnail_quality - Compression setting (0-100). Default: 30	{}

Returns:

Type	Description
	Data-URL string

decode_latin1_fallback(value)

Re-decode a metadata value that holds bytes which are not valid UTF-8 as Latin-1.

exiv2 returns such bytes as lone surrogates. Legacy IPTC text is the common case, as IPTC defaults to Latin-1 when no UTF-8 CodedCharacterSet is declared.

Parameters:

Name	Type	Description	Default
value		Metadata value as returned by exiv2	required

Returns:

Type	Description
	The value unchanged if it is valid text, otherwise its bytes decoded as Latin-1

Raises:

Type	Description
UnicodeEncodeError	If the value holds surrogates that do not stand for raw bytes