| 1 |
|
| 2 |
|
| 3 |
|
| 4 |
<WARNING: THIS DOCUMENT HAS BEEN MADE OBSOLETE |
| 5 |
BY THE LIZARDTECH SPECIFICATION "DJVU3SPEC.DJVU".> |
| 6 |
|
| 7 |
|
| 8 |
|
| 9 |
This file summarizes the file format changes |
| 10 |
between DjVu2 and DjVu3. |
| 11 |
|
| 12 |
|
| 13 |
|
| 14 |
|
| 15 |
------------------------------------------------------------ |
| 16 |
1 - DJVU3 FILE STRUCTURE OVERVIEW |
| 17 |
------------------------------------------------------------ |
| 18 |
|
| 19 |
DjVu files are organized according to the ``EA IFF 85'' layout. Pointers to |
| 20 |
the appropriate reference document are provided in section |
| 21 |
\Ref{IFFByteStream.h}. IFF files are logically composed of a sequence of |
| 22 |
data \emph{chunks}. Each chunk comes with a four character \emph{chunk |
| 23 |
identifier} describing the type of the data stored in the chunk. A few |
| 24 |
special chunk identifiers, for instance #"FORM"#, are reserved for so |
| 25 |
called \emph{composite chunks} containing a sequence of data chunks. This |
| 26 |
convention effectively provides IFF files with a hierarchical structure. |
| 27 |
Composite chunks are further identified by a \emph{secondary chunk |
| 28 |
identifier}. For convenience, both identifiers are gathered as an |
| 29 |
extended chunk identifier such as #"FORM:DJVU"#. |
| 30 |
|
| 31 |
The four octets #0x41,0x54,0x26,0x54# may be inserted in front of the IFF |
| 32 |
compliant byte stream. The decoder simply ignores these four octets when |
| 33 |
they are present. These four octets are not part of the IFF format and |
| 34 |
are not required components of a valid DjVu file. Certain versions of MSIE |
| 35 |
incorrectly recognize any IFF file as a Microsoft AIFF sound file. The |
| 36 |
presence of these four octets prevents this incorrect identification. |
| 37 |
|
| 38 |
The DjVu specification mandates that the decoder should silently |
| 39 |
skip chunks whose identifier is not recognized. This mechanism |
| 40 |
provides a backward compatible way to extend the initial format by |
| 41 |
allocating new chunk identifiers. |
| 42 |
|
| 43 |
------------------------------------------------------------ |
| 44 |
1.1 - DJVU3 IMAGE FILES |
| 45 |
------------------------------------------------------------ |
| 46 |
|
| 47 |
\textbf{Photo DjVu Image} --- |
| 48 |
|
| 49 |
Photo DjVu Image files are best used for |
| 50 |
encoding photographic images in colors or in shades of gray. The data |
| 51 |
compression model relies on the IW44 wavelet representation. This format |
| 52 |
is designed such that the IW44 decoder is able to quickly perform |
| 53 |
progressive rendering of any image segment using only a small amount of |
| 54 |
memory. Photo DjVu files are composed of a single #"FORM:DJVU"# composite |
| 55 |
chunk. This composite chunk always begins with one #"INFO"# chunk |
| 56 |
describing the image size and resolution (see \Ref{DjVuInfo.h}). One or |
| 57 |
more additional #"BG44"# chunks contains the image data encoded with the |
| 58 |
IW44 representation (see \Ref{IW44Image.h}). The image size specified in |
| 59 |
the #"INFO"# chunk and the image size specified in the IW44 data must be |
| 60 |
equal. |
| 61 |
|
| 62 |
\textbf{Bilevel DjVu Image} --- |
| 63 |
|
| 64 |
Bilevel DjVu Image files are used to compress |
| 65 |
black and white images representing text and simple drawings. The |
| 66 |
JB2 data compression model uses the soft pattern matching technique, which |
| 67 |
essentially consists of encoding each character by describing how it |
| 68 |
differs from a well chosen already encoded character. Bilevel DjVu Files |
| 69 |
are composed of a single #"FORM:DJVU"# composite chunk. This composite |
| 70 |
chunk always begins with one #"INFO"# chunk describing the image size and |
| 71 |
resolution (see \Ref{DjVuInfo.h}). An additional #"Sjbz"# chunk contains |
| 72 |
the bilevel data encoded with the JB2 representation (see |
| 73 |
\Ref{JB2Image.h}). The image size specified in the #"INFO"# chunk and the |
| 74 |
image size specified in the JB2 data must be equal. |
| 75 |
|
| 76 |
\textbf{Compound DjVu Image} --- |
| 77 |
|
| 78 |
Compound DjVu Files are an extremely |
| 79 |
efficient way to compress high resolution Compound document images |
| 80 |
containing both pictures and text, such as a page of a magazine. Compound |
| 81 |
DjVu Files represent the document images using two layers. The |
| 82 |
\emph{background layer} is used for encoding the pictures and the |
| 83 |
paper texture. |
| 84 |
The \emph{foreground layer} is used for encoding the text and the drawings. |
| 85 |
Compound DjVu Files are composed of a single #"FORM:DJVU"# composite |
| 86 |
chunk. This composite chunk always begins with one #"INFO"# chunk |
| 87 |
describing the size and the resolution of the image (see \Ref{DjVuInfo}). |
| 88 |
Additional chunks hold the components of either the foreground or the |
| 89 |
background layers. |
| 90 |
|
| 91 |
The main component of the foreground layer is a bilevel image named the |
| 92 |
\emph{foreground mask}. The pixel size of the foreground mask is equal to |
| 93 |
the size of the DjVu image. It contains a black-on-white representation |
| 94 |
of the text and the drawings. This image is encoded by a #"Sjbz"# chunk |
| 95 |
using the JB2 representation. There may also be a companion chunk |
| 96 |
#"Djbz"# containing a \emph{shape dictionary} that defines bilevel shapes |
| 97 |
referenced by the #"Sjbz"# chunk. |
| 98 |
|
| 99 |
The \emph{foreground colors} can be encoded according to two models: |
| 100 |
\begin{itemize} |
| 101 |
\item |
| 102 |
The foreground colors may be encoded using a small color image, |
| 103 |
the \emph{foreground color image}, encoded as a single #"FG44"# |
| 104 |
chunk using the |
| 105 |
IW44 representation (see \Ref{IW44Image.h}). Such compound DjVu images |
| 106 |
are rendered by painting the foreground color image on top of the |
| 107 |
background color image using the foreground mask as a stencil. The |
| 108 |
pixel size of the foreground color image is computed by rounding up the |
| 109 |
quotient of the mask size by an integer sub-sampling factor ranging from |
| 110 |
1 to 12. Most Compound DjVu Images use a foreground color sub-sampling |
| 111 |
factor of 12. Smaller sub-sampling factors produce very slightly better |
| 112 |
images. |
| 113 |
\item |
| 114 |
The foreground colors may be encoded by specifying one solid color per |
| 115 |
object described by the JB2 encoded mask. These \emph{JB2 colors} are |
| 116 |
color-quantized and stored in a single #"FGbz"# chunk (see. |
| 117 |
\Ref{DjVuPalette.h}). Such compound DjVu images are rendered by |
| 118 |
painting each foreground object on top of the background color image |
| 119 |
using the solid color specified by the #"FGbz"# chunk. |
| 120 |
\end{itemize} |
| 121 |
|
| 122 |
The background layer is a color image, \Ref{the background color image} |
| 123 |
ncoded by an arbitrary number of #"BG44"# chunks containing successive |
| 124 |
IW44 refinements (see \Ref{IW44Image.h}). The size of this image is |
| 125 |
computed by rounding up the quotient of the mask size by an integer |
| 126 |
sub-sampling factor ranging from 1 to 12. Most Compound DjVu Images use a |
| 127 |
background sub-sampling factor equal to 3. Smaller sub-sampling factors |
| 128 |
are adequate for images with a very rich paper texture. Larger |
| 129 |
sub-sampling factors are adequate for images containing no pictures. |
| 130 |
|
| 131 |
There are no ordering or interleaving constraints on these chunks except |
| 132 |
that (a) the #"INFO"# chunk must appear first, and (b) the successive |
| 133 |
#"BG44"# refinements must appear with their natural order. The chunk |
| 134 |
order simply affects the progressive rendering of DjVu images on a web |
| 135 |
browser. |
| 136 |
|
| 137 |
\textbf{IW44 Image Files} -- |
| 138 |
|
| 139 |
The IW44 Image file format is the native format for the IW44 wavelet |
| 140 |
representation. These files are deprecated in favor of Photo DjVu |
| 141 |
Images. |
| 142 |
|
| 143 |
\textbf{Alternative encodings} --- |
| 144 |
|
| 145 |
Besides the JB2 and IW44 encoding schemes, |
| 146 |
the DjVu format supports alternative encoding methods for its components. |
| 147 |
|
| 148 |
\begin{itemize} |
| 149 |
\item |
| 150 |
The foreground mask may be represented by a single #"Smmr"# chunk |
| 151 |
instead of #"Sjbz"#. The #"Smmr"# chunk contains a bilevel image |
| 152 |
encoded with the Fax-G4/MMR method. Although the resulting files |
| 153 |
are typically six times larger, this capability can be useful when |
| 154 |
DjVu is used as a front-end for fax machines and scanners with |
| 155 |
embedded Fax-G4/MMR capabilities. |
| 156 |
\item |
| 157 |
The background color image may be represented by a single #"BGjp"# |
| 158 |
chunk instead of several #"BG44"# chunks. The #"BGjp"# chunk contains |
| 159 |
a JPEG encoded color image. The resulting files are significantly |
| 160 |
larger and lack the progressivity of the usual DjVu files. |
| 161 |
This is useful because some scanners have embedded JPEG capabilities. |
| 162 |
\item |
| 163 |
The foreground color image may be represented by a single #"FGjp"# |
| 164 |
chunk instead of a single #"FG44"# chunk. This is useful because |
| 165 |
some scanners have embedded JPEG capabilities. |
| 166 |
\end{itemize} |
| 167 |
|
| 168 |
In addition, the chunk names #"BG2k"# and #"FG2k"# have been reserved for |
| 169 |
encoding the background color image and the foreground color image using |
| 170 |
the forthcoming JPEG-2000 standard. This capability is not implemented at |
| 171 |
the moment. The JPEG-2000 standard may even become the preferred encoding |
| 172 |
method for color images in DjVu. */ |
| 173 |
|
| 174 |
\textbf{Annotations and Textual Information } -- |
| 175 |
|
| 176 |
All types of DjVu images may contain |
| 177 |
annotation chunks. Annotation chunks are currently used to describe |
| 178 |
hyperlinks, to specify more closely the behavior of the viewers, |
| 179 |
and to hold metadata information. Annotations are contained in #"ANTa"# |
| 180 |
or #"ANTz"# chunks. The #"ANTa"# chunks contain the annotation in |
| 181 |
plain text. The #"ANTz"# chunks contain the same information compressed |
| 182 |
with the BZZ encoder (cf. \Ref{BSByteStream.h}). |
| 183 |
|
| 184 |
All types of DjVu image files may also contain a |
| 185 |
computer readable description of the text appearing on the page. This |
| 186 |
information is contained by either a #"TXTa"# chunk or #"TXTz"# chunk. |
| 187 |
The #"TXTa"# chunk contains uncompressed data. The #"TXTz"# chunk |
| 188 |
contains the same data compressed with the \Ref{bzz} compressor |
| 189 |
(cf. \Ref{BSByteStream.h}). The #"TXTa"# chunks begins by a 24 bit |
| 190 |
integer (most significant byte first) describing the length of the text in |
| 191 |
bytes. Then come the ISO10646/UTF8 text. Additional information |
| 192 |
indicates the position of each column/region/paragraph/line/word in the |
| 193 |
document. More information about the capabilities of the chunk can be |
| 194 |
found in section \Ref{DjVuTXT}. More information about the encoding of |
| 195 |
textual information can be found in file #"DjVuAnno.cpp"#. */ |
| 196 |
|
| 197 |
|
| 198 |
------------------------------------------------------------ |
| 199 |
1.2 - DJVU3 MULTIPAGE DOCUMENTS |
| 200 |
------------------------------------------------------------ |
| 201 |
|
| 202 |
The DjVu3 system supports two models for multi-page documents: |
| 203 |
\emph{bundled} multi-page documents and \emph{indirect} multi-page documents. |
| 204 |
|
| 205 |
\textbf{Bundled multi-page documents} --- |
| 206 |
|
| 207 |
A \emph{bundled} multi-page DjVu |
| 208 |
document uses a single file to represent the entire document. This single |
| 209 |
file contains all the pages as well as ancillary information (e.g. the |
| 210 |
page directory, data shared by several pages, thumbnails, etc.). Using a |
| 211 |
single file format is very convenient for storing documents or for sending |
| 212 |
email attachments. |
| 213 |
|
| 214 |
A bundled multi-page document is composed of a single #"FORM:DJVM"# |
| 215 |
composite chunk. This composite chunk always begins with a #"DIRM"# chunk |
| 216 |
containing the document directory (see. \Ref{DjVmDir.h}) which represents |
| 217 |
the list of the \emph{component files} that compose the document. The |
| 218 |
component files themselves are then encoded as IFF85 composite chunks |
| 219 |
following the #"DIRM"# chunk. |
| 220 |
|
| 221 |
\begin{itemize} |
| 222 |
\item |
| 223 |
Component files may be any valid DjVu image (see \Ref{DjVu Image Files}) |
| 224 |
or IW44 image (see \Ref{IW44 Image Files}.) These component files |
| 225 |
always represent a page of a document. The corresponding IFF85 chunk ids are |
| 226 |
#"FORM:DJVU"#, #"FORM:PM44"#, or #"FORM:BM44"#. |
| 227 |
\item |
| 228 |
Component files may contain shared information indirectly referenced by |
| 229 |
some document pages. These \emph{shared component files} are always composed |
| 230 |
of a single #"FORM:DJVI"# chunk containing an arbitrary collection of |
| 231 |
chunks. |
| 232 |
\item |
| 233 |
Thumbnail files contain optional thumbnail images for a few consecutive |
| 234 |
pages of the document. Thumbnail files consist of a single |
| 235 |
#"FORM:THUM"# composite chunk containing several #"TH44"# chunks |
| 236 |
containing IW44 encoded thumbnail images (see \Ref{IW44Image.h}). These |
| 237 |
thumbnails always pertain the first few page files following the |
| 238 |
thumbnail file in the document directory. |
| 239 |
\end{itemize} |
| 240 |
|
| 241 |
\textbf{Including shared information} --- |
| 242 |
|
| 243 |
Any DjVu image file contained in a multipage file may contain an #"INCL"# |
| 244 |
chunk containing the ID of a shared component file. The decoder processes |
| 245 |
the chunks contained in the shared component file as if they were |
| 246 |
contained by the DjVu image file. |
| 247 |
|
| 248 |
A shared component file is composed of a single #"FORM:DJVI"# potentially |
| 249 |
containing any information otherwise allowed in a DjVu image file (except |
| 250 |
for the #"INFO"# chunk of course). |
| 251 |
|
| 252 |
There are many benefits associated with storing such shared information in |
| 253 |
separate files. A well designed browser may keep pre-decoded copies of |
| 254 |
these files in a cache. This procedure would reduce the size of the data |
| 255 |
transferred over the Internet and also increase the display speed. The |
| 256 |
multipage DjVu compressor, for instance, identifies similar object shapes |
| 257 |
occuring in several pages. These shapes are encoded in a shape dictionary |
| 258 |
(chunk #"Djbz"#) placed in a shared component file. All relevant pages |
| 259 |
include this shared component file. Although they appear in several |
| 260 |
pages, these shared shapes are encoded only once in the document. |
| 261 |
|
| 262 |
\textbf{Browsing a multi-page document} --- |
| 263 |
|
| 264 |
You can view the pages using the DjVu plugin and a web browser. When you |
| 265 |
type the URL of a multi-page document, the browser starts downloading the |
| 266 |
whole file, but displays the first page as soon as it is available. You |
| 267 |
can immediately navigate to other pages using the DjVu toolbar. Suppose |
| 268 |
however that the document is stored on a remote web server. You can |
| 269 |
easily access the first page and see that this is not the document you |
| 270 |
wanted. Although you will never display the other pages the browser is |
| 271 |
transferring data for these pages and is wasting the bandwith of your |
| 272 |
server (and the bandwith of the Internet too). You could also see the |
| 273 |
summary of the document on the first page and jump to page 100. But page |
| 274 |
100 cannot be displayed until data for pages 1 to 99 has been received. |
| 275 |
You may have to wait for the transmission of unnecessary page data. This |
| 276 |
second problem (the unnecessary wait) can be solved using the ``byte |
| 277 |
serving'' options of the HTTP/1.1 protocol. This option has to be |
| 278 |
supported by the web server, the proxies, the caches and the browser. We |
| 279 |
are coming there but not quite yet. Byte serving however does not solve |
| 280 |
the first problem (the waste of bandwith). |
| 281 |
|
| 282 |
\textbf{Indirect multi-page documents} --- |
| 283 |
|
| 284 |
DjVu solves both problem using a |
| 285 |
special multi-page format named the \emph{indirect} model. An indirect |
| 286 |
multi-page DjVu document is composed of several files. The main file is |
| 287 |
named the \emph{index file}. You can browse a document using the URL of |
| 288 |
the index file, just like you do with a bundled multi-page document. The |
| 289 |
index file however is very small. It simply contains the document |
| 290 |
directory and the URLs of secondary files containing the page data. When |
| 291 |
you browse an indirect multi-page document, the browser only accesses data |
| 292 |
for the pages you are viewing. This can be done at a reasonable speed |
| 293 |
because the browser maintains a cache of pages and sometimes pre-fetches a |
| 294 |
few pages ahead of the current page. This model uses the web serving |
| 295 |
bandwith much more effectively. It also eliminates unnecessary delays |
| 296 |
when jumping ahead to pages located anywhere in a long document. |
| 297 |
|
| 298 |
\textbf{Obsolete Formats} --- |
| 299 |
|
| 300 |
The library also supports two other multipage |
| 301 |
formats which are now obsolete. These formats are technologically |
| 302 |
inferior and should no longer be used. */ |
| 303 |
|
| 304 |
|
| 305 |
|
| 306 |
|
| 307 |
|
| 308 |
------------------------------------------------------------ |
| 309 |
2 - CHUNK ENCODING |
| 310 |
------------------------------------------------------------ |
| 311 |
|
| 312 |
This section describes |
| 313 |
- the encoding of new chunks introduces with DjVu3 |
| 314 |
- the encoding changes of chunks already present in DjVu2 |
| 315 |
|
| 316 |
|
| 317 |
|
| 318 |
------------------------------------------------------------ |
| 319 |
2.1 - CHANGES TO JB2 ( "Sjbz" AND "Djbz" CHUNKS ) |
| 320 |
------------------------------------------------------------ |
| 321 |
|
| 322 |
Two extensions of the JB2 encoding format have been introduced |
| 323 |
with DjVu files version 21. Both extensions maintain significant |
| 324 |
backward compatibility with previous version of the JB2 format. |
| 325 |
These extensions are described below by reference to the DjVu2 spec |
| 326 |
dated August 1999. Both extension make use of the unused record |
| 327 |
type value #9# (cf. ICFDD page 24) which has been renamed |
| 328 |
#REQUIRED_DICT_OR_RESET#. |
| 329 |
|
| 330 |
\textbf{Shared Shape Dictionaries} --- This extension provides |
| 331 |
support for sharing symbol definitions between the pages of a |
| 332 |
document. To achieve this objective, the JB2 image data chunk |
| 333 |
must be able to address symbols defined elsewhere by a JB2 |
| 334 |
dictionary data chunk shared by all the pages of a document. |
| 335 |
|
| 336 |
The arithmetically encoded JB2 image data logically consist of a |
| 337 |
sequence of records. The decoder processes these records in |
| 338 |
sequence and maintains a library of symbols which can be addressed |
| 339 |
by the following records. The first record usually is a ``Start |
| 340 |
Of Image'' record describing the size of the image. |
| 341 |
|
| 342 |
Starting with version 21, a #REQUIRED_DICT_OR_RESET# (9) record |
| 343 |
type can appear \emph{before} the #START_OF_DATA# (0) record. The |
| 344 |
record type field is followed by a single number arithmetically |
| 345 |
encoded (cf. ICFDD page 26) using a sixteenth context (cf. ICFDD |
| 346 |
page 25). This record appears when the JB2 data chunk requires |
| 347 |
symbols encoded in a separate JB2 dictionary data chunk. The |
| 348 |
number (the \textbf{dictionary size}) indicates how many symbols |
| 349 |
should have been defined by the JB2 dictionary data chunk. The |
| 350 |
decoder should simply load these symbols in the symbol library and |
| 351 |
proceed as usual. New symbols potentially defined by the |
| 352 |
subsequent JB2 image data records will therefore be numbered with |
| 353 |
integers greater or equal than the dictionary size. |
| 354 |
|
| 355 |
The JB2 dictionary data format is a pure subset of the JB2 image |
| 356 |
data format. The #START_OF_DATA# (0) record always specifies an |
| 357 |
image width of zero and an image height of zero. The only allowed |
| 358 |
record types are those defining library symbols only |
| 359 |
(#NEW_SYMBOL_LIBRARY_ONLY# (2) and #MATCHED_REFINE_LIBRARY_ONLY# |
| 360 |
(5) cf. ICFDD page 24) followed by a final #END_OF_DATA# (11) |
| 361 |
record. |
| 362 |
|
| 363 |
The JB2 dictionary data is usually located in an \textbf{Djbz} chunk. |
| 364 |
Each page \textbf{FORM:DJVU} may directly contain a \textbf{Djbz} chunk, |
| 365 |
or may indirectly point to such a chunk using an \textbf{INCL} chunk |
| 366 |
(cf. \Ref{Multipage DjVu documents.}). |
| 367 |
|
| 368 |
\textbf{Numcoder Reset} --- This extension addresses a problem for |
| 369 |
hardware implementations. The encoding of numbers (cf. ICFDD page |
| 370 |
26) potentially uses an unbounded number of binary coding |
| 371 |
contexts. These contexts are normally allocated when they are used |
| 372 |
for the first time (cf. ICFDD informative note, page 27). |
| 373 |
|
| 374 |
Starting with version 21, a #REQUIRED_DICT_OR_RESET# (9) record |
| 375 |
type can appear \emph{after} the #START_OF_DATA# (0) record. The |
| 376 |
decoder should proceed with the next record after \emph{clearing |
| 377 |
all binary contexts used for coding numbers}. This operation |
| 378 |
implies that all binary contexts previously allocated for coding |
| 379 |
numbers can be deallocated. |
| 380 |
|
| 381 |
Starting with version 21, the JB2 encoder should insert a |
| 382 |
#REQUIRED_DICT_OR_RESET# record type whenever the number of these |
| 383 |
allocated binary contexts exceeds #20000#. Only very large |
| 384 |
documents ever reach such a large number of allocated binary |
| 385 |
contexts (e.g large maps). Hardware implementation however can |
| 386 |
benefit greatly from a hard bound on the total number of binary |
| 387 |
coding contexts. Old JB2 decoders will treat this record type as |
| 388 |
an #END_OF_DATA# record and cleanly stop decoding (cf. ICFDD page |
| 389 |
30, Image refinement data). |
| 390 |
|
| 391 |
|
| 392 |
|
| 393 |
|
| 394 |
------------------------------------------------------------ |
| 395 |
2.2 - JB2 COLORS ( "FGbz" CHUNK ) |
| 396 |
------------------------------------------------------------ |
| 397 |
|
| 398 |
To be documented. |
| 399 |
|
| 400 |
The #"FGbz"# contains BZZ compressed data |
| 401 |
(cf. \Ref{BSByteStream.h}). |
| 402 |
|
| 403 |
The uncompressed data can be decoded using function |
| 404 |
#DjVuPalette::decode# defined in file #"DjVuPalette.cpp"#. |
| 405 |
|
| 406 |
|
| 407 |
|
| 408 |
|
| 409 |
------------------------------------------------------------ |
| 410 |
2.3 - ANNOTATIONS ( "ANTa" AND "ANTz" CHUNKS ) |
| 411 |
------------------------------------------------------------ |
| 412 |
|
| 413 |
[MAY 19TH, 2005: |
| 414 |
New annotation types have been defined by Lizardtech. |
| 415 |
The authoritative documentation is now the djvused man page.] |
| 416 |
|
| 417 |
|
| 418 |
Annotations are contained in #"ANTa"# |
| 419 |
or #"ANTz"# chunks. The #"ANTa"# chunks contain the annotation in |
| 420 |
plain text. The #"ANTz"# chunks contain the same information compressed |
| 421 |
with the BZZ encoder (cf. \Ref{BSByteStream.h}). |
| 422 |
|
| 423 |
The complete annotation text is obtained by concatenating all annotation |
| 424 |
chunks present in the page. Pages can share annotations using an INCL |
| 425 |
chunk as explained in section \Ref{Including shared information}. |
| 426 |
A restriction of the current reference library implementation |
| 427 |
limits the number of shared annotation files to one. |
| 428 |
|
| 429 |
The syntax of the annotation text uses a simple |
| 430 |
parenthesized notation. Erroneous and unrecognized constructs are silently |
| 431 |
ignored. The following constructs are recognized: |
| 432 |
|
| 433 |
\begin{description} |
| 434 |
\item[(background <color>)] |
| 435 |
Sets the color of the viewer area surrounding the DjVu image. |
| 436 |
The color argument #color# are always represented using X11 |
| 437 |
syntax \##RRGGBB#. For instance \##000000# is black |
| 438 |
and \##FFFFFF# is white. |
| 439 |
|
| 440 |
\item[(zoom <zoom-value>)] |
| 441 |
Sets the initial zoom factor of the image. Argument #zoom-value# may |
| 442 |
be #stretch#, #one2one#, #width#, #page#, or composed of the letter |
| 443 |
#"d"# followed by a number between #1# and #999# (such as in #d300# for |
| 444 |
instance.) |
| 445 |
|
| 446 |
\item[(mode <mode-value>)] |
| 447 |
Sets the display mode for the image. Argument #mode-value# may |
| 448 |
be #color#, #bw#, #fore# or #back#. |
| 449 |
|
| 450 |
\item[(align <horz-align> <vert-align>)] |
| 451 |
Specifies how the image should be aligned on the viewer surface. |
| 452 |
By default the image is located in the center. Argument #horz-align# |
| 453 |
may be #left#, #center#, or #right#. Argument #vert-align# may be |
| 454 |
#top#, #center#, or #bottom#. |
| 455 |
|
| 456 |
\item[(maparea <url> <comment> <area> <...options...>] |
| 457 |
Defines an hyperlink for the URL specified by argument #url#. |
| 458 |
|
| 459 |
Argument #url# may have one of the following two forms: |
| 460 |
\begin{verbatim} |
| 461 |
"<href>" |
| 462 |
(url "<href>" "<target>") |
| 463 |
\end{verbatim} |
| 464 |
where #href# is a string representing the URL and #target# is a string |
| 465 |
representing the target frame for the hyperlink (cf. Documentation for |
| 466 |
the HTML tag #<A>#). Both strings are surrounded with double quotes. |
| 467 |
Argument #comment# is a string surrounded by double quotes. |
| 468 |
This string may be displayed as a tooltip when the user |
| 469 |
moves the mouse over the hyperlink. |
| 470 |
Argument #area# defines the shape of the hyperlink. |
| 471 |
The following options are supported for representing |
| 472 |
rectangle, circle, or polygons. |
| 473 |
\begin{verbatim} |
| 474 |
(rect <xmin> <ymin> <width> <height>) |
| 475 |
(oval <xmin> <ymin> <width> <height>) |
| 476 |
(polygon <x0> <y0> <x1> <y1> ....) |
| 477 |
\end{verbatim} |
| 478 |
All parameters are numbers representing coordinates measured in image |
| 479 |
pixels with the origin set at the bottom left corner of the image. The |
| 480 |
remaining arguments describe options regarding the hyperlink borders. |
| 481 |
A first set of option define the type of the borders: |
| 482 |
\begin{verbatim} |
| 483 |
(xor) |
| 484 |
(border <color> |
| 485 |
(shadow_in [<thickness>]) |
| 486 |
(shadow_out [<thickness>]) |
| 487 |
(shadow_ein [<thickness>]) |
| 488 |
(shadow_eout [<thickness>]) |
| 489 |
\end{verbatim} |
| 490 |
where parameter #color# has syntax \##RRGGBB# (as above) and parameter |
| 491 |
#thickness# is a number from 1 to 32. The last four border modes are |
| 492 |
only supported with rectangular areas. The border becomes visible when |
| 493 |
the user moves the mouse over the hyperlink. The border may be made |
| 494 |
always visible by using the following option: |
| 495 |
\begin{verbatim} |
| 496 |
(border-avis) |
| 497 |
\end{verbatim} |
| 498 |
Finally the following option may be used with rectangular areas only. |
| 499 |
The complete area will be hilited using the specified color (specified |
| 500 |
with syntax \##RRGGBB# as usual). |
| 501 |
\begin{verbatim} |
| 502 |
(hilite <color>) |
| 503 |
\end{verbatim} |
| 504 |
This is often used with an empty URL for simply emphasizing a specific |
| 505 |
segment of an image. |
| 506 |
|
| 507 |
\item[(metadata <...entries...>)] |
| 508 |
Defines multiple metadata entries. |
| 509 |
|
| 510 |
Each metadata entry has the form |
| 511 |
\begin{verbatim} |
| 512 |
(<key> "<value>") |
| 513 |
\end{verbatim} |
| 514 |
parameter #<key># is a symbolic attribute name such as #year#, |
| 515 |
#booktitle#, #editor#, #author#, and parameter #<value># |
| 516 |
is a UTF-8 encoded string representing the attribute value. |
| 517 |
Common C escape sequences are recognized. |
| 518 |
It is suggested to use the same key names as |
| 519 |
the BibTeX bibliography system. |
| 520 |
|
| 521 |
Metadata pertaining to the entire document should be placed |
| 522 |
in a shared annotation file (and therefore are seen in all pages). |
| 523 |
Metadata pertaining to a particular page are usually places |
| 524 |
inside an #"ANTz"# chunk in this particular page. |
| 525 |
|
| 526 |
\end{description} |
| 527 |
|
| 528 |
|
| 529 |
|
| 530 |
|
| 531 |
|
| 532 |
------------------------------------------------------------ |
| 533 |
2.4 - HIDDEN TEXT ( "TXTa" AND "TXTz" CHUNKS ) |
| 534 |
------------------------------------------------------------ |
| 535 |
|
| 536 |
To be documented. |
| 537 |
|
| 538 |
The #"TXTa"# chunk contains uncompressed data. |
| 539 |
The #"TXTz"# chunk contains BZZ compressed data (cf. \Ref{BSByteStream.h}). |
| 540 |
|
| 541 |
The uncompressed data can be decoded using function #DjVuText::decode# |
| 542 |
defined in file #"DjVuText.cpp"# Program #djvused# can display the content |
| 543 |
of the text chunk using a lisp syntax, and can create a text chunk from |
| 544 |
this lisp syntax. |
| 545 |
|
| 546 |
|
| 547 |
------------------------------------------------------------ |
| 548 |
2.5 - MULTIPAGE DIRECTORY CHUNK ( "DIRM" CHUNK ) |
| 549 |
------------------------------------------------------------ |
| 550 |
|
| 551 |
Multipage DjVu documents follow the EA |
| 552 |
IFF85 format (cf. \Ref{IFFByteStream.h}.) A document is composed of a |
| 553 |
#"FORM:DJVM"# whose first chunk is a #"DIRM"# chunk containing the |
| 554 |
\emph{document directory}. This directory lists all component |
| 555 |
files composing |
| 556 |
the given document, helps to access every component file and identify the |
| 557 |
pages of the document. |
| 558 |
|
| 559 |
\begin{itemize} |
| 560 |
\item |
| 561 |
In a \emph{bundled} multipage file, the component files |
| 562 |
are stored immediately after the #"DIRM"# chunk, |
| 563 |
within the #"FORM:DJVM"# composite chunk. |
| 564 |
\item |
| 565 |
In an \emph{indirect} multipage file, the component files are |
| 566 |
stored in different files whose URLs are composed using information |
| 567 |
stored in the #"DIRM"# chunk. |
| 568 |
\end{itemize} |
| 569 |
|
| 570 |
Most of the component files represent pages of a document. Some files |
| 571 |
however represent data shared by several pages. The pages refer to these |
| 572 |
supporting files by means of an inclusion chunk (#"INCL"# chunks) |
| 573 |
identifying the supporting file. Every directory record describes a |
| 574 |
component file. Each component file is identified by a small string |
| 575 |
named the identifier (ID). Each component file also contains a |
| 576 |
file name and a title. |
| 577 |
|
| 578 |
Theoretically, IDs are used to uniquely identify each component file in |
| 579 |
#"INCL"# chunks, names are used to compose the the URLs of the component |
| 580 |
files in an indirect multipage DjVu file, and titles are cosmetic names |
| 581 |
possibly displayed when viewing a page of a document. There are however |
| 582 |
many problems with this scheme, and we \emph{strongly suggest}, with the |
| 583 |
current implementation to always make the file ID, the file name and the |
| 584 |
file title identical. |
| 585 |
|
| 586 |
\textbf{Variants} --- There are two versions of the #"DIRM"# chunk format. |
| 587 |
The version number is identified by the seven low bits of the first byte |
| 588 |
of the chunk. Version \textbf{0} is obsolete and should never be used. This |
| 589 |
section describes version \textbf{1}. There are two major multipage DjVu |
| 590 |
formats supported: \emph{bundled} and \emph{indirect}. The #"DIRM"# chunk |
| 591 |
indicates which format is used in the most significant bit of the first |
| 592 |
byte of the chunk. The document is bundled when this bit is set. |
| 593 |
Otherwise the document is indirect. |
| 594 |
|
| 595 |
\textbf{Unencoded data} --- |
| 596 |
|
| 597 |
The #"DIRM"# chunk is composed some unencoded |
| 598 |
data followed by \Ref{bzz} encoded data. The unencoded data starts with |
| 599 |
the version byte and a 16 bit integer representing the number of component |
| 600 |
files. All integers are encoded with the most significant byte first. |
| 601 |
\begin{verbatim} |
| 602 |
BYTE: Flags/Version: 0x<bundled>0000011 |
| 603 |
INT16: Number of component files. |
| 604 |
\end{verbatim} |
| 605 |
When the document is a bundled document (i.e. the flag #bundled# is set), |
| 606 |
this header is followed by the offsets of each of the component files within |
| 607 |
the #"FORM:DJVM"#. These offsets allow for random component file access. |
| 608 |
\begin{verbatim} |
| 609 |
INT32: Offset of first component file. |
| 610 |
INT32: Offset of second component file. |
| 611 |
... |
| 612 |
INT32: Offset of last component file. |
| 613 |
\end{verbatim} |
| 614 |
|
| 615 |
\textbf{BZZ encoded data} --- |
| 616 |
|
| 617 |
The rest of the chunk is entirely compressed |
| 618 |
with the BZZ general purpose compressor. We describe now the data fed |
| 619 |
into (or retrieved from) the BZZ codec (cf. \Ref{BSByteStream}.) First |
| 620 |
come the sizes and the flags associated with each component file. |
| 621 |
\begin{verbatim} |
| 622 |
INT24: Size of the first component file. |
| 623 |
INT24: Size of the second component file. |
| 624 |
... |
| 625 |
INT24: Size of the last component file. |
| 626 |
BYTE: Flag byte for the first component file. |
| 627 |
BYTE: Flag byte for the second component file. |
| 628 |
... |
| 629 |
BYTE: Flag byte for the last component file. |
| 630 |
\end{verbatim} |
| 631 |
The flag bytes have the following format: |
| 632 |
\begin{verbatim} |
| 633 |
0b<hasname><hastitle>000000 for a file included by other files. |
| 634 |
0b<hasname><hastitle>000001 for a file representing a page. |
| 635 |
0b<hasname><hastitle>000010 for a file containing thumbnails. |
| 636 |
\end{verbatim} |
| 637 |
Flag #hasname# is set when the name of the file is different from the file |
| 638 |
ID. Flag #hastitle# is set when the title of the file is different from |
| 639 |
the file ID. These flags are used to avoid encoding the same string three |
| 640 |
times. Then come a sequence of zero terminated strings. There are one to |
| 641 |
three such strings per component file. The first string contains the ID |
| 642 |
of the component file. The second string contains the name of the |
| 643 |
component file. It is only present when the flag #hasname# is set. The third |
| 644 |
one contains the title of the component file. It is only present when the |
| 645 |
flag #hastitle# is set. The \Ref{bzz} encoding system makes sure that |
| 646 |
all these strings will be encoded efficiently despite their possible |
| 647 |
redundancies. |
| 648 |
\begin{verbatim} |
| 649 |
ZSTR: ID of the first component file. |
| 650 |
ZSTR: Name of the first component file (only if #hasname# is set.) |
| 651 |
ZSTR: Title of the first component file (only if #hastitle# is set.) |
| 652 |
... |
| 653 |
ZSTR: ID of the last component file. |
| 654 |
ZSTR: Name of the last component file (only if #hasname# is set.) |
| 655 |
ZSTR: Title of the last component file (only if #hastitle# is set.) |
| 656 |
\end{verbatim} |
| 657 |
|
| 658 |
|
| 659 |
|
| 660 |
------------------------------------------------------------ |
| 661 |
2.6 - INCLUDES ( "INCL" CHUNK ) |
| 662 |
------------------------------------------------------------ |
| 663 |
|
| 664 |
The chunks simply contains the ascii encoded ID |
| 665 |
of the included component file. |
| 666 |
|
| 667 |
|
| 668 |
|
| 669 |
------------------------------------------------------------ |
| 670 |
2.7 - THUMBNAILS |
| 671 |
------------------------------------------------------------ |
| 672 |
|
| 673 |
|
| 674 |
Multipage document file optionally can contain thumbnails for some or all |
| 675 |
pages. These thumbnails are stored into special component files |
| 676 |
containing thumbnails for a number of consecutive pages. |
| 677 |
|
| 678 |
The thumbnail component file is composed of a single #"FORM:THUM"# |
| 679 |
containing one or more #"TH44"# chunk. Each #"TH44"# chunk contains one |
| 680 |
IW44 encoded thumbnail image for one page (cf. \Ref{IW44Image.h}). |
| 681 |
|
| 682 |
|
| 683 |
------------------------------------------------------------ |
| 684 |
2.8 - OUTLINES/BOOKMARKS |
| 685 |
------------------------------------------------------------ |
| 686 |
|
| 687 |
[MAY 19th, 2005 |
| 688 |
Multipage files (FORM:DJVM) can contain an |
| 689 |
additional chunk "NAVM" located after the "DIRM" chunk. |
| 690 |
The NAVM chunk contains outlines and bookmarks. |
| 691 |
See the files libdjvu/DjVmNav.h and libdjvu.DjVmNav.cpp] |