Process methods reference

Here is a complete reference to process methods implemented until now. Well, if for some reason the process that you need is not here, you can implement and send to me. I'll be pleased to add your implementation in the next release.

Convert

function Convert(ChnSrc, Dst, ScalingMode: integer; Param1: single=1; Param2: single=0): pointer;

This is a powerful function that can be used in several ways. Converts one depth channel to another with optional normalization or linear transformation, but can be used to perform transformations in place. ScalingMode can assume one of follow values:

fi_NO_SCALE: No scaling is done. Conversions from 16 or 32 bits channels to 8 bits channel will be use the absolute value saturated at 255:
dst(x,y)= Min(255, Abs(Round(src(x,y))))
Conversions from 32 bits to 16 bits will be saturated at smallint range:
dst(x,y) = Min(32767, Max(-32768, Round(src(x,y))))
Param1 and Param2 are ignored.
fi_SCALE: Param1 and Param2 are used to perform a linear transformation:
dst(x,y) = src(x,y) * Param1 + Param2
Results are saturated at destination channel range (if is 8 or 16 bits).
fi_RANGE_TO_NORMAL: From 8 or 16 bits channels to 32 bits channels only. The source channel range ([0,255] to 8 bits or [-32768, 32767] to 16 bits) are used for mapping values between 0 and 1 on destination channel. Param1 and Param2 are ignored.
fi_NORMAL_TO_RANGE: From 32 bits channels to 8 or 16 bits channels only. Reverse operation as described above. Param1 and Param2 are ignored.
fi_PARAMS_TO_NORMAL: Param1 and Param2 are used to maps values between 0 and 1 (Param1 map to 0 and Param2 map to 1), destination channel must be 32 bits.
fi_NORMAL_TO_PARAMS: Reverse operation as described above. Source channel must be 32 bits and the values on Param1 and Param2 must be in destination channel range.
fi_MINMAX_TO_RANGE: The minimum and maximum values on source channel are used to map values on destination range channel. At moment, destination must be 8-bits channel. This option is very useful to graphically show 16 and 32 bits channels. Param1 and Param2 are ignored.

The table below resumes the operations allowed with channels combinations:
Source/Destination 8 bits 16 bits 32 bits
8 bits fi_NO_SCALE
fi_SCALE
fi_MINMAX_TO_RANGE fi_NO_SCALE
fi_SCALE fi_NO_SCALE
fi_SCALE
fi_RANGE_TO_NORMAL
fi_PARAMS_TO_NORMAL
16 bits fi_NO_SCALE
fi_SCALE
fi_MINMAX_TO_RANGE fi_NO_SCALE
fi_SCALE fi_NO_SCALE
fi_SCALE
fi_RANGE_TO_NORMAL
fi_PARAMS_TO_NORMAL
32 bits fi_NO_SCALE
fi_SCALE
fi_NORMAL_TO_RANGE
fi_NORMAL_TO_PARAMS
fi_MINMAX_TO_RANGE fi_NO_SCALE
fi_SCALE
fi_NORMAL_TO_RANGE
fi_NORMAL_TO_PARAMS fi_NO_SCALE
fi_SCALE
fi_PARAMS_TO_NORMAL
fi_NORMAL_TO_PARAMS

Threshold

function Threshold(ChnSrc, Dst, ThreshType: integer;
Thresh, MaxVal: single): pointer;
Fixed threshold. Thresh and MaxVal is single to compatibility, but theirs values must be in the source channel depth range. There are several types of thresholding that the function supports that are determined by ThreshType parameter. This method is inspired on cvThreshold function of OpenCV library and works similarly. MaxValue is the value that be used to represent active pixels.

ThreshType values:
fi_THRESH_BINARY:
dst(x,y)= MaxVal if src(x,y) > Thresh; 0 otherwise

fi_THRESH_BINARY_INV:
dst(x,y)= 0 if src(x,y) > Thresh; MaxVal otherwise

fi_THRESH_TRUNC:
dst(x,y)= Thresh if src(x,y) > Thresh; src(x,y) otherwise

fi_THRESH_TOZERO:
dst(x,y)= src(x,y) if src(x,y) > Thresh; 0 otherwise

fi_THRESH_TOZERO_INV:
dst(x,y)= 0 if src(x,y) > Thresh; src(x,y) otherwise

BinaryInv
function BinaryInv(ChnSrc, Dst: integer;
MaxVal: single): pointer;
Binary inversion of image. This method considers the image or channel with binary data. In this case, pixels are considered active or inactive depending of their level values. Level equal zero means inactive pixel and any other value means active. MaxVal parameter is used to represent active pixels on destination. The same effect can be obtained with Convert and Threshold methods, but BinaryInv is more efficient and faster.

Mathematical Morphology
To support operations of mathematical morphology, unit FastImgEx defines the class TfiBinMask to work as a structural element (see chapter 5). At present implementation is only performed with binary structuring elements, but they can also be applied in gray or color images. In the case of color images the operation is performed individually in each color channel.
Dilate and Erode
function Dilate(ChnSrc, Dst, Iterations: integer;
bMask: TfiBinMask; Binary: boolean=false): pointer;
function Erode(ChnSrc, Dst, Iterations: integer;
bMask: TfiBinMask; Binary: boolean=false): pointer;
Perform morphological dilation/erosion on channel/image. Iterations informs how many times the process will be applied. Mask is the structuring element that will be used (see discussion above). If Mask = nil, a square 3x3 mask will be used. Binary informs if process will be applied in binary mode or gray mode. Gray mode is more generic and works with binary images too, but in binary mode it is possible to make optimizations that make the processing at least three times faster.
Gray images
The dilate/erode operations when applied on gray images use structuring elements in gray level as well. In this case, the structuring element values and the values of image pixels are added in pairs keeping the correspondence of position and the result of operation for the pixel being processed is the maximum or minimum of the values obtained, depending on whether the operation is dilation or erosion. Since this implementation only supports binary structural elements, the maximum and minimum are calculated solely on the image pixels, without addition.
Borders
It is not very well explained by the definition of mathematical morphology how to treat border pixels when the structuring element is partially outside the image, but this is a problem that any implementation needs to solve. The solution used by this implementation is to consider in the calculation only the points of the structural element that actually are in the image and ignore the others. This solution avoids having to modify the image, adding artificial rows and columns, and allow process, although not exactly, the border pixels.
Very important
Morphological operations, like any operation involving the neighborhood of pixels, do not allow in place processing natively. However, the current implementation allows (or simulated) process in place, but for best performance, does not guarantee that the reference to maps inside the channels used will be maintained, although the references to the channel remain. This means that if you stored a reference to the map on a channel and then made a morphological operation in place with this channel, this reference has become invalid. See the example below:

var
fi: TFastImgEx;
Mp8: PByteMap;
begin
[…]
// Mp8 stores a direct reference to map inside the first channel of fi.
Mp8:= fi.Map8[fi_BIN];
[…]
// in place dilation on first channel of fi
fi.Dilate(fi_BIN, fi_INPLACE_CHN+fi_BIN, 3, Mask, true);

// Reference stored on Mp8 is invalid now, you need get again
Mp8:= fi.Map8[fi_BIN];
[…]
end;
High-level morphological operations
Erosion and dilation are the basis for a large number of highest level morphological operations. The Open and Close operations are the best known, but there are many others. The method Morphology implements high-level morphological operations based on erosion and dilation operations.

function Morphology(ChnSrc, Dst, Operation, Iterations: integer;
Mask: TfiBinMask; Binary: boolean): pointer;
The Operation parameter can assume the values below. To explanation to other parameters see the Dilate and Erode discussion above.

fi_MPH_OPEN
Open: dst = Dilate(Erode(src, mask), mask)

fi_MPH_CLOSE
Close: dst = Erode(Dilate(src, mask), mask)

fi_MPH_GRAD
Gradient: dst = Dilate(src, mask) – Erode(src, mask)

fi_MPH_TOPHAT
Top Hat: dst = src – Open(src, mask)

fi_MPH_BLACKHAT
Black Hat: dst = Close(src, mask) – src

fi_MPH_INBORD
In Border: dst = src - Erode(src, mask)

fi_MPH_OUTBORD
Out Border: dst = Dilate(src, mask) – src

Arithmetic operations
To provide arithmetic operations between images, TFastImageEx implement function Arithmetic. All arithmetic operations require two operands, the first one is a channel in the image that calls the method and the second operand is informed by parameter Operand. At present implementation arithmetic’s operations only can be performed from specific channels, not from entire image. The function returns a reference to destination channel.

function Arithmetic(ChnSrc, Dst, Operation: integer; Operand: TfiChannel;
Param1: single=1; Param2: single=1): TfiChannel;

ChnSrc:
The index of the channel to be the first operand. The constant fi_ALL_CHANNELS is not allowed here.
Dst:
Destination channel to store the results. Can be a channel on image, the second operand, or a new channel. To specify a channel in image use the constant fi_INPLACE_CHN and add the channel index. To use the second operand to store the result, use the constant fi_OPERAND and to create a new channel use the constant fi_NEW_CHANNEL or one of the constants that specify the depth of new channel: fi_NEW_CHN_8B, fi_NEW_CHN_16B, fi_NEW_CHN_32B.
Operation:
There are several operations available. The constants below select witch operation will be executed.
fi_ARIT_SUM:
dst(x,y)= src(x,y) + oper(x,y)
fi_ARIT_SUB:
dst(x,y)= src(x,y) - oper(x,y)
fi_ARIT_ABSSUB:
dst(x,y)= Abs(src(x,y) - oper(x,y))
fi_ARIT_MULT:
dst(x,y)= src(x,y) * oper(x,y)
fi_ARIT_MAX:
dst(x,y)= Max(src(x,y), oper(x,y))
fi_ARIT_MIN:
dst(x,y)= Min(src(x,y), oper(x,y))
fi_ARIT_AVRG:
dst(x,y)= (src(x,y)Param1 + oper(x,y)Param2)/(Param1+Param2)
fi_ARIT_GRAD:
dst(x,y)= sqrt(src(x,y)src(x,y) + oper(x,y)oper(x,y))
fi_ARIT_QUADSUM:
dst(x,y)= src(x,y)src(x,y) + oper(x,y)oper(x,y)

Operand:
Reference to channel that will be the second operand on operation.
Param1, Param2:
Parameters used by operation. Until now, only fi_ARIT_AVRG use these parameters, in other operations they are ignored.

Convolution
Many common filters in image processing use the convolution of masks over image. To support mask convolutions the package implements method Convolve:

function Convolve(ChnSrc, Dst: integer; gMask: TfiGrayMask): pointer;
This method performs the convolution of mask informed in parameter. Mask must be grey, binary masks are not allowed. The result of convolution for each pixel is the sum of multiplication of values on mask with pixels on corresponding position and divides by Weight attribute of mask.
Sobel
Perform the Sobel algorithm to extract borders of image. The same result can be achieved using the Convolve method with the appropriate masks, but since it is a widely used algorithm, a specific method has created. Sobel algorithm, like many others convolution filters, can produce results out of byte range, including negative values when vertical or horizontal operators are convolved. To avoid data loss, this implementation always use a 32 bits channel as temporary destination and then convert the result to depth of channel informed as final destination.

function Sobel(ChnSrc, Dst, Operation: integer): pointer;
Operation can be:
fi_SOBEL_VERT: Vertical operator.
fi_SOBEL_HOR: Horizontal operator.
fi_SOBEL_GRAD: Gradient.

Match
This function convolves a binary mask over the image and test if every point in mask match with corresponding pixels at position tested. Is a binary operation, a pixel is considered active if their value is different of zero or inactive if their value is zero.

function Match(ChnSrc, Dst, Operation: integer; bMask: TfiBinMask;
Param1, Param2: single): pointer;

Operation can be:

fi_MATCH_VALIFMATCH:
Destination pixel assume Param1 value if the mask match; no action otherwise. Param2 parameter is ignored.

fi_MATCH_VALNOMATCH:
Destination pixel assume Param2 value if the mask don’t match; no action otherwise. Param1 parameter is ignored.

fi_MATCH_VALTOBOTH:
Destination pixel assume Param1 value if the mask match or assume Param2 value if the mask don’t match.

fi_MATCH_STAMP:
Mask is stamped on destination channel if mask match with pixel on source channel, no action otherwise. There is no check, but this operation makes more sense if the destination is different of source. Param1 value is used to represent active pixels on destination and Param2 value to represent inactive pixels.