HeifImage object — pillow-heif 1.6.0 documentation

# HeifImage object

class pillow_heif.HeifImage(c_image)

  Bases: `BaseImage`

  One image in a `HeifFile` container.

  info["exif"]: bytes

    Note

    In HEIF orientation tag is only for information purposes and must not be used to rotate image.

    EXIF metadata. Can be None

  info["xmp"]: bytes

    XMP metadata. String in bytes in UTF-8 encoding. Absent if xmp data is missing.

  info["metadata"]: list[dict]

    Other metadata(IPTC for example). List of dictionaries. Usual will be empty. Keys:

    > - type: str

    > - content_type: str

    > - data: bytes

  info["primary"]: bool

    A boolean value that specifies whether the image is the main image when the file contains more than one image.

  info["bit_depth"]: int

    Shows the bit-depth of image in file(not the decoded one, so it may differs from bit depth of mode). Possible values: 8, 10 and 12.

  info["chroma"]: int

    Chroma subsampling of the image in file. Possible values: 420, 422 and 444. Absent for monochrome images.

  info["thumbnails"]: list[int]

    List of thumbnail boxes sizes. Can be empty.

  info["icc_profile"]: bytes

    ICC Profile. Can be absent. Can be empty.

  info["icc_profile_type"]: str

    Possible values: `prof` or `rICC`. Can be absent.

  info["nclx_profile"]: dict

    NCLX color profile. Can be absent. Keys:

    > - color_primaries: `HeifColorPrimaries`

    > - transfer_characteristics: `HeifTransferCharacteristics`

    > - matrix_coefficients: `HeifMatrixCoefficients`

    > - full_range_flag: bool

  info["content_light_level"]: dict

    Content light level information(`clli`). Can be absent. Keys:

    > - max_content_light_level: int

    > - max_pic_average_light_level: int

  info["mastering_display_colour_volume"]: dict

    Mastering display colour volume(`mdcv`). Can be absent. Keys:

    > - display_primaries_x: tuple[int, int, int]

    > - display_primaries_y: tuple[int, int, int]

    > - white_point_x: int

    > - white_point_y: int

    > - max_display_mastering_luminance: int

    > - min_display_mastering_luminance: int

  info["ambient_viewing_environment"]: dict

    Ambient viewing environment(`amve`). Can be absent. Keys:

    > - ambient_illumination: int

    > - ambient_light_x: int

    > - ambient_light_y: int

    Note

    These three properties hold the raw code values as defined in ITU-T H.274. Like `nclx_profile` and `icc_profile` they are written back during save; remove a key from `info` if you do not want it in the output file.

  info["pixel_aspect_ratio"]: tuple[int, int]

    Pixel aspect ratio(`pasp`) as `(horizontal_spacing, vertical_spacing)`. Absent when the image has no `pasp` box. It is written back during save.

  info["depth_images"]: list

    List of `HeifDepthImage` if any present for image. Currently libheif does not support writing of them, only reading.

  info["aux"]: dict

    Auxiliary images present for the image. Keys are the auxiliary types, e.g. `urn:com:apple:photo:2020:aux:hdrgainmap`, values are lists of IDs to pass to `get_aux_image()`. Empty when the image has no auxiliary images. Currently libheif does not support writing of them, only reading.

  info["tiling"]: dict

    Tiling information when the image is stored as a grid of tiles. Absent for non-tiled images. All values are in the display space, the same as `size`. Keys:

    > - num_columns: int

    > - num_rows: int

    > - tile_width: int

    > - tile_height: int

    > - image_width: int

    > - image_height: int

  info["heif"]: dict

    Camera matrices of the image, present only when the file contains them. Keys:

    > - camera_intrinsic_matrix: dict with focal_length_x, focal_length_y, principal_point_x, principal_point_y and skew

    > - camera_extrinsic_matrix_rot: tuple of nine float, the rotation matrix

    Note

    These values are currently not written back during save.

  property has_alpha: bool

    `True` for images with the `alpha` channel, `False` otherwise.

  property premultiplied_alpha: bool

    `True` for images with `premultiplied alpha` channel, `False` otherwise.

  to_pillow() → Image

    Helper method to create `Image` class.

    Returns:

      `Image` class created from an image.

  get_aux_image(aux_id: int) → HeifAuxImage

    Method to retrieve the auxiliary image at the given ID.

    Returns:

      a `HeifAuxImage` class instance.

  property data

    Decodes image and returns image data.

    Returns:

      `bytes` of the decoded image.

  load() → None

    Method to decode image.

    Note

    In normal cases, you should not call this method directly, when reading data or stride property of image will be loaded automatically.

  property stride: int

    Stride of the image.

    Note

    from 0.10.0 version this value always will have width * sizeof pixel in default usage mode.

    Returns:

      An Int value indicating the image stride after decoding.

  size: tuple[int, int]

    Width and height of the image.

  mode: str

    A string which defines the type and depth of a pixel in the image: Pillow Modes

    For currently supported modes by Pillow-Heif see Modes.

class pillow_heif.heif.BaseImage(c_image)

  Bases: `object`

  Base class for `HeifImage`, `HeifDepthImage` and `HeifAuxImage`.

  size: tuple[int, int]

    Width and height of the image.

  mode: str

    A string which defines the type and depth of a pixel in the image: Pillow Modes

    For currently supported modes by Pillow-Heif see Modes.

  property data

    Decodes image and returns image data.

    Returns:

      `bytes` of the decoded image.

  property stride: int

    Stride of the image.

    Note

    from 0.10.0 version this value always will have width * sizeof pixel in default usage mode.

    Returns:

      An Int value indicating the image stride after decoding.

  to_pillow() → Image

    Helper method to create `Image` class.

    Returns:

      `Image` class created from an image.

  load() → None

    Method to decode image.

    Note

    In normal cases, you should not call this method directly, when reading data or stride property of image will be loaded automatically.

class pillow_heif.heif.HeifDepthImage(c_image)

  Bases: `BaseImage`

  Class representing the depth image associated with the `HeifImage` class.

  info["metadata"]: dict

    Represents libheif `heif_depth_representation_info` struct as a dictionary.

    If someone have an example when this struct got filled let me know.

  to_pillow() → Image

    Helper method to create `Image` class.

    Returns:

      `Image` class created from an image.

  property data

    Decodes image and returns image data.

    Returns:

      `bytes` of the decoded image.

  load() → None

    Method to decode image.

    Note

    In normal cases, you should not call this method directly, when reading data or stride property of image will be loaded automatically.

  property stride: int

    Stride of the image.

    Note

    from 0.10.0 version this value always will have width * sizeof pixel in default usage mode.

    Returns:

      An Int value indicating the image stride after decoding.

  size: tuple[int, int]

    Width and height of the image.

  mode: str

    A string which defines the type and depth of a pixel in the image: Pillow Modes

    For currently supported modes by Pillow-Heif see Modes.

class pillow_heif.heif.HeifAuxImage(c_image)

  Bases: `BaseImage`

  Class representing the auxiliary image associated with the `HeifImage` class.

  property data

    Decodes image and returns image data.

    Returns:

      `bytes` of the decoded image.

  load() → None

    Method to decode image.

    Note

    In normal cases, you should not call this method directly, when reading data or stride property of image will be loaded automatically.

  property stride: int

    Stride of the image.

    Note

    from 0.10.0 version this value always will have width * sizeof pixel in default usage mode.

    Returns:

      An Int value indicating the image stride after decoding.

  to_pillow() → Image

    Helper method to create `Image` class.

    Returns:

      `Image` class created from an image.

  size: tuple[int, int]

    Width and height of the image.

  mode: str

    A string which defines the type and depth of a pixel in the image: Pillow Modes

    For currently supported modes by Pillow-Heif see Modes.