Skip to content

Core & Context API

Core classes representing HEIF containers, image handles, and decoded image buffers.


HeifContext

pylibheif.HeifContext

HeifContext()

init(self) -> None

__module__ class-attribute

__module__ = 'pylibheif._pylibheif'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

is_closed property

is_closed

(self) -> bool

max_decoding_threads property

max_decoding_threads

Maximum background threads for parallel tile decoding.

__enter__ method descriptor

__enter__()

enter(self) -> pylibheif._pylibheif.HeifContext

__exit__ method descriptor

__exit__()

exit(self, *args) -> None

__new__ builtin

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__repr__ method descriptor

__repr__()

repr(self) -> str

add_compatible_brand method descriptor

add_compatible_brand()

add_compatible_brand(self, brand: str) -> None

Add a compatible brand to the HEIF container (4-character FourCC).

add_exif_metadata method descriptor

add_exif_metadata()

add_exif_metadata(self, handle: pylibheif._pylibheif.HeifImageHandle, data: bytes) -> None

Add EXIF metadata to an image. The data should be raw EXIF bytes.

add_generic_metadata method descriptor

add_generic_metadata()

add_generic_metadata(self, handle: pylibheif._pylibheif.HeifImageHandle, data: bytes, item_type: str, content_type: str = '') -> None

Add generic metadata to an image with specified item type and optional content type.

add_visual_sequence_track method descriptor

add_visual_sequence_track()

add_visual_sequence_track(self, width: int, height: int, track_type: object | None = None, timescale: int = 1000) -> pylibheif._pylibheif.HeifTrack

Add a new visual sequence track to the HEIF container.

add_xmp_metadata method descriptor

add_xmp_metadata()

add_xmp_metadata(self, handle: pylibheif._pylibheif.HeifImageHandle, data: bytes) -> None

Add XMP metadata to an image. The data should be XMP XML as bytes.

assign_auxiliary_image method descriptor

assign_auxiliary_image()

assign_auxiliary_image(self, master_image: pylibheif._pylibheif.HeifImageHandle, auxiliary_image: pylibheif._pylibheif.HeifImageHandle, auxiliary_type: str) -> None

Assign an auxiliary image (such as an HDR gain map) to a master image.

assign_thumbnail method descriptor

assign_thumbnail()

assign_thumbnail(self, master_image: pylibheif._pylibheif.HeifImageHandle, thumbnail_image: pylibheif._pylibheif.HeifImageHandle) -> None

Assign a thumbnail image to a master image.

close method descriptor

close()

close(self) -> None

get_image_handle method descriptor

get_image_handle()

get_image_handle(self, arg: int, /) -> pylibheif._pylibheif.HeifImageHandle

get_list_of_top_level_image_IDs method descriptor

get_list_of_top_level_image_IDs()

get_list_of_top_level_image_IDs(self) -> list[int]

get_max_decoding_threads method descriptor

get_max_decoding_threads()

get_max_decoding_threads(self) -> int

Get maximum background threads used for parallel tile decoding.

get_number_of_sequence_tracks method descriptor

get_number_of_sequence_tracks()

get_number_of_sequence_tracks(self) -> int

Get number of sequence tracks in the HEIF file.

get_primary_image_handle method descriptor

get_primary_image_handle()

get_primary_image_handle(self) -> pylibheif._pylibheif.HeifImageHandle

get_sequence_duration method descriptor

get_sequence_duration()

get_sequence_duration(self) -> int

Get total sequence duration in timescale ticks.

get_sequence_timescale method descriptor

get_sequence_timescale()

get_sequence_timescale(self) -> int

Get the sequence timescale (clock ticks per second).

get_sequence_track_ids method descriptor

get_sequence_track_ids()

get_sequence_track_ids(self) -> list[int]

Get list of sequence track IDs.

get_track method descriptor

get_track()

get_track(self, track_id: int = 0) -> pylibheif._pylibheif.HeifTrack

Get a HeifTrack object for track_id (0 for first visual track).

has_sequence method descriptor

has_sequence()

has_sequence(self) -> bool

Check whether the HEIF file contains an image sequence track.

read_from_file method descriptor

read_from_file()

read_from_file(self, arg: str, /) -> None

read_from_memory method descriptor

read_from_memory()

read_from_memory(self, arg: object, /) -> None

read_from_stream method descriptor

read_from_stream()

read_from_stream(self, stream: object) -> None

Read HEIF data from a Python file-like stream object implementing read(), seek(), tell().

reset method descriptor

reset()

reset(self) -> None

set_major_brand method descriptor

set_major_brand()

set_major_brand(self, brand: str) -> None

Set the major brand of the HEIF container (4-character FourCC).

set_max_decoding_threads method descriptor

set_max_decoding_threads()

set_max_decoding_threads(self, max_threads: int) -> None

Set maximum background threads for parallel tile decoding (0 to decode in main thread).

set_number_of_sequence_repetitions method descriptor

set_number_of_sequence_repetitions()

set_number_of_sequence_repetitions(self, repetitions: int) -> None

Set playback repetition count (0 = infinite loop).

set_primary_image method descriptor

set_primary_image()

set_primary_image(self, handle: pylibheif._pylibheif.HeifImageHandle) -> None

Designate an image handle as the primary image of the context.

set_sequence_timescale method descriptor

set_sequence_timescale()

set_sequence_timescale(self, timescale: int) -> None

Set global sequence timescale.

write_to_bytes method descriptor

write_to_bytes()

write_to_bytes(self, copy: bool = True) -> object

Export context to Python bytes (copy=True) or zero-copy memoryview (copy=False).

write_to_file method descriptor

write_to_file()

write_to_file(self, arg: str, /) -> None

write_to_memoryview method descriptor

write_to_memoryview()

write_to_memoryview(self) -> object

Export context directly to a zero-copy Python memoryview.

write_to_stream method descriptor

write_to_stream()

write_to_stream(self, stream: object) -> None

Write HEIF data directly to a Python file-like stream object implementing write().


HeifImageHandle

pylibheif.HeifImageHandle

HeifImageHandle(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__module__ class-attribute

__module__ = 'pylibheif._pylibheif'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

ambient_viewing_environment property

ambient_viewing_environment

(self) -> pylibheif._pylibheif.HeifAmbientViewingEnvironment | None

chroma_bits_per_pixel property

chroma_bits_per_pixel

(self) -> int

color_profile_type property

color_profile_type

(self) -> pylibheif._pylibheif.HeifColorProfileType

content_light_level property

content_light_level

(self) -> pylibheif._pylibheif.HeifContentLightLevel | None

depth_map property

depth_map

Retrieve the primary DepthMap domain entity, or None if absent.

gain_map property

gain_map

Retrieve the primary GainMap domain entity, or None if absent.

gain_map_ids property

gain_map_ids

Find all auxiliary image IDs corresponding to HDR Gain Maps.

has_alpha property

has_alpha

(self) -> bool

has_ambient_viewing_environment property

has_ambient_viewing_environment

(self) -> bool

has_content_light_level property

has_content_light_level

(self) -> bool

has_depth_image property

has_depth_image

(self) -> bool

has_gain_map property

has_gain_map

Return True if image handle has an associated Gain Map.

has_mastering_display_colour_volume property

has_mastering_display_colour_volume

(self) -> bool

height property

height

(self) -> int

luma_bits_per_pixel property

luma_bits_per_pixel

(self) -> int

mastering_display_colour_volume property

mastering_display_colour_volume

(self) -> pylibheif._pylibheif.HeifMasteringDisplayColourVolume | None

number_of_thumbnails property

number_of_thumbnails

(self) -> int

portrait_matte property

portrait_matte

Extract Apple Portrait Matte (segmentation foreground alpha mask) if present.

width property

width

(self) -> int

__new__ builtin

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__repr__ method descriptor

__repr__()

repr(self) -> str

decode

decode(colorspace: HeifColorspace = RGB, chroma: HeifChroma = InterleavedRGB, options: Optional[HeifDecodingOptions] = None, num_threads: Optional[int] = None, target_colorspace: Optional[Union[str, bytes]] = None, intent: Union[RenderingIntent, int, str] = <RenderingIntent.PERCEPTUAL: 0>, bpc: bool = True, prefer_nclx: bool = False) -> HeifImage

Decode image handle with optional LittleCMS target color space conversion.

decode_depth

decode_depth() -> Any

Decode primary depth image and return as a 2D numpy array.

decode_gain_map

decode_gain_map() -> Any

Decode primary gain map image and return as a numpy array in range [0, 1].

decode_tile method descriptor

decode_tile()

decode_tile(self, tile_x: int, tile_y: int, colorspace: pylibheif._pylibheif.HeifColorspace = HeifColorspace.RGB, chroma: pylibheif._pylibheif.HeifChroma = HeifChroma.InterleavedRGB, options: pylibheif._pylibheif.HeifDecodingOptions | None = None, num_threads: int | None = None) -> pylibheif._pylibheif.HeifImage

decode_to_srgb

decode_to_srgb(intent: Union[RenderingIntent, int, str] = <RenderingIntent.PERCEPTUAL: 0>, bpc: bool = True, as_pillow: bool = False, prefer_nclx: bool = False) -> Any

Decode image and accurately transform pixels to sRGB color space.

get_ambient_viewing_environment method descriptor

get_ambient_viewing_environment()

get_ambient_viewing_environment(self) -> pylibheif._pylibheif.HeifAmbientViewingEnvironment | None

get_auxiliary_image_handle method descriptor

get_auxiliary_image_handle()

get_auxiliary_image_handle(self, arg: int, /) -> pylibheif._pylibheif.HeifImageHandle

get_auxiliary_image_ids method descriptor

get_auxiliary_image_ids()

get_auxiliary_image_ids(self, aux_key_mask: int = 0) -> list[int]

get_auxiliary_type method descriptor

get_auxiliary_type()

get_auxiliary_type(self) -> str

get_color_profile_bytes

get_color_profile_bytes(prefer_nclx: bool = False) -> bytes

Retrieve effective ICC profile bytes according to MIAF rules.

get_color_profile_info

get_color_profile_info(prefer_nclx: bool = False) -> Dict[str, Any]

Return dictionary of color profile metadata and wide gamut detection.

get_content_light_level method descriptor

get_content_light_level()

get_content_light_level(self) -> pylibheif._pylibheif.HeifContentLightLevel | None

get_depth_image_handle method descriptor

get_depth_image_handle()

get_depth_image_handle(self, depth_image_id: int) -> pylibheif._pylibheif.HeifImageHandle

get_depth_image_ids method descriptor

get_depth_image_ids()

get_depth_image_ids(self) -> list[int]

get_depth_representation_info method descriptor

get_depth_representation_info()

get_depth_representation_info(self, depth_image_id: int = 0) -> pylibheif._pylibheif.HeifDepthRepresentationInfo | None

get_gain_map_handle

get_gain_map_handle() -> HeifImageHandle

Return auxiliary image handle for the Gain Map.

get_gain_map_image_handle

get_gain_map_image_handle() -> HeifImageHandle

Return auxiliary image handle for the Gain Map.

get_gain_map_metadata

get_gain_map_metadata() -> Optional[GainMapMetadata]

Extract Gain Map metadata from XMP packet attached to gain map or master image.

get_image_tiling method descriptor

get_image_tiling()

get_image_tiling(self, process_transformations: bool = True) -> pylibheif._pylibheif.HeifImageTiling

get_mastering_display_colour_volume method descriptor

get_mastering_display_colour_volume()

get_mastering_display_colour_volume(self) -> pylibheif._pylibheif.HeifMasteringDisplayColourVolume | None

get_metadata_block method descriptor

get_metadata_block()

get_metadata_block(self, arg: int, /) -> bytes

get_metadata_block_ids method descriptor

get_metadata_block_ids()

get_metadata_block_ids(self, type_filter: str = '') -> list[int]

get_metadata_block_type method descriptor

get_metadata_block_type()

get_metadata_block_type(self, arg: int, /) -> str

get_nclx_color_profile method descriptor

get_nclx_color_profile()

get_nclx_color_profile(self) -> pylibheif._pylibheif.HeifColorProfileNclx | None

get_number_of_depth_images method descriptor

get_number_of_depth_images()

get_number_of_depth_images(self) -> int

get_number_of_thumbnails method descriptor

get_number_of_thumbnails()

get_number_of_thumbnails(self) -> int

get_primary_depth_image_handle method descriptor

get_primary_depth_image_handle()

get_primary_depth_image_handle(self) -> pylibheif._pylibheif.HeifImageHandle

get_raw_color_profile method descriptor

get_raw_color_profile()

get_raw_color_profile(self) -> object

get_thumbnail method descriptor

get_thumbnail()

get_thumbnail(self, thumbnail_id: int) -> pylibheif._pylibheif.HeifImageHandle

get_thumbnail_ids method descriptor

get_thumbnail_ids()

get_thumbnail_ids(self) -> list[int]

reconstruct_hdr

reconstruct_hdr(target_headroom: Optional[float] = None, output_format: str = 'linear', display_boost: Optional[float] = None) -> Any

Reconstruct an HDR image from this handle and its embedded Gain Map.

to_pillow

to_pillow(source: Any, convert_hdr_to_8bit: bool = True, options: Optional[HeifDecodingOptions] = None, num_threads: Optional[int] = None) -> Any

Convert a HeifImage or HeifImageHandle into a Pillow Image.


HeifImage

pylibheif.HeifImage

HeifImage()

init(self, arg0: int, arg1: int, arg2: pylibheif._pylibheif.HeifColorspace, arg3: pylibheif._pylibheif.HeifChroma, /) -> None

__module__ class-attribute

__module__ = 'pylibheif._pylibheif'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

ambient_viewing_environment property

ambient_viewing_environment

(self) -> pylibheif._pylibheif.HeifAmbientViewingEnvironment | None

color_profile_type property

color_profile_type

(self) -> pylibheif._pylibheif.HeifColorProfileType

content_light_level property

content_light_level

(self) -> pylibheif._pylibheif.HeifContentLightLevel | None

duration property

duration

Display duration of this frame in sequence timescale ticks.

has_ambient_viewing_environment property

has_ambient_viewing_environment

(self) -> bool

has_content_light_level property

has_content_light_level

(self) -> bool

has_mastering_display_colour_volume property

has_mastering_display_colour_volume

(self) -> bool

height property

height

(self) -> int

mastering_display_colour_volume property

mastering_display_colour_volume

(self) -> pylibheif._pylibheif.HeifMasteringDisplayColourVolume | None

width property

width

(self) -> int

__new__ builtin

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__repr__ method descriptor

__repr__()

repr(self) -> str

add_plane method descriptor

add_plane()

add_plane(self, arg0: pylibheif._pylibheif.HeifChannel, arg1: int, arg2: int, arg3: int, /) -> None

crop method descriptor

crop()

crop(self, left: int, right: int, top: int, bottom: int) -> None

Crop the image in place by trimming margins from each edge.

from_buffer

from_buffer(*args, **kwargs)

from_buffer(buffer: object, width: int, height: int, colorspace: pylibheif._pylibheif.HeifColorspace = HeifColorspace.RGB, chroma: pylibheif._pylibheif.HeifChroma = HeifChroma.InterleavedRGB, bit_depth: int = 8, stride: int = 0) -> pylibheif._pylibheif.HeifImage

Create a HeifImage directly from a Python buffer (bytes, bytearray, memoryview).

from_bytes

from_bytes(*args, **kwargs)

from_bytes(data: object, width: int, height: int, colorspace: pylibheif._pylibheif.HeifColorspace = HeifColorspace.RGB, chroma: pylibheif._pylibheif.HeifChroma = HeifChroma.InterleavedRGB, bit_depth: int = 8, stride: int = 0) -> pylibheif._pylibheif.HeifImage

Create a HeifImage directly from raw bytes.

from_numpy

from_numpy(*args, **kwargs)

from_numpy(arr: numpy.ndarray) -> HeifImage from_numpy(arr: numpy.ndarray, bit_depth: int = 10) -> HeifImage

from_pillow

from_pillow(pil_image: Any, bit_depth: int = 8) -> Any

Convert a Pillow Image into a pylibheif HeifImage.

get_height method descriptor

get_height()

get_height(self, arg: pylibheif._pylibheif.HeifChannel, /) -> int

get_nclx_color_profile method descriptor

get_nclx_color_profile()

get_nclx_color_profile(self) -> pylibheif._pylibheif.HeifColorProfileNclx | None

get_plane method descriptor

get_plane()

get_plane(self, channel: HeifChannel, writeable: bool = False) -> numpy.ndarray

get_raw_color_profile method descriptor

get_raw_color_profile()

get_raw_color_profile(self) -> object

get_width method descriptor

get_width()

get_width(self, arg: pylibheif._pylibheif.HeifChannel, /) -> int

set_nclx_color_profile method descriptor

set_nclx_color_profile()

set_nclx_color_profile(self, color_profile: pylibheif._pylibheif.HeifColorProfileNclx) -> None

set_raw_color_profile method descriptor

set_raw_color_profile()

set_raw_color_profile(self, profile_type: str, data: bytes) -> None

to_pillow

to_pillow(source: Any, convert_hdr_to_8bit: bool = True, options: Optional[HeifDecodingOptions] = None, num_threads: Optional[int] = None) -> Any

Convert a HeifImage or HeifImageHandle into a Pillow Image.


HeifPlane

pylibheif.HeifPlaneLayout

HeifPlaneLayout(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__module__ class-attribute

__module__ = 'pylibheif._pylibheif'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

bits_per_pixel property

bits_per_pixel

(self) -> int

bytes_per_channel property

bytes_per_channel

(self) -> int

channel property

channel

(self) -> pylibheif._pylibheif.HeifChannel

height property

height

(self) -> int

is_big_endian property

is_big_endian

(self) -> bool

num_channels property

num_channels

(self) -> int

stride_bytes property

stride_bytes

(self) -> int

width property

width

(self) -> int

__new__ builtin

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__repr__ method descriptor

__repr__()

repr(self) -> str

shape method descriptor

shape()

shape(self) -> list[int]

strides method descriptor

strides()

strides(self) -> list[int]