| EPSILON(1) | User Commands | EPSILON(1) |
EPSILON - powerful Open Source wavelet image compressor
epsilon COMMAND [OPTIONS] FILES...
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.
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.
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.
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).
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
Alexander Simakov, <xander@entropyware.info>
| April 2008 | epsilon |