| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Pnmtojbig User Manual" 1 "28 July 2020" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
|
| 10 |
pnmtojbig - PNM to JBIG file converter |
| 11 |
|
| 12 |
.UN synopsis |
| 13 |
.SH SYNOPSIS |
| 14 |
|
| 15 |
\fBpnmtojbig\fP |
| 16 |
|
| 17 |
[\fIoptions\fP] |
| 18 |
[\fIinput-file\fP [\fIoutput-file\fP]] |
| 19 |
|
| 20 |
.UN description |
| 21 |
.SH DESCRIPTION |
| 22 |
.PP |
| 23 |
This program is part of |
| 24 |
.BR "Netpbm" (1)\c |
| 25 |
\&. |
| 26 |
.PP |
| 27 |
\fBpnmtojbig\fP reads a PBM or PGM image, compresses it, and |
| 28 |
outputs the image as a JBIG bi-level image entity (BIE) file. |
| 29 |
.PP |
| 30 |
JBIG is a highly effective lossless compression algorithm for |
| 31 |
bi-level images (one bit per pixel), which is particularly suitable |
| 32 |
for scanned document pages. |
| 33 |
.PP |
| 34 |
A JBIG encoded image can be stored in several resolutions |
| 35 |
(progressive mode). These resolution layers can be stored all in one |
| 36 |
single BIE or they can be stored in several separate BIE files. All |
| 37 |
resolution layers except the lowest one are stored merely as |
| 38 |
differences to the next lower resolution layer, because this requires |
| 39 |
less space than encoding the full image completely every time. Each |
| 40 |
resolution layer has twice the number of horizontal and vertical |
| 41 |
pixels than the next lower layer. JBIG files can also store several |
| 42 |
bits per pixel as separate bitmap planes, and \fBpnmtojbig\fP |
| 43 |
can read a PGM file and transform it into a multi-bitplane BIE. |
| 44 |
|
| 45 |
.UN options |
| 46 |
.SH OPTIONS |
| 47 |
.PP |
| 48 |
In addition to the options common to all programs based on libnetpbm |
| 49 |
(most notably \fB-quiet\fP, see |
| 50 |
.UR index.html#commonoptions |
| 51 |
Common Options |
| 52 |
.UE |
| 53 |
\&), \fBpnmtojbig\fP recognizes the following |
| 54 |
command line options: |
| 55 |
|
| 56 |
|
| 57 |
|
| 58 |
.TP |
| 59 |
\fB-q\fP |
| 60 |
Encode the image in one single resolution layer (sequential |
| 61 |
mode). This is usually the most efficient compression method. By |
| 62 |
default, the number of resolution layers is chosen automatically such |
| 63 |
that the lowest layer image is not larger than 640 \(mu 480 pixels. |
| 64 |
|
| 65 |
.TP |
| 66 |
\fB-x\fP \fInumber\fP |
| 67 |
Specify the maximal horizontal size of the lowest resolution |
| 68 |
layer. The default is 640 pixels. |
| 69 |
|
| 70 |
.TP |
| 71 |
\fB-y\fP \fInumber\fP |
| 72 |
Specify the maximal vertical size of the lowest resolution layer. |
| 73 |
The default is 480 pixels. |
| 74 |
|
| 75 |
.TP |
| 76 |
\fB-l\fP \fInumber\fP |
| 77 |
Select the lowest resolution layer that will be written to the |
| 78 |
BIE. It is possible to store the various resolution layers of a JBIG |
| 79 |
image in progressive mode into different BIEs. Options \fB-l\fP and |
| 80 |
\fB-h\fP allow you to select the resolution-layer interval that will |
| 81 |
appear in the created BIE. The lowest resolution layer has number 0 |
| 82 |
and this is also the default value. By default, \fBpnmtojbig\fP |
| 83 |
writes all layers. |
| 84 |
|
| 85 |
.TP |
| 86 |
\fB-h\fP \fInumber\fP |
| 87 |
Select the highest resolution layer that will be written to the |
| 88 |
BIE. By default, \fBpnmtojbig\fP writes all layers. See also option |
| 89 |
\fB-l\fP. |
| 90 |
|
| 91 |
.TP |
| 92 |
\fB-b\fP |
| 93 |
Use binary values instead of Gray code words in order to encode |
| 94 |
pixel values in multiple bitplanes. This option has only an effect if |
| 95 |
the input is a PGM file and if more than one bitplane is |
| 96 |
produced. Note that the decoder has to make the same selection but |
| 97 |
cannot determine from the BIE, whether Gray or binary code words were |
| 98 |
used by the encoder. |
| 99 |
|
| 100 |
.TP |
| 101 |
\fB-d\fP \fInumber\fP |
| 102 |
Specify the total number of differential resolution layers into |
| 103 |
which the input image will be split in addition to the lowest layer. |
| 104 |
Each additional layer reduces the size of layer 0 by 50 %. This |
| 105 |
option overrides options \fB-x\fP and \fB-y\fP, which are usually a |
| 106 |
more comfortable way of selecting the number of resolution layers. |
| 107 |
|
| 108 |
.TP |
| 109 |
\fB-s\fP \fInumber\fP |
| 110 |
The JBIG algorithm splits each image into a number of horizontal |
| 111 |
stripes. This option specifies that each stripe shall have |
| 112 |
\fInumber\fP lines in layer 0. The default value is selected so that |
| 113 |
approximately 35 stripes will be used for the whole image. |
| 114 |
|
| 115 |
.TP |
| 116 |
\fB-m\fP \fInumber\fP |
| 117 |
Select the maximum horizontal offset of the adaptive template pixel. The |
| 118 |
JBIG encoder uses a number of neighbour pixels in order to get statistical a |
| 119 |
priori knowledge of the probability, whether the next pixel will be black or |
| 120 |
white. One single pixel out of this template of context neighbor pixels can |
| 121 |
be moved around. Especially for dithered images it can be a significant |
| 122 |
advantage to have one neighbor pixel which has a distance large enough to |
| 123 |
cover the period of a dither function. By default, the adaptive template |
| 124 |
pixel can be moved up to 8 pixels away. This encoder go up to 23 pixels, |
| 125 |
however as decoders are only required to handle at least a distance of 16 |
| 126 |
pixels by the standard, no higher value than 16 for |
| 127 |
\fInumber\fP is recommended in order to maintain interoperability |
| 128 |
with other JBIG implementations. The maximal vertical offset of the |
| 129 |
adaptive template pixel is always zero. |
| 130 |
|
| 131 |
.TP |
| 132 |
\fB-t\fP \fInumber\fP |
| 133 |
Encode only the specified number of most significant bit planes. |
| 134 |
This option allows one to reduce the depth of an input PGM file if not all |
| 135 |
bits per pixel are needed in the output. |
| 136 |
|
| 137 |
.TP |
| 138 |
\fB-o\fP \fInumber\fP |
| 139 |
JBIG separates an image into several horizontal stripes, |
| 140 |
resolution layers and planes, were each plane contains one bit per |
| 141 |
pixel. One single stripe in one plane and layer is encoded as a data |
| 142 |
unit called stripe data entity (SDE) inside the BIE. There are 12 |
| 143 |
different possible orders in which the SDEs can be stored inside the |
| 144 |
BIE and \fInumber\fP selects which one shall be used. The order of |
| 145 |
the SDEs is only relevant for applications that want to decode a JBIG |
| 146 |
file which has not yet completely arrived from e.g. a slow network |
| 147 |
connection. For instance some applications prefer that the outermost |
| 148 |
of the three loops (stripes, layers, planes) is over all layers so |
| 149 |
that all data of the lowest resolution layer is transmitted first. |
| 150 |
.sp |
| 151 |
The following values for \fInumber\fP select these loop |
| 152 |
arrangements for writing the SDEs (outermost loop first): |
| 153 |
|
| 154 |
|
| 155 |
.TP |
| 156 |
0 |
| 157 |
planes, layers, stripes |
| 158 |
|
| 159 |
.TP |
| 160 |
2 |
| 161 |
layers, planes, stripes |
| 162 |
|
| 163 |
.TP |
| 164 |
3 |
| 165 |
layers, stripes, planes |
| 166 |
|
| 167 |
.TP |
| 168 |
4 |
| 169 |
stripes, planes, layers |
| 170 |
|
| 171 |
.TP |
| 172 |
5 |
| 173 |
planes, stripes, layers |
| 174 |
|
| 175 |
.TP |
| 176 |
6 |
| 177 |
stripes, layers, planes |
| 178 |
|
| 179 |
|
| 180 |
.sp |
| 181 |
All loops count starting with zero, however by adding 8 to the |
| 182 |
above order code, the layer loop can be reversed so that it counts |
| 183 |
down to zero and then higher resolution layers will be stored before |
| 184 |
lower layers. Default order is 3 which writes at first all planes of |
| 185 |
the first stripe and then completes layer 0 before continuing with the |
| 186 |
next layer and so on. |
| 187 |
|
| 188 |
.TP |
| 189 |
\fB-p\fP \fInumber\fP |
| 190 |
This option allows you to activate or deactivate various optional |
| 191 |
algorithms defined in the JBIG standard. Just add the numbers of the |
| 192 |
following options which you want to activate in order to get the |
| 193 |
\fInumber\fP value: |
| 194 |
|
| 195 |
|
| 196 |
.TP |
| 197 |
4 |
| 198 |
deterministic prediction (DPON) |
| 199 |
|
| 200 |
.TP |
| 201 |
8 |
| 202 |
typical prediction (TPBON) |
| 203 |
|
| 204 |
.TP |
| 205 |
16 |
| 206 |
diff. layer typical prediction (TPDON) |
| 207 |
|
| 208 |
.TP |
| 209 |
64 |
| 210 |
layer 0 two-line template (LRLTWO) |
| 211 |
|
| 212 |
|
| 213 |
.sp |
| 214 |
Except for special applications (like communication with JBIG |
| 215 |
subset implementations) and for debugging purposes you will normally |
| 216 |
not want to change anything here. The default is 28, which provides |
| 217 |
the best compression result. |
| 218 |
|
| 219 |
.TP |
| 220 |
\fB-c\fP |
| 221 |
The adaptive template pixel movement is determined as suggested in |
| 222 |
annex C of the standard. By default the template change takes place |
| 223 |
directly in the next line which is most effective. However a few |
| 224 |
conformance test examples in the standard require the adaptive |
| 225 |
template change to be delayed until the first line of the next stripe. |
| 226 |
This option selects this special behavior, which is normally not |
| 227 |
required except in order to pass some conformance test suite. |
| 228 |
|
| 229 |
.TP |
| 230 |
\fB-v\fP |
| 231 |
After \fBpnmtojbig\fP creates the BIE, it lists a few technical |
| 232 |
details of the created file (verbose mode). |
| 233 |
|
| 234 |
|
| 235 |
|
| 236 |
.UN formats |
| 237 |
.SH FORMATS |
| 238 |
.PP |
| 239 |
Most of the format \fBpnmtojbig\fP creates is defined by the |
| 240 |
JBIG standard. |
| 241 |
.PP |
| 242 |
The standard, however, does not specify which values in the BIE mean |
| 243 |
white and which mean black. It contains a recommendation that for a |
| 244 |
single plane image zero mean background and one mean foreground, but |
| 245 |
the Netpbm formats have no concept of foreground and background. And |
| 246 |
the standard says nothing about values for multiple plane BIEs. |
| 247 |
.PP |
| 248 |
\fBpnmtojbig\fP follows Markus Kuhn's implementation of the |
| 249 |
standard in the \fBpbmtojbg\fP program that comes with his |
| 250 |
JBIG library: If the BIE is a single plane BIE, zero means |
| 251 |
white and one means black. If it is a multiple plane BIE, zero means |
| 252 |
black and the maximal value is white. |
| 253 |
|
| 254 |
.UN standards |
| 255 |
.SH STANDARDS |
| 256 |
.PP |
| 257 |
This program implements the JBIG image coding algorithm as |
| 258 |
specified in ISO/IEC 11544:1993 and ITU-T T.82(1993). |
| 259 |
|
| 260 |
.UN author |
| 261 |
.SH AUTHOR |
| 262 |
|
| 263 |
\fBpnmtojbig\fP is based on the JBIG library by Markus Kuhn, part of |
| 264 |
his \fBJBIG-KIT\fP package. The \fBpbmtojbg\fP program is part of |
| 265 |
the \fIJBIG-KIT\fP package. The most recent version of that library |
| 266 |
and tools set is freely available on the Internet from anonymous ftp |
| 267 |
server |
| 268 |
.UR ftp://ftp.informatik.uni-erlangen.de |
| 269 |
ftp.informatik.uni-erlangen.de |
| 270 |
.UE |
| 271 |
\& |
| 272 |
in directory pub/doc/ISO/JBIG/. |
| 273 |
.PP |
| 274 |
\fBpnmtojbig\fP is part of the Netpbm package of graphics tools. |
| 275 |
|
| 276 |
.UN seealso |
| 277 |
.SH SEE ALSO |
| 278 |
.BR "pnm" (1)\c |
| 279 |
\&, |
| 280 |
.BR "jbigtopnm" (1)\c |
| 281 |
\& |
| 282 |
|
| 283 |
.UN license |
| 284 |
.SH LICENSE |
| 285 |
.PP |
| 286 |
There was at one time concern about the need for patent licenses to |
| 287 |
use \fBpnmtojbig\fP, but any relevant patents expired by 2012. |
| 288 |
.SH DOCUMENT SOURCE |
| 289 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 290 |
source. The master documentation is at |
| 291 |
.IP |
| 292 |
.B http://netpbm.sourceforge.net/doc/pnmtojbig.html |
| 293 |
.PP |