README for imgdataopt: raster (bitmap) image data size optimizer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
imgdataopt is a command-line tool that converts PNG and PNM raster (bitmap)
image formats to each other, doing some lossless size optimizations such as
converting RGB to grayscale or indexed (palette), converting high bit depth
to low, saving the PNG file with a high flate compression level. imgdataopt
is written in ANSI C (C89). For much slower alternatives which produce
smaller PNG files, see PNGOUT, zopflipng, optipng, ECT, advpng.

How to use:

* Compile it using `make', or use one of the released binary executables on
  http://github.com/pts/imgdataopt/releases .

* Run the conversion in the command-line (terminal window) as:

    ./imgdataopt input.img output.img

  The input file format is autodetected.

  The output file format is derived from the filename extension of output.img.

  The output filename can be the same as the input filename.

  You can pass command-line flags in front of input.img, for example, do
  this to get grayscale output:

    ./imgdataopt -s:grays input.img output.img

* There is no GUI.

Features and comparison
~~~~~~~~~~~~~~~~~~~~~~~
* imgdataopt is a command-line tool, there is no GUI.

* imgdataopt is relatively fast. It's much faster than the PNG optimizers
  PNGOUT, zopflipng, optipng, ECT, advpng. As a tradeoff, imgdataopt produces
  a bit larger PNG output than those.

* imgdataopt does only lossless processing: it keeps all the colors intact,
  and it retains the original width and height.

* imgdataopt is idempontent: running it again on the output, with the same
  flags produces an output image file identical to the first output.

* imgdataopt is small: it's less than 2500 lines of C code in a single file
  (excluding zlib). Similar image conversion tools such as sam2p and
  ImageMagick have much larger codebases, and some are implemented in C++
  (thus they may be more complicated to understand and they may have more
  library dependencies).

* imgdataopt is portable: it is written in ANSI C, and it's ported
  officially to Linux (i386 and amd64 etc.), macOS 10.5 or later, and Windows
  (Win32, Windows 95 or later).

* imgdataopt compiles and works with a wide variety of programming language
  versions and compilers:

  * C89: gcc -ansi
  * C99: gcc -std=c99
  * C11: gcc -std=c11
  * C++98: g++ -ansi
  * C++11: g++ -std=c++0x
  * C++17: g++ -std=c++1y
  * gcc -m32 (i386) and gcc -m64 (amd64)
  * gcc-4.1 ... gcc-4.4 ... gcc-4.8 ...
  * g++-4.1 ... g++-4.4 ... g++-4.8 ...
  * i686-w64-mingw32-gcc (gcc 4.8.2)
  * clang-3.0 ... clang-3.5 ...
  * clang++-3.0 ... clang++-3.5 ...
  * o32-clang and o64-clang on macOS
  * tcc 0.9.25 ... 0.9.26 ...

* imgdataopt is self-contained: it doesn't have any external dependencies
  other than libc (the C standard library) and zlib (-lz). There is a
  also a copy of zlib bundled with imgdataopt in zlib_src. Other tools such
  as ImageMagick have dozens of dependencies, with libpng (-lpng) as a
  minimum. sam2p also has the dependency on png22pnm (or pngtopnm).

* imgdataopt doesn't support all features of image file formats when
  reading, e.g. it is not able to read interlaced PNG, it ignores PNG gamma
  correction and transparency, and it is not able to read ASCII PNM.

* imgdataopt doesn't support transperency or alpha channel (e.g. RGBA): it
  can read and write only images without an alpha channel, and all pixels
  are assumed to have an implicit alpha value of 255 (fully opaque). sam2p
  supports images with transparency, i.e. the pixel alpha values of 0 (fully
  transparent) and 255 (fully opaque), but no arbitrary alpha values.

* imgdataopt has some tests (see the png_test directory) for various bit
  depths and predictors.

* imgdataopt uses a reasonable amout of memory: it uses about 300 000 + 3 *
  width * (height + 6) bytes of memory (including to the code size). That
  is, it can keep an uncompressed RGB8 version of the image in memory. 300
  kB is needed for the code, the ZIP compression window (of 32 kB) and
  other buffers. (In fact, it uses even less memory: the multiplier 3 will
  be only 1 if the input image has the colorspace Gray or Indexed.)

* imgdataopt can read PNG files generated by pdfsizeopt.

* imgdataopt can convert RGB images to grayscale and indexed (palette) etc.,
  and does it by default.

* imgdataopt can convert an 8-bits-per-sample image to 4, 2 and 1, and does
  it by default, picking the smallest value.

* imgdataopt can write PNG files with smart predictor selection for each
  row. To get this, use `imgdataopt -c:zip:15'.

* imgdataopt can write PNG files with the None predictor in each row
  (like sam2p without the -c:zip:15 flag).

* imgdataopt can write PNG-like files without a per-row predictor specified.
  This is compatible with PDF /Filter /FlateDecode without any /Predictor.
  To get this non-conforming PNG output, use `imgdataopt -j:ext
  -c:zip:none'.

* imgdataopt works successfully even if the input image data is truncated,
  has the wrong checksum, or is too long. In this case it will succeed and
  use color 0 for the rest of the image.

* imgdataopt can write PNG-like files with RGB and bit depth smaller than 8.
  To get this, use `igmdataopt -j:ext'.

Motivation
~~~~~~~~~~
imgdataopt was designed as a fast backend tool for image size optimization
in pdfsizeopt, as a replacement of sam2p. pdfsizeopt will find images
embedded in the PDF, create a PNG file for each, call image optimizers such
as imgdataopt, and replace the PDF image object data with the output of the
optimizers.

The reasons why a replacement of sam2p was designed:

* In pts/pdfsizeopt#51, it's hard to implement
  recovery from truncated, too long or bad-checksum image data with sam2p.

* In pts/pdfsizeopt#52, it's hard to make sam2p
  find the right tool (png22pnm or pdftopnm) to parse PNG files. One way
  to solve is making sam2p able to read PNG files directly. The other way
  is writing a brand new tool (i.e. imgdataopt) which can do it.

* sam2p has too many features not needed by pdfsizeopt.

* sam2p is implemented in C++, and it has a bit brittle build system. A
  small and simple tool written in C such as imgdataopt is much more
  future-compatible.

See also pts/pdfsizeopt#51 for more comments on
the motivation and initial design of imgdataopt.

Copyright
~~~~~~~~~
imgdataopt is written and owned by Péter Szabó <[email protected]> (except for
the zlib_src directory).

imgdataopt may be used, modified and redistributed only under the terms of the
GNU General Public License, version 2 or newer, found at

  http://www.fsf.org/licenses/gpl.html

__END__