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