F_VN_HistogramExp
Calculate the (multi-channel) histogram of an image. (expert function)
Can use available TwinCAT Job Tasks for executing parallel code regions.
Syntax
Definition:
FUNCTION F_VN_HistogramExp : HRESULT
VAR_INPUT
ipSrcImage : ITcVnImage;
ipDestHistogram : Reference To ITcVnContainer;
END_VAR
VAR_IN_OUT
nBins : UDINT;
fLowerBound : LREAL;
fUpperBound : LREAL;
END_VAR
VAR_INPUT
ipMask : ITcVnImage;
hrPrev : HRESULT;
END_VAR
Inputs
|
Name |
Type |
Description |
|---|---|---|
|
ipSrcImage |
Source image | |
|
ipDestHistogram |
Reference To ITcVnContainer |
Returns a container with a multi-channel histogram, where every channel is represented as a vector of UDINT (ContainerType_Vector_Vector_UDINT. Non-zero interface pointers are reused.) |
|
ipMask |
Source image mask (TCVN_ET_USINT, 1 channel. Mask is optional, set to 0 if not required.) | |
|
hrPrev |
HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.) |
In/Outputs
|
Name |
Type |
Description |
|---|---|---|
|
nBins |
UDINT |
Desired number of bins or 0 to keep the default for the corresponding image format (in) and default number of bins (out) |
|
fLowerBound |
LREAL |
Lower (inclusive) boundary of the 0-th histogram bin (in), or receive the default if fLowerBound AND fUpperBound are set to 0 (out) |
|
fUpperBound |
LREAL |
Upper (exclusive) boundary of the last histogram bin nBins-1 (in), or receive the default if fLowerBound AND fUpperBound are set to 0 (out) |
Return valueFurther information
The function F_VN_HistogramExp is the expert version of F_VN_Histogram. It contains additional parameters.
Parameter
Input image
The input image ipSrcImage can have any format.
Histogram
The calculated multichannel histogram is returned as a container ipDestHistogram of the type ContainerType_Vector_Vector_UDINT. Each sub-element corresponds to the histogram of one channel. Each container of the histogram is represented as a UDINT, which specifies the number of pixels belonging to the container.
Container
The number nBins defines how many containers the observed pixel spectrum is to be divided into.
Limits
The lower limit fLowerBound and the upper limit fUpperBound define which pixel values are taken into account when creating the histogram.
Mask
The mask ipMask defines which pixels of the input image ipSrcImage are taken into account in the calculation of the histogram. It is described by a 1-channel image with the element type USINT, which has the same size as the input image ipSrcImage. All pixels in the mask image with a value <> 0 are taken into account in the calculation of the histogram.
Application
The calculation of a histogram with 10 containers for the value range 100-200 with a circular mask looks like this, for example:
VAR
ipImageMask : ITcVnImage;
END_VAR
// Create mask image with a circle at image center.
hr := F_VN_CopyImage(ipImageIn, ipImageMask, hr);
hr := F_VN_SetPixels(ipImageMask, aBlack, hr);
hr := F_VN_DrawCircle(400, 300, 300, ipImageMask, aWhite, -1, hr);
hr := F_VN_HistogramExp(
ipSrcImage := ipImageIn,
ipDestHistogram := ipHistograms,
nBins := 10,
fLowerBound := 100,
fUpperBound := 201,
ipMask := ipImageMask,
hrPrev := hr
);
Samples
- Handling histograms
Required License
TC3 Vision Base
System Requirements
Development environment | Target platform | PLC libraries to include |
|---|---|---|
TwinCAT V3.1.4024.54 or later | PC or CX (x64) with PL50, e.g. Intel 4-core Atom CPU | Tc3_Vision |