0
# PyPNG
1

2
A pure Python library for reading and writing PNG images without external dependencies. PyPNG provides complete coverage of PNG formats supporting all allowable bit depths (1/2/4/8/16/24/32/48/64 bits per pixel) and color combinations including greyscale, RGB, RGBA, and LA (greyscale with alpha) formats.
3

4
## Package Information
5

6
- **Package Name**: pypng
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install pypng`
10

11
## Core Imports
12

13
```python
14
import png
15
```
16

17
## Basic Usage
18

19
```python
20
import png
21

22
# Create a simple PNG from array data
23
png.from_array([[255, 0, 0, 255],
24
                [0, 255, 255, 0]], 'L').save("small_smiley.png")
25

26
# Read a PNG file
27
reader = png.Reader(filename='image.png')
28
width, height, rows, info = reader.read()
29

30
# Write a PNG file using Writer
31
writer = png.Writer(width=256, height=256, greyscale=False)
32
with open('output.png', 'wb') as f:
33
    writer.write_array(f, pixel_data)
34
```
35

36
## Architecture
37

38
PyPNG follows a clean separation between reading and writing operations:
39

40
- **Reader**: Decodes PNG files into Python data structures with format conversion capabilities
41
- **Writer**: Encodes Python data into PNG files with full format control and metadata support  
42
- **Image**: Container object that bridges readers and writers with convenient save/write methods
43
- **Utility Functions**: High-level convenience functions for common operations
44

45
This design provides both high-level convenience methods and low-level control over PNG creation and parsing, making it suitable for simple image tasks and complex PNG manipulation workflows. PyPNG also includes a comprehensive suite of command-line tools for PNG manipulation and conversion tasks.
46

47
## Capabilities
48

49
### PNG Reading Operations
50

51
Comprehensive PNG decoding with format conversion, chunk access, and metadata extraction. Supports all PNG color types and bit depths with automatic format detection.
52

53
```python { .api }
54
class Reader:
55
    def __init__(self, _guess=None, filename=None, file=None, bytes=None): ...
56
    def read(self, lenient=False): ...
57
    def read_flat(self): ...
58
    def asRGB(self): ...
59
    def asRGBA(self): ...
60
    def asRGB8(self): ...
61
    def asRGBA8(self): ...
62
    def asDirect(self): ...
63
    def chunk(self, lenient=False): ...
64
    def chunks(self): ...
65
    def preamble(self, lenient=False): ...
66
    def palette(self, alpha='natural'): ...
67
```
68

69
[PNG Reading](./reading.md)
70

71
### PNG Writing Operations
72

73
Full PNG encoding with comprehensive format control, metadata support, and optimization options. Handles all PNG color types, bit depths, and optional chunks.
74

75
```python { .api }
76
class Writer:
77
    def __init__(self, width=None, height=None, size=None, greyscale=Default, 
78
                 alpha=False, bitdepth=8, palette=None, transparent=None, 
79
                 background=None, gamma=None, compression=None, interlace=False,
80
                 planes=None, colormap=None, maxval=None, chunk_limit=2**20,
81
                 x_pixels_per_unit=None, y_pixels_per_unit=None, unit_is_meter=False): ...
82
    def write(self, outfile, rows): ...
83
    def write_array(self, outfile, pixels): ...
84
    def write_packed(self, outfile, rows): ...
85
    def write_passes(self, outfile, rows): ...
86
```
87

88
[PNG Writing](./writing.md)
89

90
### Image Container Operations
91

92
Convenient image data container with automatic format handling and multiple output methods for easy PNG manipulation workflows.
93

94
```python { .api }
95
class Image:
96
    def save(self, file): ...
97
    def write(self, file): ...
98
    def stream(self): ...
99
```
100

101
[Image Container](./image-container.md)
102

103
### High-Level Convenience Functions
104

105
Simple functions for quick PNG creation and manipulation without requiring detailed format knowledge or class instantiation.
106

107
```python { .api }
108
def from_array(a, mode=None, info={}): ...
109
def write_chunks(out, chunks): ...
110
```
111

112
[Convenience Functions](./convenience.md)
113

114
### Command-Line Tools
115

116
Comprehensive suite of command-line utilities for PNG manipulation, format conversion, and image processing tasks. These tools can be used directly from the command line without programming.
117

118
```python { .api }
119
# Command-line utilities available after installation:
120
# prichunkpng - Add/remove PNG chunks and metadata
121
# pricolpng - Join PNG images vertically (column)  
122
# priditherpng - Apply dithering to PNG images
123
# priforgepng - Generate test patterns and synthetic images
124
# prigreypng - Convert PNG to greyscale
125
# pripalpng - Extract/manipulate PNG palettes
126
# pripamtopng - Convert NetPBM PAM/PNM files to PNG
127
# priplan9topng - Convert Plan 9 image format to PNG
128
# pripnglsch - PNG file analysis and validation
129
# pripngtopam - Convert PNG to NetPBM PAM/PNM files
130
# prirowpng - Join PNG images horizontally (row)
131
# priweavepng - Advanced PNG channel manipulation and weaving
132
```
133

134
## Exception Types
135

136
```python { .api }
137
class Error(Exception): ...
138
class FormatError(Error): ...
139
class ProtocolError(Error): ...
140
class ChunkError(FormatError): ...
141
```
142

143
## Core Types
144

145
```python { .api }
146
import collections
147

148
Resolution = collections.namedtuple('_Resolution', 'x y unit_is_meter')
149

150
class Default:
151
    """Sentinel class for default greyscale parameter"""
152
```
153

154
## Module Constants
155

156
```python { .api }
157
__version__: str = "0.20220715.0"
158
signature: bytes  # PNG file signature
159
adam7: tuple      # Adam7 interlacing pattern coordinates
160
fromarray = from_array  # Alternative name for from_array
161
```