'\" t
.\"     Title: econvert
.\"    Author: Jakub Wilk <jwilk@debian.org>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/11/2010
.\"    Manual: ExactImage Manual
.\"    Source: econvert
.\"  Language: English
.\"
.TH "ECONVERT" "1" "04/11/2010" "econvert" "ExactImage Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
econvert \- image converter of the ExactImage toolkit
.SH "SYNOPSIS"
.HP \w'\fBeconvert\fR\ 'u
\fBeconvert\fR [\fIoption\fR...] [{\fB\-i\fR\ |\ \fB\-\-input\fR}\ \fIinput\-file\fR...] [{\fB\-o\fR\ |\ \fB\-\-output\fR}\ \fIoutput\-file\fR...]
.HP \w'\fBeconvert\fR\ 'u
\fBeconvert\fR {\fB\-h\fR | \fB\-\-help\fR}
.SH "DESCRIPTION"
.PP
ExactImage is a fast C++ image processing library\&. Unlike many other library frameworks it allows operation in several color spaces and bit depths natively, resulting in low memory and computational requirements\&.
.PP
\fBeconvert\fR
is a command line frontend for the image processing library and mimics ImageMagick\*(Aqs convert\&. However econvert syntax is not compatible with convert\&.
.SH "OPTIONS"
.SS "Input/output"
.PP
\fB\-i \fR\fB\fIfile\fR\fR, \fB\-\-input \fR\fB\fIfile\fR\fR
.RS 4
Read image from the specified file\&. Optionally, filenames can be prefixed with format name, e\&.g\&.
jpg:\-
or
raw:rgb8\-dump\&.
.RE
.PP
\fB\-o \fR\fB\fIfile\fR\fR, \fB\-\-output \fR\fB\fIfile\fR\fR
.RS 4
Save output image to the specified file\&. Optionally, filenames can be prefixed with format name, e\&.g\&.
jpg:\-
or
raw:rgb8\-dump\&.
.RE
.PP
\fB\-a \fR\fB\fIfile\fR\fR, \fB\-\-append \fR\fB\fIfile\fR\fR
.RS 4
Append output image to the specified file\&. Existing image must have the same width as the appended one\&. Optionally, filenames can be prefixed with format name, e\&.g\&.
jpg:\-
or
raw:rgb8\-dump\&.
.RE
.PP
\fB\-\-compress \fR\fB\fImethod\fR\fR
.RS 4
Use the specified compression method for writing images, e\&.g\&.
G3,
G4,
Zip, \&... The default depends on the output format\&.
.RE
.PP
\fB\-\-decompress \fR\fB\fImethod\fR\fR
.RS 4
Use the specified decompression method for reading images\&.
.RE
.PP
\fB\-\-quality \fR\fB\fIn\fR\fR
.RS 4
Use the specified quality used for writing compressed images\&. Valid values are integers from 0 to 100\&. The default is 75\&.
.RE
.PP
\fB\-\-resolution \fR\fB\fIxdpi\fR\fR\fB \fR\fB\fI[ydpi]\fR\fR
.RS 4
Set metadata resolution\&.
.RE
.PP
\fB\-\-size \fR\fB\fIwidth\fR\fR\fB \fR\fB\fIheight\fR\fR
.RS 4
Set image dimensions for raw images\&.
.RE
.PP
\fB\-\-split \fR\fB\fIfile\&...\fR\fR
.RS 4
Split the image in Y\-direction into multiple images\&.
.RE
.SS "Scaling, cropping, transformations"
.PP
\fB\-\-bicubic\-scale \fR\fB\fIx\fR\fR
.RS 4
Scale image data with bi\-cubic filter\&. Use scale factor
\fIx\fR\&.
.RE
.PP
\fB\-\-bilinear\-scale \fR\fB\fIx\fR\fR
.RS 4
Scale image data with bi\-linear filter\&. Use scale factor
\fIx\fR\&.
.RE
.PP
\fB\-\-box\-scale \fR\fB\fIx\fR\fR
.RS 4
(Down)scale image data with box filter\&. Use scale factor
\fIx\fR\&.
.RE
.PP
\fB\-\-ddt\-scale \fR\fB\fIx\fR\fR
.RS 4
Scale image data with data dependent triangulation\&. Use scale factor
\fIx\fR\&.
.RE
.PP
\fB\-\-nearest\-scale \fR\fB\fIx\fR\fR
.RS 4
Scale image data to nearest neighbour\&. Use scale factor
\fIx\fR\&.
.RE
.PP
\fB\-\-scale \fR\fB\fIx\fR\fR
.RS 4
Scale image data using a method suitable for specified factor
\fIx\fR\&.
.RE
.PP
\fB\-\-thumbnail \fR\fB\fIx\fR\fR
.RS 4
Quick and dirty down\-scale for a thumbnail\&. Use scale factor
\fIx\fR\&.
.RE
.PP
\fB\-\-crop \fR\fB\fIx\fR\fR\fB \fR\fB\fIy\fR\fR\fB \fR\fB\fIw\fR\fR\fB \fR\fB\fIh\fR\fR
.RS 4
Crop the specified area out of the image\&.
.RE
.PP
\fB\-\-fast\-auto\-crop\fR
.RS 4
Fast auto crop\&.
.RE
.PP
\fB\-\-flip\fR
.RS 4
Flip the image vertically\&.
.RE
.PP
\fB\-\-flop\fR
.RS 4
Flip the image horizontally\&.
.RE
.PP
\fB\-\-rotate \fR\fB\fIn\fR\fR
.RS 4
Rotate the image
\fIn\fR
degrees\&.
.RE
.SS "Colors"
.PP
\fB\-\-brightness \fR\fB\fIx\fR\fR
.RS 4
Change the image brightness\&.
.RE
.PP
\fB\-\-contrast \fR\fB\fIx\fR\fR
.RS 4
Change the image contrast\&.
.RE
.PP
\fB\-\-saturation \fR\fB\fIx\fR\fR
.RS 4
Change the image saturation\&.
.RE
.PP
\fB\-\-lightness \fR\fB\fIx\fR\fR
.RS 4
Change the image lightness\&.
.RE
.PP
\fB\-\-hue \fR\fB\fIx\fR\fR
.RS 4
Change the image hue\&.
.RE
.PP
\fB\-\-negate\fR
.RS 4
Negate the image\&.
.RE
.PP
\fB\-\-gamma \fR\fB\fIx\fR\fR
.RS 4
Change the image gamma\&.
.RE
.PP
\fB\-\-normalize\fR
.RS 4
Transform the image to span the full color range\&.
.RE
.PP
\fB\-\-colorspace colorspace\fR
.RS 4
Convert image colorspace\&. Valid values are:
BW,
BILEVEL,
GRAY,
GRAY1,
GRAY2,
GRAY4,
RGB,
YUV
and
CYMK\&.
.RE
.PP
\fB\-\-floyd\-steinberg \fR\fB\fIn\fR\fR
.RS 4
Perform Floyd\-Steinberg dithering using
\fIn\fR
shades\&.
.RE
.PP
\fB\-\-riemersma \fR\fB\fIn\fR\fR
.RS 4
Perform Riemersma dithering using
\fIn\fR
shades\&.
.RE
.SS "Filters"
.PP
\fB\-\-blur stdev\fR
.RS 4
Perform gaussian blur with standard deviation
\fIstdev\fR\&.
.RE
.PP
\fB\-\-deinterlace\fR
.RS 4
Shuffle every 2nd line\&.
.RE
.PP
\fB\-\-edge\fR
.RS 4
Detect edges\&.
.RE
.PP
\fB\-\-convolve \fR\fB\fIx11\fR\fR\fB \fR\fB\fIx12\fR\fR\fB \fR\fB\fI\&...\fR\fR\fB \fR\fB\fIx1n\fR\fR\fB \fR\fB\fI\&...\fR\fR\fB \fR\fB\fIxn1\fR\fR\fB \fR\fB\fIxn2\fR\fR\fB \fR\fB\fI\&...\fR\fR\fB \fR\fB\fIxnn\fR\fR
.RS 4
Convolve the image using the specified convolution matrix\&.
.RE
.SS "Drawing"
.PP
\fB\-\-foreground \fR\fB\fIcolor\fR\fR
.RS 4
Set foreground color\&.
.RE
.PP
\fB\-\-background \fR\fB\fIcolor\fR\fR
.RS 4
Set background color\&.
.RE
.PP
\fB\-\-font \fR\fB\fIfont\fR\fR
.RS 4
Use the specified font for drawing text\&.
.RE
.PP
\fB\-\-text\-rotation \fR\fB\fIn\fR\fR
.RS 4
Use the specified text rotation\&.
.RE
.PP
\fB\-\-text \fR\fB\fIx1\fR\fR\fB \fR\fB\fIy1\fR\fR\fB \fR\fB\fIheight\fR\fR\fB \fR\fB\fItext\fR\fR
.RS 4
Draw text\&.
.RE
.PP
\fB\-\-stroke\-width \fR\fB\fIn\fR\fR
.RS 4
Set stroke width for vector primitives\&.
.RE
.PP
\fB\-\-line \fR\fB\fIx1\fR\fR\fB\ \&\fR\fB\fIy1\fR\fR\fB \fR\fB\fIx2\fR\fR\fB \fR\fB\fIy2\fR\fR
.RS 4
Draw a line\&.
.RE
.SS "Help"
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Display help text and exit\&.
.RE
.SH "EXAMPLES"
.SS "Basics"
.PP
Image data must be read using
\fB\-i\fR
or
\fB\-\-input\fR, processing routines are selected by their name with two leading dashes (e\&.g\&.
\fB\-\-rotate\fR) and at any point the data might be written into a file with
\fB\-o\fR
or
\fB\-\-output\fR, for example:
.sp
.if n \{\
.RS 4
.\}
.nf
econvert \-i lenea\&.tiff \-\-box\-scale 0\&.5 \-o medium\&.png \-\-box\-scale 0\&.5 \-o little\&.png
.fi
.if n \{\
.RE
.\}
.SS "Lossless transformations of JPEG files"
.PP
The library delays image decoding as much as possible and provides lossless algorithms to work on compressed data (such as JPEGs) directly:
.sp
.if n \{\
.RS 4
.\}
.nf
econvert \-i AV220\-Scan\&.JPG \-\-resolution 300x300 \-o 1\&.jpg \-\-rotate 90 \-o 2\&.jpg \-\-rotate 180 \-o 3\&.jpg \-\-rotate \-90 \-o 4\&.jpg \-\-flip \-o 5\&.jpg \-\-flop \-o 6\&.jpg \-\-scale 0\&.25 \-o thumb\&.jpg
.fi
.if n \{\
.RE
.\}
.PP
In this example
1\&.jpg
will be created from the original JPEG DCT coefficients, those coefficients will be rearranged and
2\&.jpg,
3\&.jpg,
4\&.jpg,
5\&.jpg
and
6\&.jpg
will be written without any additional loss in quality\&. Only at the end, for image
thumb\&.jpg, the DCT will actually be decoded \(em but due to the accelerated JPEG scaling only partially\&.
.SS "Thumbnails of bi\-level images"
.PP
When 1 bit, black and white, images are scaled down, the output often looks bad, as the library algorithms always operate in the color\-space the image data is stored in\&. To work around this problem, the colorspace must be changed (e\&.g\&. to 8 bit gray) before applying the box scaler\&. At the end the result might be converted back to just a few shades of gray such as 2 or 4 bit:
.sp
.if n \{\
.RS 4
.\}
.nf
econvert \-i avision\-bw\-scan\&.pbm \-\-colorspace gray8 \-\-box\-scale 0\&.125 \-\-colorspace gray2 \-o thumb\&.png
.fi
.if n \{\
.RE
.\}
.SS "Faster JPEG down\-scaling"
.PP
If you don\*(Aqt care about quality, only about throughput, you can force nearest neighbor scaling by just specifying a scale factor the JPEG decoder can accelerate (\(12, \(14, or 1/8) and apply the remaining scaling manually\&. To achieve faster scaling with the effective factor 1/3:
.sp
.if n \{\
.RS 4
.\}
.nf
econvert \-i big\&.jpg \-\-scale \&.5 \-\-nearest\-scale 0\&.66 \-o thumb\&.jpg
.fi
.if n \{\
.RE
.\}
.SS "Working with digital camera RAW data"
.PP
Wide range of digital camera RAW formats is supported\&. Usually decoding of RAW data should be transparent and automatic, however some formats also are also valid TIFF files and the embedded thumbnail might be picked by in favour of the actual RAW content\&. This this cases the
dcraw
decoder can explicitly be requested with the decoder prefix of the input parameter:
.sp
.if n \{\
.RS 4
.\}
.nf
econvert \-i dcraw:img_0123\&.cr2 \&...
.fi
.if n \{\
.RE
.\}
.PP
To quickly extract the embedded thumbnail preview, specify
thumb
as decompression method before the image is loaded:
.sp
.if n \{\
.RS 4
.\}
.nf
econvert \-\-decompress thumb \-i dcraw:img_0123\&.cr2 \&...
.fi
.if n \{\
.RE
.\}
.SS "Loading arbitrary raw data"
.PP
It is possible to load arbitrary raw data via the
raw:
codec specification; color\-depth (colorspace) and size for the raw data have to be explicitly specified:
.sp
.if n \{\
.RS 4
.\}
.nf
econvert \-\-size 1696x32 \-\-colorspace rgb8 \-i raw:data\-file \&...
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBexactimage\fR(7)
.SH "AUTHORS"
.PP
\fBJakub Wilk\fR <\&jwilk@debian\&.org\&>
.RS 4
Wrote this manual page for the Debian system\&.
.RE
.PP
\fB\m[blue]\fB\%https://exactcode.com/opensource/exactimage/\fR\m[]\fR
.RS 4
This manual page incorporates texts found on the ExactImage homepage\&.
.RE
.SH "COPYRIGHT"
.br
.PP
This manual page was written for the Debian system (and may be used by others)\&.
.PP
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or (at your option) any later version published by the Free Software Foundation\&.
.PP
On Debian systems, the complete text of the GNU General Public License can be found in
/usr/share/common\-licenses/GPL\-2\&.
.sp