/usr/share/doc/libminidjvu-dev/encode.html

<HTML>
<H1>minidjvu: how to compress into DjVu</H1>

This file describes minidjvu 0.3 library;
this is also fully applicable to 0.33 version.
<P>
The library interface is <B>unstable</B>.
<P>
See also: <a href="decode.html">how to decode a DjVu page</a>
<HR>
<H3>Step 0: get things working</H3>
Add this include line to you source files that use minidjvu:
<PRE>
    #include &lt;minidjvu.h&gt;
</PRE>
I'll assume that your compiler can find the minidjvu headers
and your linker can link against the library. If not, try to read INSTALL
or README, or try to add the parent release directory into the header search path.
<P>
This examples also require
<PRE>
    #include &lt;assert.h&gt;
    #include &lt;stdio.h&gt;
    #include &lt;stdlib.h&gt;
</PRE>

<HR>
<H3>Step 1: get the bitmap to compress</H3>

There are many ways to get a bitmap, but only loading from files is demonstrated here.
<P>
To load a Windows BMP file, use <I>mdjvu_load_bmp()</I>; here's the example with
error handling:

<PRE>
    const char *input = "your_input_file_name_here.bmp";
    mdjvu_error_t error;
    mdjvu_bitmap_t bitmap = mdjvu_load_bmp(input, &amp;error);
    if (!bitmap)
    {
        fprintf(stderr, "%s: %s\n", input, mdjvu_get_error_message(error));
        exit(1);
    }
</PRE>

PBM files are read in the same way with <I>mdjvu_load_pbm()</I>:

<PRE>
    const char *input = "your_input_file_name_here.pbm";
    mdjvu_error_t error;
    mdjvu_bitmap_t bitmap = mdjvu_load_pbm(input, &amp;error);
    if (!bitmap)
    {
        fprintf(stderr, "%s: %s\n", input, mdjvu_get_error_message(error));
        exit(1);
    }
</PRE>

TIFF files are a bit different: the function <I>mdjvu_load_tiff()</I>
receives another argument, a pointer to resolution:

<PRE>
    const char *input = "your_input_file_name_here.pbm";
    mdjvu_error_t error;
    int32 resolution = 300; // always set a default value in case TIFF has no dpi recorded
    mdjvu_bitmap_t bitmap = mdjvu_load_tiff(input, &amp;resolution, &amp;error);
    if (!bitmap)
    {
        fprintf(stderr, "%s: %s\n", input, mdjvu_get_error_message(error));
        exit(1);
    }
</PRE>

<HR>
<H3>Step 2 (optional): smooth the bitmap</H3>
"Smoothing" is a filter applied to the bitmap before splitting into letters.
The idea is to remove pixels that are probably noise. Right now, the
implementation is very simple, but still wins up to 5% of file size
(on scanned documents). Use
<PRE>
    mdjvu_smooth(bitmap);
</PRE>
to smooth it.


<HR>
<H3>Step 3: split the bitmap</H3>
We have the bitmap now; but we need a split image.
A split image, or simply an image, is a sequence of commands "put (a bitmap)
at point x = (an integer), y = (an integer)". An image is obtained from a bitmap by splitting.
<P>
You have to supply the resolution (in dots per inch) and a pointer to options,
which may be NULL.
<PRE>
    int32 dpi = 300;    // change the resolution if necessary
    mdjvu_image_t image = mdjvu_split(bitmap, dpi, NULL);
    assert(image);
</PRE>

<HR>
<H3>Step 4: call compression routine</H3>

The main compression function is called <I>mdjvu_compress_image()</I>.
It takes two arguments: the image and options. For lossless compression,
NULL option will do:
<PRE>
    mdjvu_compress_image(image, NULL);
</PRE>

Lossy compression is trickier: you have to create options structure
and options for the pattern matcher. Suppose you want to compress with
the aggression of 110, cleaning and printing verbose messages to stdout;
here's the example of doing it:

<PRE>
    mdjvu_matcher_options_t m_options = mdjvu_matcher_options_create();
    mdjvu_compression_options_t options = mdjvu_compression_options_create();
    mdjvu_set_aggression(m_options, 110);
    mdjvu_set_matcher_options(options, m_options);
    mdjvu_set_clean(options, 1);
    mdjvu_set_verbose(options, 1);
    
    mdjvu_compress_image(image, options);

    mdjvu_compression_options_destroy(options);
</PRE>

You don't have to destroy the matcher options,
since destroying compression options does this.

<HR>
<H3>Step 5: save the image</H3>
Just one call to <I>mdjvu_save_djvu_page()</I> does the job.
The file is silently rewritten if it exists.
<P>
The function mdjvu_save_djvu_page() takes an extra parameter: erosion flag.
<P>
Here's an example of dealing with possible errors:
<PRE>
    int erosion = 0;
    const char *output = "your_output_file_name_here.djvu";
    mdjvu_error_t error;
    if (!mdjvu_save_djvu_page(image, output, &amp;error, erosion))
    {
        fprintf(stderr, "%s: %s\n", output, mdjvu_get_error_message(error));
        exit(1);
    }
</PRE>
For the sake of completeness, there's a second declaration of <I>error</I>
in this example. Obviously, you should remove it if you plan to compile this.
<HR>
<H3>Step 6: clean up</H3>
If you no longer need the image and the bitmap, destroy them:
<PRE>
    mdjvu_image_destroy(image);
    mdjvu_bitmap_destroy(bitmap);
</PRE>
You could as well destroy the bitmap immediately after splitting it.
</HTML>
libminidjvu-dev 0.8.svn.2010.05.06+dfsg-5+b2 / usr / share / doc / libminidjvu-dev / encode.html
