Depth Map & Auxiliary API

Domain entities, physical metric depth conversions (ISO/IEC 23008-12 / ITU-T H.265), colormaps, and auxiliary image extractors.

---

DepthMap

pylibheif.DepthMap

DepthMap(master_handle: Any, aux_handle: Any, item_id: int)

High-Dynamic Range & Metric Depth Map domain entity.

Encapsulates a HEIF depth image item, its representation info (ISO/IEC 23008-12), metric distance calculation, and zero-dependency pseudocolor visualization.

Maintains a strong reference to the master HeifImageHandle to guarantee memory safety and prevent premature garbage collection of native C++ handles.

info cached property

info: Optional[Any]

Depth representation metadata (HeifDepthRepresentationInfo) if present.

master_handle property

master_handle

The master/primary image handle.

decode

decode(normalize: bool = False, invert_if_disparity: bool = False) -> np.ndarray

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

Parameters:

Name	Type	Description	Default
normalize	bool	If True, scale pixel values to float32 range [0.0, 1.0].	False
invert_if_disparity	bool	If True and data is disparity, invert values so 0.0 represents closest objects and 1.0 represents infinity.	False

to_metric_depth

to_metric_depth() -> Optional[np.ndarray]

Compute true physical metric distance matrix Z (in meters) as float32.

Uses the exact ISO/IEC 23008-12 and ITU-T H.265 Depth Representation formulas. Returns None if calibrated metric depth parameters (z_near / z_far) are absent.

to_pillow

to_pillow(colormap: Optional[str] = 'turbo', size: Optional[Tuple[int, int]] = None, resample: Any = None) -> Any

Render depth map as a Pillow Image with zero external dependencies.

Parameters:

Name	Type	Description	Default
colormap	Optional[str]	'turbo' (default, high contrast), 'inferno', 'viridis', or 'grayscale'/'none'.	'turbo'
size	Optional[Tuple[int, int]]	Optional (width, height) to resize the output depth image to match master image dimensions.	None
resample	Any	Optional PIL resampling filter (defaults to BILINEAR if size is specified).	None

---

AsyncDepthMap

pylibheif.AsyncDepthMap

AsyncDepthMap(master_handle: Any, sync_depth_map: DepthMap, executor: Any = None)

Asynchronous Depth Map domain entity attached to AsyncHeifImageHandle.

info property

info

master_handle property

master_handle

decode

decode(normalize: bool = False, invert_if_disparity: bool = False) -> np.ndarray

to_metric_depth

to_metric_depth() -> Optional[np.ndarray]

to_pillow

to_pillow(colormap: Optional[str] = 'turbo', size: Optional[Tuple[int, int]] = None, resample: Any = None) -> Any

---

DepthRepresentationType

pylibheif.DepthRepresentationType

Bases: enum.IntEnum

HEIF depth representation types according to ISO/IEC 23008-12 & ITU-T H.265 SEI.

NONUNIFORM_DISPARITY class-attribute

NONUNIFORM_DISPARITY = <DepthRepresentationType.NONUNIFORM_DISPARITY: 3>

HEIF depth representation types according to ISO/IEC 23008-12 & ITU-T H.265 SEI.

UNIFORM_DISPARITY class-attribute

UNIFORM_DISPARITY = <DepthRepresentationType.UNIFORM_DISPARITY: 1>

HEIF depth representation types according to ISO/IEC 23008-12 & ITU-T H.265 SEI.

UNIFORM_INVERSE_Z class-attribute

UNIFORM_INVERSE_Z = <DepthRepresentationType.UNIFORM_INVERSE_Z: 0>

HEIF depth representation types according to ISO/IEC 23008-12 & ITU-T H.265 SEI.

UNIFORM_Z class-attribute

UNIFORM_Z = <DepthRepresentationType.UNIFORM_Z: 2>

HEIF depth representation types according to ISO/IEC 23008-12 & ITU-T H.265 SEI.

__doc__ class-attribute

__doc__ = 'HEIF depth representation types according to ISO/IEC 23008-12 & ITU-T H.265 SEI.'

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'.

__module__ class-attribute

__module__ = 'pylibheif.depth'

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'.

__format__ method descriptor

__format__(format_spec)

Convert to a string according to format_spec.

---

Top-Level Extraction Helpers

pylibheif.extract_depth_map

extract_depth_map(handle: Any) -> Optional[DepthMap]

Inspect a HeifImageHandle and return a DepthMap domain entity if present, or None.

pylibheif.extract_portrait_matte

extract_portrait_matte(handle: Any) -> Optional[np.ndarray]

Extract Apple Portrait Matte (hair/subject foreground alpha mask) if present.