Debian Codegraph @

doc/old/djvu3changes.txt

raw
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]