<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [

<!--ArborText, Inc., 1988-1999, v.4002-->

<!ENTITY cmd "jpegtran">

<!ENTITY % commonents SYSTEM "smancommon.ent">

%commonents;

<!ENTITY % booktitles SYSTEM "booktitles.ent">

%booktitles;

<!ENTITY suncopy "Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.">

]>

<?Pub UDT _bookmark _target>

<?Pub Inc>

<refentry id="jpegtran-1">

<refmeta><refentrytitle>jpegtran</refentrytitle><manvolnum>1</manvolnum>

<refmiscinfo class="date">26 Mar 2004</refmiscinfo>

<refmiscinfo class="sectdesc">&man1;</refmiscinfo>

<refmiscinfo class="software">&release;</refmiscinfo>

<refmiscinfo class="arch">generic</refmiscinfo>

<refmiscinfo class="copyright">&suncopy;</refmiscinfo>

</refmeta>

<indexterm><primary>jpegtran</primary></indexterm><indexterm><primary>lossless

transformation of JPEG files</primary></indexterm>

<refnamediv id="jpegtran-1-name"><refname>jpegtran</refname><refpurpose>lossless

transformation of JPEG files</refpurpose></refnamediv>

<refsynopsisdiv id="jpegtran-1-synp"><title>&synp-tt;</title>

<cmdsynopsis><command>&cmd;</command><arg choice="opt"><option role="nodash"><replaceable>

options</replaceable></option></arg><arg choice="opt"><option role="nodash"><replaceable>

filename</replaceable></option></arg>

</cmdsynopsis></refsynopsisdiv>

<refsect1 id="jpegtran-1-desc"><title>&desc-tt;</title>

<para><command>&cmd;</command> performs various useful transformations of

JPEG files. <command>&cmd;</command> can translate the coded representation

from one variant of JPEG to another, for example from baseline JPEG to progressive

JPEG or vice versa. <command>&cmd;</command> can also perform some rearrangements

of the image data, for example turning an image from landscape to portrait

format by rotation.</para>

<para><command>&cmd;</command> works by rearranging the compressed data (DCT

coefficients), without ever fully decoding the image. Therefore, <command>&cmd;</command>

transformations are lossless: there is no image degradation at all, which

would not be true if you used <command>djpeg</command> followed by <command>

cjpeg</command> to accomplish the same conversion. However, <command>&cmd;</command>

cannot perform lossy operations such as changing the image quality.</para>

<para><command>&cmd;</command> reads the named JPEG/JFIF file, or the standard

input if no file is named, and produces a JPEG/JFIF file on the standard output.

</para>

</refsect1>

<refsect1 id="jpegtran-1-opts"><title>&opts-tt;</title>

<para>All options may be abbreviated. For example, <option>optimize</option>

may be written <option>opt</option> or <option>o</option>. Upper and lower

case are equivalent. British spellings are also accepted. For example, <option>

optimise</option>.</para>

<para>The following options are supported:</para>

<variablelist termlength="medium">

<varlistentry><term><option>copy all</option></term><listitem><para>Copy all

extra markers. This option preserves miscellaneous markers found in the source

file, such as JFIF thumbnails and source-application settings. In some files,

these extra markers can be sizable.</para>

</listitem></varlistentry>

<varlistentry><term><option>copy comments</option></term><listitem><para>

Copy only comment markers. This option copies comments from the source file,

but discards any other inessential data. This is the default.</para>

</listitem></varlistentry>

<varlistentry><term><option>copy none</option></term><listitem><para>Copy

no extra markers from the source file. This option suppresses all comments

and other excess information present in the source file.</para>

</listitem></varlistentry>

<varlistentry><term><option>flip horizontal</option></term><listitem><para>

Create a mirror image horizontally, that is, from left to right. This is a

lossless transformation.</para>

</listitem></varlistentry>

<varlistentry><term><option>flip vertical</option></term><listitem><para>

Create a mirror image vertically, that is, from top to bottom. This is a lossless

transformation.</para>

</listitem></varlistentry>

<varlistentry><term><option>grayscale</option></term><listitem><para>Force

grayscale output. This is not a lossless transformation. For more information

about the <option>grayscale</option> option, see the Extended Description

section.</para>

</listitem></varlistentry>

<varlistentry><term><option>maxmemory <replaceable>N</replaceable></option></term>

<listitem><para>Set the limit for the amount of memory to use in processing

large images. <replaceable>N</replaceable> is specified in thousands of bytes,

or in millions of bytes if "M" is specified with the number. For example, <option>

max 4m</option> selects 4000000 bytes. If more space is needed, temporary

files are used.</para>

</listitem></varlistentry>

<varlistentry><term><option>optimize</option></term><listitem><para>Optimize

the entropy encoding parameters. For more information about the <option>optimize

</option> option, see <citerefentry><refentrytitle>cjpeg</refentrytitle><manvolnum>

1</manvolnum></citerefentry>.</para>

</listitem></varlistentry>

<varlistentry><term><option>outfile <replaceable>name</replaceable></option></term>

<listitem><para>Send the output image to the named file, instead of to the

standard output.</para>

</listitem></varlistentry>

<varlistentry><term><option>progressive</option></term><listitem><para>Create

a progressive JPEG file. For more information about the <option>progressive

</option> option, see <citerefentry><refentrytitle>cjpeg</refentrytitle><manvolnum>

1</manvolnum></citerefentry>.</para>

</listitem></varlistentry>

<varlistentry><term><option>restart <replaceable>N</replaceable></option></term>

<listitem><para>Emit a JPEG restart marker every <replaceable>N</replaceable>

MCU rows, or every <replaceable>N</replaceable> MCU blocks if "B" is specified

with the number. For more information about the <option>restart</option> option,

see <citerefentry><refentrytitle>cjpeg</refentrytitle><manvolnum>1</manvolnum>

</citerefentry>.</para>

</listitem></varlistentry>

<varlistentry><term><option>rotate 90</option></term><listitem><para>Rotate

the image 90 degrees clockwise. This is a lossless transformation.</para>

</listitem></varlistentry>

<varlistentry><term><option>rotate 180</option></term><listitem><para>Rotate

the image 180 degrees clockwise. This is a lossless transformation.</para>

</listitem></varlistentry>

<varlistentry><term><option>rotate 270</option></term><listitem><para>Rotate

the image 270 degrees clockwise, or 90 degrees anticlockwise. This is a lossless

transformation.</para>

</listitem></varlistentry>

<varlistentry><term><option>scans <replaceable>file</replaceable></option></term>

<listitem><para>Use the scan script provided in the specified text file.</para>

</listitem></varlistentry>

<varlistentry><term><option>transpose</option></term><listitem><para>Transpose

the image, that is, across the UL-to-LR axis. This is a lossless transformation.

For more information about the <option>transpose</option> option, see the

Extended Description section.</para>

</listitem></varlistentry>

<varlistentry><term><option>transverse</option></term><listitem><para>Transverse

transpose the image, that is, across the UR-to-LL axis. This is a lossless

transformation.</para>

</listitem></varlistentry>

<varlistentry><term><option>trim</option></term><listitem><para>Drop non-transformable

edge blocks. This is not a lossless transformation. For more information about

the <option>trim</option> option, see the Extended Description section.</para>

</listitem></varlistentry>

<varlistentry><term><option>verbose</option></term><listitem><para>Display

version information at startup, and enable debug printout. The <option>vv

</option> option displays more verbose output than the <option>v</option>

option. The <option>vvv</option> option displays the most verbose output.

</para>

<para>You can also use <option>debug</option> to specify this option.</para>

</listitem></varlistentry>

</variablelist></refsect1>

<refsect1 id="jpegtran-1-oper"><title>&oper-tt;</title>

<para>The following operands are supported:</para>

<variablelist termlength="medium">

<varlistentry><term><option role="nodash"><replaceable>filename</replaceable></option></term>

<listitem><para>The name of the JPEG file to be transformed.</para>

</listitem></varlistentry>

</variablelist></refsect1>

<refsect1 id="jpegtran-1-exde"><title>&exde-tt;</title>

<para>If you do not specify one of the following options, you get a plain

baseline-JPEG output file: <option>optimize</option>, <option>progressive

</option>, <option>restart <replaceable>N</replaceable></option>, <option>

scans <replaceable>file</replaceable></option>. In such cases, the quality

setting and other settings are determined by the input file.</para>

<refsect2 id="jpegtran-1-exde-lossless">

<title>Lossless Transformations</title>

<para>The transpose transformation has no restrictions as regards image dimensions.

The other transformations operate rather oddly if the image dimensions are

not a multiple of the iMCU siz, usually 8 or 16 pixels, because they can only

transform complete blocks of DCT coefficient data in the desired way. The

default behavior when transforming an odd-size image is designed to preserve

exact reversibility and mathematical consistency of the transformation set.

</para>

<para>As stated, transpose can flip the entire image area. Horizontal mirroring

leaves any partial iMCU column at the right edge untouched, but is able to

flip all rows of the image. Similarly, vertical mirroring leaves any partial

iMCU row at the bottom edge untouched, but is able to flip all columns.</para>

<para>The other transforms can be built up as sequences of transpose and flip

operations. For consistency, their actions on edge pixels are defined to be

the same as the end result of the corresponding transpose-and-flip sequence.

</para>

</refsect2>

<refsect2 id="jpegtran-1-exde-notlossless">

<title>Not-Lossless Transformations</title>

<para>You may prefer to discard any untransformable edge pixels rather than

have a strange-looking strip along the right or bottom edges of a transformed

image. To do this, use the <option>trim</option> option. Obviously, a transformation

with <option>trim</option> is not reversible, so strictly speaking <command>&cmd;</command>

with this option is not lossless. Also, the expected mathematical equivalences

between the transformations no longer hold. For example, <option>rot 270</option> <option>

trim</option> trims only the bottom edge, but <option>rot 90</option> <option>

trim</option> followed by <option>rot 180</option> <option>trim</option> trims

both edges.</para>

<para>Another not-strictly-lossless transformation option is <option>grayscale

</option>. This option discards the chrominance channels if the input image

is YCbCr (that is, a standard color JPEG), which results in a grayscale JPEG

file. The luminance channel is preserved exactly, so this is a better method

of reducing to grayscale than decompression, conversion, and recompression.

The <option>grayscale</option> option is particularly useful for fixing a

monochrome picture that was mistakenly encoded as a color JPEG. In such a

case, the space saved by discarding the near-empty chrominance channels is

not large, but the decoding time for a grayscale JPEG is substantially less

than that for a color JPEG.</para>

</refsect2>

</refsect1>

<refsect1 id="jpegtran-1-exam"><title>&exam-tt;</title>

<example role="example">

<title>Converting a Baseline JPEG File to Progressive Form</title>

<para><screen>example% <userinput>&cmd; -progressive test.jpg > testprog.jpg

</userinput></screen></para>

</example>

<example role="example">

<title>Rotating an Image 90 Degrees Clockwise, Discarding Any Unrotatable

Edge Pixels</title>

<para><screen>example% <userinput>&cmd; rot 90 -trim test.jpg > test90.jpg

</userinput></screen></para>

</example>

</refsect1>

<refsect1 id="jpegtran-1-envr"><title>&envr-tt;</title>

<para><command>&cmd;</command> uses the following environment variables:</para>

<variablelist>

<varlistentry><term>JPEGMEM</term><listitem><para>The value of this environment

variable, if set, is the default memory limit. The value is specified as described

for the <option>maxmemory</option> option. JPEGMEM overrides the default value

specified when the program was compiled, and is in turn overridden by an explicit <option>

maxmemory</option> option.</para>

</listitem></varlistentry>

</variablelist></refsect1>

<refsect1 id="jpegtran-1-attr"><title>&attr-tt;</title>

<para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry>

<refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>

for descriptions of the following attributes:</para>

<informaltable frame="all">

<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="COLSPEC0" colwidth="1*">

<colspec colname="COLSPEC1" colwidth="1*">

<thead>

<row><entry align="center" valign="middle">ATTRIBUTE TYPE</entry><entry align="center"

valign="middle">ATTRIBUTE VALUE</entry></row>

</thead>

<tbody>

<row><entry><para>Availability</para></entry><entry><para>image/library/libjpeg</para></entry>

</row>

<row><entry colname="COLSPEC0"><para>Interface stability</para></entry><entry

colname="COLSPEC1"><para>Uncommitted</para></entry></row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 id="jpegtran-1-also"><title>&also-tt;</title>

<para>Wallace, Gregory K., <citetitle>The JPEG Still Picture Compression Standard

</citetitle> Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

</para>

<para><citerefentry><refentrytitle>cjpeg</refentrytitle><manvolnum>1</manvolnum>

</citerefentry>, <citerefentry><refentrytitle>djpeg</refentrytitle><manvolnum>

1</manvolnum></citerefentry>, <citerefentry><refentrytitle>rdjpgcom</refentrytitle>

<manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>wrjpgcom

</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>

</refsect1>

<refsect1 id="jpegtran-1-note"><title>&note-tt;</title>

<para>Arithmetic coding is not supported. </para>

<para>The entire image is read into memory and then written out again, even

in cases where this is not really necessary. Expect swapping on large images,

especially when using the more complex transform options.</para>

<para>This man page was originally written by the Independent JPEG Group.

Updated by Breda McColgan, Sun Microsystems Inc., 2004. </para>

</refsect1>

</refentry>