capturegraph.adapters.dng_convert

Cross-Platform DNG Conversion

Convert DNG (Digital Negative) raw files to PIL Images, JPEG, HEIF, and PNG. Tries Apple Core Image first (best quality on macOS), then falls back to rawpy with high-quality tone mapping settings.

Example

from capturegraph.adapters import dng_to_jpeg, dng_to_heif, dng_to_png, dng_to_pil

# Get as PIL Image for editing
pil_img = dng_to_pil("photo.dng")
pil_img.thumbnail((1024, 1024))
pil_img.save("thumb.jpg")

# Convert to JPEG (uses Apple on macOS, rawpy elsewhere)
dng_to_jpeg("photo.dng", "output.jpg")

# Convert to HEIF
dng_to_heif("photo.dng", "output.heic", quality=0.9)

# Convert to PNG (lossless)
dng_to_png("photo.dng", "output.png")

dng_to_pil(dng_path, max_axis=None)

Open a DNG file and return it as a PIL Image.

Uses Apple Core Image on macOS for best quality (native tone mapping), falls back to rawpy with high-quality AHD demosaicing elsewhere.

Parameters:

Name	Type	Description	Default
dng_path	str | Path	Path to the input DNG file.	required
max_axis	int	If provided, resize so the largest dimension equals this value.	None

Returns:

Type	Description
Image	PIL.Image.Image: The processed image.

Note

Remember to call .close() on the returned image when done.

Example

from capturegraph.adapters import dng_to_pil

pil = dng_to_pil("photo.dng")
pil.thumbnail((1024, 1024))
pil.save("thumb.jpg")
pil.close()

# Get a smaller version directly
small = dng_to_pil("photo.dng", max_axis=1024)

Source code in capturegraph-lib/capturegraph/adapters/dng_convert.py

def dng_to_pil(dng_path: str | Path, max_axis: int = None) -> Image:
    """
    Open a DNG file and return it as a PIL Image.

    Uses Apple Core Image on macOS for best quality (native tone mapping),
    falls back to rawpy with high-quality AHD demosaicing elsewhere.

    Args:
        dng_path: Path to the input DNG file.
        max_axis: If provided, resize so the largest dimension equals this value.

    Returns:
        PIL.Image.Image: The processed image.

    Note:
        Remember to call `.close()` on the returned image when done.

    Example:
        ```python
        from capturegraph.adapters import dng_to_pil

        pil = dng_to_pil("photo.dng")
        pil.thumbnail((1024, 1024))
        pil.save("thumb.jpg")
        pil.close()

        # Get a smaller version directly
        small = dng_to_pil("photo.dng", max_axis=1024)
        ```
    """
    dng_path = Path(dng_path).resolve()

    if _APPLE_AVAILABLE:
        img = apple_dng_to_pil(dng_path)
    else:
        img = _rawpy_to_pil(dng_path)

    if max_axis is not None:
        # Calculate new size maintaining aspect ratio
        width, height = img.size
        if width > height:
            new_width = max_axis
            new_height = int(height * max_axis / width)
        else:
            new_height = max_axis
            new_width = int(width * max_axis / height)
        img = img.resize((new_width, new_height), Image.Resampling.LANCZOS)

    return img

dng_to_jpeg(dng_path, output_path, quality=1.0, max_axis=None)

Convert a DNG file to JPEG with high-quality tone mapping.

Uses Apple Core Image on macOS for best quality, falls back to rawpy with AHD demosaicing elsewhere.

Parameters:

Name	Type	Description	Default
dng_path	str | Path	Path to the input DNG file.	required
output_path	str | Path	Path for the output JPEG file.	required
quality	float	Compression quality (0.0-1.0). Default is 1.0 for max quality.	1.0
max_axis	int	If provided, resize so the largest dimension equals this value.	None

Returns:

Type	Description
Path	Path to the created JPEG file.

Example

from capturegraph.adapters import dng_to_jpeg

dng_to_jpeg("photo.dng", "output.jpg")
dng_to_jpeg("photo.dng", "output.jpg", quality=0.95)

# Save a smaller version for analysis
dng_to_jpeg("photo.dng", "thumb.jpg", max_axis=1024)

Source code in capturegraph-lib/capturegraph/adapters/dng_convert.py

def dng_to_jpeg(
    dng_path: str | Path,
    output_path: str | Path,
    quality: float = 1.0,
    max_axis: int = None,
) -> Path:
    """
    Convert a DNG file to JPEG with high-quality tone mapping.

    Uses Apple Core Image on macOS for best quality, falls back to rawpy
    with AHD demosaicing elsewhere.

    Args:
        dng_path: Path to the input DNG file.
        output_path: Path for the output JPEG file.
        quality: Compression quality (0.0-1.0). Default is 1.0 for max quality.
        max_axis: If provided, resize so the largest dimension equals this value.

    Returns:
        Path to the created JPEG file.

    Example:
        ```python
        from capturegraph.adapters import dng_to_jpeg

        dng_to_jpeg("photo.dng", "output.jpg")
        dng_to_jpeg("photo.dng", "output.jpg", quality=0.95)

        # Save a smaller version for analysis
        dng_to_jpeg("photo.dng", "thumb.jpg", max_axis=1024)
        ```
    """
    dng_path = Path(dng_path).resolve()
    output_path = Path(output_path).resolve()

    if _APPLE_AVAILABLE:
        return apple_dng_to_jpeg(dng_path, output_path, quality, max_axis=max_axis)

    quality_int = max(1, min(100, int(quality * 100)))
    image = dng_to_pil(dng_path)
    return _save_pil_image(image, output_path, "JPEG", quality_int, max_axis=max_axis)

dng_to_heif(dng_path, output_path, quality=1.0, max_axis=None)

Convert a DNG file to HEIF with high-quality tone mapping.

Uses Apple Core Image on macOS for best quality, falls back to rawpy with AHD demosaicing elsewhere.

Parameters:

Name	Type	Description	Default
dng_path	str | Path	Path to the input DNG file.	required
output_path	str | Path	Path for the output HEIF file (.heic extension).	required
quality	float	Compression quality (0.0-1.0). Default is 1.0 for max quality.	1.0
max_axis	int	If provided, resize so the largest dimension equals this value.	None

Returns:

Type	Description
Path	Path to the created HEIF file.

Example

from capturegraph.adapters import dng_to_heif

dng_to_heif("photo.dng", "output.heic")
dng_to_heif("photo.dng", "output.heic", quality=0.9)

# Save a smaller version for analysis
dng_to_heif("photo.dng", "thumb.heic", max_axis=1024)

Source code in capturegraph-lib/capturegraph/adapters/dng_convert.py

def dng_to_heif(
    dng_path: str | Path,
    output_path: str | Path,
    quality: float = 1.0,
    max_axis: int = None,
) -> Path:
    """
    Convert a DNG file to HEIF with high-quality tone mapping.

    Uses Apple Core Image on macOS for best quality, falls back to rawpy
    with AHD demosaicing elsewhere.

    Args:
        dng_path: Path to the input DNG file.
        output_path: Path for the output HEIF file (.heic extension).
        quality: Compression quality (0.0-1.0). Default is 1.0 for max quality.
        max_axis: If provided, resize so the largest dimension equals this value.

    Returns:
        Path to the created HEIF file.

    Example:
        ```python
        from capturegraph.adapters import dng_to_heif

        dng_to_heif("photo.dng", "output.heic")
        dng_to_heif("photo.dng", "output.heic", quality=0.9)

        # Save a smaller version for analysis
        dng_to_heif("photo.dng", "thumb.heic", max_axis=1024)
        ```
    """
    dng_path = Path(dng_path).resolve()
    output_path = Path(output_path).resolve()

    if _APPLE_AVAILABLE:
        return apple_dng_to_heif(dng_path, output_path, quality, max_axis=max_axis)

    # Register HEIF opener for saving

    register_heif_opener()

    quality_int = max(1, min(100, int(quality * 100)))
    image = dng_to_pil(dng_path)
    return _save_pil_image(image, output_path, "HEIF", quality_int, max_axis=max_axis)

dng_to_png(dng_path, output_path, max_axis=None)

Convert a DNG file to PNG (lossless) with high-quality tone mapping.

Uses Apple Core Image on macOS for best quality, falls back to rawpy with AHD demosaicing elsewhere.

Parameters:

Name	Type	Description	Default
dng_path	str | Path	Path to the input DNG file.	required
output_path	str | Path	Path for the output PNG file.	required
max_axis	int	If provided, resize so the largest dimension equals this value.	None

Returns:

Type	Description
Path	Path to the created PNG file.

Example

from capturegraph.adapters import dng_to_png

dng_to_png("photo.dng", "output.png")

# Save a smaller version for analysis
dng_to_png("photo.dng", "thumb.png", max_axis=1024)

Source code in capturegraph-lib/capturegraph/adapters/dng_convert.py

def dng_to_png(
    dng_path: str | Path,
    output_path: str | Path,
    max_axis: int = None,
) -> Path:
    """
    Convert a DNG file to PNG (lossless) with high-quality tone mapping.

    Uses Apple Core Image on macOS for best quality, falls back to rawpy
    with AHD demosaicing elsewhere.

    Args:
        dng_path: Path to the input DNG file.
        output_path: Path for the output PNG file.
        max_axis: If provided, resize so the largest dimension equals this value.

    Returns:
        Path to the created PNG file.

    Example:
        ```python
        from capturegraph.adapters import dng_to_png

        dng_to_png("photo.dng", "output.png")

        # Save a smaller version for analysis
        dng_to_png("photo.dng", "thumb.png", max_axis=1024)
        ```
    """
    dng_path = Path(dng_path).resolve()
    output_path = Path(output_path).resolve()

    if _APPLE_AVAILABLE:
        return apple_dng_to_png(dng_path, output_path, max_axis=max_axis)

    image = dng_to_pil(dng_path)
    return _save_pil_image(image, output_path, "PNG", max_axis=max_axis)