This file is indexed.

/usr/share/doc/libleptonica-dev/README.html is in libleptonica-dev 1.71-2.1+b2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
<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  (1.71: 28 June 2014)
---------------------------

gunzip leptonica-1.71.tar.gz
tar -xvf leptonica-1.71.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="#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.71'.  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

  There are two 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 src/environ.h and src/makefile for details.
        Note: if you are going to develop with leptonica, I encourage
        you to use the static makefiles.

    (2) Using autoconf.  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.

  In more detail:

    (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 I/O functions that depend on external
             libraries [use flags in src/environ.h]
         (b) Adding functions for redirecting formatted image stream
             I/O to memory [use flag in src/environ.h]
         (c) 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.

       * To make the programs in the prog directory, first make liblept
         in src, and then do 'make' in the prog directory.

       VERY IMPORTANT: the 240+ programs in the prog directory are
       an integral part of this package.  These 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, printimage and printsplitimage.
         (2) Programs that are used as regression tests in alltests_reg.
             These are named *_reg, and 63 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.

    (2) Building using autoconf  (Thanks to James Le Cuirot)

       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 the progs into /usr/local/bin/ ]
          make [-j4] check  [runs the alltests_reg set of regression tests.
                             This works even if you build in a different
                             place from the distribution.]

       Configure also supports building in a separate directory from the
       source.  Run "/(path-to)/leptonica-1.71/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 for this
       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) Cross-compiling for windows

       You can use src/makefile.mingw for cross-compiling in linux.


3. Building on Windows

   (a) Building with Visual Studio

       Tom Powers has provided a set of developer notes and project files
       for building the library and applications under windows with VC++ 2008:
     </pre>
     <p style='margin-left:5em;'>
        <A href="http://www.leptonica.org/vs2008doc/index.html">
                http:///www.leptonica.org/vs2008doc/index.html</A><br>
        <A href="http://www.leptonica.org/download.html#VS2008">
                http:///www.leptonica.org/download.html#VS2008</A>
     <pre>

       He has also supplied a zip file that contains the entire 'lib'
       and 'include' directories needed to build Windows-based programs
       using static or dynamic versions of the leptonica library
       (including static library versions of zlib, libpng, libjpeg,
       libtiff, and giflib).
       </pre>
       <p style='margin-left:5em;'>
      <A href="http://www.leptonica.org/source/leptonica-1.68-win32-lib-include-dirs.zip">
              leptonica-1.68-win32-lib-include-dirs.zip</A>
       <pre>

       You can download Tom's vs2008 package either from the download
       page or from code.google.com/p/leptonica.

   (b) Building for mingw with <a href="http://www.mingw.org/">MSYS</a>
       (Thanks to David Bryan)

       MSYS is a Unix-compatible build environment for the mingw compiler.
       Installing the "MSYS Base System" and "MinGW Compiler Suite" 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 added to the make command:

         CC="gcc -D_BSD_SOURCE -DANSI"

       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
          <a href="http://sourceforge.net/projects/ezwinports/">ezwinports project</a>.

   (c) Building for <a href="http://www.cygwin.com/">Cygwin</a>
       (Thanks to David Bryan)

       Cygwin is a Unix-compatible build and runtime environment.  Installing
       the "Base" and "Devel" packages, plus the desired graphics libraries
       from the "Graphics" and "Libs" packages, will allow building the
       library with autoconf as in (2) above.  If the graphics libraries
       are not present in the /lib, /usr/lib, or /usr/local/lib directories,
       you must run make with the "LDFLAGS=-L/(path-to-image)/lib" option.
       It will also allow building with the static makefile as in (1)
       above if this option is added to the make command:

         CC="gcc -ansi -D_BSD_SOURCE -DANSI"

       Only the static library may be built this way; the autoconf method must
       be used if a shared (DLL) library is desired.
</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, libgif, libwebp, libopenjp2

   These libraries are easy to obtain.  For example, using the
   debian package manager:
       sudo apt-get install <package>
   where <package> = {libpng12-dev, libjpeg62-dev, libtiff4-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 png encoding.  Wrapping of jpeg2000
   images in PDF is also implemented.

   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

   To read and write gif files:
      (1) Download version giflib-5.0.X from souceforge
      (2) #define  HAVE_LIBGIF   1  (in environ.h)
      (3) In prog/makefile, edit ALL_LIBS to include -lgif
      (4) If the library is 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.
      (5) Note: do not use giflib-4.1.4: binary comp and decomp
          don't pack the pixel data and are ridiculously slow.

   To read and write jpeg2000 files:
      (1) Download libopenjp2, version 2.X, from their distribution,
          along with cmake.  There is no debian version of openjpeg 2.X
          as of 6/20/2014.
      (2) #define HAVE_LIBJP2K   1  (in environ.h)
      (3) In prog/makefile, edit ALL_LIBS to include -lopenjp2
</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. 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 not to enable them, in
   deference to the OSX developers, who don't have these functions
   available.  To enable, #define HAVE_FMEMOPEN  1  (in environ.h).
   If it is not enabled, raster to compressed data in memory is
   accomplished 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.

3. 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).

4. Compile-time control over stderr output (see environ.h)

   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 run-time 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.

5. 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.

6. 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.

7. 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.
   The low-level code is in roplow.c and ropiplow.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.  The low-level code is in graymorphlow.c.

   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 called "antialiasing".  Very fast color area mapping
   rotation is provided.  The low-level code is in rotateamlow.c.

   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

   A few simple image enhancement routines for grayscale and
   color images have been provided.  These include intensity mapping
   with gamma correction and contrast enhancement, as well as edge
   sharpening, smoothing, and hue and saturation modification.

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 (as of Dec 2013).
      Leptonica provides an interface through webp into the underlying
      codec.  You need to download libwebp.

    - JP2K (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.

    - 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).   See gifio.c.

   Here's a summary of compression support and limitations:
      - All formats except JPEG, WEBP and JP2K support 1 bpp binary.
      - All formats support 8 bpp grayscale (GIF must have a colormap).
      - All formats except GIF support rgb color.
      - All formats except PNM, JPEG, WEBP and JP2K support 8 bpp colormap.
      - PNG and PNM support 2 and 4 bpp images.
      - PNG supports 2 and 4 bpp colormap, and 16 bpp without colormap.
      - PNG, JPEG, TIFF, WEBP, JP2K and GIF support image compression;
        PNM and BMP do not.
      - WEBP supports rgb color and rgba.
      - JP2K supports 8 bpp grayscale, rgb color and rgba.
   Use prog/ioformats_reg for a regression test on all but GIF, WEBP, and JP2K.
   Use prog/pngio_reg for a thorough testing of PNG.
   Use prog/gifio_reg for testing GIF.
   Use prog/webpio_reg for testing WEBP.
   Use prog/jp2kio_reg for testing JP2K.

   We provide generators for PS output, from all types of input images.
   The output can be either uncompressed or compressed with level 2
   (ccittg4 or dct) or level 3 (flate) encoding.  You have flexibility
   for scaling and placing of images, and for printing at different
   resolutions.  You can also compose mixed raster (text, image) PS.
   See psio1.c for examples of how to output PS for different applications.
   As examples of usage, see:
     * prog/converttops.c for a general image --> PS conversion
           for printing.  You can specify compression level (1, 2, or 3).
     * prog/convertfilestops.c to generate a multipage level 3 compressed
           PS file that can then be converted to pdf with ps2pdf.
     * prog/convertsegfilestops.c to generate a multipage, mixed raster,
           level 2 compressed PS file.

   We provide generators for PDF output, again from all types of input
   images, and with ccittg4, dct, flate and jpx (jpeg2000) compression.
   You can do the following for PDF:
     * Put any number of images onto a page, with specified input
       resolution, location and compression.
     * Write a mixed raster PDF, given an input image and a segmentation
       mask.  Non-image regions are written in G4 (fax) encoding.
     * Concatenate single-page PDF wrapped images into a single PDF file.
     * Build a PDF file of all images in a directory or array of file names.

   Note: any or all of these I/O library calls can be stubbed out at
         compile time, using the environment variables in environ.h.

   For all formatted reads and writes, we support read from memory
   and write to memory.  (We cheat with gif, using a file intermediary.)
   For all formats except for TIFF, these memory I/O functions
   are supported through open_memstream() and fmemopen(),
   which only is available with the gnu C runtime library (glibc).
   Therefore, except for TIFF, you will not be able to do memory
   supported read/writes on these platforms:
       OSX, Windows, Solaris
   By default, these non-POSIX functions are disabled.  To enable memory
   I/O for image formatted read/writes, see environ.h.

   We also provide fast serialization and deserialization between a pix
   in memory and a file (spixio.c).  This works on all types of pix images.

10. Colormap removal and color quantization

   Leptonica provides functions that remove colormaps, for conversion
   to either 8 bpp gray or 24 bpp RGB.  It also provides the inverse
   function to colormap removal; namely, color quantization
   from 24 bpp full color to 8 bpp colormap with some number
   of colormap colors.  Several versions are provided, some that
   use a fast octree vector quantizer and others that use
   a variation of the median cut quantizer.  For high-level interfaces,
   see for example: pixConvertRGBToColormap(), pixOctreeColorQuant(),
   pixOctreeQuantByPopulation(), pixFixedOctcubeQuant256(),
   and pixMedianCutQuant().

11. Programmatic image display

   For debugging, several pixDisplay* functions in writefile.c are given.
   Two (pixDisplay and pixDisplayWithTitle) can be called to display
   an image using one of several display programs (xv, xli, xzgv, l_view).
   If necessary to fit on the screen, the image is reduced in size,
   with 1 bpp images being converted to grayscale for readability.
   (This is much better than letting xv do the reduction).
   Another function, pixDisplayWrite(), writes images to disk under
   control of a reduction/disable flag, which then allows
   either viewing with pixDisplayMultiple(), or the generation
   of a composite image using, for example, pixaDisplayTiledAndScaled().
   These files can also be gathered up into a compressed PostScript file,
   using prog/convertfilestops, and viewed with evince, or converted
   to pdf.  Common image display programs are: xv, xli, xzgv, display,
   gthumb, gqview, evince, gv and acroread.  Finally, a set of
   images can be saved into a pixa (array of pix), specifying the
   eventual layout into a single pix, using pixaSaveTiled*().

12. Document image analysis

   Many functions have been included specifically to help with
   document image analysis.  These include skew and text orientation
   detection; page segmentation; baseline finding for text;
   unsupervised classification of connected components, characters
   and words; dewarping camera images; adaptive binarization; and
   a simple book-adaptive classifier for various character sets,
   segmentation for newspaper articles, etc.

13. Data structures

   Simple data structures are provided for safe and efficient handling
   of arrays of numbers, strings, pointers, and bytes.  The generic
   pointer array is implemented in four ways: as a stack, a queue,
   a heap (used to implement a priority queue), and an array with
   insertion and deletion, from which the stack operations form a subset.
   Byte arrays are implemented both as a wrapper around the actual
   array and as a queue.  The string arrays are particularly useful
   for both parsing and composing text.  Generic lists with
   doubly-linked cons cells are also provided.

14. Examples of programs that are easily built using the library:

    - for plotting x-y data, we give a programmatic interface
      to the gnuplot program, with output to X11, png, ps or eps.
      We also allow serialization of the plot data, in a form
      such that the data can be read, the commands generated,
      and (finally) the plot constructed by running gnuplot.

    - a simple jbig2-type classifier, using various distance
      metrics between image components (correlation, rank
      hausdorff); see prog/jbcorrelation.c, prog/jbrankhaus.c.

    - a simple color segmenter, giving a smoothed image
      with a small number of the most significant colors.

    - a program for converting all images in a directory
      to a PostScript file, and a program for printing an image
      in any (supported) format to a PostScript printer.

    - various programs for generating pdf files from compressed
      images, including very fast ones that don't scale and
      avoid transcoding if possible.

    - converters between binary images and SVG format.

    - an adaptive recognition utility for training and identifying
      text characters in a multipage document such as a book.

    - a bitmap font facility that allows painting text onto
      images.  We currently support one font in several sizes.
      The font images and postscript programs for generating
      them are stored in prog/fonts/.

    - a binary maze game lets you generate mazes and find shortest
      paths between two arbitrary points, if such a path exists.
      You can also compute the "shortest" (i.e., least cost) path
      between points on a grayscale image.

    - a 1D barcode reader.  This is still in an early stage of development,
      with little testing, and it only decodes 6 formats.

    - a utility that will dewarp images of text that were captured
      with a camera at close range.

    - a sudoku solver, including a pretty good test for uniqueness

    - see (13, above) for other document image applications.

15. JBig2 encoder

   Leptonica supports an open source jbig2 encoder (yes, there is one!),
   which can be downloaded from:
       http://www.imperialviolet.org/jbig2.html.
   To build the encoder, use the most recent version.  This bundles
   Leptonica 1.63.  Once you've built the encoder, use it to compress
   a set of input image files:  (e.g.)
       ./jbig2 -v -s <imagefile1 ...>  >   <jbig2_file>
   You can also generate a pdf wrapping for the output jbig2.  To do that,
   call jbig2 with the -p arg, which generates a symbol file (output.sym)
   plus a set of location files for each input image (output.0000, ...):
        ./jbig2 -v -s -p <imagefile1 ...>
   and then generate the pdf:
       python pdf.py output  >  <pdf_file>
   See the usage documentation for the jbig2 compressor at:
       http://www.imperialviolet.org/binary/jbig2enc.html
   You can uncompress the jbig2 files using jbig2dec, which can be
   downloaded and built from:
       http://jbig2dec.sourceforge.net/

16. Versions

   New versions of the Leptonica library are released approximately
   6 times a year, and version numbers are provided for each release in
   the makefile and in allheaders.h.  All even versions from 1.42 to 1.60
   have been archived at http://code.google.com/p/leptonica, as well as all
   versions after 1.60.  However, code.google.com no longer supports
   uploads of new distributions, which you can get at the leptonica.org
   web site.

   The number of downloads of leptonica increased by nearly an order
   of magnitude with 1.69, due to bundling with tesseract and
   incorporation in ubuntu 12-04.  Leptonica has about 2400 functions,
   and the binary API changed slightly with the new 1.71 release.  Having
   a proper binary release version is required for all debian packages.
   The binary release version for 1.69 is 3.0.0, for 1.70 it is 4.0.0,
   and for 1.71 it is 4.2.0.

   A brief version chronology is maintained in version-notes.html.
   Starting with gcc 4.3.3, error warnings (-Werror) are given for
   minor infractions like not checking return values of built-in C
   functions.  I have attempted to eliminate these warnings.
   In any event, you will see warnings with the -Wall flag.

</pre>

<!-- JS Window Closer -----
<form>
<center>
<input type="button" onclick="window.close();" value="Close this window">
</center>
</form>
----- JS Window Closer -->

</body>
</html>