Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/leptonica/README.html @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 <html>
2 <body BGCOLOR=FFFFE4>
3
4 <!-- JS Window Closer -----
5 <form>
6 <center>
7 <input type="button" onclick="window.close();" value="Close this window">
8 </center>
9 </form>
10 ----- JS Window Closer -->
11
12
13 <!-- Creative Commons License -->
14 <a rel="license" href="http://creativecommons.org/licenses/by/2.5/"><img alt="Creative Commons License" border="0" src="http://creativecommons.org/images/public/somerights20.gif" /></a>
15 This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/2.5/">Creative Commons Attribution 2.5 License</a>.
16 <!-- /Creative Commons License -->
17
18
19 <!--
20
21 <rdf:RDF xmlns="http://web.resource.org/cc/"
22 xmlns:dc="http://purl.org/dc/elements/1.1/"
23 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
24 <Work rdf:about="">
25 <dc:title>leptonica</dc:title>
26 <dc:date>2001</dc:date>
27 <dc:description>An open source C library for efficient image processing and image analysis operations</dc:description>
28 <dc:creator><Agent>
29 <dc:title>Dan S. Bloomberg</dc:title>
30 </Agent></dc:creator>
31 <dc:rights><Agent>
32 <dc:title>Dan S. Bloomberg</dc:title>
33 </Agent></dc:rights>
34 <dc:type rdf:resource="http://purl.org/dc/dcmitype/Text" />
35 <dc:source rdf:resource="www.leptonica.com"/>
36 <license rdf:resource="http://creativecommons.org/licenses/by/2.5/" />
37 </Work>
38
39 <License rdf:about="http://creativecommons.org/licenses/by/2.5/">
40 <permits rdf:resource="http://web.resource.org/cc/Reproduction" />
41 <permits rdf:resource="http://web.resource.org/cc/Distribution" />
42 <requires rdf:resource="http://web.resource.org/cc/Notice" />
43 <requires rdf:resource="http://web.resource.org/cc/Attribution" />
44 <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks" />
45 </License>
46
47 </rdf:RDF>
48
49 -->
50
51 <pre>
52 /*====================================================================*
53 - Copyright (C) 2001 Leptonica. All rights reserved.
54 -
55 - Redistribution and use in source and binary forms, with or without
56 - modification, are permitted provided that the following conditions
57 - are met:
58 - 1. Redistributions of source code must retain the above copyright
59 - notice, this list of conditions and the following disclaimer.
60 - 2. Redistributions in binary form must reproduce the above
61 - copyright notice, this list of conditions and the following
62 - disclaimer in the documentation and/or other materials
63 - provided with the distribution.
64 -
65 - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
66 - ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
67 - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
68 - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANY
69 - CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
70 - EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
71 - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
72 - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
73 - OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
74 - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
75 - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
76 *====================================================================*/
77
78 README (version 1.85.0)
79 File update: Oct 16 2024
80 ---------------------------
81
82 gunzip leptonica-1.85.0.tar.gz
83 tar -xvf leptonica-1.85.0.tar
84
85 </pre>
86
87 <!--Navigation Panel-->
88 <hr>
89 <P>
90 <A HREF="#BUILDING">Building leptonica</A><br>
91 <A HREF="#DEPENDENCIES">I/O libraries leptonica is dependent on</A><br>
92 <A HREF="#DOXYGEN">Generating documentation using doxygen</A><br>
93 <A HREF="#DEVELOP">Developing with leptonica</A><br>
94 <A HREF="#CONTENTS">What's in leptonica?</A><br>
95 <P>
96 <hr>
97 <!--End of Navigation Panel-->
98
99
100 <h2> <A NAME="BUILDING">
101 Building leptonica
102 </h2>
103
104 <pre>
105 1. Top view
106
107 This tar includes:
108 (1) src: library source and function prototypes for building liblept
109 (2) prog: source for regression test, usage example programs, and
110 sample images
111 for building on these platforms:
112 - Linux on x86 (i386) and AMD 64 (x64)
113 - OSX (both powerPC and x86).
114 - Cygwin, msys and mingw on x86
115 There is an additional zip file for building with MS Visual Studio.
116
117 Libraries, executables and prototypes are easily made, as described below.
118
119 When you extract from the archive, all files are put in a
120 subdirectory 'leptonica-1.85.0'. In that directory you will
121 find a src directory containing the source files for the library,
122 and a prog directory containing source files for various
123 testing and example programs.
124
125 2. Building on Linux/Unix/MacOS
126
127 The software can be downloaded from either a release tar file or
128 from the current head of the source. For the latter, go to a directory
129 and clone the tree into it (note the '.' at the end):
130 cd [some directory]
131 git clone https://github.com/DanBloomberg/leptonica.git .
132
133 There are three ways to build the library:
134
135 (1) By customization: Use the existing static makefile,
136 src/makefile.static and customize the build by setting flags
137 in src/environ.h. See details below.
138 Note: if you are going to develop with leptonica, the static
139 makefiles are useful.
140
141 (2) Using autoconf (supported by James Le Cuirot).
142 Run ./configure in this directory to
143 build Makefiles here and in src. Autoconf handles the
144 following automatically:
145 * architecture endianness
146 * enabling Leptonica I/O image read/write functions that
147 depend on external libraries (if the libraries exist)
148 * enabling functions for redirecting formatted image stream
149 I/O to memory (on Linux only)
150 After running ./configure: make; make install. There's also
151 a 'make check' for testing.
152
153 (3) Using cmake (supported by Egor Pugin).
154 The build must always be in a different directory from the root
155 of the source (here). It is common to build in a subdirectory
156 of the root. From the root directory, do this:
157 mkdir build
158 cd build
159 Then to make only the library:
160 cmake ..
161 make
162 To make both the library and the programs:
163 cmake .. -DBUILD_PROG=1
164 make
165 To clean out the current build, just remove everything in
166 the build subdirectory.
167
168 In more detail for these three methods:
169
170 (1) Customization using the static makefiles:
171
172 * FIRST THING: Run make-for-local. This simply renames
173 src/makefile.static --> src/makefile
174 prog/makefile.static --> prog/makefile
175 [Note: the autoconf build will not work if you have any files
176 named "makefile" in src or prog. If you've already run
177 make-for-local and renamed the static makefiles, and you then
178 want to build with autoconf, run make-for-auto to rename them
179 back to makefile.static.]
180
181 * You can customize for:
182 (a) Including Leptonica image I/O functions that depend on external
183 libraries, such as libpng. Use environment variables in
184 src/environ.h, such as HAVE_LIBPNG.
185 (b) Disabling the GNU functions for redirecting formatted stream I/O
186 to memory. By default, HAVE_FMEMOPEN is enabled in src/environ.h.
187 (c) Using special memory allocators (see src/environ.h).
188 (d) Changing compile and runtime defaults for messages to stderr.
189 The default in src/environ.h is to output info, warning and
190 error messages.
191 (e) Specifying the location of the object code. By default it
192 goes into a tree whose root is also the parent of the src
193 and prog directories. This can be changed using the
194 ROOT_DIR variable in makefile.
195
196 * Build the library:
197 - To make an optimized version of the library (in src):
198 make
199 - To make a debug version of the library (in src):
200 make DEBUG=yes debug
201 - To make a shared library version (in src):
202 make SHARED=yes shared
203 - To make the prototype extraction program (in src):
204 make (to make the library first)
205 make xtractprotos
206
207 * To use shared libraries, you need to include the location of
208 the shared libraries in your LD_LIBRARY_PATH. For example,
209 after you have built programs with 'make SHARED=yes' in the
210 prog directory, you need to tell the programs where the shared
211 libraries are:
212 export LD_LIBRARY_PATH=../lib/shared:$LD_LIBRARY_PATH
213
214 * Make the programs in prog/ (after you have make liblept):
215 - Customize the makefile by setting ALL_LIBS to link the
216 external image I/O libraries. By default, ALL_LIBS assumes that
217 libtiff, libjpeg and libpng are available.
218 - To make an optimized version of all programs (in prog):
219 make
220 - To make a debug version of all programs (in prog):
221 make DEBUG=yes
222 - To make a shared library version of all programs (in prog):
223 make SHARED=yes
224 - To run the programs, be sure to set
225 export LD_LIBRARY_PATH=../lib/shared:$LD_LIBRARY_PATH
226
227 (2) Building using autoconf (Thanks to James Le Cuirot)
228
229 * If you downloaded from a release tar, it will be "configure ready".
230 * If you cloned from the git master tree, you need to make the
231 configure executable. To do this, run
232 autogen.sh.
233
234 Use the standard incantation, in the root directory (the
235 directory with configure):
236 ./configure [build the Makefile]
237 make [builds the library and shared library versions of
238 all the progs]
239 make install [as root; this puts liblept.a into /usr/local/lib/
240 and 13 of the progs into /usr/local/bin/ ]
241 make [-j2] check [runs the alltests_reg set of regression tests.
242 This works even if you build in a different
243 place from the distribution. The -j parameter
244 should not exceed half the number of cores.
245 NOTE: If the test fails, it's likely due to a race
246 condition. Rerun with 'make check']
247
248 Configure supports installing in a local directory (e.g., one that
249 doesn't require root access). For example, to install in $HOME/local,
250 ./configure --prefix=$HOME/local/
251 make install
252 For different ways to build and link leptonica with tesseract, see
253 https://github.com/tesseract-ocr/tesseract/wiki/Compiling
254 In brief, using autotools to build tesseract and then install it
255 in $HOME/local (after installing leptonica there), do the
256 following from your tesseract root source directory:
257 ./autogen.sh
258 LIBLEPT_HEADERSDIR=$HOME/local/include ./configure \
259 --prefix=$HOME/local/ --with-extra-libraries=$HOME/local/lib
260 make install
261
262 Configure also supports building in a separate directory from the
263 source. Run "/(path-to)/leptonica-1.85.0/configure" and then "make"
264 from the desired build directory.
265
266 Configure has a number of useful options; run "configure --help" for
267 details. If you're not planning to modify the library, adding the
268 "--disable-dependency-tracking" option will speed up the build. By
269 default, both static and shared versions of the library are built. Add
270 the "--disable-shared" or "--disable-static" option if one or the other
271 isn't needed. To skip building the programs, use "--disable-programs".
272
273 By default, the library is built with debugging symbols. If you do not
274 want these, use "CFLAGS=-O2 ./configure" to eliminate symbols for
275 subsequent compilations, or "make CFLAGS=-O2" to override the default
276 for compilation only. Another option is to use the 'install-strip'
277 target (i.e., "make install-strip") to remove the debugging symbols
278 when the library is installed.
279
280 Finally, if you find that the installed programs are unable to link
281 at runtime to the installed library, which is in /usr/local/lib,
282 try to run configure in this way:
283 LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" ./configure
284 which causes the compiler to pass those options through to the linker.
285
286 For the Debian distribution, out of all the programs in the prog
287 directory, we only build a small subset of general purpose
288 utility programs. This subset is the same set of programs that
289 'make install' puts into /usr/local/bin. It has no dependency on
290 the image files that are bundled in the prog directory for testing.
291
292 (3) Using cmake
293
294 The usual method is to build in a directory that is a subdirectory
295 of the root. First do this from the root directory:
296 mkdir build
297 cd build
298
299 The default build (shared libraries, no debug, only the library)
300 is made with
301 cmake ..
302 For other options, you can use these flags on the cmake line:
303 * To make a static library:
304 cmake .. -DBUILD_SHARED_LIBS=OFF
305 make
306 * To make a dynamic library (default) and STATIC (or builtin) dependencies:
307 cmake .. -DSW_BUILD_SHARED_LIBS=0
308 make
309 * To build with debug:
310 cmake .. -DCMAKE_BUILD_TYPE=Debug
311 make
312 * To make both the library and the programs:
313 cmake .. -DBUILD_PROG=1
314 make
315
316 The programs are put in build/bin/
317 To run these (e.g., for testing), move them to the prog
318 directory and run them from there:
319 cd bin
320 mv * ../../prog/
321 cd ../../prog
322 alltests_reg generate
323 alltests_reg compare
324
325 To build the library directly from the root directory instead of
326 the build subdirectory:
327 mkdir build
328 cmake -H . -Bbuild (-H means the source directory,
329 -B means the directory for the build
330 make
331
332 3. Building on Windows
333
334 (a) Building with Visual Studio
335
336 1. Download the latest SW
337 (Software Network https://software-network.org/)
338 client from https://software-network.org/client/
339 2. Unpack it, add to PATH.
340 3. Run once to perform cmake integration:
341 sw setup
342 4. Run:
343 git clone https://github.com/danbloomberg/leptonica
344 cd leptonica
345 mkdir build
346 cd build
347 cmake ..
348 5. Build a solution (leptonica.sin) in your Visual Studio version.
349
350 (b) Building for mingw32 with <a href="http://www.mingw.org/">MSYS</a>
351 (Thanks to David Bryan)
352
353 MSYS is a Unix-compatible build environment for the Windows-native
354 mingw32 compiler. Selecting the "mingw-developer-toolkit",
355 "mingw32-base", and "msys-base" packages during installation will allow
356 building the library with autoconf as in (2) above. It will also allow
357 building with the static makefile as in (1) above if this option is used
358 in the make command line:
359
360 CC='gcc -std=c99 -U__STRICT_ANSI__'
361
362 Only the static library may be built this way; the autoconf method must
363 be used if a shared (DLL) library is desired.
364
365 External image libraries (see below) must be downloaded separately,
366 built, and installed before building the library. Pre-built libraries
367 are available from the <a
368 href="http://sourceforge.net/projects/ezwinports/">ezwinports</a> project.
369
370 (c) Building for <a href="http://www.cygwin.com/">Cygwin</a>
371 (Thanks to David Bryan)
372
373 Cygwin is a Unix-compatible build and runtime environment. Adding the
374 "binutils", "gcc-core", and "make" packages from the "Devel" category and
375 the "diffutils" package from the "Utils" category to the packages
376 installed by default will allow building the library with autoconf as in
377 (2) above. Pre-built external image libraries are available in the
378 "Graphics" and "Libs" categories and may be selected for installation.
379 If the libraries are not installed into the /lib, /usr/lib, or
380 /usr/local/lib directories, you must run make with the
381 "LDFLAGS=-L/(path-to-image)/lib" option. Building may also be performed
382 with the static makefile as in (1) above if this option is used in the
383 make command:
384
385 CC='gcc -std=c99 -U__STRICT_ANSI__'
386
387 Only the static library may be built this way; the autoconf method must
388 be used if a shared (DLL) library is desired.
389
390 4. Building and running oss-fuzz programs
391
392 The oss-fuzz programs are in prog/fuzzing/. They are run by oss-fuzz
393 on a continual basis with random inputs. clang-10, which is required
394 to build these programs, can be installed using the command
395 sudo apt-get install clang-10
396
397 Stefan Weil has provided this method for building the fuzzing programs.
398 From your github root:
399 ./autogen.sh (to make configure)
400 mkdir -p bin/fuzzer
401 cd bin/fuzzer
402 Run configure to generate the Makefiles:
403 address sanitizer issue:
404 ../../configure CC=clang-10 CXX=clang++-10 CFLAGS="-g -O2 \
405 -D_GLIBCXX_DEBUG -fsanitize=fuzzer-no-link,address,undefined" \
406 CXXFLAGS="-g -O2 -D_GLIBCXX_DEBUG \
407 -fsanitize=fuzzer-no-link,address,undefined"
408 memory sanitizer issue:
409 ../../configure CC=clang-10 CXX=clang++-10 CFLAGS="-g -O2 \
410 -D_GLIBCXX_DEBUG -fsanitize=fuzzer-no-link,memory,undefined" \
411 CXXFLAGS="-g -O2 -D_GLIBCXX_DEBUG \
412 -fsanitize=fuzzer-no-link,memory,undefined"
413 Build:
414 address sanitizer issue:
415 make fuzzers CXX=clang++-10 CXXFLAGS="-g -O2 -D_GLIBCXX_DEBUG \
416 -fsanitize=fuzzer,address,undefined"
417 memory sanitizer issue:
418 make fuzzers CXX=clang++-10 CXXFLAGS="-g -O2 -D_GLIBCXX_DEBUG \
419 -fsanitize=fuzzer,memory,undefined"
420
421 When an oss-fuzz issue has been created, download the Reproducer
422 Testcase file (e.g, name it "/tmp/payload"). To run one of the
423 fuzzing executables in bin/fuzzer, e.g., pix4_fuzzer:
424 cd ../../prog/fuzzing
425 ../../bin/fuzzer/pix4_fuzzer /tmp/payload
426
427 5. The 270+ programs in the prog directory are an integral part of this
428 package. They can be divided into four groups:
429
430 (1) Programs that are useful applications for running on the
431 command line. They can be installed from autoconf builds
432 using 'make install'. Examples of these are the PostScript
433 and pdf conversion programs: converttopdf, converttops,
434 convertfilestopdf, convertfilestops, convertsegfilestopdf,
435 convertsegfilestops, imagetops, printimage and printsplitimage.
436
437 (2) Programs that are used as regression tests in alltests_reg.
438 These are named *_reg, and 100 of them are invoked together
439 (alltests_reg). The regression test framework has been
440 standardized, and regresstion tests are relatively easy
441 to write. See regutils.h for details.
442
443 (3) Other regression tests, some of which have not (yet) been
444 put into the framework. They are also named *_reg.
445
446 (4) Programs that were used to test library functions or auto-generate
447 library code. These are useful for testing the behavior of small
448 sets of functions and for providing example code.
449
450 6. Sanitizers can be used on all the regression tests in alltests_reg.c.
451
452 First run autogen.sh to generate the configure script
453 autogen.sh
454 Then run configure to generate the Makefile with the address sanitizer
455 ./configure '--disable-shared' '--enable-debug' 'CFLAGS=-D_GLIBCXX_DEBUG -DDEBUG=1 -Wall -pedantic -g -O0 -fsanitize=address,undefined -fstack-protector-strong -ftrapv'
456 Make and run all the regression tests
457 make check
458 </pre>
459
460 <h2> <A NAME="DEPENDENCIES">
461 I/O libraries leptonica is dependent on
462 </h2>
463
464 <pre>
465 Leptonica is configured to handle image I/O using these external
466 libraries: libjpeg, libtiff, libpng, libz, libwebp, libgif, libopenjp2
467
468 These libraries are easy to obtain. For example, using the
469 Debian package manager:
470 sudo apt-get install <package>
471 where <package> = {libpng-dev, libjpeg62-turbo-dev, libtiff5-dev,
472 libwebp-dev, libopenjp2-7-dev, libgif-dev}.
473
474 Leptonica also allows image I/O with bmp and pnm formats, for which
475 we provide the serializers (encoders and decoders). It also
476 gives output drivers for wrapping images in PostScript and PDF, which
477 in turn use tiffg4, jpeg and flate (i.e., zlib) encoding. PDF will
478 also wrap jpeg2000 images.
479
480 There is a programmatic interface to gnuplot. To use it, you
481 need only the gnuplot executable (suggest version 3.7.2 or later);
482 the gnuplot library is not required.
483
484 If you build with automake, libraries on your system will be
485 automatically found and used.
486
487 The rest of this section is for building with the static makefiles.
488 The entries in environ.h specify which of these libraries to use.
489 The default is to link to these four libraries:
490 libjpeg.a (standard jfif jpeg library, version 6b or 7, 8 or 9))
491 libtiff.a (standard Leffler tiff library, version 3.7.4 or later;
492 libpng.a (standard png library, suggest version 1.4.0 or later)
493 libz.a (standard gzip library, suggest version 1.2.3)
494 current non-beta version is 3.8.2)
495
496 These libraries (and their shared versions) should be in /usr/lib.
497 (If they're not, you can change the LDFLAGS variable in the makefile.)
498 Additionally, for compilation, the following header files are
499 assumed to be in /usr/include:
500 jpeg: jconfig.h
501 png: png.h, pngconf.h
502 tiff: tiff.h, tiffio.h
503
504 If for some reason you do not want to link to specific libraries,
505 even if you have them, stub files are included for the ten
506 different output formats:
507 bmp, jpeg, png, pnm, ps, pdf, tiff, gif, webp and jp2.
508 For example, if you don't want to include the tiff library,
509 in environ.h set:
510 #define HAVE_LIBTIFF 0
511 and the stubs will be linked in.
512
513 To read and write webp files:
514 (1) Download libwebp from sourceforge
515 (2) #define HAVE_LIBWEBP 1 (in environ.h)
516 (3) In prog/makefile, edit ALL_LIBS to include -lwebp
517 (4) The library will be installed into /usr/local/lib.
518 You may need to add that directory to LDFLAGS; or, equivalently,
519 add that path to the LD_LIBRARY_PATH environment variable.
520
521 To read and write jpeg2000 files:
522 (1) Download libopenjp2, version 2.3, from their distribution.
523 (2) #define HAVE_LIBJP2K 1 (in environ.h)
524 (2a) If you have version 2.X, X != 3, edit LIBJP2K_HEADER (in environ.h)
525 (3) In prog/makefile, edit ALL_LIBS to include -lopenjp2
526 (4) The library will be installed into /usr/local/lib.
527
528 To read and write gif files:
529 (1) Download version giflib-5.1.X+ from souceforge
530 (2) #define HAVE_LIBGIF 1 (in environ.h)
531 (3) In prog/makefile, edit ALL_LIBS to include -lgif
532 (4) The library will be installed into /usr/local/lib.
533 </pre>
534
535
536 <h2> <A NAME="DOXYGEN">
537 Generating documentation using doxygen
538 </h2>
539
540 <pre>
541 The source code is set up to allow generation of documentation using doxygen.
542 To do this:
543 (1) Download the Debian doxygen package:
544 sudo apt-get install doxygen
545 (2) In the root client directory containing Doxyfile:
546 doxygen Doxyfile
547 The documentation will be generated in a 'doc' subdirectory, accessible
548 from this file (relative to the root)
549 ./doc/html/index.html
550 </pre>
551
552
553 <h2> <A NAME="DEVELOP">
554 Developing with leptonica
555 </h2>
556
557 <pre>
558 You are encouraged to use the static makefiles if you are developing
559 applications using leptonica. The following instructions assume
560 that you are using the static makefiles and customizing environ.h.
561
562 1. Automatic generation of prototypes
563
564 The prototypes are automatically generated by the program xtractprotos.
565 They can either be put in-line into allheaders.h, or they can be
566 written to a file leptprotos.h, which is #included in allheaders.h.
567 Note: (1) We supply the former version of allheaders.h.
568 (2) all .c files simply include allheaders.h.
569
570 First, make xtractprotos:
571 make xtractprotos
572
573 Then to generate the prototypes and make allheaders.h, do one of
574 these two things:
575 make allheaders [puts everything into allheaders.h]
576 make allprotos [generates a file leptprotos.h containing the
577 function prototypes, and includes it in allheaders.h]
578
579 Things to note about xtractprotos, assuming that you are developing
580 in Leptonica and need to regenerate the prototypes in allheaders.h:
581
582 (1) xtractprotos is part of Leptonica. You can 'make' it in either
583 src or prog (see the makefile).
584 (2) You can output the prototypes for any C file to stdout by running:
585 xtractprotos <cfile> or
586 xtractprotos -prestring=[string] <cfile>
587 (3) The source for xtractprotos has been packaged up into a tar
588 containing just the Leptonica files necessary for building it
589 in Linux. The tar file is available at:
590 www.leptonica.com/source/xtractlib-1.5.tar.gz
591
592 2. Global parameter to enable development and testing
593
594 For security reasons, with the exception of the regression utility
595 (regutils.c), leptonica as shipped (starting with 1.77) does not allow:
596 * 'system(3)' fork/exec
597 * writes to temp files with compiled-in names
598 System calls are used either to run gnuplot or display an image on
599 the screen.
600
601 This is enforced with a global parameter, LeptDebugOK, initialized to 0.
602 It can be overridden either at compile time by changing the initialization
603 (in writefile.c), or at runtime, using setLeptDebugOK().
604 The programs in the prog directory, which mostly test functions in
605 the library, are not subject to this restriction.
606
607 3. GNU runtime functions for stream redirection to memory
608
609 There are two non-standard gnu functions, fmemopen() and open_memstream(),
610 that only work on Linux and conveniently allow memory I/O with a file
611 stream interface. This is convenient for compressing and decompressing
612 image data to memory rather than to file. Stubs are provided
613 for all these I/O functions. Default is to enable them; OSX developers
614 must disable by setting #define HAVE_FMEMOPEN 0 (in environ.h).
615 If these functions are not enabled, raster to compressed data in
616 memory is accomplished safely but through a temporary file.
617 See 9 for more details on image I/O formats.
618
619 If you're building with the autoconf programs, these two functions are
620 automatically enabled if available.
621
622 4. Runtime functions not available on all platforms
623
624 Some functions are not available on all systems. One example of such a
625 function is fstatat(). If possible, such functions will be replaced by
626 wrappers, stubs or behavioral equivalent functions. By default, such
627 functions are disabled; enable them by setting #define HAVE_FUNC 1 (in
628 environ.h).
629
630 If you're building with the autoconf or cmake programs, these functions are
631 automatically enabled if available.
632
633 5. Typedefs
634
635 A deficiency of C is that no standard has been universally
636 adopted for typedefs of the built-in types. As a result,
637 typedef conflicts are common, and cause no end of havoc when
638 you try to link different libraries. If you're lucky, you
639 can find an order in which the libraries can be linked
640 to avoid these conflicts, but the state of affairs is aggravating.
641
642 The most common typedefs use lower case variables: uint8, int8, ...
643 The png library avoids typedef conflicts by altruistically
644 appending "png_" to the type names. Following that approach,
645 Leptonica appends "l_" to the type name. This should avoid
646 just about all conflicts. In the highly unlikely event that it doesn't,
647 here's a simple way to change the type declarations throughout
648 the Leptonica code:
649 (1) customize a file "converttypes.sed" with the following lines:
650 /l_uint8/s//YOUR_UINT8_NAME/g
651 /l_int8/s//YOUR_INT8_NAME/g
652 /l_uint16/s//YOUR_UINT16_NAME/g
653 /l_int16/s//YOUR_INT16_NAME/g
654 /l_uint32/s//YOUR_UINT32_NAME/g
655 /l_int32/s//YOUR_INT32_NAME/g
656 /l_float32/s//YOUR_FLOAT32_NAME/g
657 /l_float64/s//YOUR_FLOAT64_NAME/g
658 (2) in the src and prog directories:
659 - if you have a version of sed that does in-place conversion:
660 sed -i -f converttypes.sed *
661 - else, do something like (in csh)
662 foreach file (*)
663 sed -f converttypes.sed $file > tempdir/$file
664 end
665
666 If you are using Leptonica with a large code base that typedefs the
667 built-in types differently from Leptonica, just edit the typedefs
668 in environ.h. This should have no side-effects with other libraries,
669 and no issues should arise with the location in which liblept is
670 included.
671
672 For compatibility with 64 bit hardware and compilers, where
673 necessary we use the typedefs in stdint.h to specify the pointer
674 size (either 4 or 8 byte).
675
676 6. Compile and runtime control over stderr output (see environ.h and utils1.c)
677
678 Leptonica provides both compile-time and run-time control over
679 messages and debug output (thanks to Dave Bryan). Both compile-time
680 and run-time severity thresholds can be set. The runtime threshold
681 can also be set by an environmental variable. Messages are
682 vararg-formatted and of 3 types: error, warning, informational.
683 These are all macros, and can be further suppressed when
684 NO_CONSOLE_IO is defined on the compile line. For production code
685 where no output is to go to stderr, compile with -DNO_CONSOLE_IO.
686
687 Runtime redirection of stderr output is also possible, using a
688 callback mechanism. The callback function is registered using
689 leptSetStderrHandler(). See utils1.c for details.
690
691 7. In-memory raster format (Pix)
692
693 Unlike many other open source packages, Leptonica uses packed
694 data for images with all bit/pixel (bpp) depths, allowing us
695 to process pixels in parallel. For example, rasterops works
696 on all depths with 32-bit parallel operations throughout.
697 Leptonica is also explicitly configured to work on both little-endian
698 and big-endian hardware. RGB image pixels are always stored
699 in 32-bit words, and a few special functions are provided for
700 scaling and rotation of RGB images that have been optimized by
701 making explicit assumptions about the location of the R, G and B
702 components in the 32-bit pixel. In such cases, the restriction
703 is documented in the function header. The in-memory data structure
704 used throughout Leptonica to hold the packed data is a Pix,
705 which is defined and documented in pix.h. The alpha component
706 in RGB images is significantly better supported, starting in 1.70.
707
708 Additionally, a FPix is provided for handling 2D arrays of floats,
709 and a DPix is provided for 2D arrays of doubles. Converters
710 between these and the Pix are given.
711
712 8. Conversion between Pix and other in-memory raster formats
713
714 . If you use Leptonica with other imaging libraries, you will need
715 functions to convert between the Pix and other image data
716 structures. To make a Pix from other image data structures, you
717 will need to understand pixel packing, pixel padding, component
718 ordering and byte ordering on raster lines. See the file pix.h
719 for the specification of image data in the pix.
720
721 9. Custom memory management
722
723 Leptonica allows you to use custom memory management (allocator,
724 deallocator). For Pix, which tend to be large, the alloc/dealloc
725 functions can be set programmatically. For all other structs and arrays,
726 the allocators are specified in environ.h. Default functions
727 are malloc and free. We have also provided a sample custom
728 allocator/deallocator for Pix, in pixalloc.c.
729 </pre>
730
731
732 <h2> <A NAME="CONTENTS">
733 What's in leptonica?
734 </h2>
735 <pre>
736 1. Rasterops
737
738 This is a source for a clean, fast implementation of rasterops.
739 You can find details starting at the Leptonica home page,
740 and also by looking directly at the source code.
741 Some of the low-level code is in roplow.c, and an interface is
742 given in rop.c to the simple Pix image data structure.
743
744 2. Binary morphology
745
746 This is a source for efficient implementations of binary morphology
747 Details are found starting at the Leptonica home page, and by reading
748 the source code.
749
750 Binary morphology is implemented two ways:
751
752 (a) Successive full image rasterops for arbitrary
753 structuring elements (Sels)
754
755 (b) Destination word accumulation (dwa) for specific Sels.
756 This code is automatically generated. See, for example,
757 the code in fmorphgen.1.c and fmorphgenlow.1.c.
758 These files were generated by running the program
759 prog/fmorphautogen.c. Results can be checked by comparing dwa
760 and full image rasterops; e.g., prog/fmorphauto_reg.c.
761
762 Method (b) is considerably faster than (a), which is the
763 reason we've gone to the effort of supporting the use
764 of this method for all Sels. We also support two different
765 boundary conditions for erosion.
766
767 Similarly, dwa code for the general hit-miss transform can
768 be auto-generated from an array of hit-miss Sels.
769 When prog/fhmtautogen.c is compiled and run, it generates
770 the dwa C code in fhmtgen.1.c and fhmtgenlow.1.c. These
771 files can then be compiled into the libraries or into other programs.
772 Results can be checked by comparing dwa and rasterop results;
773 e.g., prog/fhmtauto_reg.c
774
775 Several functions with simple parsers are provided to execute a
776 sequence of morphological operations (plus binary rank reduction
777 and replicative expansion). See morphseq.c.
778
779 The structuring element is represented by a simple Sel data structure
780 defined in morph.h. We provide (at least) seven ways to generate
781 Sels in sel1.c, and several simple methods to generate hit-miss
782 Sels for pattern finding in selgen.c.
783
784 In use, the most common morphological Sels are separable bricks,
785 of dimension n x m (where either n or m, but not both, is commonly 1).
786 Accordingly, we provide separable morphological operations on brick
787 Sels, using for binary both rasterops and dwa. Parsers are provided
788 for a sequence of separable binary (rasterop and dwa) and grayscale
789 brick morphological operations, in morphseq.c. The main
790 advantage in using the parsers is that you don't have to create
791 and destroy Sels, or do any of the intermediate image bookkeeping.
792
793 We also give composable separable brick functions for binary images,
794 for both rasterop and dwa. These decompose each of the linear
795 operations into a sequence of two operations at different scales,
796 reducing the operation count to a sum of decomposition factors,
797 rather than the (un-decomposed) product of factors.
798 As always, parsers are provided for a sequence of such operations.
799
800 3. Grayscale morphology and rank order filters
801
802 We give an efficient implementation of grayscale morphology for brick
803 Sels. See the Leptonica home page and the source code.
804
805 Brick Sels are separable into linear horizontal and vertical elements.
806 We use the van Herk/Gil-Werman algorithm, that performs the calculations
807 in a time that is independent of the size of the Sels. Implementations
808 of tophat and hdome are also given.
809
810 We also provide grayscale rank order filters for brick filters.
811 The rank order filter is a generalization of grayscale morphology,
812 that selects the rank-valued pixel (rather than the min or max).
813 A color rank order filter applies the grayscale rank operation
814 independently to each of the (r,g,b) components.
815
816 4. Image scaling
817
818 Leptonica provides many simple and relatively efficient
819 implementations of image scaling. Some of them are listed here;
820 for the full set see the web page and the source code.
821
822 Grayscale and color images are scaled using:
823 - sampling
824 - lowpass filtering followed by sampling,
825 - area mapping
826 - linear interpolation
827
828 Scaling operations with antialiased sampling, area mapping,
829 and linear interpolation are limited to 2, 4 and 8 bpp gray,
830 24 bpp full RGB color, and 2, 4 and 8 bpp colormapped
831 (bpp == bits/pixel). Scaling operations with simple sampling
832 can be done at 1, 2, 4, 8, 16 and 32 bpp. Linear interpolation
833 is slower but gives better results, especially for upsampling.
834 For moderate downsampling, best results are obtained with area
835 mapping scaling. With very high downsampling, either area mapping
836 or antialias sampling (lowpass filter followed by sampling) give
837 good results. Fast area map with power-of-2 reduction are also
838 provided. Optional sharpening after resampling is provided to
839 improve appearance by reducing the visual effect of averaging
840 across sharp boundaries.
841
842 For fast analysis of grayscale and color images, it is useful to
843 have integer subsampling combined with pixel depth reduction.
844 RGB color images can thus be converted to low-resolution
845 grayscale and binary images.
846
847 For binary scaling, the dest pixel can be selected from the
848 closest corresponding source pixel. For the special case of
849 power-of-2 binary reduction, low-pass rank-order filtering can be
850 done in advance. Isotropic integer expansion is done by pixel replication.
851
852 We also provide 2x, 3x, 4x, 6x, 8x, and 16x scale-to-gray reduction
853 on binary images, to produce high quality reduced grayscale images.
854 These are integrated into a scale-to-gray function with arbitrary
855 reduction.
856
857 Conversely, we have special 2x and 4x scale-to-binary expansion
858 on grayscale images, using linear interpolation on grayscale
859 raster line buffers followed by either thresholding or dithering.
860
861 There are also image depth converters that don't have scaling,
862 such as unpacking operations from 1 bpp to grayscale, and
863 thresholding and dithering operations from grayscale to 1, 2 and 4 bpp.
864
865 5. Image shear and rotation (and affine, projective, ...)
866
867 Image shear is implemented with both rasterops and linear interpolation.
868 The rasterop implementation is faster and has no constraints on image
869 depth. We provide horizontal and vertical shearing about an
870 arbitrary point (really, a line), both in-place and from source to dest.
871 The interpolated shear is used on 8 bpp and 32 bpp images, and
872 gives a smoother result. Shear is used for the fastest implementations
873 of rotation.
874
875 There are three different types of general image rotators:
876
877 a. Grayscale rotation using area mapping
878 - pixRotateAM() for 8 bit gray and 24 bit color, about center
879 - pixRotateAMCorner() for 8 bit gray, about image UL corner
880 - pixRotateAMColorFast() for faster 24 bit color, about center
881
882 b. Rotation of an image of arbitrary bit depth, using
883 either 2 or 3 shears. These rotations can be done
884 about an arbitrary point, and they can be either
885 from source to dest or in-place; e.g.
886 - pixRotateShear()
887 - pixRotateShearIP()
888
889 c. Rotation by sampling. This can be used on images of arbitrary
890 depth, and done about an arbitrary point. Colormaps are retained.
891
892 The area mapping rotations are slower and more accurate, because each
893 new pixel is composed using an average of four neighboring pixels
894 in the original image; this is sometimes also also called "antialiasing".
895 Very fast color area mapping rotation is provided.
896
897 The shear rotations are much faster, and work on images of arbitrary
898 pixel depth, but they just move pixels around without doing any averaging.
899 The pixRotateShearIP() operates on the image in-place.
900
901 We also provide orthogonal rotators (90, 180, 270 degree; left-right
902 flip and top-bottom flip) for arbitrary image depth.
903 And we provide implementations of affine, projective and bilinear
904 transforms, with both sampling (for speed) and interpolation
905 (for antialiasing).
906
907 6. Sequential algorithms
908
909 We provide a number of fast sequential algorithms, including
910 binary and grayscale seedfill, and the distance function for
911 a binary image. The most efficient binary seedfill is
912 pixSeedfill(), which uses Luc Vincent's algorithm to iterate
913 raster- and antiraster-ordered propagation, and can be used
914 for either 4- or 8-connected fills. Similar raster/antiraster
915 sequential algorithms are used to generate a distance map from
916 a binary image, and for grayscale seedfill. We also use Heckbert's
917 stack-based filling algorithm for identifying 4- and 8-connected
918 components in a binary image. A fast implementation of the
919 watershed transform, using a priority queue, is included.
920
921 7. Image enhancement
922
923 Some simple image enhancement routines for grayscale and color
924 images have been provided. These include intensity mapping with
925 gamma correction and contrast enhancement, histogram equalization,
926 edge sharpening, smoothing, and various color-shifting operations.
927
928 8. Convolution and cousins
929
930 A number of standard image processing operations are also
931 included, such as block convolution, binary block rank filtering,
932 grayscale and rgb rank order filtering, and edge and local
933 minimum/maximum extraction. Generic convolution is included,
934 for both separable and non-separable kernels, using float arrays
935 in the Pix. Two implementations are included for grayscale and
936 color bilateral filtering: a straightforward (slow) one, and a
937 fast, approximate, separable one.
938
939 9. Image I/O
940
941 Some facilities have been provided for image input and output.
942 This is of course required to build executables that handle images,
943 and many examples of such programs, most of which are for
944 testing, can be built in the prog directory. Functions have been
945 provided to allow reading and writing of files in JPEG, PNG,
946 TIFF, BMP, PNM ,GIF, WEBP and JP2 formats. These formats were chosen
947 for the following reasons:
948
949 - JFIF JPEG is the standard method for lossy compression
950 of grayscale and color images. It is supported natively
951 in all browsers, and uses a good open source compression
952 library. Decompression is supported by the rasterizers
953 in PS and PDF, for level 2 and above. It has a progressive
954 mode that compresses about 10% better than standard, but
955 is considerably slower to decompress. See jpegio.c.
956
957 - PNG is the standard method for lossless compression
958 of binary, grayscale and color images. It is supported
959 natively in all browsers, and uses a good open source
960 compression library (zlib). It is superior in almost every
961 respect to GIF (which, until recently, contained proprietary
962 LZW compression). See pngio.c.
963
964 - TIFF is a common interchange format, which supports different
965 depths, colormaps, etc., and also has a relatively good and
966 widely used binary compression format (CCITT Group 4).
967 Decompression of G4 is supported by rasterizers in PS and PDF,
968 level 2 and above. G4 compresses better than PNG for most
969 text and line art images, but it does quite poorly for halftones.
970 It has good and stable support by Leffler's open source library,
971 which is clean and small. Tiff also supports multipage
972 images through a directory structure. Note: because jpeg is
973 a supported tiff compression mode, leptonica requires linking
974 both libtiff and libjpeg to read and write tiff. See tiffio.c
975
976 - BMP has (until recently) had no compression. It is a simple
977 format with colormaps that requires no external libraries.
978 It is commonly used because it is a Microsoft standard,
979 but has little besides simplicity to recommend it. See bmpio.c.
980
981 - PNM is a very simple, old format that still has surprisingly
982 wide use in the image processing community. It does not
983 support compression or colormaps, but it does support binary,
984 grayscale and rgb images. Like BMP, the implementation
985 is simple and requires no external libraries. See pnmio.c.
986
987 - WEBP is a new wavelet encoding method derived from libvpx,
988 a video compression library. It is rapidly growing in acceptance,
989 and is supported natively in several browsers. Leptonica provides
990 an interface through webp into the underlying codec. You need
991 to download libwebp. See webpio.c.
992
993 - JP2 (jpeg2000) is a wavelet encoding method, that has clear
994 advantages over jpeg in compression and quality (especially when
995 the image has sharp edges, such as scanned documents), but is
996 only slowly growing in acceptance. For it to be widely supported,
997 it will require support on a major browser (as with webp).
998 Leptonica provides an interface through openjpeg into the underlying
999 codec. You need to download libopenjp2, version 2.X. See jp2kio.c.
1000
1001 - GIF is still widely used in the world. With the expiration
1002 of the LZW patent, it is practical to add support for GIF files.
1003 The open source gif library is relatively incomplete and
1004 unsupported (because of the Sperry-Rand-Burroughs-Univac
1005 patent history). Leptonica supports versions 5.1+. See gifio.c.
1006
1007 Here's a summary of compression support and limitations:
1008 - All formats except JPEG, WEBP and JP2K support 1 bpp binary.
1009 - All formats support 8 bpp grayscale (GIF must have a colormap).
1010 - All formats except GIF support rgb color.
1011 - All formats except PNM, JPEG, WEBP and JP2K support 8 bpp colormap.
1012 - PNG and PNM support 2 and 4 bpp images.
1013 - PNG supports 2 and 4 bpp colormap, and 16 bpp without colormap.
1014 - PNG, JPEG, TIFF, WEBP, JP2K and GIF support image compression;
1015 PNM and BMP do not.
1016 - WEBP supports rgb color and rgba.
1017 - JP2 supports 8 bpp grayscale, rgb color and rgba.
1018 Use prog/ioformats_reg for a regression test on all formats, including
1019 thorough testing on TIFF.
1020 For more thorough testing on other formats, use:
1021 - prog/pngio_reg for PNG.
1022 - prog/gifio_reg for GIF
1023 - prog/webpio_reg for WEBP
1024 - prog/jp2kio_reg for JP2
1025
1026 We provide generators for PS output, from all types of input images.
1027 The output can be either uncompressed or compressed with level 2
1028 (ccittg4 or dct) or level 3 (flate) encoding. You have flexibility
1029 for scaling and placing of images, and for printing at different
1030 resolutions. You can also compose mixed raster (text, image) PS.
1031 See psio1.c for examples of how to output PS for different applications.
1032 As examples of usage, see:
1033 * prog/converttops.c for a general image --> PS conversion
1034 for printing. You can specify the PS compression level (1, 2, or 3).
1035 * prog/imagetops.c for a special image --> PS conversion
1036 for printing at maximum size on 8.5 x 11 paper. You can
1037 specify the PS compression level (1, 2, or 3).
1038 * prog/convertfilestops.c to generate a multipage level 3 compressed
1039 PS file that can then be converted to pdf with ps2pdf.
1040 * prog/convertsegfilestops.c to generate a multipage, mixed raster,
1041 level 2 compressed PS file.
1042
1043 We provide generators for PDF output, again from all types of input
1044 images, and with ccittg4, dct, flate and jpx (jpeg2000) compression.
1045 You can do the following for PDF:
1046 * Put any number of images onto a page, with specified input
1047 resolution, location and compression.
1048 * Write a mixed raster PDF, given an input image and a segmentation
1049 mask. Non-image regions are written in G4 (fax) encoding.
1050 * Concatenate single-page PDF wrapped images into a single PDF file.
1051 * Build a PDF file of all images in a directory or array of file names.
1052 As examples of usage, see:
1053 * prog/converttopdf.c: fast pdf generation with one image/page.
1054 For speed, this avoids transcoding whenever possible.
1055 * prog/convertfilestopdf.c: more flexibility in the output. You
1056 can set the resolution, scaling, encoding type and jpeg quality.
1057 * prog/convertsegfilestopdf.c: generates a multipage, mixed raster pdf,
1058 with separate controls for compressing text and non-text regions.
1059
1060 Note: any or all of these I/O library calls can be stubbed out at
1061 compile time, using the environment variables in environ.h.
1062
1063 For all formatted reads and writes, we support read from memory
1064 and write to memory. The gnu C runtime library (glibc) supports
1065 two I/O functions, open_memstream() and fmemopen(), which read
1066 and write directly to memory as if writing to a file stream.
1067 * On all platforms, leptonica supports direct read/write with memory
1068 for TIFF, PNG, BMP, GIF and WEBP formats.
1069 * On linux, leptonica uses the special gnu libraries to enable
1070 direct read/write with memory for JPEG, PNM and JP2.
1071 * On platforms without the gnu libraries, such as OSX, Windows
1072 and Solaris, read/write with memory for JPEG, PNM and JP2 goes
1073 through temp files.
1074 To enable/disable memory I/O for image read/write, see environ.h.
1075
1076 We also provide fast serialization and deserialization between a pix
1077 in memory and a file (spixio.c). This works on all types of pix images.
1078
1079 10. Colormap removal and color quantization
1080
1081 Leptonica provides functions that remove colormaps, for conversion
1082 to either 8 bpp gray or 24 bpp RGB. It also provides the inverse
1083 function to colormap removal; namely, color quantization
1084 from 24 bpp full color to 8 bpp colormap with some number
1085 of colormap colors. Several versions are provided, some that
1086 use a fast octree vector quantizer and others that use
1087 a variation of the median cut quantizer. For high-level interfaces,
1088 see for example: pixConvertRGBToColormap(), pixOctreeColorQuant(),
1089 pixOctreeQuantByPopulation(), pixFixedOctcubeQuant256(),
1090 and pixMedianCutQuant().
1091
1092 11. Programmatic image display
1093
1094 For debugging, pixDisplay() and pixDisplayWithTitle() in writefile.c
1095 can be called to display an image using one of several display
1096 programs (xzgv, xli, xv, l_view). If necessary to fit on the screen,
1097 the image is reduced in size, with 1 bpp images being converted
1098 to grayscale for readability. Another common debug method is to
1099 accumulate intermediate images in a pixa, and then either view these
1100 as a mosaic (using functions in pixafunc2.c), or gather them into
1101 a compressed PDF or PostScript file for viewing with evince. Common
1102 image display programs are: xzgv, xli, xv, display, gthumb, gqview,
1103 evince, gv and acroread.
1104
1105 12. Document image analysis
1106
1107 Many functions have been included specifically to help with
1108 document image analysis. These include skew and text orientation
1109 detection; page segmentation; baseline finding for text;
1110 unsupervised classification of connected components, characters
1111 and words; dewarping camera images; adaptive binarization; and
1112 a simple book-adaptive classifier for various character sets,
1113 segmentation for newspaper articles, etc.
1114
1115 13. Data structures
1116
1117 Several simple data structures are provided for safe and efficient handling
1118 of arrays of numbers, strings, pointers, and bytes. The generic
1119 pointer array is implemented in four ways: as a stack, a queue,
1120 a heap (used to implement a priority queue), and an array with
1121 insertion and deletion, from which the stack operations form a subset.
1122 Byte arrays are implemented both as a wrapper around the actual
1123 array and as a queue. The string arrays are particularly useful
1124 for both parsing and composing text. Generic lists with
1125 doubly-linked cons cells are also provided. Other data structures
1126 are provided for handling ordered sets and maps, as well as hash sets
1127 and hash maps.
1128
1129 14. Examples of programs that are easily built using the library:
1130
1131 - for plotting x-y data, we give a programmatic interface
1132 to the gnuplot program, with output to X11, png, ps or eps.
1133 We also allow serialization of the plot data, in a form
1134 such that the data can be read, the commands generated,
1135 and (finally) the plot constructed by running gnuplot.
1136
1137 - a simple jbig2-type classifier, using various distance
1138 metrics between image components (correlation, rank
1139 hausdorff); see prog/jbcorrelation.c, prog/jbrankhaus.c.
1140
1141 - a simple color segmenter, giving a smoothed image
1142 with a small number of the most significant colors.
1143
1144 - a program for converting all images in a directory
1145 to a PostScript file, and a program for printing an image
1146 in any (supported) format to a PostScript printer.
1147
1148 - various programs for generating pdf files from compressed
1149 images, including very fast ones that don't scale and
1150 avoid transcoding if possible.
1151
1152 - converters between binary images and SVG format.
1153
1154 - an adaptive recognition utility for training and identifying
1155 text characters in a multipage document such as a book.
1156
1157 - a bitmap font facility that allows painting text onto
1158 images. We currently support one font in several sizes.
1159 The font images and postscript programs for generating
1160 them are stored in prog/fonts/, and also as compiled strings
1161 in bmfdata.h.
1162
1163 - a binary maze game lets you generate mazes and find shortest
1164 paths between two arbitrary points, if such a path exists.
1165 You can also compute the "shortest" (i.e., least cost) path
1166 between points on a grayscale image.
1167
1168 - a 1D barcode reader. This is still in an early stage of development,
1169 with little testing, and it only decodes 6 formats.
1170
1171 - a utility that will dewarp images of text that were captured
1172 with a camera at close range.
1173
1174 - a sudoku solver and generator, including a good test for uniqueness
1175
1176 - see (13, above) for other document image applications.
1177
1178 15. JBig2 encoder
1179
1180 Leptonica supports an open source jbig2 encoder (yes, there is one!),
1181 which can be downloaded from:
1182 http://www.imperialviolet.org/jbig2.html.
1183 To build the encoder, use the most recent version. This bundles
1184 Leptonica 1.63. Once you've built the encoder, use it to compress
1185 a set of input image files: (e.g.)
1186 ./jbig2 -v -s <imagefile1 ...> > <jbig2_file>
1187 You can also generate a pdf wrapping for the output jbig2. To do that,
1188 call jbig2 with the -p arg, which generates a symbol file (output.sym)
1189 plus a set of location files for each input image (output.0000, ...):
1190 ./jbig2 -v -s -p <imagefile1 ...>
1191 and then generate the pdf:
1192 python pdf.py output > <pdf_file>
1193 See the usage documentation for the jbig2 compressor at:
1194 http://www.imperialviolet.org/binary/jbig2enc.html
1195 You can uncompress the jbig2 files using jbig2dec, which can be
1196 downloaded and built from:
1197 http://jbig2dec.sourceforge.net/
1198
1199 16. Versions
1200
1201 New versions of the Leptonica library are released several times
1202 a year, and version numbers are provided for each release in the
1203 following files:
1204 src/makefile.static
1205 CMakeLists.txt
1206 configure.ac
1207 allheaders_top.txt (and propagated to allheaders.h)
1208 All even versions from 1.42 to 1.60 were originally archived at
1209 http://code.google.com/p/leptonica, as well as all versions after 1.60.
1210 These have now been transferred by Egor Pugin to github:
1211 github.com/danbloomberg/leptonica
1212 where all releases (1.42 - 1.85.0) are available; e.g.,
1213 https://github.com/DanBloomberg/leptonica/releases/tag/1.85.0
1214 The more recent releases, from 1.80, are also available at
1215 leptonica.org/download.html
1216 Note that if you are downloading from github, the releases are more
1217 likely to be stable than the master. Also, if you download from
1218 the master and use autotools (e.g., Makefile.am), you must first run
1219 autogen.sh to generate the configure program and the Makefiles.
1220
1221 The number of downloads of leptonica increased by nearly an order
1222 of magnitude with 1.69, due to bundling with tesseract and
1223 incorporation in ubuntu 12-04. Jeff Breidenbach has built all
1224 the Debian releases, which require release version numbers.
1225 The Debian binary release versions to date are:
1226 1.69 : 3.0.0
1227 1.70 : 4.0.0
1228 1.71 : 4.2.0
1229 1.72 : 4.3.0
1230 1.73 : 5.0.0
1231 1.74 : 5.1.0
1232 1.75 : 5.2.0
1233 1.76 : 5.3.0
1234 1.77 : 5.3.0
1235 1.78 : 5.3.0
1236 1.79 : 5.4.0
1237 1.80 : 5.4.0
1238 1.81 : 5.4.0
1239 1.82 : 5.4.0
1240 1.83 : 6.0.0
1241 1.84 : 6.0.0
1242 1.85 : 6.0.0 (in progress)
1243
1244 A brief version chronology is maintained in version-notes.html.
1245 Starting with gcc 4.3.3, error warnings (-Werror) are given for
1246 minor infractions like not checking return values of built-in C
1247 functions. I have attempted to eliminate these warnings.
1248 In any event, you will see warnings with the -Wall flag.
1249
1250 </pre>
1251
1252 <!-- JS Window Closer -----
1253 <form>
1254 <center>
1255 <input type="button" onclick="window.close();" value="Close this window">
1256 </center>
1257 </form>
1258 ----- JS Window Closer -->
1259
1260 </body>
1261 </html>