Image processing primitives

Common scanner interface

Instances of image processing primitives are called scanners. Scanners possess any number of state variables called parameters, each of which may be readable, writable, or both.

All scanners share a set of methods, independently of the number of images they process, the number and type of their parameters, the fact that they are stateful or stateless, et caetera.

A scanner has an accessor and a mutator method, à la Tk:

myScanner cget -paramName
myScanner configure ?-paramName value1?...

The cget method is only avaible for scanners which have at least one readable parameter. The configure method is only avaible for scanners which have at least one writable parameter. Multiple parameters may be written using one method call.

The constructor of scanners accepts the same arguments as the configure method:

gmlScannerMyScanner myScanner ?-paramName value?...

The process method is used to run a scanner on a number of operands. Operands are defined by a number of bitmaps and regions of interest. For instance, for a scanner that accepts two operands:

myScanner process bitmap0 bitmap1
                  -rect0 {left0 top0 right0 bottom0}
                  -rect1 {left0 top0 right0 bottom0}

gmlScannerAdaptativeThreshold

Threshold (binarize) a grayscale bitmap (operand 0).

Source values above the adapted threshold are given the value 0xFF (white), 0x00 (black) else.

Number of operands: 2 (in, out).

Parameters:

gmlScannerAdd

Store in the destination bitmap (operand 2) the pixel-wise sum of the source bitmaps (operands 0 and 1).

With <-saturate>, addition saturates, i.e. is not done modulo 256. For instance if operand 1 has value 140 and operand 0 has value 120, the result is 255.

Number of operands: 3 (in, in, out).

Parameters:

gmlScannerApplyGaussian

Create a correspondence map between a bitmap and a colormodel gaussian.

Number of operands: 2 (in, out).

Parameters:

gmlScannerApplyHistogram

Create a correspondence map between a bitmap and a colormodel histogram; each output pixel is set to the corresponding histogram bin value, scaled so that the maximum bin value corresponds to the maximum pixel value if the output image.

Number of operands: 2 (in, out).

Parameters:

gmlScannerChannel

If first operand is a planar image, copy it to a given channel of the (multi-channel) destination image.

If the first operand is a multi-channel image, copy one of its channels to the destination planar image.

Only works for encodings where channels are 1 byte wide. For 1-bit wide channel, use the <bitmask> series of scanners.

Number of operands: 2 (in, out).

Parameters:

gmlScannerCopy

Copies a bitmap (operand 0) to another (operand 1), possibly changing the pixel format.

Number of operands: 2 (in, out).

gmlScannerCorrelate

Compute the peak of the normalized cross-corelation coefficient between a bitmap (operand 0) and a model (passed as parameter).

If requested, a non-normalized correlation map will also be output to the destination bitmap (operand 1).

Note that the scanned region in operand 0 must be smaller than the image: borders corresponding to the model's horizontal and vertical radii must be respected.

Number of operands: 2 (in, out).

Parameters:

gmlScannerDemultiplex

Break a 4-channel image into 4 gray-scale planes.

Number of operands: 5 (in, out, out, out, out).

gmlScannerDistancemap

Compute the distance between two images and store it in a planar image.

The metric used depends on the encoding. If both bitmaps are planar, the absolute difference is used; if both are in RGB colorspace, the city block distance is used; if one of the bitmaps is in LRG or HSV colorspace, the other is converted to the same colorspace and the Distance() method of the corresponding class is used.

As this scanner is intended to be used to compare similar images, the distance can be linearly scaled up using the -scale-factor option.

Number of operands: 3 (in, in, out).

Parameters:

gmlScannerDump

Dump a textual representation of a bitmap to a file.

Zeroes are replaced with periods (dots).

Number of operands: 1 (in).

Parameters:

gmlScannerExposure

Store in the destination bitmap (operand 1) over- and under-exposure information about the source bitmap (operand 0).

Destination values are 0x00 (under-exposed pixel), 0xFF (over-exposed pixel), and 0x7F (normal pixel). Exposure theshdold is configurable.

Number of operands: 2 (in, out).

Parameters:

gmlScannerFill

Fills a bitmap (operand 0) with a given color.

If an alpha channel is present, it it used to blend the image with the fill color.

Number of operands: 1 (inout).

Parameters:

gmlScannerHistogram

Fill in the parameter histogram using the luminance or chrominance samples of the bitmap (operand 0).

If an alpha channel is present, the samples are weighted by the alpha value.

Number of operands: 1 (in).

Parameters:

gmlScannerInvertLuminance

Inverts the luminance component of a bitmap.

For RGB encodings, this is acheived by converting each pixel to a colorspace that separates the luminance component (namely, HLS).

Number of operands: 2 (in, out).

gmlScannerLookup

Generates a greyscale bitmap (operand 1) by applying an histogram lookup to the input (operand 0) image.

XXX detail cases per-encoding

Number of operands: 2 (in, out).

Parameters:

gmlScannerLrg

Transform a bitmap between RGB and LRG colorspaces.

Number of operands: 2 (in, out).

gmlScannerLuminance

Compute the mean and standard deviation of the image (operand 0) luminance, and the normalized image energy.

When possible, each luminance value is weighted with the alpha value.

Number of operands: 1 (in).

Parameters:

gmlScannerMapThreshold

Threshold (binarize) a grayscale bitmap (operand 0).

The thresholding operation is:

p2 = (p0 < factor * p1) ? 0x00 : 0xFF

where <factor> is a scanner parameter (defaults to 15%).

Number of operands: 3 (in, in, out).

Parameters:

gmlScannerMapmerge

Merge some of the second operand bitmap into the first, according to the merge map in the third operand.

The lookup table provided as parameter is used to transform the map coefficients. It can be generated using the Scanner_ramps module.

Naming the two source pixels p0 and p1, the corresponding map pixel w0 (scalar weight), and the lookup table t, p0 will be overwritten by:

p0 * (1 - t[w0]) + p1 * t[w0]

Number of operands: 3 (inout, in, in).

Parameters:

gmlScannerMerge

Composite two images, a background (first operand) and a layer (second operand), according to the layer alpha (opacity) channel.

The layer's overall opacity is the scanner's parameter. The composited image is stored in the third operand.

Number of operands: 3 (in, in, out).

Parameters:

gmlScannerMoments

Compute the moments of a greyscale (or planar) image. Each pixel weight is its value (shade of gray), white (0xFF) being the highest weight.

BUG: For now only the first moment is computed. Finding the second moment will probably require a second pass on the image.

Number of operands: 1 (in).

Parameters:

gmlScannerMorphCsmooth

Conservative smoothing filer. Clamp the value of each pixel center coefficient within the minimum and maximum values of its neighborhood.

Number of operands: 2 (inout, out).

gmlScannerMorphDilate

Applies a 3x3 morphological dilation using the MAX operator.

Number of operands: 2 (inout, out).

gmlScannerMorphDilateBin

Applies a 3x3 morphological dilation using the OR operator.

Number of operands: 2 (inout, out).

gmlScannerMorphErode

Applies a 3x3 morphological erosion using the MIN operator.

Number of operands: 2 (inout, out).

gmlScannerMorphErodeBin

Applies a 3x3 morphological erosion using the AND operator.

Number of operands: 2 (inout, out).

gmlScannerMorphGauss

Applies a gaussian blur to the image, using a 3x3 kernel.

Number of operands: 2 (inout, out).

gmlScannerMorphMedian

Median smoothing filter.

Number of operands: 2 (inout, out).

gmlScannerMorphMedianBin

Median smoothing filter.

Number of operands: 2 (inout, out).

gmlScannerMorphSobelMax

Applies a Sobel filter to the image, using a 3x3 kernel. The resulting image show the gradient module (approximated the maximum of the horizontal and vertical derivatives).

Number of operands: 2 (inout, out).

gmlScannerMorphSobelx

Applies a horizontal Sobel filter to the image, using a 3x3 kernel.

Number of operands: 2 (inout, out).

gmlScannerMorphSobely

Applies a vertical Sobel filter to the image, using a 3x3 kernel.

Number of operands: 2 (inout, out).

gmlScannerMultiplex

Merge 4 gray-scale planes into one multi-channel image.

Number of operands: 5 (out, in, in, in, in).

gmlScannerNoise

Add noise to a bitmap. One of several algorithms can be used:

0. uniform noise, with radius sigma (from 0 to 1)
1. gaussian white noise, with radius sigma

Number of operands: 2 (in, out).

Parameters:

gmlScannerOpacify

Copy the source image (operand 0) to the destination image (operand 1), preserving the R, G, and B channels but setting the X or A destination channel to 0xFF.

Number of operands: 2 (in, out).

gmlScannerProject

caca

Number of operands: 1 (out).

Parameters:

gmlScannerScaleGray

Input image is a gray-scale (or single-channel) image in operand 0. Each output pixel p1 is obtained as:

p1 = (scale * p0 + bias) ^ exp

where scale and bias and exp are given as scanner parameters.

Number of operands: 2 (in, out).

Parameters:

gmlScannerShift

Bit-shift each pixel value right by the number of bits given as parameter.

Number of operands: 2 (in, out).

Parameters:

gmlScannerStriplets

Number of operands: 2 (in, out).

Parameters:

gmlScannerSubstract

Pixel-wise substract operand 1 from operand 0, storing the result in operand 2.

With -saturate, substraction saturates, i.e. is not done modulo 256. For instance if operand 1 has value 255 and operand 0 has value 120, the result is 0.

Number of operands: 3 (in, in, out).

Parameters:

gmlScannerSwap

Swap channels in an image. The implemented variants are:

0. BGR to RGB, or XBGR to XRGB
1. RGBX to XRGB
2. BGRX to XRGB

Number of operands: 2 (in, out).

Parameters:

gmlScannerThreshold

Threshold (binarize) a grayscale bitmap (operand 0).

Source values above the parameter threshold are given the value 0xFF (white), 0x00 (black) else. Regardless of the source encoding, threholds should have values between 0 and 255 inclusive.

Number of operands: 2 (in, out).

Parameters: