Image processing primitives

This page lists the interfaces of all image processing primitives present in the GML toolkit.

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:

Flag Direction Description
-threshold <float> inout Threshold
-window <float> inout Window
-direction <0|1> inout 0 is horizontal, 1 is vertical

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:

Flag Direction Description
-saturate <boolean> in If false, computation is done modulo 256

gmlScannerApplyGaussian

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

Number of operands: 2 (in, out).

Parameters:

Flag Direction Description
-model <5-floats> in Gaussian model

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:

Flag Direction Description
-histogram <histogram object> in Destination histogram object
-scale <small-integer> in histogram bits (default 8)

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:

Flag Direction Description
-channel <integer> in Index of the operand channel

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:

Flag Direction Description
-model <bitmap> inout Model used for cross-correlation
-ccc-min <float> out Minimum computed cross-correlation coefficient
-ccc-max <float> out Maximum computed cross-correlation coefficient
-peak <float pair> out Coordinates of the peak of the cross-correlation coefficient
-flag-output-map <boolean> inout Should the correlation map be output?
-refine-peak <integer> inout Radius of the peak refinement post-processing

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:

Flag Direction Description
-scale-factor <integer> inout Factor used to scale up the distance map

gmlScannerDump

Dump a textual representation of a bitmap to a file.

Zeroes are replaced with periods (dots).

Number of operands: 1 (in).

Parameters:

Flag Direction Description
-file-name <file path> in Path to dump file

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:

Flag Direction Description
-threshold <integer> in Value under which a pixel is considered to be hyper-exposed
-under-exposed <integer> in Set under-exposed pixels to this value
-over-exposed <integer> in Set over-exposed pixels to this value
-normal <integer> in Set over-exposed pixels to this value

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:

Flag Direction Description
-color <rgb color> in Fill color

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:

Flag Direction Description
-histogram <histogram object> in Destination histogram object
-scale <small-integer> in histogram bits (default 8)

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:

Flag Direction Description
-histogram <value list> inout Lookup histogram object

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:

Flag Direction Description
-mean <float> out Computed luminance average
-stddev <float> out Computed luminance standard deviation
-energy <float> out Computed image energy

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:

Flag Direction Description
-factor <fraction> inout Threshold factor (0..1)

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:

Flag Direction Description
-ramp <fraction list> in Lookup table of composition coefficients. Length must be 256.

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:

Flag Direction Description
-factor <fraction> inout Compositing factor (overall opacity)

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:

Flag Direction Description
-center <<float list>> out Computed first moment
-covariance <<float list>> out Computed covariance

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:

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

Number of operands: 2 (in, out).

Parameters:

Flag Direction Description
-variant <integer> inout The index of the noise algorithm used
-sigma <integer> inout The radius of the spread noise

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:

Flag Direction Description
-matrix <float-list> inout Row-major flat 3x3 matrix
-source <bitmap> in Source image

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:

Flag Direction Description
-scale <float> inout Scale applied to input fragments
-bias <float> inout Bias applied to input fragments
-scaling <boolean> inout Should exponential scaling be applied ?
-scaling-exp <boolean> inout What scaling exponent should be applied ?

gmlScannerShift

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

Number of operands: 2 (in, out).

Parameters:

Flag Direction Description
-bits <small integer> in Number of bits to shift right.

gmlScannerStriplets

Number of operands: 2 (in, out).

Parameters:

Flag Direction Description
-setup <list-of-floats> inout Coordinates of all striplets. List of n*8 floating-point values, where n is the number of striplets.
-matrix <list-of-floats> inout The 9 elements of the homography from projector to camera coordinates, in row-major order.
-result <list of floats> out List of the striplet responses, ranging from -1 to 1.
-reset <flag> inout Indicate that the list of striplets was updated.
-flag-output-map <boolean> inout Should the striplet mask map be output?

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:

Flag Direction Description
-saturate <boolean> in If false, computation is done modulo 256

gmlScannerSwap

Swap channels in an image. The implemented variants are:

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

Number of operands: 2 (in, out).

Parameters:

Flag Direction Description
-variant <integer> inout Channel swapping variant to use

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:

Flag Direction Description
-threshold <float> in Threshold