.\" @(#)cwsq.1 2008/10/02 NIST
.\" I Image Group
.\" Craig Watson and Michael D. Garris
.\"
.TH CWSQ 1G "02 October 2008" "NIST" "NBIS Reference Manual"
.SH NAME
cwsq \- WSQ compresses grayscale fingerprint images.
.SH SYNOPSIS
.B cwsq
.I <r bitrate>
.I <outext>
.I <image file>
.br
.RS
[\fB-raw_in \fIw\fR,\fIh\fR,\fId\fR,[\fIppi\fR]]
[\fIcomment file\fR]
.SH DESCRIPTION
.B Cwsq
takes as input a file containing an uncompressed grayscale fingerprint
image.  Two possible input file formats are accepted, NIST IHead files
and raw pixmap files.  If a raw pixmap file is to be compressed, then
its image attributes must be provided on the command line as well.
Once read into memory, the pixmap is \fIlossy\fR compressed
using Wavelet Scalar Quantization as described in the FBI's Criminal
Justice Information Services (CJIS) document, "WSQ Gray-scale Fingerprint
Compressions Specification," Dec. 1997.  The results are then written
to an output file in a format dictated by this document.  This is
the only fingerprint compression format accepted by the FBI IAFIS system.

.SH OPTIONS
All switch names may be abbreviated; for example,
\fB-raw_in\fR may be written \fB-r\fR.
.TP
.I <r bitrate>
determines the amount of lossy compression.
.br
.RS
Suggested settings:
.RS 3
.br
\fIr bitrate\fR = 2.25 yields around 5:1 compression
.br
\fIr bitrate\fR = 0.75 yields around 15:1 compression
.RE
.RE
.TP
.I <outext>
the extension of the compressed output file.
To construct the output filename, \fBcwsq\fR takes the
input filename and replaces its extension with the one
specified here.
.TP
.I <image file>
the input file, either an IHead file or raw pixmap file,
containing the fingerprint image to be compressed.
.TP
\fB-raw_in \fIw\fR,\fIh\fR,\fId\fR,[\fIppi\fR]
the attributes of the input image.  This option must
be included on the command line if the input is a
raw pixmap file.
.br
.RS
.TP
.I w
the pixel width of the pixmap
.TP
.I h
the pixel height of the pixmap
.TP
.I d
the pixel depth of the pixmap
.TP
.I ppi
the optional scan resolution of the image in integer units of
pixels per inch.
.RE
.TP
.I comment file
an optional user-supplied ASCII comment file.  (See COMMENT
OPTIONS below.)
.TP
\fB-version
\fRPrint ANSI/NIST stardand and NBIS software version.

.SH COMMENT OPTIONS
Upon successful compression, this utility generates and inserts
in the compressed output file a specially formatted comment block,
called a NISTCOM.  A NISTCOM is a text-based attribute list comprised
of (name, value) pairs, one pair per text line.
The first line of a NISTCOM always has name = "NIST_COM" 
and its value is always the total number of attributes included in
the list.  The utility \fBrdwsqcom\fR scans a WSQ compressed file for
any and all comment blocks.  Once found, the contents of each comment
block is printed to standard output.  Using this utility, the NISTCOM
provides easy access to relevant image attributes.  The following is
an example NISTCOM generated by \fBcwsq\fR:

.RS
NIST_COM 9
.br
PIX_WIDTH 500
.br
PIX_HEIGHT 500
.br
PIX_DEPTH 8
.br
PPI 500
.br
LOSSY 1
.br
COLORSPACE GRAY
.br
COMPRESSION WSQ
.br
WSQ_BITRATE 0.750000

.RE
\fBCwsq\fR also accepts an optional comment file on the command
line.  If provided, the contents of this file are also inserted
into the compressed output file.  If the comment file is a
NISTCOM attribute list, then its contents are merged with the
NISTCOM internally generated by \fBcwsq\fR and a single NISTCOM
is written to the compressed output file.  Note that \fBcwsq\fR
gives precedence to internally generated attribute values.
If the user provides a non-NISTCOM comment file,
then the contents of file are stored to a separate comment block in
the output file.  Using these comment options enables the user
to store application-specific information in a WSQ file.

.SH EXAMPLES
From \fItest/imgtools/execs/cwsq/cwsq.src\fR:
.PP
.RS
.B % cwsq .75 wsq finger.raw -r 500,500,8,500
.br
compresses a raw fingerprint pixmap.

.SH SEE ALSO
.BR dpyimage (1G),
.BR dwsq (1G),
.BR rdwsqcom (1G),
.BR wrwsqcom (1G)

.SH AUTHOR
NIST/ITL/DIV894/Image Group