Debian Codegraph @

doc/encode.html

raw
1 <HTML>
2 <H1>minidjvu: how to compress into DjVu</H1>
3
4 This file describes minidjvu 0.3 library;
5 this is also fully applicable to 0.33 version.
6 <P>
7 The library interface is <B>unstable</B>.
8 <P>
9 See also: <a href="decode.html">how to decode a DjVu page</a>
10 <HR>
11 <H3>Step 0: get things working</H3>
12 Add this include line to you source files that use minidjvu:
13 <PRE>
14 #include &lt;minidjvu.h&gt;
15 </PRE>
16 I'll assume that your compiler can find the minidjvu headers
17 and your linker can link against the library. If not, try to read INSTALL
18 or README, or try to add the parent release directory into the header search path.
19 <P>
20 This examples also require
21 <PRE>
22 #include &lt;assert.h&gt;
23 #include &lt;stdio.h&gt;
24 #include &lt;stdlib.h&gt;
25 </PRE>
26
27 <HR>
28 <H3>Step 1: get the bitmap to compress</H3>
29
30 There are many ways to get a bitmap, but only loading from files is demonstrated here.
31 <P>
32 To load a Windows BMP file, use <I>mdjvu_load_bmp()</I>; here's the example with
33 error handling:
34
35 <PRE>
36 const char *input = "your_input_file_name_here.bmp";
37 mdjvu_error_t error;
38 mdjvu_bitmap_t bitmap = mdjvu_load_bmp(input, &amp;error);
39 if (!bitmap)
40 {
41 fprintf(stderr, "%s: %s\n", input, mdjvu_get_error_message(error));
42 exit(1);
43 }
44 </PRE>
45
46 PBM files are read in the same way with <I>mdjvu_load_pbm()</I>:
47
48 <PRE>
49 const char *input = "your_input_file_name_here.pbm";
50 mdjvu_error_t error;
51 mdjvu_bitmap_t bitmap = mdjvu_load_pbm(input, &amp;error);
52 if (!bitmap)
53 {
54 fprintf(stderr, "%s: %s\n", input, mdjvu_get_error_message(error));
55 exit(1);
56 }
57 </PRE>
58
59 TIFF files are a bit different: the function <I>mdjvu_load_tiff()</I>
60 receives another argument, a pointer to resolution:
61
62 <PRE>
63 const char *input = "your_input_file_name_here.pbm";
64 mdjvu_error_t error;
65 int32 resolution = 300; // always set a default value in case TIFF has no dpi recorded
66 mdjvu_bitmap_t bitmap = mdjvu_load_tiff(input, &amp;resolution, &amp;error);
67 if (!bitmap)
68 {
69 fprintf(stderr, "%s: %s\n", input, mdjvu_get_error_message(error));
70 exit(1);
71 }
72 </PRE>
73
74 <HR>
75 <H3>Step 2 (optional): smooth the bitmap</H3>
76 "Smoothing" is a filter applied to the bitmap before splitting into letters.
77 The idea is to remove pixels that are probably noise. Right now, the
78 implementation is very simple, but still wins up to 5% of file size
79 (on scanned documents). Use
80 <PRE>
81 mdjvu_smooth(bitmap);
82 </PRE>
83 to smooth it.
84
85
86 <HR>
87 <H3>Step 3: split the bitmap</H3>
88 We have the bitmap now; but we need a split image.
89 A split image, or simply an image, is a sequence of commands "put (a bitmap)
90 at point x = (an integer), y = (an integer)". An image is obtained from a bitmap by splitting.
91 <P>
92 You have to supply the resolution (in dots per inch) and a pointer to options,
93 which may be NULL.
94 <PRE>
95 int32 dpi = 300; // change the resolution if necessary
96 mdjvu_image_t image = mdjvu_split(bitmap, dpi, NULL);
97 assert(image);
98 </PRE>
99
100 <HR>
101 <H3>Step 4: call compression routine</H3>
102
103 The main compression function is called <I>mdjvu_compress_image()</I>.
104 It takes two arguments: the image and options. For lossless compression,
105 NULL option will do:
106 <PRE>
107 mdjvu_compress_image(image, NULL);
108 </PRE>
109
110 Lossy compression is trickier: you have to create options structure
111 and options for the pattern matcher. Suppose you want to compress with
112 the aggression of 110, cleaning and printing verbose messages to stdout;
113 here's the example of doing it:
114
115 <PRE>
116 mdjvu_matcher_options_t m_options = mdjvu_matcher_options_create();
117 mdjvu_compression_options_t options = mdjvu_compression_options_create();
118 mdjvu_set_aggression(m_options, 110);
119 mdjvu_set_matcher_options(options, m_options);
120 mdjvu_set_clean(options, 1);
121 mdjvu_set_verbose(options, 1);
122
123 mdjvu_compress_image(image, options);
124
125 mdjvu_compression_options_destroy(options);
126 </PRE>
127
128 You don't have to destroy the matcher options,
129 since destroying compression options does this.
130
131 <HR>
132 <H3>Step 5: save the image</H3>
133 Just one call to <I>mdjvu_save_djvu_page()</I> does the job.
134 The file is silently rewritten if it exists.
135 <P>
136 The function mdjvu_save_djvu_page() takes an extra parameter: erosion flag.
137 <P>
138 Here's an example of dealing with possible errors:
139 <PRE>
140 int erosion = 0;
141 const char *output = "your_output_file_name_here.djvu";
142 mdjvu_error_t error;
143 if (!mdjvu_save_djvu_page(image, output, &amp;error, erosion))
144 {
145 fprintf(stderr, "%s: %s\n", output, mdjvu_get_error_message(error));
146 exit(1);
147 }
148 </PRE>
149 For the sake of completeness, there's a second declaration of <I>error</I>
150 in this example. Obviously, you should remove it if you plan to compile this.
151 <HR>
152 <H3>Step 6: clean up</H3>
153 If you no longer need the image and the bitmap, destroy them:
154 <PRE>
155 mdjvu_image_destroy(image);
156 mdjvu_bitmap_destroy(bitmap);
157 </PRE>
158 You could as well destroy the bitmap immediately after splitting it.
159 </HTML>