1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
# pngtools
A suite of command-line utilities for inspecting and manipulating PNG
image files, modelled on libtiff's tifftools. pngtools is packaged by
several Linux distributions.
## Tools
- **pnginfo**: Display detailed metadata about PNG files (dimensions,
bit depth, colour type, interlacing, compression, text chunks, etc).
Supports tiffinfo-compatible output labels (`-t`) and bitmap
dumping (`-d`, `-D`).
- **pngchunks**: List the raw chunk structure of a PNG file by
directly parsing chunk headers. Shows chunk type, length, CRC,
IHDR fields, and the case-encoded properties of each chunk name.
- **pngchunkdesc**: Read PNG chunk names from stdin and decode the
meaning of each letter's case (critical/ancillary, public/private,
PNG 1.2 compliant, safe to copy).
- **pngcp**: Copy a PNG file while optionally changing the bit depth
(`-d`) and number of samples per pixel (`-s`).
## Building
Requires libpng-dev and optionally docbook-utils (for man pages):
```bash
aclocal && autoconf && automake --add-missing && autoreconf
./configure
make
make install
```
## Usage Examples
```bash
# Show PNG metadata
pnginfo image.png
# Show metadata with tiffinfo-compatible labels
pnginfo -t image.png
# Dump image bitmap as hex
pnginfo -d image.png
# List raw chunk structure
pngchunks image.png
# Decode chunk name properties
echo "tEXt" | pngchunkdesc
# Copy with changed bit depth
pngcp -d 16 input.png output.png
```
## Testing
The test suite uses Python testtools + stestr:
```bash
# One-time setup
python3 -m venv tests/.venv
tests/.venv/bin/pip install -r test-requirements.txt
# Generate additional test images
tests/.venv/bin/python tests/generate_test_images.py
# Run all tests
tests/.venv/bin/stestr run
# Run a specific test module
tests/.venv/bin/stestr run test_pnginfo
```
Or use the all-in-one script that handles building and testing
(including first-time setup):
```bash
scripts/build-and-test.sh
```
### Pre-commit Hooks
Pre-commit hooks enforce formatting (clang-format), static
analysis (cppcheck), and run the full build-and-test cycle:
```bash
pip install pre-commit
pre-commit install
```
You can also run the format checker directly:
```bash
scripts/check-format.sh # check only
scripts/check-format.sh fix # auto-format in place
```
## Releasing
1. Update the version in `configure.ac` (`AC_INIT(pngtools, [X.Y])`)
2. Commit and push to `master`
3. Go to **Actions > Release > Run workflow**
4. Enter the version string (must match `configure.ac`)
The workflow will:
- Verify the version matches `configure.ac`
- Build and run the full test suite
- Create a `make dist` tarball (includes test suite and test images)
- Create a Sigstore-signed git tag (`vX.Y`)
- Publish a GitHub Release with the tarball and changelog
- Attest the tarball provenance via Sigstore
Release artifacts can be verified with:
```bash
gh attestation verify pngtools-X.Y.tar.gz --owner mikalstill
```
## Documentation
- [ARCHITECTURE.md](ARCHITECTURE.md) -- code structure, data flow,
and known bugs
- [AGENTS.md](AGENTS.md) -- guidelines for AI agents working on
this codebase
- Man pages are built from DocBook SGML sources in the `man/`
directory
## License
GNU General Public License v2. See COPYING for details.
## Author
Michael Still (mikal@stillhq.com)
https://www.madebymikal.com/category/pngtools/
|
