leptonic == (historical revision 44798)

You are looking at historical revision 44798 of this page. It may differ significantly from its current revision.

leptonic ==

This egg provides a Scheme interface to the leptonica image processing library authored by Dan Bloomberg. The egg offers a subset of the extensive leptonica C-API, focusing on a set of high-level leptonica functions that are likely to be useful to Scheme programmers.

Author ===

Jules Altfas

Repository ===

https://codeberg.org/jrapdx/leptonic

Requirements ===

The egg has these dependencies:

the leptonica library – https://github.com/DanBloomberg/leptonica, which is dependent on:
- libjpeg – https://sourceforge.net/projects/libjpeg-turbo/
- libtiff – https://gitlab.com/libtiff/libtiff
- libpng – https://libpng.sourceforge.io/index.html
- libz – https://zlib.net/
- libwebp – https://github.com/webmproject/libwebp
- libgif – https://giflib.sourceforge.net
- libopenjp2 – https://github.com/uclouvain/openjpeg

The image libraries are available on many platforms through their respective package systems. Installing from source is an option if one or more are not otherwise available.

Installing ===

On unix platforms, the egg should install normally with <code>chicken-install -s leptonic</code>, or alternatively, clone/download the repo and run <code>chicken-install -s</code> in the local directory.

On Windows, the leptonica library needs to be installed before installing the egg. Make sure <code>libleptonica-6.dll</code> is in a directory on the exec path. Then <code>chicken-install</code> should compile/install the egg without errors.

Programs using/importing <code>leptonic</code> need to be linked with the leptonica library.

Install image libraries through the system package manager or from source if not otherwise available.
Install the leptonica library. (See the leptonica site at http://www.leptonica.org/source/README.html for detailed instructions for compiling from source.)

Using the leptonic egg ===

The leptonica library abstracts image data into one of several C-structs which are used by functions to read/write image files, perform scaling, morphing, modifying and coverting images. An advantage of this approach is the simplicity and uniformity it provides for library users. libleptonica includes a wealth of high- and low-level functions for these purposes. A selection of the library’s high-level functions are represented in this egg.

The primary C-struct is “Pix” with fields including width, height, depth (1,2,4,8,32 bits/pixel), samples/pixel, xres, yres, colormap, and img-data (array of <code>unsigned-int32</code>). Users should regard Pix and other structures as opaque as the “internals” are handled by the procedures. Most of the Scheme procedures take/return ‘ppix’ (ptr to struct Pix) along with other arguments.

A major benefit of leptonica is that image processing is decoupled from input/output format, greatly simplifying programs that handle image files. A typical usage pattern starts with reading an image file with ‘pix-read’ (or ‘pix-read-FORMAT’), returning a ppix (ptr to Pix). Manipulations are applied and finally, ‘pix-write’ or ‘pix-write-FORMAT’ writes ppix data to an output file.

Leptonic egg api ===

Format-type procedures ====

<procedure> n->ftype N </procedure> in - N - <code>int</code>, with value 0 to 19. returns: symbol, e.g., ’IFF_JFIF_JPEG

<procedure> ftype->n TYPE </procedure> in - TYPE - <code>symbol</code> returns: <code>int</code>. (See TABLE.)

TABLE. leptonica formats

{| class="wikitable" |- ! integer ! symbol |- | 0 | IFF_UNKNOWN |- | 1 | IFF_BMP |- | 2 | IFF_JFIF_JPEG |- | 3 | IFF_PNG |- | 4 | IFF_TIFF |- | 5 | IFF_TIFF_PACKBITS |- | 6 | IFF_TIFF_RLE |- | 7 | IFF_TIFF_G3 |- | 8 | IFF_TIFF_G4 |- | 9 | IFF_TIFF_LZW |- | 10 | IFF_TIFF_ZIP |- | 11 | IFF_PNM |- | 12 | IFF_PS |- | 13 | IFF_GIF |- | 14 | IFF_JP2 |- | 15 | IFF_WEBP |- | 16 | IFF_LPDF |- | 17 | IFF_TIFF_JPEG |- | 18 | IFF_DEFAULT |- | 19 | IFF_SPIX |}

Foreign types ====

<pre>(define-foreign-type pix (struct Pix)) (define-foreign-type ppix (c-ptr (struct Pix))) (define-foreign-type pixa (struct Pixa)) (define-foreign-type ppixa (c-ptr (struct Pixa))) (define-foreign-type fpix (struct FPix)) ;; float pix (define-foreign-type pfpix (c-ptr (struct FPix))) (define-foreign-type fpixa (struct FPixa)) ;; array of FPix (define-foreign-type pfpixa (c-ptr (struct FPixa)))</pre> Use <code>(include "leptonic-types.scm")</code> to make these available to a program.

Opening/reading image files ====

<procedure> pix-read FILENAME </procedure> in - FILENAME returns: ppix or #f on error.

<procedure> pix-read-header FILENAME PFMT PW PH PBPS PSPP PISCMAP </procedure> in - FILENAME - <code>string</code> in - PFMT PW PH PBPS PSPP PISCMAP - <code>ptr to unsigned-int32</code>. Other args are optional, pass #f to skip. Optionals, in order: image-format, width, height, bits/sample, samples/pixel, img has colormap?(0=no/1=yes).

<pre>(define-external fmt unsigned-int32) (define-external w unsigned-int32) (define-external h unsigned-int32) (pix-read-header "img1.jpg" (location fmt) (location w)

                           (location h) #f #f #f)

; fmt -> 2, w -> 898, h -> 606</pre>

<procedure> pix-get-width PPIX </procedure> in - PPIX returns: width as <code>int</code>.

<procedure> pix-get-height PPIX </procedure> in - PPIX returns: height as <code>int</code>.

<procedure> get-implied-fmt FILENAME </procedure> in- FILENAME - <code>string</code> returns: format as <code>int</code>.

<procedure> find-file-fmt FILENAME PFMT </procedure> in - FILENAME - <code>string</code>. out - PFMT - <code>ptr to int</code>. returns: 0 on success, 1 if error/unrecognized format.

<pre>(define-external fmt int) (define r (find-file-fmt "file0.png" (location fmt)))

; r -> 0 (no error), fmt -> 3</pre>

Writing image files ====

<procedure> pix-write FILENAME PPIX FORMAT </procedure> in - FILENAME <code>string</code> in - PPIX in - FORMAT <code>int</code> returns: 0 on success, 1 if error.

<procedure> pix-write-jpeg FILENAME PPIX QUALITY PROGRESSIVE </procedure> in - FILENAME - <code>string</code> in - PPIX in - QUALITY - <code>int32</code> - 1 to 100, 75 is default in - PROGRESSIVE - <code>int32</code> - 1=yes, 0=no returns: 0 on success, 1 if error.

<procedure> pix-write-png FILENAME PPIX GAMMA </procedure> in - FILENAME - <code>string</code> in - PPIX in - GAMMA - <code>float</code> - 0.0 if not defined returns: 0 on success, 1 if error.

<procedure> pix-write-webp FILENAME PPIX QUALITY LOSSLESS </procedure> in - FILENAME - <code>string</code> in - PPIX in - QUALITY - <code>int32</code> - 1 to 100 in - LOSSLESS - <code>int32</code> - 1=yes, 0=no returns: 0 on success, 1 if error.

<procedure> pix-copy PPIXD PPIX </procedure> in - PPIXD - #f or PPIX (in-place: <code>pix-copy ppix ppix</code>) in - PPIX returns: copy of ppix

Disposing of ppix/img-data ====

<procedure> pix-destroy PTR-TO-PPIX </procedure> in - PTR-TO-PPIX - <code>ptr ppix</code> returns: no return value

<pre>(define-external ppx ppix (pix-read "img0.jpg")) ... (pix-destroy (location ppx))</pre> <procedure> pix-free-data PPIX </procedure> in - PPIX (Deallocates data member but not Pix structure itself) returns: no return value

Scaling ====

<procedure> pix-scale PPIX SCALEX SCALEY </procedure> in - PPIX - input in - SCALEX, SCALEY - <code>float</code> values. (Uses: sharpening for scale factors 0.2-0.7, ‘linear interpolation’ for factors 0.7-1.4, and no sharpening when scale factors > 1.4.) returns: scaled ppix on success, #f on error.

<procedure> pix-scale-general PPIX SCALEX SCALEY SHARPFRAC SHARPWIDTH </procedure> in - PPIX in - SCALEX/Y, SHARPFRAC - <code>flaot</code>. in - SHARPWIDTH - <code>int</code>, 1 or 2. returns: modified ppix. (When max scalex/y is < 0.2, no sharpening applied. Between .2 and 1.4, sharpen according to input values. With scalex/y > 1.4, no sharpening is applied. For precise control, call <code>pix-scale-general</code> with sharpfrac 0.0 followed by call to <code>pix-unsharp-mask</code>.)

<pre>(define-external ppix0 ppix (pix-read "img0.webp")) (define scaledpix (pix-scale-general ppix0 1.2 1.2 0.25 1)) ... (define res (pix-write scaledpix "img0-1.2x.webp" scaledpix 15))

; res -> 0 </pre>

<procedure> pix-scale-smooth PPIX SCALEX SCALEY </procedure> in - PPIX in - SCALEX/Y - <code>float</code>. (Scale factors MUST BE <0.7.) returns: modified ppix, or #f on error.

<procedure> pix-scale-to-size PPIX WIDTH HEIGHT </procedure> in - PPIX in - WIDTH/HEIGHT - <code>int32</code> - pixels. (To preserve aspect ratio, set width 0, use height as target. Or set height to 0 to use width as target.) returns: modified ppix or #f on error.

Unsharp mask ====

<procedure> pix-unsharp-mask PPIX SMOOTHING AMOUNT </procedure> in - PPIX in - SMOOTHING - filter is odd <code>int</code> such as 3, 5, 7. Input is halfwidth = (size - 1)/2, i.e., 1, 2, 3. in - AMOUNT is <code>float</code>, typically in range 0.2 to 0.7. returns: modified ppix.

<procedure> pix-unsharp-mask-fast PPIX HALFWIDTH AMOUNT DIRECTION </procedure> in - PPIX in - HALFWIDTH - <code>int</code>, 1 or 2 in - AMOUNT = <code>float</code>, 0.2 to 0.7 in - DIRECTION - <code>int</code>, horz: 1, vert: 2, both: 3 returns: modified ppix.

Pixel data input/output ====

<procedure> pix-create WIDTH HEIGHT DEPTH </procedure> in - WIDTH/HEIGHT - <code>int32</code>, in pixels. in - DEPTH - must be 1, 2, 4, 8, or 32 (Pix->data is <code>ptr to unsigned-int32</code>, array length = wh, elements initialized to 0.)* returns: ppix on success, #f on error.

<procedure> pix-get-data PPIX </procedure> in - PPIX (Returned data-array remains “owned” by ppix, array modified in place.) returns: <code>ptr to unsigned-int32</code> if successful, #f on error.

<procedure> pix-extract-data PPIX </procedure> in - PPIX (Unlike <code>pix-get-data</code>, returned value is ptr to newly alloc copy of ppix->data. ppix->data is set to NULL if ppix->refcount == 1.) returns: <code>ptr to unsigned-int32</code> on success, #f on error.

<procedure> pix-set-data PPIX DATAPTR </procedure> in - PPIX in - DATAPTR - <code>ptr to unsigned-int32</code> returns: 0 if successful, 1 on error. (Use <code>pix-free-data</code> prior to setting ppix data.)

<procedure> pix-get-pixel PPIX X Y PTR-PIXVAL </procedure> in - PPIX in - X, Y - <code>int32</code> - raster position out - PTR-PIXVAL - <code>ptr to unsigned-int32</code> returns: 0 on success, 1 on error

<procedure> pix-set-pixel PPIX X Y PIXEL-VALUE </procedure> in - PPIX in - X, Y - <code>int32</code> - raster position in - PIXEL-VALUE - <code>unsigned-int32</code> returns: 0 on success, 1 on error

<procedure> pix-get-rgb-component PPIX COLOR </procedure> in - PPIX in - COLOR - <code>int32</code>, one of COLOR_RED, COLOR_GREEN, COLOR_BLUE returns: ppix with data set to COLOR component, #f on error.

<procedure> extract-rgb-vals PIXEL PRED PGREEN PBLUE </procedure> in - a PIXEL - <code>unsigned-int32</code> in - PRED, PGREEN, PBLUE - optional, <code>ptr to int32</code> or #f returns: no return value.

<procedure> pix-get-rgb-line PPIX ROW PR PG PB </procedure> in - PPIX in - ROW - <code>int32</code> in - PR, PG, PB - <code>ptr to unsigned-byte</code>, array length = image width returns: 0 if success, 1 on error.

<pre>(import chicken.number-vector leptonic) (define red (make-u8vector img-width)) (define green (make-u8vector img-width)) (define blue (make-u8vector img-width)) (define r (pix-get-rgb-line ppix row (location red)

                           (locaton green) (location blue)))

(if (zero? r)

   ;; use red, green, blue vectors ...
   ;; handle error)</pre>

<procedure> pix-get-raster-data PPIX PUBYTE PNBYTES </procedure> in - PPIX out - PUBYTE - <code>ptr to unsigned-byte</code>, array-length = w * h * 3 out - PNBYTES - <code>ptr to size_t</code> returns: 0 on success, 1 if error.

Image manipulation ====

<procedure> pix-modify-sat PPIXD PPIX SAT </procedure> in - PPIXD - destination ppix, may be set to #f in - PPIX in - SAT - <code>float</code> - from -1.0 to 1.0 returns: modified ppix, or #f on error

<procedure> pix-invert PPIXD PPIX </procedure> in - PPIXD - may be #f in - PPIX returns: - inverted ppix or #f on error

<procedure> pix-and PPIXD PPIX0 PPIX1 </procedure> in - PPIXD - may be #f in - PPIX0, PPIX1 - image data to be “anded” returns: - PPIX0 AND PPIX1, or #f on error

<procedure> pix-or PPIXD PPIX0 PPIX1 </procedure> in - PPIXD - #f in - PPIX0, PPIX1 - image data to be “ored” returns: - PPIX0 OR PPIX1, or #f on error

<procedure> pix-xor PPIXD PPIX0 PPIX1 </procedure> in - PPIXD - #f in - PPIX0, PPIX1 - image data to be “xored” returns: - PPIX0 XOR PPIX1, or #f on error

<procedure> pix-shiftRGB PPIX RFRAC GFRAC BFRAC </procedure> in - PPIX in - RFRAC, GFRAC, BFRAC - <code>float</code> - fractional amount of change per channel returns: modified ppix or #f on error.

<procedure> pix-contrast PPIXD PPIX FACTOR </procedure> in- PPIXD - dest - #f or PPIX (use ‘pix-contrast PPIX PPIX …’) in - PPIX in - FACTOR - amount, 0.0 to 1.0 returns: modified ppix or #f if error.

<procedure> pix-mod-brightness PPIXD PPIX FACTOR </procedure> in - PPIXD - #f or PPIX in - PPIX in - FACTOR - amount -1.0 to 1.0 returns: modified ppix or #f if error.

<procedure> pix-mod-hue PPIXD PPIX FACTOR </procedure> in - PPIXD - #f or PPIX in - PPIX in - FACTOR - amount -1.0 to 1.0 (1.0/-1.0 == 360 degrees, no hue change) returns: modified ppix or #f if error.

<procedure> pix-equalize PPIXD PPIX FRAC SUBSAMPLE </procedure> in - PPIXD - #f or PPIX in - PPIX in - FRAC - 0.0 to 1.0 “equalization movement of pixels”, 1.0 == complete. in - SUBSAMPLE - factor > 1 => reduced computation returns: modified ppix or #f if error.

<procedure> pix-gamma PPIXD PPIX GAMMA MIN MAX </procedure> in - PPIXD - #f or PPIX (in-place modification, (<code>pix-gamma</code> PPIX PPIX ..) ) in - PPIX in - GAMMA - 1.0, no change, <1.0 darker, >1.0 lighter in - Min - MIN usually >=0, but may be < 0–black will be gray. in - MAX - MAX usually <= 255, but may be > 255, then whites are gray… returns: modified ppix or #f if error.

<procedure> pix-remove-alpha PPIX </procedure> in - PPIX returns: ppix with alpha removed, or #f on error.

<procedure> pix-map-to-color PPIXD PPIX SRCVAL DSTVAL </procedure> in - PPIXD - #f or same as PPIX in - PPIX in - SRCVAL - color specified as 0xrrggbb00 in - DSTVAL - color specified as 0xrrggbb00 returns: modified ppix or #f if error.

<procedure> pix-colorize-gray PPIX PIXEL CMAP? </procedure> in - PPIX - 8bit (grayscale) in - PIXEL - 32bit color spec, e.g., 0xrrggbb00 in - CMAP? - add colormap, 0 or 1 returns: modified ppix or #f if error.

<procedure> pix-bilateral PPIX SPATIAL RANGE NCOMPS REDUCTION </procedure> in - PPIX in - SPATIAL - stddev of gaussian kernel, pixels, >0.5 in - RANGE - stddev of gaussian range kernel, >5.0, typically 50.0 in - NCOMPS - intermediate sums, 4..30 in - REDUCTION - 1, 2, 4 returns: modified ppix or #f if error.

<procedure> pix-warp-stereo PPIX ZBEND ZSHIFTT ZSHIFTB YBENDT YBENDB RLEFT </procedure> in - PPIX in - ZBEND - <code>int</code> - horz sep (in px) red/cyan left/right sides in - ZSHIFTT - <code>int</code> Push top of image plane away (>0) or towards (<0) viewer in - ZSHIFTB - <code>int</code> - push bottom of image away or towards viewer in - YBENDT - <code>int</code> - Param for displacement right/left edge, y= ybendt*(2x/w-1)^2 in - RLEFT - <code>int</code> - 1 to put red filter on left, 0 otherwise returns: modified ppix or #f on error.

<procedure> pix-blend-color PPIXD PPIX1 PPIX2 X Y FRACT TRANSPARENT TRANSPIX </procedure> in - PPIXD - may be #f or same as PPIX in - PPIX1 - “blendee” in - PPIX2 - “blender”, usually smaller area than PPIX1 in - X, Y - origin of PPIX2 relative to origin of PPIX1 (pixels) in - FRACT - blending fraction in - TRANSPARENT - 1: use transparency, 0: don’t use transparency. in - TRANSPIX - color in PPIX2 to be made transparent, typically 0 or 0xffffff00 returns: blended ppix or #f on error.

Image properties ====

<procedure> ***pix-sizes-equal PPIX1 PPIX2 </procedure> in - PPIX1 PPIX2 - ppix to compare returns: 1 if {h,w,d} the same, 0 if not.

<procedure> ***pix-get-pixel-avg PPIX PPIXM X Y FACTOR PVAL </procedure> in - PPIX in - PPIXM - (optional) 1bit mask of area to measure, may be #f in - X Y - UL coords of mask relative to PPIX - ignored if PPIXM is #f in - FACTOR - subsampling factor 1, 2, 4 out - PVAL - <code>ptr to unsigned-int</code> - avg pixel val returns: 0 if “OK”, 1 on error.

<procedure> pix-compare-gray-or-RGB PPIX1 PPIX2 CMPTYPE PLOT PSAME PDIFF PRMSDIFF PPIXDIFF </procedure> in - PPIX1, PPIX2 - image data to compare in - CMPTYPE - subtract: 2, abs-diff: 3 in - PLOT - plot type, use 0 for no plot. out - PSAME PDIFF PRMSDIFF PPIXPTR - these are optional, use #f to skip. Otherwise, PSAME is <code>ptr to int32</code>, PDIFF/PRMSDIFF are <code>ptr to float</code>, PPIXDIFF is <code>ptr to ppix</code>. returns: 0 if “OK”, 1 if error.

<procedure> pix-color-content PPIX RREF GREF BREF MINGRAY RCONT GCONT BCONT </procedure> in - PPIX in - RREF GREF BREF - <code>int32</code> reference values for red,green,blue component. RREF/GREF/BREF must all be 0 or all not 0. When not 0, ref values describe an unbalanced white point, or mean color of background of scanned images. Set to 0 to turn off color transforms. in - MINGRAY - <code>int32</code> Pixels less than mingray are set to 0,0,0. set mingray to 0 to turn off filtering dark pixels. out - RCONT GCONT BCONT - <code>ptr to ppix</code> (optional, set to #f if unused) If used, filled with R/G/B 8bpp ppix corresponding to component color content. returns: 0 if “OK”, 1 on error.

<pre>(import scheme.base leptonic) (include "leptonic-types.scm") (define-external imgpix ppix (pix-read "myimage.jpg")) (define-external rcont ppix) (define-external gcont ppix) (define-external bcont ppix) (define r (pix-color-content imgpix 0 0 0 20 (location rcont)

   (location gcont) (location bcont)))

(if (zero? r)

   (begin
       ;; -- use the ppixs: rcont, gcont, bcont --
       (pix-destroy (location imgpix))
       (pix-destroy (location rcont))
       (pix-destroy (location gcont))
       (pix-destroy (location bcont)))
   ;; -- handle error --)</pre>

<procedure> pix-color-fraction PPIX DARKTHR LIGHTTHR DIFFTHR FACTOR PIXFRAC COLORFRAC </procedure> in - PPIX - 32bpp in - DARKTHR - <code>int32</code> Threshold near black. Pixels below aren’t included in stats. Typical: 20 in - LIGHTTHR - <code>int32</code> Threshold near white. Pixels above aren’t included in stats. Typical: 244 in - DIFFTHR - <code>int32</code> Threshold for max diff between R/G/B values. When diff is less, pixel is considered insufficiently colorful. Typical: 60 in - FACTOR - <code>int32</code> - Subsampling factor, 1, 2, 4. 1 is no subsampling. out - PIXFRAC - <code>ptr to float</code> - optional, use #f to skip. Fraction of pixels considered for color content. out - COLORFRAC - <code>ptr to float</code> - optional, use #f to skip. Fraction of pixels meeting criterion for sufficient color. 0.0 on error. returns: 0 if “OK”, 1 on error.

<procedure> pix-color-magnitude PPIX RREF GREF BREF TYPE </procedure> in - PPIX - 32bpp or 8bpp w/cmap in - RREF GREF BREF - <code>int32</code> Reference values for red, green, blue components, representing unbalanced white or avg background color of a scanned image. Image colors are adjusted according to the ref values. Set all to 0 to skip this adjustment. in - TYPE - one of intermediate-diff: 1, avg-max-diff: 2, max_diff: 3 returns: 8bpp ppix (amt of color in each src pixel) or #f on error.

Effects ====

<procedure> pix-clean-image PPIX CONTRAST ROTATE SCALE OPEN-SIZE </procedure> in - PPIX in - CONTRAST - <code>int32</code> - 1 (lightest) to 10 (darkest) in - ROTATE - <code>int32</code> - 0,1,2,3 (0,90,180,270 degrees cw) in - SCALE - <code>int32</code> - 1 or 2 (for 2X upscaling) in - OPEN-SIZE - <code>int32</code> - size for noise removal (0/1-none, 2,3 to use) returns: cleaned ppix or #f if error.

<procedure> gen-bin-maze WIDTH HEIGHT X Y SIDEWALL AHEAD </procedure> in - WIDTH - <code>int32</code> - image width in - HEIGHT - <code>int32</code> - image height in - X - <code>int32</code> - x start of maze in - Y - <code>int32</code> - y start of maze in - SIDEWALL - <code>float</code> - probability of wall to side of direction in - AHEAD - <code>float</code> - probability of wall drawn ahead of direction (Generates binary (monochrome) maze) returns: ppix or #f on error.

<pre>(import scheme.base chicken.foreign leptonic) (include "leptonic-types.scm") (define-external maze ppix)

; generate maze, 100x75px, starts at x=5,y=70px

(set! maze (gen-bin-maze 100 75 5 70 .52 .48)) (pix-write "maze.jpg" maze 2) (pix-destroy (location maze))</pre> <procedure> pix-sobel-edge-filter PPIX ORIENTATION </procedure> in - PPIX - 8bpp in - ORIENTATION - <code>int32</code> edges: horizontal: 0, vertical: 1, all: 2. returns: 8bpp ppix or #f if error.

Dithering ====

<procedure> pix-dither-2bpp PPIX CMAP? </procedure> in - PPIX - 8bpp/graymap in - CMAP? - generate colormap? 0=no, 1=yes Dithers to equally spaced gray values at 0, 85, 170, 255. returns: dithered ppix or #f if error.

<procedure> pix-dither-2bpp-spec PPIX LOWCLIP UPCLIP CMAP? </procedure> in - PPIX - 8bpp/graymap in - LOWCLIP - lower clipping point, should be 0 or a small number. in - UPCLIP - upper clipping point, should be 255 or slightly less. in - CMAP? - generate colormap, 0 or 1. returns: dithered ppix or #f if error.

<procedure> pix-dither-binary PPIX </procedure> in - PPIX - 8bpp/grayscale image. returns: dithered ppix or #f if error.

<procedure> pix-dither-bin-spec PPIX LOWCLIP UPCLIP </procedure> in - PPIX - 8bpp in - LOWCLIP - lower clipping point, should be 0 or a small number. in - UPCLIP - upper clipping point, should be 255 or slightly less. returns: dithered ppix or #f if error.

Threshold ====

<procedure> pix-threshold-to-binary PPIX THRESH </procedure> in - PPIX - 4 or 8bpp in - THRESH - if src pixel is < THRESH, dest is 1, else dest is 0. (Max pixel value for 8bpp == 255, 4bpp == 15.) returns: dithered 1bpp ppix or #f on error.

<procedure> pix-threshold-to-2bpp PPIX NLEVELS CMAP? </procedure> in - PPIX - 8bpp in - NLEVELS - 2..4 equally spaced levels in output ppix in - CMAP? - 0/1 returns: dithered 2bpp ppix or #f on error.

<procedure> pix-threshold-to-4bpp PPIX NLEVELS CMAP? </procedure> in - PPIX - 8bpp in - NLEVELS - 2..16 equally spaced levels in output in - CMAP? - 0/1 returns: dithered 4bpp ppix or #f on error.

<procedure> pix-threshold-on-8bpp PPIX NLEVELS CMAP? </procedure> in - PPIX - 8bpp in - NLEVELS - 2..256 equally spaced levels in output in - CMAP? - 0/1 returns: dithered 8bpp ppix or #f on error.

Conversion ====

<procedure> pix-RGB-to-gray PPIX RWT GWT BWT </procedure> in - PPIX - 32bpp RGB image in - RWT GWT BWT - <code>float</code> values, weights should add up to 1. returns: 8bpp ppix or #f if error.

<procedure> pix-RGB-to-gray-fast PPIX </procedure> in - PPIX - 32bpp RGB image returns: 8bpp ppix or #f if error.

<procedure> pix->32bit PPIX </procedure> in - PPIX - 1, 2, 4, 8, 16, 24 or 32 bpp returns: ppix or #f on error.

<procedure> pix->16bit PPIX </procedure> in - PPIX - 1, 8 bpp returns: ppix or #f on error.

<procedure> pix->8bit PPIX </procedure> in - PPIX - 1, 2, 4, 8, 16, 24 or 32 bpp returns: ppix or #f on error.

<procedure> pix->4bit PPIX </procedure> in - PPIX - 1, 2, 4, 8, 24 or 32 bpp returns: ppix or #f on error.

<procedure> pix->2bit PPIX </procedure> in - PPIX - 1, 2, 4, 8, 24 or 32 bpp returns: ppix or #f on error.

<procedure> pix->1bit PPIX </procedure> in - PPIX - 1, 2, 4, 8, 16, 24 or 32 bpp returns: ppix or #f on error.

<procedure> pix-RGB->HSV PPIXD PPIX </procedure> in - PPIXD - #f in - PPIX returns: converted ppix or #f on error.

<procedure> pix-HSV->RGB PPIXD PPIX </procedure> in - PPIXD - #f in - PPIX returns: converted ppix or #f on error.

<procedure> pix-RGB->XYZ PPIX </procedure> in - PPIX returns: converted ppix or #f on error.

<procedure> pix-RGB->YUV PPIXD PPIX </procedure> in - PPIXD - #f in - PPIX returns: converted ppix or #f on error.

<procedure> pix-YUV->RGB PPIXD PPIX </procedure> in - PPIXD - #f in - PPIX returns: converted ppix or #f on error.

<procedure> pix-RGB->hue PPIX </procedure> in - PPIX returns: converted ppix or #f on error.

<procedure> pix-RGB->sat PPIX </procedure> in - PPIX returns: converted ppix or #f on error.

<procedure> pix-RGB->value PPIX </procedure> in - PPIX returns: converted ppix or #f on error.

<procedure> pix-RGB->Lab PPIX </procedure> in - ppix returns: converted PFPIXA or #f on error.

<procedure> fpixa-Lab->RGB PFPIXA </procedure> in - PFPIXA (Lab) returns: converted PPIX or #f on error.

<procedure> fpixa-Lab->XYZ PFPIXA </procedure> in - PFPIXA (Lab) returns: converted PFPIXA or #f on error.

<procedure> fpixa-XYZ->Lab PFPIXA </procedure> in - PFPIXA (XYZ) returns: converted PFPIXA or #f on error.

<procedure> fpixa-XYZ->RGB PFPIXA </procedure> in - PFPIXA (XYZ) returns: converted PPIX or #f on error.

Error messages ====

<procedure> set-msg-level LEVEL </procedure> in - LEVEL <code>int32</code> - 1:all 2:debug+ 3:info+ 4:warn+ 5:error+ 6:none returns: - old level <code>int32</code>

Serializing data 32bit to 8bit, 8bit to 32bit ====

These routines are not from leptonica, but provided to facilitate conversion of 32 bpp data to 8 bpp arrays (in RGB order) and vice versa.

<procedure> u32->u8''3 PTR32 LEN PTR8* </procedure> in - PTR32 - <code>ptr to unsigned-int32</code> in - LEN - <code>int</code> - length of data - (image width * height) out - PTR8 - <code>ptr to unsigned-byte</code> returns: number of 32bit pixels (should be equal to LEN)

<procedure> u8''3->u32 PTR8 LEN PTR32* </procedure> in - PTR8 - <code>ptr to unsigned-byte</code> in - LEN - <code>int</code> - length of data (image width * height) out - PTR32 - <code>ptr to unsigned-int32</code> returns: number of 32bit pixels (should be equal to LEN)

<pre>(import scheme.base

       chicken.foreign 
       chicken.number-vector
       leptonic)

(include "leptonic-types.scm")

(define-external ppx0 ppix (pix-read "input.png")) (define data0 (pix-get-data ppx0))

(define w (pix-get-width ppx0)) (define h (pix-get-height ppx0)) (define len (* w h))

(define v8 (make-u8vector (* len 3) 0)) (u32->u8*3 data0 len (location v8))

; ... modify v8 ...

(define-external ppx1 ppix (pix-create w h 32)) (define data1 (pix-get-data ppx1))

(u8*3->u32 (location v8) len data1)

(define fmt (get-implied-fmt "output.png")) (pix-write "output.png" ppx1 fmt)

(pix-destroy (location ppx0)) (pix-destroy (location ppx1))</pre> Note: if u8vector ‘v8’ is not modified, then output to data1 (in u8*3->u32), will be identical to the input data in data0. IOW “output.png” will be a copy of “input.png”. Comparing the two image files serves as a test of the procedures: if everything is working properly, the image files should be completely indistinguishable.

Versions ===

0.1.0 (initial release)