Metadata-Version: 2.4
Name: HEIC2PNG
Version: 1.2.1
Summary: Convert format of HEIC image to PNG by using Python.
Home-page: https://github.com/NatLee/heic2png
Author: Nat Lee
Author-email: natlee.work@gmail.com
Project-URL: Documentation, https://github.com/NatLee/heic2png
Project-URL: Bug Reports, https://github.com/NatLee/heic2png/issues
Project-URL: Source Code, https://github.com/NatLee/heic2png
Keywords: HEIC,PNG,converter,image
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow
Requires-Dist: pillow-heif
Provides-Extra: dev
Requires-Dist: check-manifest; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: numpy; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

﻿# HEIC2PNG

[![Test](https://github.com/NatLee/heic2png/actions/workflows/test.yml/badge.svg)](https://github.com/NatLee/heic2png/actions/workflows/test.yml)
[![Release](https://github.com/NatLee/heic2png/actions/workflows/release.yml/badge.svg)](https://github.com/NatLee/heic2png/actions/workflows/release.yml)

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](#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

```bash
pip install heic2png
```

Visit [HEIC2PNG on PyPI](https://pypi.org/project/HEIC2PNG/) for more details.

## Quick Start

### Regular File Processing (with processing info)
```bash
# 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)
```bash
# 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:

```python
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:

```bash
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:

```bash
heic2png -i test.heic -q 90
```

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

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

## Usage Examples

### Regular File Processing

#### Basic Conversion
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Convert to JPEG
cat image.heic | heic2png --format jpg > output.jpg

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

#### Advanced Pipeline Examples
```bash
# 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

```bash
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](https://github.com/tomchen/example_pypi_package)
- [Pillow HEIF](https://github.com/bigcat88/pillow_heif)
- [PIL Image.quantize()](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.quantize)
