Read Me

================================================================================
PNG-TO-JPEG Conversion Utility                                   version 1.0.2.2
================================================================================

1. Building
2. Usage
3. Advanced JPEG options
4. Miscellaneous Notes
5. Contact Details

--------------------------------------------------------------------------------
1. Building
--------------------------------------------------------------------------------

This program can be built with a C99 standard-compliant C compiler.
However, it depends on a few development libraries being installed:

    LIBRARY NAME                OFFICIAL DOWNLOAD LINK
    ----------------------------------------------------------------------------
    libjpeg                     http://ijg.org/files/
    libpng                      http://libpng.org/pub/png/libpng.html
    zlib                        http://zlib.net/
    ----------------------------------------------------------------------------

In Linux distributions, the above development packages are usually available
under the following names:

    LIBRARY NAME        DEB DISTRO              RPM DISTRO
    ----------------------------------------------------------------------------
    libjpeg             libjpeg-dev             N/A (libjpeg-turbo-devel)
    libpng              libpng-dev              libpng-devel
    zlib                zlib1g-dev              zlib-devel
    ----------------------------------------------------------------------------

If you have GNU Make and GCC installed then the `GNUmakefile` can be used,
for example:

    $ cd png2jpeg-VERSION/
    $ MODENV="-m64" CC="gcc" make

--------------------------------------------------------------------------------
2. Usage
--------------------------------------------------------------------------------

The syntax is:

    png2jpeg [OPTIONS] input_file

The following options are supported:

    LONG NAME       SHORT   ARGUMENT        MEANING
    ----------------------------------------------------------------------------
    --help          -h      (none)          print help information
    --help2         -H      (none)          print help for advanced JPEG
    --version       -V      (none)          print version information
    --verbose       -v      (none)          print debug information
    --grayscale     -g      (none)          create monochrome JPEG
    --progressive   -p      (none)          create progressive JPEG
    --quality       -q      0 to 100        set quality
    --sample        -s      HxV             set component sampling factors
    --background    -b      R,G,B           set background color
    --infile        -i      filename        provide input filename
    --outfile       -o      filename        override output filename
    ----------------------------------------------------------------------------

Examples:

    png2jpeg input.png
    ----------------------------------------------------------------------------
    Creates a JPEG file named "input.png.jpg" with the default settings:
        * grayscale             NO
        * progressive           NO
        * quality               75
        * outfile               input.png.jpg
        * sample                2x2
        * background            0,0,0

    png2jpeg -p --quality 95 --sample 1x1 -o converted.jpeg original.png
    ----------------------------------------------------------------------------
    Creates a JPEG file named "converted.jpeg" with the user settings:
        * grayscale             NO
        * progressive           YES
        * quality               95
        * outfile               converted.jpeg
        * sample                1x1
        * background            0,0,0

    png2jpeg -q 50 --background 128,255,0 icon.png
    ----------------------------------------------------------------------------
    Creates a JPEG file named "icon.png.jpg" with the user settings:
        * grayscale             NO
        * progressive           NO
        * quality               50
        * outfile               icon.png.jpg
        * sample                2x2
        * background            128,255,0

--------------------------------------------------------------------------------
3. Advanced JPEG options
--------------------------------------------------------------------------------

WARNING: Using these options may generate a backwards-incompatible JPEG file
         that cannot be loaded by legacy applications or image libraries!

    LONG NAME       SHORT   ARGUMENT        MEANING
    ----------------------------------------------------------------------------
    --arith         -a      (none)          use arithmetic coding
    --smooth        -S      0 to 100        set smoothing factor
    ----------------------------------------------------------------------------

The option "--arith" enables the use of Arithmetic Coding instead of the usual
Huffman Coding. While Arithmetic Coding offers better compression ratios, its
widespread adoption was hindered by patents. Huffman Coding is used by default
for the sake of compatibility.

The option "--smooth" enables the blurring of the input image, which results
in a smaller JPEG output file. Smoothing is disabled by default (set to 0).

--------------------------------------------------------------------------------
4. Miscellaneous Notes
--------------------------------------------------------------------------------

Long names and shorthands have equal priority.
If an option is given multiple times, only the last occurrence is used.
Invalid options are shown in errors, and invalid arguments are silently
corrected if possible.

Input file options "--infile" and "-i" have priority over free filenames.
If multiple free filenames are provided, only the first one is used.

The background color option is useful when converting PNG files that employ
transparency. It sets the background color to a given RGB code composed of
values from 0 to 255 for Red, Green and Blue. For grayscale images a shade of
gray is calculated as ((R + G + B) / 3) and used instead.

The program always optimizes the Huffman table.
No "--optimize" option is available, unlike in the official `cjpeg` program.

To disable chroma subsampling (downsampling), set the sampling factors
to one-by-one with the "--sample 1x1" option. By doing this, the image
quality is improved at the cost of greater file size.

The maximum practical quality is 95. Using a value greater than this will
result in a much larger JPEG file with almost no quality improvement.

The maximum possible quality of 100 is not recommended for normal use and
is regarded as a mathematical limit rather than a sensible setting. In
particular, it does not make the JPEG conversion lossless.

--------------------------------------------------------------------------------
5. Contact Details
--------------------------------------------------------------------------------

    Project:    https://sourceforge.net/projects/png2jpeg/
    Email:      ab396356@users.sourceforge.net