HEIC2PNG

This is a tool for converting the format of HEIC images to PNG using Python. It now supports quality adjustment and has an option to overwrite existing files, enhancing the flexibility and usability of the tool.

Features

• HEIC to PNG conversion, also to JPEG with --format jpg
• Quality control (1-100) for smaller files — see About quality for what it does to colors
• Pure Python implementation using PIL (Pillow) built-in optimization
• Cross-platform compatibility - works on all platforms

About quality

The command line uses quality 80 by default. For PNG output, any quality below 100 turns the image into a palette image with at most 256 colors (quality × 2.56), which makes the file much smaller but loses color detail: a typical phone photo with ~150,000 distinct colors ends up with about 200.

• To keep every color, use --quality 100 (or -q 100).
• In Python, HEIC2PNG(path) keeps every color by default; pass quality= to reduce it.
• For JPEG output, quality is the normal JPEG quality setting.

Installation

pip install heic2png

Visit HEIC2PNG on PyPI for more details.

Quick Start

Regular File Processing (with processing info)

# Convert with default settings
heic2png -i image.heic
# Output: Converting image...
#         Successfully saved converted image to: image.png

# Convert with quality optimization
heic2png -i image.heic --quality 50 -o optimized.png

Stream Processing (silent, for pipelines)

# Silent conversion for shell pipelines
cat image.heic | heic2png > output.png

# With quality optimization
cat image.heic | heic2png --quality 50 > optimized.png

Usage

As a Library

You can use HEIC2PNG in your Python code as shown below:

from heic2png import HEIC2PNG

if __name__ == '__main__':
    heic_img = HEIC2PNG('test.heic', quality=90)  # Specify the quality of the converted image
    heic_img.save()  # The converted image will be saved as `test.png`
    heic_img.save('other.jpg', extension='.jpg')  # Or choose the path and format yourself

HEIC2PNG() without a path reads from stdin, and save() then writes to stdout.

Command Line Interface

HEIC2PNG also provides a CLI for easy conversion of HEIC images to PNG. Here are some examples:

Convert a HEIC image to PNG with a specified output path:

heic2png -i test.heic -o test.png -q 90  # -q is short for --quality

Use --quiet to hide progress messages (it has no short form).

If you want to keep the original name, use the command below. It will generate test.png for you:

heic2png -i test.heic -q 90

To overwrite an existing PNG file, use the -w flag:

heic2png -i test.heic -o test.png -q 90 -w

Usage Examples

Regular File Processing

Basic Conversion

# Convert with default settings (shows processing info)
heic2png -i image.heic
# Output: Converting image...
#         Successfully saved converted image to: image.png

# Convert with explicit output file
heic2png -i image.heic -o output.png

# Convert with quality optimization
heic2png -i image.heic --quality 50 -o optimized.png

Verbose Mode

# Show detailed conversion settings
heic2png -i image.heic --verbose
# Output:
# Converting image...
# Conversion settings:
# Input: image.heic
# Output: image.png
# Quality: 80
# Format: png
# Overwrite: False
# Successfully saved converted image to: image.png

Quality Control

# Keep every color (no palette reduction)
heic2png -i image.heic --quality 100 -o full_color.png

# High quality palette (up to 243 colors)
heic2png -i image.heic --quality 95 -o high_quality.png

# Low quality (smaller file)
heic2png -i image.heic --quality 30 -o compressed.png

# Default quality (80, up to 204 colors)
heic2png -i image.heic -o default.png

Format Conversion

# Convert to JPEG (transparent areas become white, since JPEG has no transparency)
heic2png -i image.heic --format jpg -o output.jpg

# Convert to PNG (default)
heic2png -i image.heic -o output.png

Batch Processing

# Process multiple files
for file in *.heic; do
    heic2png -i "$file" --quality 60 --overwrite
done

# Process with different quality settings
heic2png -i photo1.heic --quality 90 -o photo1_hq.png
heic2png -i photo2.heic --quality 50 -o photo2_compressed.png

Stream Processing (stdin/stdout)

HEIC2PNG supports reading from stdin and writing to stdout, making it perfect for shell pipelines and automated processing:

Basic Stream Processing

# Read from stdin, write to stdout (no processing messages)
cat image.heic | heic2png > output.png

# Read from stdin, write to file (no processing messages)
cat image.heic | heic2png -o output.png

# Note: 'heic2png -i image.heic > output.png' now shows processing info
# Use 'cat image.heic | heic2png > output.png' for silent stream processing

Quality Optimization in Streams

# Low quality (smaller file size)
cat image.heic | heic2png --quality 30 > optimized.png

# High quality (larger file size)
cat image.heic | heic2png --quality 90 > high_quality.png

Format Conversion in Streams

# Convert to JPEG
cat image.heic | heic2png --format jpg > output.jpg

# Convert to PNG (default)
cat image.heic | heic2png > output.png

Advanced Pipeline Examples

# Batch processing with quality optimization
for file in *.heic; do
    cat "$file" | heic2png --quality 50 > "${file%.heic}_optimized.png"
done

# Process and compress in one pipeline
cat image.heic | heic2png --quality 40 | gzip > compressed.png.gz

# Convert and resize (requires additional tools)
cat image.heic | heic2png | convert - -resize 50% resized.png

Stream Processing Notes

• Input: If no -i parameter is specified, input is read from stdin
• Output: If no -o parameter is specified, output is written to stdout
• Messages: Stream mode (no -i parameter) produces no processing messages
• Quality: Works with all quality settings (1-100)
• Formats: Supports PNG, JPG, and JPEG output formats
• Transparency: Preserved in PNG output; JPEG output puts transparent areas on white
• Behavior: heic2png -i file.heic > output.png shows processing info (regular mode)
• Behavior: cat file.heic | heic2png > output.png is silent (stream mode)

Development

pip install -e ".[test]"   # the package plus pytest and numpy (used only by the tests)
pytest tests
tox -e py                   # what CI runs: check-manifest + tests

References

• Example PyPi Package
• Pillow HEIF
• PIL Image.quantize()