.\" Copyright (c) 2001-2003 Leon Bottou, Yann Le Cun, Patrick Haffner,

.\" Copyright (c) 2001 AT&T Corp., and Lizardtech, Inc.

.\"

.\" This is free documentation; you can redistribute it and/or

.\" modify it under the terms of the GNU General Public License as

.\" published by the Free Software Foundation; either version 2 of

.\" the License, or (at your option) any later version.

.\"

.\" The GNU General Public License's references to "object code"

.\" and "executables" are to be interpreted as the output of any

.\" document formatting or typesetting system, including

.\" intermediate and printed output.

.\"

.\" This manual is distributed in the hope that it will be useful,

.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

.\" GNU General Public License for more details.

.\"

.\" You should have received a copy of the GNU General Public

.\" License along with this manual. Otherwise check the web site

.\" of the Free Software Foundation at http://www.fsf.org.

.TH C44 1 "10/11/2001" "DjVuLibre-3.5" "DjVuLibre-3.5"

.SH NAME

c44 \- DjVuPhoto encode.

.

.SH SYNOPSIS

.BI "c44 [" "options" "] " "inputfilename" " [" "outputfilename" "]"

.

.SH DESCRIPTION

Produces a DjVuPhoto encoded image.

The input image file 

.I inputfilename

can be either a portable gray-map (\c

.SM PGM\c

) or a portable pix-map (\c

.SM PPM\c

).

Input images compressed with

.SM JPEG

are also accepted. It is however suggested to only use 

high quality 

.SM JPEG

files (low compression ratio, large size)

because the wavelet compression will increase the defects

already present in highly compressed

.SM JPEG

files.

.P

The program produces a DjVuPhoto file

.IR outputfilename .

If the output file name is not specified,

a default file name will be generated by replacing

the input file name suffix by suffix 

.IR djvu .

.P

The main design objective for the DjVu wavelets consisted of allowing

progressive rendering and smooth scrolling of large images with limited memory

requirements.  Decoding functions process the compressed data and update a

memory efficient representation of the wavelet coefficients.  Imaging function

then can quickly render an arbitrary segment of the image using the available

data.  Both process can be carried out in two threads of execution.  This

design plays an important role in the DjVu system.  We investigated various

state-of-the-art wavelet compression schemes.  Although these schemes may

achieve slightly smaller file sizes, the decoding functions did not even

approach our requirements.  The

.SM IW44

wavelets reach these requirements today and may in the future implement more

modern refinements if these refinements can be implemented within our

constraints.

.

.SH QUALITY SELECTION OPTIONS

.

DjVuPhoto files are logically composed of a sequence of "slices" containing

successive image refinements.  Slices are grouped in "chunks" defining the

progressive rendering sequence.  The viewer is able to display an intermediate

image after processing each chunk.  A typical DjVuPhoto files contains 80 to

120 slices grouped into 1 to 4 chunks.

.P

The quality selection options provide various ways to specify the number of

chunks and the number of slices per chunk.  The 

.B c44

program adds slices to the current chunk until exceeding a target

number of slices, a target file size, or a target quality specification.

The following options define targets for each chunk.  The option 

argument contain several numerical values (one per chunk) separated

by either commas or pluses.

.

.TP

.BI "-slice " "n" "+...+" "n"

Specify the number of slices in each chunk.

The option argument contains plus-separated numerical values (one per chunk)

indicating the number of slices per chunk.  Option 

.BR "-slice 74+13+10" ,

for instance, would be appropriate for compressing a photographic image

with three progressive refinements.  More quality and more refinements

can be obtained with option

.BR "-slice 72+11+10+10" .

.TP

.BI "-slice " "n" ",...," "n"

Specify the cumulative number of slices for each chunk.

Since the final quality is determined by the total number of slices,

it is often more convenient to use comma-separated values (one per chunk)

indicating the cumulative number of slices for each chunk (i.e.\& including

those encoded in all previous chunks).  The values suggested above

can also be expressed as

.B "-slice 74,87,97"

and

.BR "-slice 72,83,93,103".

.TP

.BI "-size " "n" ",...," "n"

Specify size targets for each chunk expressed in bytes.

The option argument can be either a plus-separated list specifying a size

for each chunk, or a comma separated list specifying cumulative sizes

for each chunk and all previous chunks.  Size targets are approximates.

Slices will be added to each chunk until exceeding the specified target.

.TP

.BI "-bpp " "n" ",...," "n"

Specify size targets for each chunk expressed in bits-per-pixel.

Both comma-separated and plus-separated specifications are accepted.

Option 

.B -bpp 0.25,0.5,1

usually provides good results.

.TP

.BI "-percent " "n" ",...," "n"

Specify size targets for each chunk expressed as a percentage of the

input file size.  Both comma-separated and plus-separated specifications

are accepted.  Results can be drastically different according to the

format of the input image (raw or 

.SM JPEG

compressed).

.TP

.BI "-decibel " "n" ",...," "n"

Specify quality targets for each chunk expressed as a comma-separated list of

increasing decibel values.  Decibel values range from 16 (very low quality) to

48 (very high quality).  This criterion should not be relied upon when

re-encoding an image previously compressed by another compression scheme.

Selecting this option significantly increases the compression time.

.TP

.BI "-dbfrac " "frac"

Indicate that the decibel values specified in option

.B -decibel

should be computed by averaging the mean squared errors of only the fraction

.I frac

of the most mis-represented blocks of 32 x 32 pixels.  This option is useful

with composite images containing solid color features (e.g.\& an image with a

large white border).

.PP

Providing no quality specification options automatically selects a default

quality specification

.BR "-slice 74,89,99" .

Multiple quality specification options are allowed.  The program outputs a

file whose total number of chunks is the largest number of chunks of all

quality specifications.  Slices are added to each chunk until reaching any of

the quality target for this chunk.

.

.SH OTHER OPTIONS

The following additional options are supported:

.TP

.BI "-dpi " n

Specify the resolution information encoded into the output file expressed in

dots per inch. The resolution information encoded in DjVu files determine how

the decoder scales the image on a particular display.  Meaningful resolutions

range from 25 to 1200.  The default value, 100 dpi, should be suitable for

most photographic images.

.TP

.BI "-gamma " n

Specify the gamma correction information encoded into the output file.

The argument 

.I n

specified the gamma value of the device for which the input image was

designed. The default value is 2.2.  This is appropriate for images 

designed for a standard computer monitor.

.TP

.BI "-mask " pbmfilename

The design of the 

.SM IW44

wavelets allows for compressing partially masked images.

This option can be used when certain pixels of a background

image are going to be covered by foreground objects like text or drawings.

File 

.I pbmfile 

must be a 

.SM PBM 

file whose size matches the size of the input file.  

Each black pixel in 

.I pbmfile 

means that the value of the corresponding pixel in the input file is

irrelevant.  The 

.SM IW44

encoder will replace the masked pixels by a color value whose coding 

cost is minimal (see 

.B http://www.djvuzone.org/djvu/techpapers/mask/index.djvu

for technical details.)

.TP

.BI "-crcbnormal "

Select normal chrominance encoding. 

Chrominance information is encoded at the same resolution as the luminance.

This is the default.

.TP

.BI "-crcbhalf "

Selects half resolution chrominance encoding.  Chrominance information is

encoded at half the luminance resolution.

.TP

.BI "-crcbdelay " n

This option can be used with 

.B -crcbnormal

and

.B -crcbhalf

to modify the quality of the chrominance information.

The option arguments specifies a parameter

.IR n ,

expressed in slices, that reduces the bit-rate associated with

the chrominance.  The default chrominance encoding delay is 

10 slices.

.TP

.BI "-crcbfull "

Select the highest possible quality for encoding the chrominance information. This

is equivalent to specifying 

.BR "-crcbnormal" " and " "-crcbdelay 0" .

.TP

.BI "-crcbnone "

Disable the encoding of the chrominance.  Only the luminance information will

be encoded. The resulting image will show in shades of gray.

.

.SH REMARKS

The default quality setting of the DjVuLibre version of

.B c44

has been increased.  

It produces larger files with a better quality.  

Quality can be lowered using the quality selection options!

.

.SH BUGS

The encoder requires more memory than necessary.

.br

The rechunking capability is currently broken.

.

.SH CREDITS

This program was written by L\('eon Bottou <leonb@users.sourceforge.net> and

was then improved by Andrei Erofeev <andrew_erofeev@yahoo.com>, Bill Riemers

<docbill@sourceforge.net> and many others.

.

.SH SEE ALSO

.BR djvu (1),

.BR pnm (5),

.BR cjpeg (1).