Convert any file into a PNG and back!
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
Gillian B. 962e560bd0 fix: updated url in README 2 months ago
img Initial commit 3 months ago
man fix: added DESTDIR to makefile, checking fread() return value 2 months ago
src fix: added DESTDIR to makefile, checking fread() return value 2 months ago
Examples.md Initial commit 3 months ago
FAQ.md Initial commit 3 months ago
INSTALL.md Initial commit 3 months ago
LICENSE Initial commit 3 months ago
Makefile fix: added DESTDIR to makefile, checking fread() return value 2 months ago
README.md fix: updated url in README 2 months ago

README.md

octaPNG

Convert any file into a PNG and back!

Description

octaPNG is a tool for encoding any file into a regular PNG image by simply writing the file's binary data as colored pixels, and decoding by reversing this process. I refer to PNG images created by this tool as "oPNGs".

The codebase is written in portable ANSI C (C89) and depends on the libraries libpng and zlib. Currently there's only a command line version of octaPNG, however a graphical (GUI) version is planned.

Read the FAQ.

Example

Here's The Legend of Sleepy Hollow by Washington Irving encoded into an oPNG:

See more examples on this page.

How It Works

octaPNG operates in two modes; encoding and decoding. Encoding involves writing an input file into an oPNG, and decoding involves reading the oPNG to recreate the original input file. The whole process is lossless, an oPNG always stores a byte-for-byte identical copy of whatever data you encode into it.

During the encoding process, octaPNG creates a blank PNG image and writes into it a few pixels that constitute the oPNG "header", these "header pixels" contain information about the input file so it may be decoded correctly later. The pixels are divided as follows:

_______________________________________
| Pixel | Byte* | Description          |
|¯¯¯¯¯¯¯|¯¯¯¯¯¯¯|¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|
| 0     | 0     | oPNG version.        |
|       |_______|______________________|
|       | 1     |                      |
|_______| 2     | Binary data size in  |
|       | 3     | bytes, big endian    |
| 1     | 4     | order.               |
|       |_______|______________________|
|_______| 5     |                      |
|       | 6     | CRC32 sum of the     |
| 2     | 7     | binary data, big     |
|       | 8     | endian order.        |
________|_______|______________________|

* Assuming 1 byte = 8 bits (1 octet)

After the "header pixels" are written, octaPNG writes the input file itself. The file is read as a stream of bytes where every 3 bytes of data are treated as an RGB color triplet and written to the image as a pixel, until the entire file is written. If there are still "empty" pixels remaining in the image they get filled with dummy data as padding.

Decoding is the reverse of the encoding process; the oPNG "header pixels" are read first, then the data pixels are read as bytes and written into a new file, while padding pixels are skipped... To ensure the original input file has been recreated correctly, a CRC32 checksum is calculated for the newly-decoded file and compared against the checksum stored in the oPNG "header". If both checksums match then the decoded file is indeed identical to the original input file, if not then the file may have been corrupted.

Both encode and decode operations are zero-copy, meaning data is progressively read from / written to disk and not kept in memory. Only a PNG row buffer is kept.

Getting Started

Pre-built binaries for Windows and Linux are available on the releases page for users to download. The binaries are self-contained and require no installation, simply download and run.

To compile from source see the INSTALL.md file.

Usage

To encode a file, open a command prompt or terminal window and run:

octapng -e file.zip

To decode an oPNG run:

octapng -d file.zip.png

Guidelines

To prevent oPNG corruption please take note of the following guidelines.

You should not...

  • Distort (e.g. crop, stretch, scale) an oPNG
  • Add your own graphics on, above, or to the left/right of an oPNG
  • Convert an oPNG from the PNG format to a lossy image format such as JPEG or GIF
  • Change the bit depth of an oPNG
  • Add transparency to an oPNG
  • Make an oPNG interlaced

You may...

  • Extend the canvas size of an oPNG from the bottom to add your own graphics (e.g. icons or logos) if you like, provided you do not overlap the oPNG's original pixels.

    Some examples of acceptable graphics placement:

Roadmap

[*] Encoding binary data into a PNG image
[*] Decoding binary data from a PNG image
[*] Verifying binary data integrity using CRC32
[ ] Creating GUI version
[ ] Supporting interlaced PNG images

License

octaPNG is licensed under the zlib License.

Licenses for the used libraries: libpng, zlib, parg