Ubuntu Manpage: EPSILON - powerful Open Source wavelet image compressor

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!