Ubuntu Manpage: EPSILON - powerful Open Source wavelet image compressor

Provided by: epsilon-bin_0.9.2+dfsg-5_amd64

NAME

       EPSILON - powerful Open Source wavelet image compressor

SYNOPSIS

       epsilon COMMAND [OPTIONS] FILES...

DESCRIPTION

EPSILON is a powerful Open Source wavelet image compressor. The project is aimed on
parallel and robust image processing. EPSILON source package consists of two core parts:
portable, well-designed, thread-safe library and codec, build on the top of the library.
The library API is very clean, simple and carefully documented.

EPSILON's compression algorithm is based on wavelet transform and so called embedded
coding. The former is a well-known mathematical theory and the latter is a very effective,
yet simple method of progressive image coding. The actual algorithm employed in EPSILON is
called SPECK - Set Partitioned Embedded bloCK coder introduced by Asad Islam and William
Pearlman.

At the moment, EPSILON supports more than 30 wavelet filters and have automated interface
for adding new ones. The script called make_filterbank.pl translates XML-files with filter
descriptions to the C source code suitable for EPSILON. So, the only manual operation is
to copy-and-paste program's output into the EPSILON's source code. After recompilation
new filters will be ready to use. Special note: if you succeed in adding new filters,
please send them to me. They will be included into the main source tree.

EPSILON project follows an old and fruitful UNIX tradition to Keep It Simple. For example,
EPSILON works with PPM (Portable PixelMap) and PGM (Portable GrayMap) images only. They
provide basic functionality and serve as a least-common-denominator for interchanging
truecolor and grayscale images between different platforms and operating systems. Looking
for a converter? Try Netpbm (http://netpbm.sourceforge.net/) - perfect Open Source tool-
kit with more than 220 handy utilities!

For storing and interchanging compressed images EPSILON defines it's own PSI (ePSIlon)
file format. The PSI format is designed with simplicity and fault-tolerance in mind. A
typical PSI file consists of several independent blocks. Each block represents a tile from
the original image and have completely self-contained header. Each block is protected with
CRC and (actually with two CRCs: one for the header and another for the data) separated
from other blocks with a special unique marker. This simple yet effective technique makes
stream synchronization and error localization almost trivial. Moreover, block headers are
saved as a plain text: you can edit them by-hand with your favorite text editor. Check it
out!

EPSILON have a lot of interesting features. For example, you can finely control
compression ratio (thank`s to embedded coding), manually distribute bit-budget among image
channels, switch to different encoding and filtering modes and so on. EPSILON also
supports HUGE files with constant memory and linear time complexity.

Another nice feature is multi-threading support. Try to (re)compile EPSILON with Pthreads
enabled (see INSTALL for more info) and you will surely notice significant coding speed-up
(assuming you have multicore CPU or several CPUs on you computer).

As of release 0.6.1 EPSILON also supports clustering mode. This is a very powerful feature
if you have several machines linked with a high-capacity network, say gigabit ethernet or
even faster. To build cluster-aware EPSILON version please read INSTALL file.

Although EPSILON have a rich set of special ad-hoc options you are not obliged to use
them. Defaults are usually just fine. EPSILON's command line interface is very friendly
and designed to be similar to GZIP or BZIP. So, `epsilon foo.ppm' and `epsilon -d
bar.psi' is usually enough.

OPTIONS

Commands:
-e, --encode-file
Encode specified file(s). This is a default action if no command is given.

-d, --decode-file
Decode specified file(s).

-t, --truncate-file
Truncate specified file(s). Due to embedded coding, block truncation is equivalent
to block re-compression. In other words, truncation further compresses PSI-files.

-s, --start-node
Start cluster node. Note: this option is available in cluster-aware EPSILON version
only and is intended for SLAVE nodes. In other words, you should invoke epsilon -s
on each SLAVE node in your cluster. Stopping cluster node is even simpler: killall
epsilon.

This command runs a daemon program that accepts TCP connections at certain port
(2718 by default). For each connection a new child process is forked and the main
program waits for a next connecton. Encoding and decoding statistics is SYSLOG-ed
using LOG_DAEMON facility.

If you have DSH (Distributed SHell) installed on MASTER node, you can also use two
handy scripts, namely start_epsilon_nodes.pl and stop_epsilon_nodes.pl, for
starting and stopping all cluster nodes respectively.

Host configuration is taken from so called .epsilon.nodes file. By default,
program checks .epsilon.nodes in the current directory. If there is no such file,
program tries .epsilon.nodes in user`s home directory. You can also explicitly
specify file location as an argument to the script. File format is described below.

-a, --list-all-fb
List all available filterbanks. This command shows ID, NAME and orthogonality TYPE
for each available filterbank. As of release 0.8.1 EPSILON also supports lifting
implementation of a famous Daubechies 9/7 biorthogonal wavelet transform. It works
faster than generic filter-based counterpart. Default ID is daub97lift

-V, --version
Print program version.

Options to use with `--encode-file' command:
-f, --filter-id=ID
Wavelet filterbank ID. See also --list-all-fb command.

-b, --block-size=VALUE
Block size to use: 32, 64, 128, 256, 512 or 1024. The default value is 256. Using
very small blocks as well as using very large blocks is not recommended: the former
adds substantial header overhead and the latter slows down encoding/decoding
without any profit in image quality. Nevertheless, in some rare circumstances this
rule is quite opposite.

-n, --mode-normal
Use so called normal processing mode. This mode can be used with the both
orthogonal and biorthogonal filters. In practice you should avoid this parameter
unless you are making some research in wavelets.

-o, --mode-otlpf
Use so called OTLPF processing mode. In a few words, OTLPF is some kind of hack to
reduce boundary artefacts when image is broken into several tiles (as usually
happens). Due to mathematical constrains this method can be applied to biorthogonal
filters only. This option is turned on by default.

-r, --ratio=VALUE
With this parameter you can finely control desired compression ratio. This value is
not obliged to be integral: for example, the value of 34.102 is just fine. For
obvious reasons compression ratio should be grater than 1. Although EPSILON's bit-
allocation algorithm is pretty precise, too high compression ratios will be clipped
due to block headers overhead. On the other hand, blank image (e.g. entirely black)
surely will be encoded just in a couple of hundreds of bytes regardless of
compression ratio you desire. Nevertheless, for a most real-life images and
compression ratios (let us say 10..200) actual compression ratio will be very close
to the value you desire. Default compression ratio is 10.

-2, --two-pass
By default EPSILON uses constant bit-rate (CBR) bit-allocation algorithm. CBR is
pretty fast and usually gives acceptable image quality. If image quality is a
concern, try two-pass variable bit-rate (VBR) bit-allocation algorithm instead.
VBR gives better results than CBR, but runs about twice slower.

-N, --node-list
File with cluster configuration. Note: this option is available in cluster-aware
EPSILON version only and is intended for MASTER node. Each line in this file should
comply with the following format:

user@host:port^number_of_CPUs

All fields are mandatory. No comments, spaces or blank lines are allowed here. The
second field can be either IP address or host name. The last field is actually the
number of simultaneous TCP connections with a corresponding SLAVE node. Usually it
is set to the number of CPUs or somewhat larger.

If you omit this option, EPSILON will try .epsilon.nodes in the current and home
directory (in that order).

Note 1: 'user' field is used by start_epsilon_nodes.pl and stop_epsilon_nodes.pl to
SSH into the target box.

Note 2: 'port' is EPSILON node's port not SSH's.

-T, --threads
Number of encoding threads. Note: this option is available in thread-aware EPSILON
version only.

--Y-ratio=VALUE, --Cb-ratio=VALUE, --Cr-ratio=VALUE
Bit-budget percent for the Y, Cb and Cr channels respectively. The values should
give 100% altogether. Note that these options have sense for truecolor (i.e. PPM)
images only. The default values are 90-5-5.

--no-resampling
By default EPSILON resamples truecolor images using so called 4:2:0 resampling
scheme. This trick essentially speed-ups encoding/decoding without sacrificing
image quality. Usually there is no reason to disable resampling.

Options to use with `--decode-file' command:
-T, --threads
Number of decoding threads. Note: this option is available in thread-aware EPSILON
version only.

user@host:port^number_of_CPUs

If you omit this option, EPSILON will try .epsilon.nodes in the current and home
directory (in that order).

--ignore-hdr-crc
Ignore header CRC errors.

--ignore-data-crc
Ignore data CRC errors.

--ignore-format-err
Skip over malformed blocks.

Options to use with `--truncate-file' command:
-r, --ratio=VALUE
Desired truncation ratio. See also --truncate-file command.

Options to use with `--start-node' command:
-P, --port=VALUE
By default cluster node listens port number 2718. With this option you can set
another port number.

Common options:
-H, --halt-on-errors
By default if something fails EPSILON proceeds to the next input file. With this
option you can change default behaviour: EPSILON will halt on first error. Note
that in MPI mode this option is not available and EPSILON always halts on errors.

-q, --quiet
By default EPSILON shows pretty statistics during its operation. With this option
you can ask EPSILON to be quiet.

-O, --output-dir=DIR
Output directory for encoded, decoded and truncated files. If not set, output
files will be saved in the same directory as input ones.

Help options:
-?, --help
Show help message.

--usage
Display brief usage message.

EXAMPLES

       Encode all PPM files in current directory with two-pass VBR algorithm:

       epsilon *.ppm -2

       Encode PGM file with 1:100 compression ratio using 4 threads:

       epsilon -e big.pgm -r 100 -T 4

       Decode all files to the /tmp directory, operate quietly:

       epsilon -dq *.psi -O /tmp

       Decode a list of heavily corrupted files:

       epsilon -d *.psi --ignore-hdr-crc --ignore-data-crc --ignore-format-err

       Start cluster node with non-standard port number:

       epsilon -s -P 1234

       Encode files using custom cluster configuration:

       epsilon *.ppm *.pgm -N /path/to/.epsilon.nodes

       Encode file with MPI engine using all available processors:

       mpirun C epsilon test.ppm

AUTHOR

       Alexander Simakov, <xander@entropyware.info>

       Feedback, bug-reports and patches are welcome. Feel free to write!