Core & Context API¶
Core classes representing HEIF containers, image handles, and decoded image buffers.
HeifContext¶
pylibheif.HeifContext ¶
init(self) -> None
__module__
class-attribute
¶
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'.
max_decoding_threads
property
¶
Maximum background threads for parallel tile decoding.
__new__
builtin
¶
Create and return a new object. See help(type) for accurate signature.
add_compatible_brand
method descriptor
¶
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(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(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(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(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(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(self, master_image: pylibheif._pylibheif.HeifImageHandle, thumbnail_image: pylibheif._pylibheif.HeifImageHandle) -> None
Assign a thumbnail image to a master image.
get_image_handle
method descriptor
¶
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(self) -> list[int]
get_max_decoding_threads
method descriptor
¶
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(self) -> int
Get number of sequence tracks in the HEIF file.
get_primary_image_handle
method descriptor
¶
get_primary_image_handle(self) -> pylibheif._pylibheif.HeifImageHandle
get_sequence_duration
method descriptor
¶
get_sequence_duration(self) -> int
Get total sequence duration in timescale ticks.
get_sequence_timescale
method descriptor
¶
get_sequence_timescale(self) -> int
Get the sequence timescale (clock ticks per second).
get_sequence_track_ids
method descriptor
¶
get_sequence_track_ids(self) -> list[int]
Get list of sequence track IDs.
get_track
method descriptor
¶
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(self) -> bool
Check whether the HEIF file contains an image sequence track.
read_from_memory
method descriptor
¶
read_from_memory(self, arg: object, /) -> None
read_from_stream
method descriptor
¶
read_from_stream(self, stream: object) -> None
Read HEIF data from a Python file-like stream object implementing read(), seek(), tell().
set_major_brand
method descriptor
¶
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(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(self, repetitions: int) -> None
Set playback repetition count (0 = infinite loop).
set_primary_image
method descriptor
¶
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(self, timescale: int) -> None
Set global sequence timescale.
write_to_bytes
method descriptor
¶
write_to_bytes(self, copy: bool = True) -> object
Export context to Python bytes (copy=True) or zero-copy memoryview (copy=False).
write_to_memoryview
method descriptor
¶
write_to_memoryview(self) -> object
Export context directly to a zero-copy Python memoryview.
write_to_stream
method descriptor
¶
write_to_stream(self, stream: object) -> None
Write HEIF data directly to a Python file-like stream object implementing write().
HeifImageHandle¶
pylibheif.HeifImageHandle ¶
Initialize self. See help(type(self)) for accurate signature.
__module__
class-attribute
¶
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
¶
(self) -> pylibheif._pylibheif.HeifAmbientViewingEnvironment | None
color_profile_type
property
¶
(self) -> pylibheif._pylibheif.HeifColorProfileType
content_light_level
property
¶
(self) -> pylibheif._pylibheif.HeifContentLightLevel | None
mastering_display_colour_volume
property
¶
(self) -> pylibheif._pylibheif.HeifMasteringDisplayColourVolume | None
portrait_matte
property
¶
Extract Apple Portrait Matte (segmentation foreground alpha mask) if present.
__new__
builtin
¶
Create and return a new object. See help(type) for accurate signature.
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_gain_map ¶
Decode primary gain map image and return as a numpy array in range [0, 1].
decode_tile
method descriptor
¶
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(self) -> pylibheif._pylibheif.HeifAmbientViewingEnvironment | None
get_auxiliary_image_handle
method descriptor
¶
get_auxiliary_image_handle(self, arg: int, /) -> pylibheif._pylibheif.HeifImageHandle
get_auxiliary_image_ids
method descriptor
¶
get_auxiliary_image_ids(self, aux_key_mask: int = 0) -> list[int]
get_color_profile_bytes ¶
Retrieve effective ICC profile bytes according to MIAF rules.
get_color_profile_info ¶
Return dictionary of color profile metadata and wide gamut detection.
get_content_light_level
method descriptor
¶
get_content_light_level(self) -> pylibheif._pylibheif.HeifContentLightLevel | None
get_depth_image_handle
method descriptor
¶
get_depth_image_handle(self, depth_image_id: int) -> pylibheif._pylibheif.HeifImageHandle
get_depth_image_ids
method descriptor
¶
get_depth_image_ids(self) -> list[int]
get_depth_representation_info
method descriptor
¶
get_depth_representation_info(self, depth_image_id: int = 0) -> pylibheif._pylibheif.HeifDepthRepresentationInfo | None
get_gain_map_handle ¶
Return auxiliary image handle for the Gain Map.
get_gain_map_image_handle ¶
Return auxiliary image handle for the Gain Map.
get_gain_map_metadata ¶
Extract Gain Map metadata from XMP packet attached to gain map or master image.
get_image_tiling
method descriptor
¶
get_image_tiling(self, process_transformations: bool = True) -> pylibheif._pylibheif.HeifImageTiling
get_mastering_display_colour_volume
method descriptor
¶
get_mastering_display_colour_volume(self) -> pylibheif._pylibheif.HeifMasteringDisplayColourVolume | None
get_metadata_block
method descriptor
¶
get_metadata_block(self, arg: int, /) -> bytes
get_metadata_block_ids
method descriptor
¶
get_metadata_block_ids(self, type_filter: str = '') -> list[int]
get_metadata_block_type
method descriptor
¶
get_metadata_block_type(self, arg: int, /) -> str
get_nclx_color_profile
method descriptor
¶
get_nclx_color_profile(self) -> pylibheif._pylibheif.HeifColorProfileNclx | None
get_number_of_depth_images
method descriptor
¶
get_number_of_depth_images(self) -> int
get_number_of_thumbnails
method descriptor
¶
get_number_of_thumbnails(self) -> int
get_primary_depth_image_handle
method descriptor
¶
get_primary_depth_image_handle(self) -> pylibheif._pylibheif.HeifImageHandle
get_raw_color_profile
method descriptor
¶
get_raw_color_profile(self) -> object
get_thumbnail
method descriptor
¶
get_thumbnail(self, thumbnail_id: int) -> pylibheif._pylibheif.HeifImageHandle
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 ¶
init(self, arg0: int, arg1: int, arg2: pylibheif._pylibheif.HeifColorspace, arg3: pylibheif._pylibheif.HeifChroma, /) -> None
__module__
class-attribute
¶
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
¶
(self) -> pylibheif._pylibheif.HeifAmbientViewingEnvironment | None
color_profile_type
property
¶
(self) -> pylibheif._pylibheif.HeifColorProfileType
content_light_level
property
¶
(self) -> pylibheif._pylibheif.HeifContentLightLevel | None
mastering_display_colour_volume
property
¶
(self) -> pylibheif._pylibheif.HeifMasteringDisplayColourVolume | None
__new__
builtin
¶
Create and return a new object. See help(type) for accurate signature.
add_plane
method descriptor
¶
add_plane(self, arg0: pylibheif._pylibheif.HeifChannel, arg1: int, arg2: int, arg3: int, /) -> None
crop
method descriptor
¶
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(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(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(arr: numpy.ndarray) -> HeifImage from_numpy(arr: numpy.ndarray, bit_depth: int = 10) -> HeifImage
from_pillow ¶
Convert a Pillow Image into a pylibheif HeifImage.
get_height
method descriptor
¶
get_height(self, arg: pylibheif._pylibheif.HeifChannel, /) -> int
get_nclx_color_profile
method descriptor
¶
get_nclx_color_profile(self) -> pylibheif._pylibheif.HeifColorProfileNclx | None
get_plane
method descriptor
¶
get_plane(self, channel: HeifChannel, writeable: bool = False) -> numpy.ndarray
get_raw_color_profile
method descriptor
¶
get_raw_color_profile(self) -> object
get_width
method descriptor
¶
get_width(self, arg: pylibheif._pylibheif.HeifChannel, /) -> int
set_nclx_color_profile
method descriptor
¶
set_nclx_color_profile(self, color_profile: pylibheif._pylibheif.HeifColorProfileNclx) -> None
set_raw_color_profile
method descriptor
¶
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 ¶
Initialize self. See help(type(self)) for accurate signature.
__module__
class-attribute
¶
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'.
__new__
builtin
¶
Create and return a new object. See help(type) for accurate signature.