commit 372aec2290b9215335a7fbc3c3f42da629b0aa5f
parent aee24c55d0415a0bf86411ad1178cad97993d452
Author: FRIGN <dev@frign.de>
Date: Tue, 10 Nov 2015 17:52:41 +0100
Update farbfeld-documentation
Diffstat:
| A | FORMAT | | | 14 | ++++++++++++++ |
| A | README | | | 67 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| D | SPECIFICATION | | | 56 | -------------------------------------------------------- |
3 files changed, 81 insertions(+), 56 deletions(-)
diff --git a/FORMAT b/FORMAT
@@ -0,0 +1,14 @@
+
+ FARBFELD IMAGE FORMAT SPECIFICATION
+
+ +--------+-----------------------------------------------------------+
+ | Bytes | Description |
+ +--------+-----------------------------------------------------------+
+ | 8 | "farbfeld" magic value |
+ +--------+-----------------------------------------------------------+
+ | 4 | 32-Bit BE unsigned integer (width) |
+ +--------+-----------------------------------------------------------+
+ | 4 | 32-Bit BE unsigned integer (height) |
+ +--------+-----------------------------------------------------------+
+ | [2222] | 4*16-Bit BE unsigned integers [RGBA] / pixel, row-aligned |
+ +--------+-----------------------------------------------------------+
diff --git a/README b/README
@@ -0,0 +1,67 @@
+
+ ███ ███ ██ ██ ███ ███ █ ██
+ █ █ █ █ █ █ █ █ █ █ █ █
+ ██ ███ ███ ███ ██ ██ █ █ █
+ █ █ █ █ █ █ █ █ █ █ █ █
+ █ █ █ █ █ ██ █ ███ ███ ██
+
+
+WHAT IS FARBFELD?
+ Farbfeld is a lossless image-format designed to be
+ parsed and piped easily.
+ It can be compressed easily and beats PNG's filesize
+ in many cases.
+
+WHY FARBFELD?
+ Current image-formats have integrated compression,
+ making it complicated to read the image data.
+ One is forced to use complex libraries like libpng,
+ libjpeg, libjpeg-turbo, giflib and others, read the
+ documentation and write a lot of boilerplate in order
+ to get started.
+ Farbfeld leaves this behind and is designed to be as
+ simple as possible, leaving the task of compression
+ to outside tools.
+ The simple design, which was the primary objective,
+ implicitly lead to the very good compression
+ characteristics, as it often happens when you go with
+ the UNIX philosophy.
+ Reading farbfeld images doesn't require any special
+ libraries. The tools in this folder are just a toolbox
+ to make it easy to convert between common image formats
+ and farbfeld.
+
+HOW DOES IT WORK?
+ In Farbfeld, pattern resolution is not done while
+ converting, but while compressing the image.
+ For example, farbfeld always stores the alpha-channel,
+ even if the image doesn't have alpha-variation.
+ This may sound like a big waste at first, but as
+ soon as you compress an image of this kind, the
+ compression-algorithm (e.g. bz2) recognizes the
+ pattern that every 48 bits the 16 bits store the
+ same information.
+ And the compression-algorithms get better and better
+ at this.
+ Same applies to the idea of having 16 bits per channel.
+ It sounds excessive, but if you for instance only have
+ a greyscale image, the R, G and B channels will store
+ the same value, which is recognized by the compression
+ algorithm easily.
+ This effectively leads to filesizes you'd normally only
+ reach with paletted images, and in some cases bz2 even
+ beats png's compression, for instance when you're dealing
+ with grayscale data, line drawings, decals and even
+ photographs.
+
+HOW DO I USE THE TOOLS?
+ encoding:
+ png2ff < example.png > example.ff
+ png2ff < example.png | bzip2 > example.ff.bz2
+
+ decoding:
+ ff2png < example.ff > example.png
+ bzcat example.ff.bz2 | ff2png > example.png
+
+ bz2 is recommended for compression, but you can use
+ any algorithm you want.
diff --git a/SPECIFICATION b/SPECIFICATION
@@ -1,56 +0,0 @@
-The farbfeld-format is meant to be parsed easily
-and used to pipe images losslessly.
-
-# WHY FARBFELD?
-
-Most current image-formats have their compression
-incorporated in their format itself.
-This has some advantages, but reaches its limits
-with lossless formats (e.g. PNG).
-The basic idea of the farbfeld-format is to separate
-these to and having a completely transparent image-format.
-
-Pattern resolution is done while compressing, not while
-converting the image.
-For example, farbfeld always stores an alpha-channel,
-even if the image doesn't have alpha-variation.
-This may sound like a big waste, but as soon as you
-compress an image of this kind, the bzip2-algorithm
-takes care of the easy pattern, that each 4th character
-has the same value.
-This leads to almost no overhead while keeping parsing
-really simple.
-Same applies to the idea of having 64 bits per channel.
-It sounds excessive, but if you only have 8 bits of
-entropy, the compression will take care of it, while
-you only need to do the endian-handling for 64 bit
-chunks.
-
-# FORMAT:
-
-Bytes Description
-8 farbfeld
-4 32 bit BE Unsigned Integer (width)
-4 32 bit BE Unsigned Integer (height)
-[2222] RGBA-row-aligned-pixel-array
- 16 bit BE Unsigned Integers (per channel)
-
-# EXAMPLES:
-
-encoding:
-png2ff < example.png > example.ff
-png2ff < example.png | bzip2 > example.ff.bz2
-
-decoding:
-ff2png < example.ff > example.png
-bzcat example.ff.bz2 | ff2png > example.png
-
-# WHY BZ2?
-
-Using BZ2, you can get smaller filesizes than with PNG,
-especially with line-drawings.
-For normal pictures, the bz2-compression yields roughly
-the same sizes as png does.
-Always keep in mind that using PNG involves having to
-rely on libpng to decode the image for you, whereas
-farbfeld is a completely transparent format.
