4 <!-- JS Window Closer -----
7 <input type="button" onclick="window.close();" value="Close this window">
10 ----- JS Window Closer -->
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 -->
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#">
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>
29 <dc:title>Dan S. Bloomberg</dc:title>
32 <dc:title>Dan S. Bloomberg</dc:title>
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/" />
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" />
52 /*====================================================================*
53 - Copyright (C) 2001 Leptonica. All rights reserved.
55 - Redistribution and use in source and binary forms, with or without
56 - modification, are permitted provided that the following conditions
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.
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 *====================================================================*/
78 README (1.73: 25 Jan 2016)
79 ---------------------------
81 gunzip leptonica-1.73.tar.gz
82 tar -xvf leptonica-1.73.tar
86 <!--Navigation Panel-->
89 <A HREF="#BUILDING">Building leptonica</A><br>
90 <A HREF="#DEPENDENCIES">I/O libraries leptonica is dependent on</A><br>
91 <A HREF="#DEVELOP">Developing with leptonica</A><br>
92 <A HREF="#CONTENTS">What's in leptonica?</A><br>
95 <!--End of Navigation Panel-->
98 <h2> <A NAME="BUILDING">
106 (1) src: library source and function prototypes for building liblept
107 (2) prog: source for regression test, usage example programs, and
109 for building on these platforms:
110 - Linux on x86 (i386) and AMD 64 (x64)
111 - OSX (both powerPC and x86).
112 - Cygwin, msys and mingw on x86
113 There is an additional zip file for building with MS Visual Studio.
115 Libraries, executables and prototypes are easily made, as described below.
117 When you extract from the archive, all files are put in a
118 subdirectory 'leptonica-1.73'. In that directory you will
119 find a src directory containing the source files for the library,
120 and a prog directory containing source files for various
121 testing and example programs.
123 2. Building on Linux/Unix/MacOS
125 There are three ways to build the library:
127 (1) By customization: Use the existing static makefile,
128 src/makefile.static and customize the build by setting flags
129 in src/environ.h. See src/environ.h and src/makefile for details.
130 Note: if you are going to develop with leptonica, I encourage
131 you to use the static makefiles.
133 (2) Using autoconf (supported by James Le Cuirot).
134 Run ./configure in this directory to
135 build Makefiles here and in src. Autoconf handles the
136 following automatically:
137 * architecture endianness
138 * enabling Leptonica I/O image read/write functions that
139 depend on external libraries (if the libraries exist)
140 * enabling functions for redirecting formatted image stream
141 I/O to memory (on linux only)
142 After running ./configure: make; make install. There's also
143 a 'make check' for testing.
145 (3) Using cmake (supported by Egor Pugin).
146 The build must always be in a different directory from the root
147 of the source (here). It is common to build in a subdirectory
148 of the root. From here:
153 Alternatively, from here:
155 cmake -H . -Bbuild (-H means the source directory,
156 -B means the director for the build
158 To clean out the current build, just remove everything in
159 the build subdirectory.
163 (1) Customization using the static makefiles:
165 * FIRST THING: Run make-for-local. This simply renames
166 src/makefile.static --> src/makefile
167 prog/makefile.static --> prog/makefile
168 [Note: the autoconf build will not work if you have any files
169 named "makefile" in src or prog. If you've already run
170 make-for-local and renamed the static makefiles, and you then
171 want to build with autoconf, run make-for-auto to rename them
172 back to makefile.static.]
174 * You can customize for:
175 (a) Including Leptonica I/O functions that depend on external
176 libraries [use flags in src/environ.h]
177 (b) Adding functions for redirecting formatted image stream
178 I/O to memory [use flag in src/environ.h]
179 (c) Specifying the location of the object code. By default it
180 goes into a tree whose root is also the parent of the src
181 and prog directories. This can be changed using the
182 ROOT_DIR variable in makefile.
185 - To make an optimized version of the library (in src):
187 - To make a debug version of the library (in src):
189 - To make a shared library version (in src):
190 make SHARED=yes shared
191 - To make the prototype extraction program (in src):
192 make (to make the library first)
195 * To use shared libraries, you need to include the location of
196 the shared libraries in your LD_LIBRARY_PATH.
198 * To make the programs in the prog directory, first make liblept
199 in src. Then in prog you can customize the makefile for linking
200 the external libraries:
201 Finally, do 'make' in the prog directory.
203 VERY IMPORTANT: the 240+ programs in the prog directory are
204 an integral part of this package. These can be divided into
206 (1) Programs that are useful applications for running on the
207 command line. They can be installed from autoconf builds
208 using 'make install'. Examples of these are the PostScript
209 and pdf conversion programs: converttopdf, converttops,
210 convertfilestopdf, convertfilestops, convertsegfilestopdf,
211 convertsegfilestops, printimage and printsplitimage.
212 (2) Programs that are used as regression tests in alltests_reg.
213 These are named *_reg, and 66 of them are invoked together
214 (alltests_reg). The regression test framework has been
215 standardized, and regresstion tests are relatively easy
216 to write. See regutils.h for details.
217 (3) Other regression tests, some of which have not (yet) been
218 put into the framework. They are also named *_reg.
219 (4) Programs that were used to test library functions or
220 auto-generate library code. These are useful for testing
221 the behavior of small sets of functions, and for
222 providing example code.
224 (2) Building using autoconf (Thanks to James Le Cuirot)
226 Use the standard incantation, in the root directory (the
227 directory with configure):
228 ./configure [build the Makefile]
229 make [builds the library and shared library versions of
231 make install [as root; this puts liblept.a into /usr/local/lib/
232 and 13 of the the progs into /usr/local/bin/ ]
233 make [-j2] check [runs the alltests_reg set of regression tests.
234 This works even if you build in a different
235 place from the distribution. The -j parameter
236 should not exceed half the number of cores.
237 If the test fails, just run with 'make check']
239 Configure also supports building in a separate directory from the
240 source. Run "/(path-to)/leptonica-1.73/configure" and then "make"
241 from the desired build directory.
243 Configure has a number of useful options; run "configure --help" for
244 details. If you're not planning to modify the library, adding the
245 "--disable-dependency-tracking" option will speed up the build. By
246 default, both static and shared versions of the library are built. Add
247 the "--disable-shared" or "--disable-static" option if one or the other
248 isn't needed. To skip building the programs, use "--disable-programs".
250 By default, the library is built with debugging symbols. If you do not
251 want these, use "CFLAGS=-O2 ./configure" to eliminate symbols for
252 subsequent compilations, or "make CFLAGS=-O2" to override the default
253 for compilation only. Another option is to use the 'install-strip'
254 target (i.e., "make install-strip") to remove the debugging symbols
255 when the library is installed.
257 Finally, if you find that the installed programs are unable to link
258 at runtime to the installed library, which is in /usr/local/lib,
259 try to run configure in this way:
260 LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" ./configure
261 which causes the compiler to pass those options through to the linker.
263 For the debian distribution, out of all the programs in the prog
264 directory, we only build a small subset of general purpose
265 utility programs. This subset is the same set of programs that
266 'make install' puts into /usr/local/bin. It has no dependency on
267 the image files that are bundled in the prog directory for testing.
271 There are a couple of flags you can use on the cmake line to
272 determine what is built here.
274 * By default, cmake builds a shared library. To make a static
278 * By default, cmake only builds the library, not the programs.
279 To make progs from the build subdirectory:
280 cmake .. -DBUILD_PROG=1
282 (4) Cross-compiling for windows
284 You can use src/makefile.mingw for cross-compiling in linux.
287 3. Building on Windows
289 (a) Building with Visual Studio
291 Tom Powers has provided a set of developer notes and project files
292 for building the library and applications under windows with VC++ 2008:
294 <p style='margin-left:5em;'>
295 <A href="http://www.leptonica.org/vs2008doc/index.html">
296 http:///www.leptonica.org/vs2008doc/index.html</A><br>
297 <A href="http://www.leptonica.org/download.html#VS2008">
298 http:///www.leptonica.org/download.html#VS2008</A>
301 He has also supplied a zip file that contains the entire 'lib'
302 and 'include' directories needed to build Windows-based programs
303 using static or dynamic versions of the leptonica library
304 (including static library versions of zlib, libpng, libjpeg,
305 libtiff, and giflib).
307 <p style='margin-left:5em;'>
308 <A href="http://www.leptonica.org/source/leptonica-1.68-win32-lib-include-dirs.zip">
309 leptonica-1.68-win32-lib-include-dirs.zip</A>
312 You can download Tom's vs2008 package either from the download
313 page or from code.google.com/p/leptonica.
315 (b) Building for mingw with <a href="http://www.mingw.org/">MSYS</a>
316 (Thanks to David Bryan)
318 MSYS is a Unix-compatible build environment for the mingw compiler.
319 Installing the "MSYS Base System" and "MinGW Compiler Suite" will allow
320 building the library with autoconf as in (2) above. It will also allow
321 building with the static makefile as in (1) above if this option
322 is added to the make command:
324 CC="gcc -D_BSD_SOURCE -DANSI"
326 Only the static library may be built this way; the autoconf method must
327 be used if a shared (DLL) library is desired.
329 External image libraries (see below) must be downloaded separately,
330 built, and installed before building the library. Pre-built libraries
332 <a href="http://sourceforge.net/projects/ezwinports/">ezwinports project</a>.
334 (c) Building for <a href="http://www.cygwin.com/">Cygwin</a>
335 (Thanks to David Bryan)
337 Cygwin is a Unix-compatible build and runtime environment. Installing
338 the "Base" and "Devel" packages, plus the desired graphics libraries
339 from the "Graphics" and "Libs" packages, will allow building the
340 library with autoconf as in (2) above. If the graphics libraries
341 are not present in the /lib, /usr/lib, or /usr/local/lib directories,
342 you must run make with the "LDFLAGS=-L/(path-to-image)/lib" option.
343 It will also allow building with the static makefile as in (1)
344 above if this option is added to the make command:
346 CC="gcc -ansi -D_BSD_SOURCE -DANSI"
348 Only the static library may be built this way; the autoconf method must
349 be used if a shared (DLL) library is desired.
353 <h2> <A NAME="DEPENDENCIES">
354 I/O libraries leptonica is dependent on
358 Leptonica is configured to handle image I/O using these external
359 libraries: libjpeg, libtiff, libpng, libz, libgif, libwebp, libopenjp2
361 These libraries are easy to obtain. For example, using the
362 debian package manager:
363 sudo apt-get install <package>
364 where <package> = {libpng12-dev, libjpeg62-dev, libtiff4-dev}.
366 Leptonica also allows image I/O with bmp and pnm formats, for which
367 we provide the serializers (encoders and decoders). It also
368 gives output drivers for wrapping images in PostScript and PDF, which
369 in turn use tiffg4, jpeg and flate (i.e., zlib) encoding. PDF will
370 also wrap jpeg2000 images.
372 There is a programmatic interface to gnuplot. To use it, you
373 need only the gnuplot executable (suggest version 3.7.2 or later);
374 the gnuplot library is not required.
376 If you build with automake, libraries on your system will be
377 automatically found and used.
379 The rest of this section is for building with the static makefiles.
380 The entries in environ.h specify which of these libraries to use.
381 The default is to link to these four libraries:
382 libjpeg.a (standard jfif jpeg library, version 6b or 7, 8 or 9))
383 libtiff.a (standard Leffler tiff library, version 3.7.4 or later;
384 libpng.a (standard png library, suggest version 1.4.0 or later)
385 libz.a (standard gzip library, suggest version 1.2.3)
386 current non-beta version is 3.8.2)
388 These libraries (and their shared versions) should be in /usr/lib.
389 (If they're not, you can change the LDFLAGS variable in the makefile.)
390 Additionally, for compilation, the following header files are
391 assumed to be in /usr/include:
393 png: png.h, pngconf.h
394 tiff: tiff.h, tiffio.h
396 If for some reason you do not want to link to specific libraries,
397 even if you have them, stub files are included for the ten
398 different output formats:
399 bmp, jpeg, png, pnm, ps, pdf, tiff, gif, webp and jp2.
400 For example, if you don't want to include the tiff library,
402 #define HAVE_LIBTIFF 0
403 and the stubs will be linked in.
405 To read and write webp files:
406 (1) Download libwebp from sourceforge
407 (2) #define HAVE_LIBWEBP 1 (in environ.h)
408 (3) In prog/makefile, edit ALL_LIBS to include -lwebp
409 (4) The library will be installed into /usr/local/lib.
410 You may need to add that directory to LDFLAGS; or, equivalently,
411 add that path to the LD_LIBRARY_PATH environment variable.
413 To read and write jpeg2000 files:
414 (1) Download libopenjp2, version 2.X, from their distribution,
415 along with cmake. There is no debian version of openjpeg 2.X
417 (2) #define HAVE_LIBJP2K 1 (in environ.h)
418 (2a) If you have version 2.X, X != 1, edit LIBJP2K_HEADER (in environ.h)
419 (3) In prog/makefile, edit ALL_LIBS to include -lopenjp2
420 (4) The library will be installed into /usr/local/lib.
422 To read and write gif files:
423 (1) Download version giflib-5.X.X from souceforge
424 (2) #define HAVE_LIBGIF 1 (in environ.h)
425 (3) In prog/makefile, edit ALL_LIBS to include -lgif
426 (4) The library will be installed into /usr/local/lib.
427 (5) Note: do not use giflib-4.1.4: binary comp and decomp
428 don't pack the pixel data and are ridiculously slow.
432 <h2> <A NAME="DEVELOP">
433 Developing with leptonica
437 You are encouraged to use the static makefiles if you are developing
438 applications using leptonica. The following instructions assume
439 that you are using the static makefiles and customizing environ.h.
441 1. Automatic generation of prototypes
443 The prototypes are automatically generated by the program xtractprotos.
444 They can either be put in-line into allheaders.h, or they can be
445 written to a file leptprotos.h, which is #included in allheaders.h.
446 Note: (1) We supply the former version of allheaders.h.
447 (2) all .c files simply include allheaders.h.
449 First, make xtractprotos:
452 Then to generate the prototypes and make allheaders.h, do one of
454 make allheaders [puts everything into allheaders.h]
455 make allprotos [generates a file leptprotos.h containing the
456 function prototypes, and includes it in allheaders.h]
458 Things to note about xtractprotos, assuming that you are developing
459 in Leptonica and need to regenerate the prototypes in allheaders.h:
461 (1) xtractprotos is part of Leptonica. You can 'make' it in either
462 src or prog (see the makefile).
463 (2) You can output the prototypes for any C file to stdout by running:
464 xtractprotos <cfile> or
465 xtractprotos -prestring=[string] <cfile>
466 (3) The source for xtractprotos has been packaged up into a tar
467 containing just the Leptonica files necessary for building it
468 in linux. The tar file is available at:
469 www.leptonica.com/source/xtractlib-1.5.tar.gz
471 2. GNU runtime functions for stream redirection to memory
473 There are two non-standard gnu functions, fmemopen() and open_memstream(),
474 that only work on linux and conveniently allow memory I/O with a file
475 stream interface. This is convenient for compressing and decompressing
476 image data to memory rather than to file. Stubs are provided
477 for all these I/O functions. Default is to enable them; OSX developers
478 must disable by setting #define HAVE_FMEMOPEN 0 (in environ.h).
479 If these functions are not enabled, raster to compressed data in
480 memory is accomplished safely but through a temporary file.
481 See 9 for more details on image I/O formats.
483 If you're building with the autoconf programs, these two functions are
484 automatically enabled if available.
488 A deficiency of C is that no standard has been universally
489 adopted for typedefs of the built-in types. As a result,
490 typedef conflicts are common, and cause no end of havoc when
491 you try to link different libraries. If you're lucky, you
492 can find an order in which the libraries can be linked
493 to avoid these conflicts, but the state of affairs is aggravating.
495 The most common typedefs use lower case variables: uint8, int8, ...
496 The png library avoids typedef conflicts by altruistically
497 appending "png_" to the type names. Following that approach,
498 Leptonica appends "l_" to the type name. This should avoid
499 just about all conflicts. In the highly unlikely event that it doesn't,
500 here's a simple way to change the type declarations throughout
502 (1) customize a file "converttypes.sed" with the following lines:
503 /l_uint8/s//YOUR_UINT8_NAME/g
504 /l_int8/s//YOUR_INT8_NAME/g
505 /l_uint16/s//YOUR_UINT16_NAME/g
506 /l_int16/s//YOUR_INT16_NAME/g
507 /l_uint32/s//YOUR_UINT32_NAME/g
508 /l_int32/s//YOUR_INT32_NAME/g
509 /l_float32/s//YOUR_FLOAT32_NAME/g
510 /l_float64/s//YOUR_FLOAT64_NAME/g
511 (2) in the src and prog directories:
512 - if you have a version of sed that does in-place conversion:
513 sed -i -f converttypes.sed *
514 - else, do something like (in csh)
516 sed -f converttypes.sed $file > tempdir/$file
519 If you are using Leptonica with a large code base that typedefs the
520 built-in types differently from Leptonica, just edit the typedefs
521 in environ.h. This should have no side-effects with other libraries,
522 and no issues should arise with the location in which liblept is
525 For compatibility with 64 bit hardware and compilers, where
526 necessary we use the typedefs in stdint.h to specify the pointer
527 size (either 4 or 8 byte).
529 4. Compile-time control over stderr output (see environ.h)
531 Leptonica provides both compile-time and run-time control over
532 messages and debug output (thanks to Dave Bryan). Both compile-time
533 and run-time severity thresholds can be set. The run-time threshold
534 can also be set by an environmental variable. Messages are
535 vararg-formatted and of 3 types: error, warning, informational.
536 These are all macros, and can be further suppressed when
537 NO_CONSOLE_IO is defined on the compile line. For production code
538 where no output is to go to stderr, compile with -DNO_CONSOLE_IO.
540 5. In-memory raster format (Pix)
542 Unlike many other open source packages, Leptonica uses packed
543 data for images with all bit/pixel (bpp) depths, allowing us
544 to process pixels in parallel. For example, rasterops works
545 on all depths with 32-bit parallel operations throughout.
546 Leptonica is also explicitly configured to work on both little-endian
547 and big-endian hardware. RGB image pixels are always stored
548 in 32-bit words, and a few special functions are provided for
549 scaling and rotation of RGB images that have been optimized by
550 making explicit assumptions about the location of the R, G and B
551 components in the 32-bit pixel. In such cases, the restriction
552 is documented in the function header. The in-memory data structure
553 used throughout Leptonica to hold the packed data is a Pix,
554 which is defined and documented in pix.h. The alpha component
555 in RGB images is significantly better supported, starting in 1.70.
557 Additionally, a FPix is provided for handling 2D arrays of floats,
558 and a DPix is provided for 2D arrays of doubles. Converters
559 between these and the Pix are given.
561 6. Conversion between Pix and other in-memory raster formats
563 . If you use Leptonica with other imaging libraries, you will need
564 functions to convert between the Pix and other image data
565 structures. To make a Pix from other image data structures, you
566 will need to understand pixel packing, pixel padding, component
567 ordering and byte ordering on raster lines. See the file pix.h
568 for the specification of image data in the pix.
570 7. Custom memory management
572 Leptonica allows you to use custom memory management (allocator,
573 deallocator). For Pix, which tend to be large, the alloc/dealloc
574 functions can be set programmatically. For all other structs and arrays,
575 the allocators are specified in environ.h. Default functions
576 are malloc and free. We have also provided a sample custom
577 allocator/deallocator for Pix, in pixalloc.c.
581 <h2> <A NAME="CONTENTS">
587 This is a source for a clean, fast implementation of rasterops.
588 You can find details starting at the Leptonica home page,
589 and also by looking directly at the source code.
590 The low-level code is in roplow.c and ropiplow.c, and an
591 interface is given in rop.c to the simple Pix image data structure.
595 This is a source for efficient implementations of binary morphology
596 Details are found starting at the Leptonica home page, and by reading
599 Binary morphology is implemented two ways:
601 (a) Successive full image rasterops for arbitrary
602 structuring elements (Sels)
604 (b) Destination word accumulation (dwa) for specific Sels.
605 This code is automatically generated. See, for example,
606 the code in fmorphgen.1.c and fmorphgenlow.1.c.
607 These files were generated by running the program
608 prog/fmorphautogen.c. Results can be checked by comparing dwa
609 and full image rasterops; e.g., prog/fmorphauto_reg.c.
611 Method (b) is considerably faster than (a), which is the
612 reason we've gone to the effort of supporting the use
613 of this method for all Sels. We also support two different
614 boundary conditions for erosion.
616 Similarly, dwa code for the general hit-miss transform can
617 be auto-generated from an array of hit-miss Sels.
618 When prog/fhmtautogen.c is compiled and run, it generates
619 the dwa C code in fhmtgen.1.c and fhmtgenlow.1.c. These
620 files can then be compiled into the libraries or into other programs.
621 Results can be checked by comparing dwa and rasterop results;
622 e.g., prog/fhmtauto_reg.c
624 Several functions with simple parsers are provided to execute a
625 sequence of morphological operations (plus binary rank reduction
626 and replicative expansion). See morphseq.c.
628 The structuring element is represented by a simple Sel data structure
629 defined in morph.h. We provide (at least) seven ways to generate
630 Sels in sel1.c, and several simple methods to generate hit-miss
631 Sels for pattern finding in selgen.c.
633 In use, the most common morphological Sels are separable bricks,
634 of dimension n x m (where either n or m, but not both, is commonly 1).
635 Accordingly, we provide separable morphological operations on brick
636 Sels, using for binary both rasterops and dwa. Parsers are provided
637 for a sequence of separable binary (rasterop and dwa) and grayscale
638 brick morphological operations, in morphseq.c. The main
639 advantage in using the parsers is that you don't have to create
640 and destroy Sels, or do any of the intermediate image bookkeeping.
642 We also give composable separable brick functions for binary images,
643 for both rasterop and dwa. These decompose each of the linear
644 operations into a sequence of two operations at different scales,
645 reducing the operation count to a sum of decomposition factors,
646 rather than the (un-decomposed) product of factors.
647 As always, parsers are provided for a sequence of such operations.
649 3. Grayscale morphology and rank order filters
651 We give an efficient implementation of grayscale morphology for brick
652 Sels. See the Leptonica home page and the source code.
654 Brick Sels are separable into linear horizontal and vertical elements.
655 We use the van Herk/Gil-Werman algorithm, that performs the calculations
656 in a time that is independent of the size of the Sels. Implementations
657 of tophat and hdome are also given. The low-level code is in graymorphlow.c.
659 We also provide grayscale rank order filters for brick filters.
660 The rank order filter is a generalization of grayscale morphology,
661 that selects the rank-valued pixel (rather than the min or max).
662 A color rank order filter applies the grayscale rank operation
663 independently to each of the (r,g,b) components.
667 Leptonica provides many simple and relatively efficient
668 implementations of image scaling. Some of them are listed here;
669 for the full set see the web page and the source code.
671 Grayscale and color images are scaled using:
673 - lowpass filtering followed by sampling,
675 - linear interpolation
677 Scaling operations with antialiased sampling, area mapping,
678 and linear interpolation are limited to 2, 4 and 8 bpp gray,
679 24 bpp full RGB color, and 2, 4 and 8 bpp colormapped
680 (bpp == bits/pixel). Scaling operations with simple sampling
681 can be done at 1, 2, 4, 8, 16 and 32 bpp. Linear interpolation
682 is slower but gives better results, especially for upsampling.
683 For moderate downsampling, best results are obtained with area
684 mapping scaling. With very high downsampling, either area mapping
685 or antialias sampling (lowpass filter followed by sampling) give
686 good results. Fast area map with power-of-2 reduction are also
687 provided. Optional sharpening after resampling is provided to
688 improve appearance by reducing the visual effect of averaging
689 across sharp boundaries.
691 For fast analysis of grayscale and color images, it is useful to
692 have integer subsampling combined with pixel depth reduction.
693 RGB color images can thus be converted to low-resolution
694 grayscale and binary images.
696 For binary scaling, the dest pixel can be selected from the
697 closest corresponding source pixel. For the special case of
698 power-of-2 binary reduction, low-pass rank-order filtering can be
699 done in advance. Isotropic integer expansion is done by pixel replication.
701 We also provide 2x, 3x, 4x, 6x, 8x, and 16x scale-to-gray reduction
702 on binary images, to produce high quality reduced grayscale images.
703 These are integrated into a scale-to-gray function with arbitrary
706 Conversely, we have special 2x and 4x scale-to-binary expansion
707 on grayscale images, using linear interpolation on grayscale
708 raster line buffers followed by either thresholding or dithering.
710 There are also image depth converters that don't have scaling,
711 such as unpacking operations from 1 bpp to grayscale, and
712 thresholding and dithering operations from grayscale to 1, 2 and 4 bpp.
714 5. Image shear and rotation (and affine, projective, ...)
716 Image shear is implemented with both rasterops and linear interpolation.
717 The rasterop implementation is faster and has no constraints on image
718 depth. We provide horizontal and vertical shearing about an
719 arbitrary point (really, a line), both in-place and from source to dest.
720 The interpolated shear is used on 8 bpp and 32 bpp images, and
721 gives a smoother result. Shear is used for the fastest implementations
724 There are three different types of general image rotators:
726 a. Grayscale rotation using area mapping
727 - pixRotateAM() for 8 bit gray and 24 bit color, about center
728 - pixRotateAMCorner() for 8 bit gray, about image UL corner
729 - pixRotateAMColorFast() for faster 24 bit color, about center
731 b. Rotation of an image of arbitrary bit depth, using
732 either 2 or 3 shears. These rotations can be done
733 about an arbitrary point, and they can be either
734 from source to dest or in-place; e.g.
738 c. Rotation by sampling. This can be used on images of arbitrary
739 depth, and done about an arbitrary point. Colormaps are retained.
741 The area mapping rotations are slower and more accurate,
742 because each new pixel is composed using an average of four
743 neighboring pixels in the original image; this is sometimes
744 also called "antialiasing". Very fast color area mapping
745 rotation is provided. The low-level code is in rotateamlow.c.
747 The shear rotations are much faster, and work on images
748 of arbitrary pixel depth, but they just move pixels
749 around without doing any averaging. The pixRotateShearIP()
750 operates on the image in-place.
752 We also provide orthogonal rotators (90, 180, 270 degree; left-right
753 flip and top-bottom flip) for arbitrary image depth.
754 And we provide implementations of affine, projective and bilinear
755 transforms, with both sampling (for speed) and interpolation
758 6. Sequential algorithms
760 We provide a number of fast sequential algorithms, including
761 binary and grayscale seedfill, and the distance function for
762 a binary image. The most efficient binary seedfill is
763 pixSeedfill(), which uses Luc Vincent's algorithm to iterate
764 raster- and antiraster-ordered propagation, and can be used
765 for either 4- or 8-connected fills. Similar raster/antiraster
766 sequential algorithms are used to generate a distance map from
767 a binary image, and for grayscale seedfill. We also use Heckbert's
768 stack-based filling algorithm for identifying 4- and 8-connected
769 components in a binary image. A fast implementation of the
770 watershed transform, using a priority queue, is included.
774 A few simple image enhancement routines for grayscale and
775 color images have been provided. These include intensity mapping
776 with gamma correction and contrast enhancement, as well as edge
777 sharpening, smoothing, and hue and saturation modification.
779 8. Convolution and cousins
781 A number of standard image processing operations are also
782 included, such as block convolution, binary block rank filtering,
783 grayscale and rgb rank order filtering, and edge and local
784 minimum/maximum extraction. Generic convolution is included,
785 for both separable and non-separable kernels, using float arrays
786 in the Pix. Two implementations are included for grayscale and
787 color bilateral filtering: a straightforward (slow) one, and a
788 fast, approximate, separable one.
792 Some facilities have been provided for image input and output.
793 This is of course required to build executables that handle images,
794 and many examples of such programs, most of which are for
795 testing, can be built in the prog directory. Functions have been
796 provided to allow reading and writing of files in JPEG, PNG,
797 TIFF, BMP, PNM ,GIF, WEBP and JP2 formats. These formats were chosen
798 for the following reasons:
800 - JFIF JPEG is the standard method for lossy compression
801 of grayscale and color images. It is supported natively
802 in all browsers, and uses a good open source compression
803 library. Decompression is supported by the rasterizers
804 in PS and PDF, for level 2 and above. It has a progressive
805 mode that compresses about 10% better than standard, but
806 is considerably slower to decompress. See jpegio.c.
808 - PNG is the standard method for lossless compression
809 of binary, grayscale and color images. It is supported
810 natively in all browsers, and uses a good open source
811 compression library (zlib). It is superior in almost every
812 respect to GIF (which, until recently, contained proprietary
813 LZW compression). See pngio.c.
815 - TIFF is a common interchange format, which supports different
816 depths, colormaps, etc., and also has a relatively good and
817 widely used binary compression format (CCITT Group 4).
818 Decompression of G4 is supported by rasterizers in PS and PDF,
819 level 2 and above. G4 compresses better than PNG for most
820 text and line art images, but it does quite poorly for halftones.
821 It has good and stable support by Leffler's open source library,
822 which is clean and small. Tiff also supports multipage
823 images through a directory structure. See tiffio.c
825 - BMP has (until recently) had no compression. It is a simple
826 format with colormaps that requires no external libraries.
827 It is commonly used because it is a Microsoft standard,
828 but has little besides simplicity to recommend it. See bmpio.c.
830 - PNM is a very simple, old format that still has surprisingly
831 wide use in the image processing community. It does not
832 support compression or colormaps, but it does support binary,
833 grayscale and rgb images. Like BMP, the implementation
834 is simple and requires no external libraries. See pnmio.c.
836 - WEBP is a new wavelet encoding method derived from libvpx,
837 a video compression library. It is rapidly growing in acceptance,
838 and is supported natively in several browsers. Leptonica provides
839 an interface through webp into the underlying codec. You need
842 - JP2K (jpeg2000) is a wavelet encoding method, that has clear
843 advantages over jpeg in compression and quality (especially when
844 the image has sharp edges, such as scanned documents), but is
845 only slowly growing in acceptance. For it to be widely supported,
846 it will require support on a major browser (as with webp).
847 Leptonica provides an interface through openjpeg into the underlying
848 codec. You need to download libopenjp2, version 2.X.
850 - GIF is still widely used in the world. With the expiration
851 of the LZW patent, it is practical to add support for GIF files.
852 The open source gif library is relatively incomplete and
853 unsupported (because of the Sperry-Rand-Burroughs-Univac
854 patent history). See gifio.c.
856 Here's a summary of compression support and limitations:
857 - All formats except JPEG, WEBP and JP2K support 1 bpp binary.
858 - All formats support 8 bpp grayscale (GIF must have a colormap).
859 - All formats except GIF support rgb color.
860 - All formats except PNM, JPEG, WEBP and JP2K support 8 bpp colormap.
861 - PNG and PNM support 2 and 4 bpp images.
862 - PNG supports 2 and 4 bpp colormap, and 16 bpp without colormap.
863 - PNG, JPEG, TIFF, WEBP, JP2K and GIF support image compression;
865 - WEBP supports rgb color and rgba.
866 - JP2K supports 8 bpp grayscale, rgb color and rgba.
867 Use prog/ioformats_reg for a regression test on all formats, including
868 thorough testing on TIFF.
869 For more thorough testing on other formats, use:
870 - prog/pngio_reg for PNG.
871 - prog/gifio_reg for GIF
872 - prog/webpio_reg for WEBP
873 - prog/jp2kio_reg for JP2K
875 We provide generators for PS output, from all types of input images.
876 The output can be either uncompressed or compressed with level 2
877 (ccittg4 or dct) or level 3 (flate) encoding. You have flexibility
878 for scaling and placing of images, and for printing at different
879 resolutions. You can also compose mixed raster (text, image) PS.
880 See psio1.c for examples of how to output PS for different applications.
881 As examples of usage, see:
882 * prog/converttops.c for a general image --> PS conversion
883 for printing. You can specify compression level (1, 2, or 3).
884 * prog/convertfilestops.c to generate a multipage level 3 compressed
885 PS file that can then be converted to pdf with ps2pdf.
886 * prog/convertsegfilestops.c to generate a multipage, mixed raster,
887 level 2 compressed PS file.
889 We provide generators for PDF output, again from all types of input
890 images, and with ccittg4, dct, flate and jpx (jpeg2000) compression.
891 You can do the following for PDF:
892 * Put any number of images onto a page, with specified input
893 resolution, location and compression.
894 * Write a mixed raster PDF, given an input image and a segmentation
895 mask. Non-image regions are written in G4 (fax) encoding.
896 * Concatenate single-page PDF wrapped images into a single PDF file.
897 * Build a PDF file of all images in a directory or array of file names.
898 As examples of usage, see:
899 * prog/converttopdf.c: fast pdf generation with one image/page.
900 For speed, this avoids transcoding whenever possible.
901 * prog/convertfilestopdf.c: more flexibility in the output. You
902 can set the resolution, scaling, encoding type and jpeg quality.
903 * prog/convertsegfilestopdf.c: generates a multipage, mixed raster pdf,
904 with separate controls for compressing text and non-text regions.
906 Note: any or all of these I/O library calls can be stubbed out at
907 compile time, using the environment variables in environ.h.
909 For all formatted reads and writes, we support read from memory
910 and write to memory. (We cheat with gif, using a file intermediary.)
911 For all formats except for TIFF, these memory I/O functions
912 are supported through open_memstream() and fmemopen(),
913 which only is available with the gnu C runtime library (glibc).
914 Therefore, except for TIFF, you will not be able to do memory
915 supported read/writes on these platforms:
916 OSX, Windows, Solaris
917 To enable/disable memory I/O for image read/write, see environ.h.
919 We also provide fast serialization and deserialization between a pix
920 in memory and a file (spixio.c). This works on all types of pix images.
922 10. Colormap removal and color quantization
924 Leptonica provides functions that remove colormaps, for conversion
925 to either 8 bpp gray or 24 bpp RGB. It also provides the inverse
926 function to colormap removal; namely, color quantization
927 from 24 bpp full color to 8 bpp colormap with some number
928 of colormap colors. Several versions are provided, some that
929 use a fast octree vector quantizer and others that use
930 a variation of the median cut quantizer. For high-level interfaces,
931 see for example: pixConvertRGBToColormap(), pixOctreeColorQuant(),
932 pixOctreeQuantByPopulation(), pixFixedOctcubeQuant256(),
933 and pixMedianCutQuant().
935 11. Programmatic image display
937 For debugging, several pixDisplay* functions in writefile.c are given.
938 Two (pixDisplay and pixDisplayWithTitle) can be called to display
939 an image using one of several display programs (xzgv, xli, xv, l_view).
940 If necessary to fit on the screen, the image is reduced in size,
941 with 1 bpp images being converted to grayscale for readability.
942 (This is much better than letting xv do the reduction, for example).
943 Another function, pixDisplayWrite(), writes images to disk under
944 control of a reduction/disable flag, which then allows
945 either viewing with pixDisplayMultiple(), or the generation
946 of a composite image using, for example, pixaDisplayTiledAndScaled().
947 These files can also be gathered up into a compressed PDF or PostScript
948 file and viewed with evince. Common image display programs are: xzgv,
949 xli, xv, display, gthumb, gqview, evince, gv and acroread. Finally,
950 a set of images can be saved into a pixa (array of pix), specifying the
951 eventual layout into a single pix, using pixaDisplay*().
953 12. Document image analysis
955 Many functions have been included specifically to help with
956 document image analysis. These include skew and text orientation
957 detection; page segmentation; baseline finding for text;
958 unsupervised classification of connected components, characters
959 and words; dewarping camera images; adaptive binarization; and
960 a simple book-adaptive classifier for various character sets,
961 segmentation for newspaper articles, etc.
965 Several simple data structures are provided for safe and efficient handling
966 of arrays of numbers, strings, pointers, and bytes. The generic
967 pointer array is implemented in four ways: as a stack, a queue,
968 a heap (used to implement a priority queue), and an array with
969 insertion and deletion, from which the stack operations form a subset.
970 Byte arrays are implemented both as a wrapper around the actual
971 array and as a queue. The string arrays are particularly useful
972 for both parsing and composing text. Generic lists with
973 doubly-linked cons cells are also provided.
975 14. Examples of programs that are easily built using the library:
977 - for plotting x-y data, we give a programmatic interface
978 to the gnuplot program, with output to X11, png, ps or eps.
979 We also allow serialization of the plot data, in a form
980 such that the data can be read, the commands generated,
981 and (finally) the plot constructed by running gnuplot.
983 - a simple jbig2-type classifier, using various distance
984 metrics between image components (correlation, rank
985 hausdorff); see prog/jbcorrelation.c, prog/jbrankhaus.c.
987 - a simple color segmenter, giving a smoothed image
988 with a small number of the most significant colors.
990 - a program for converting all images in a directory
991 to a PostScript file, and a program for printing an image
992 in any (supported) format to a PostScript printer.
994 - various programs for generating pdf files from compressed
995 images, including very fast ones that don't scale and
996 avoid transcoding if possible.
998 - converters between binary images and SVG format.
1000 - an adaptive recognition utility for training and identifying
1001 text characters in a multipage document such as a book.
1003 - a bitmap font facility that allows painting text onto
1004 images. We currently support one font in several sizes.
1005 The font images and postscript programs for generating
1006 them are stored in prog/fonts/, and also as compiled strings
1009 - a binary maze game lets you generate mazes and find shortest
1010 paths between two arbitrary points, if such a path exists.
1011 You can also compute the "shortest" (i.e., least cost) path
1012 between points on a grayscale image.
1014 - a 1D barcode reader. This is still in an early stage of development,
1015 with little testing, and it only decodes 6 formats.
1017 - a utility that will dewarp images of text that were captured
1018 with a camera at close range.
1020 - a sudoku solver, including a pretty good test for uniqueness
1022 - see (13, above) for other document image applications.
1026 Leptonica supports an open source jbig2 encoder (yes, there is one!),
1027 which can be downloaded from:
1028 http://www.imperialviolet.org/jbig2.html.
1029 To build the encoder, use the most recent version. This bundles
1030 Leptonica 1.63. Once you've built the encoder, use it to compress
1031 a set of input image files: (e.g.)
1032 ./jbig2 -v -s <imagefile1 ...> > <jbig2_file>
1033 You can also generate a pdf wrapping for the output jbig2. To do that,
1034 call jbig2 with the -p arg, which generates a symbol file (output.sym)
1035 plus a set of location files for each input image (output.0000, ...):
1036 ./jbig2 -v -s -p <imagefile1 ...>
1037 and then generate the pdf:
1038 python pdf.py output > <pdf_file>
1039 See the usage documentation for the jbig2 compressor at:
1040 http://www.imperialviolet.org/binary/jbig2enc.html
1041 You can uncompress the jbig2 files using jbig2dec, which can be
1042 downloaded and built from:
1043 http://jbig2dec.sourceforge.net/
1047 New versions of the Leptonica library are released several times
1048 a year, and version numbers are provided for each release in
1049 the makefile and in allheaders.h. All even versions from 1.42 to 1.60
1050 have been archived at http://code.google.com/p/leptonica, as well as all
1051 versions after 1.60. However, code.google.com no longer supports
1052 uploads of new distributions, which you can get at the leptonica.org
1055 The number of downloads of leptonica increased by nearly an order
1056 of magnitude with 1.69, due to bundling with tesseract and
1057 incorporation in ubuntu 12-04. Leptonica has about 2400 functions,
1058 and the binary API changed slightly with the new 1.71 release. Having
1059 a proper binary release version is required for all debian packages.
1060 The binary release versions are:
1067 A brief version chronology is maintained in version-notes.html.
1068 Starting with gcc 4.3.3, error warnings (-Werror) are given for
1069 minor infractions like not checking return values of built-in C
1070 functions. I have attempted to eliminate these warnings.
1071 In any event, you will see warnings with the -Wall flag.
1075 <!-- JS Window Closer -----
1078 <input type="button" onclick="window.close();" value="Close this window">
1081 ----- JS Window Closer -->
projects / platform / upstream / libleptonica.git / blob