HEIF Auxiliary Image Extractor

Build a tool that extracts and processes auxiliary images from HEIF/AVIF image files. Many modern HEIF files contain auxiliary images like alpha mattes, gain maps, and other metadata images that are stored alongside the main image.

Capabilities

Extract auxiliary images from HEIF files

• Given a HEIF file with auxiliary images, the tool extracts all available auxiliary images and returns them as a list of dictionaries containing the auxiliary type and image data @test
• Given a HEIF file with no auxiliary images, the tool returns an empty list @test

Retrieve specific auxiliary image by ID

• Given a HEIF file and a valid auxiliary image ID, the tool retrieves the specific auxiliary image and returns its properties (size, mode, and data) @test
• Given an invalid auxiliary image ID, the tool raises an appropriate error @test

Implementation

@generates

API

def extract_aux_images(heif_path: str) -> list[dict]:
    """
    Extract all auxiliary images from a HEIF file.

    Args:
        heif_path: Path to the HEIF/AVIF file

    Returns:
        List of dictionaries, each containing:
        - 'aux_type': str - The type of auxiliary image
        - 'aux_id': int - The ID of the auxiliary image
        - 'size': tuple - (width, height) of the auxiliary image
        - 'mode': str - Color mode of the auxiliary image
    """
    pass

def get_aux_image_by_id(heif_path: str, aux_id: int) -> dict:
    """
    Retrieve a specific auxiliary image by its ID.

    Args:
        heif_path: Path to the HEIF/AVIF file
        aux_id: ID of the auxiliary image to retrieve

    Returns:
        Dictionary containing:
        - 'size': tuple - (width, height) of the image
        - 'mode': str - Color mode of the image
        - 'data': bytes - Raw image data

    Raises:
        ValueError: If the auxiliary image ID is invalid
    """
    pass

Dependencies { .dependencies }

pillow-heif { .dependency }

Provides support for reading HEIF/AVIF files and accessing auxiliary images.

@satisfied-by