ColorHistogram3 Method

Syntax

CWIMAQVision.ColorHistogram3 SourceImage, ColorFormat [, NumberOfClasses = 256] [, Plane1HistogramReport] [, Plane2HistogramReport] [, Plane3HistogramReport] [, WhiteReference] [, MaskImage]

Return Type

Variant

On success, this method returns 0. On failure, this method returns a negative number.

Purpose

Calculates the histogram, or pixel distribution, of a color image.

Remarks

Use this method with image types RGB32 and HSL32. MaskImage must be a U8 image.

Parameters

SourceImage As CWIMAQImage

The color image used to compute the histogram.

ColorFormat As CWIMAQColorFormats

The color space in which to perform the histogram.

NumberOfClasses As Variant

[Optional] The number of classes into which the method separates the pixels.

This parameter has a default value of 256.

Plane1HistogramReport As Variant

[Optional] On return, a CWIMAQHistogramReport object containing detailed statistics from the histogram calculated on the red, hue, X, or L* plane, depending on the value of ColorFormat.

Plane2HistogramReport As Variant

[Optional] On return, a CWIMAQHistogramReport object containing detailed statistics from the histogram calculated on the green, saturation, Y, or a* plane, depending on the value of ColorFormat.

Plane3HistogramReport As Variant

[Optional] On return, a CWIMAQHistogramReport object containing detailed statistics from the histogram calculated on the blue, lightness, value, intensity, Z, or b* plane, depending on the value of ColorFormat.

WhiteReference As Variant

[Optional] A CWIMAQCIEXYZColor object specifying the white reference value to use when the CIE Lab color format is selected.

MaskImage As Variant

[Optional] A CWIMAQImage object that indicates the region to use for computing the histogram. The method calculates the histogram using only those pixels in the image whose corresponding pixels in the mask are non-zero. Do not set this parameter if you want to perform a histogram on the entire image.

Example

'To run this example, add three picture boxes to your form, select a region of interest,
'and click run.
Private Sub Run_Click()
    Dim RedPlaneReport As New CWIMAQHistogramReport
    Dim GreenPlaneReport As New CWIMAQHistogramReport
    Dim BluePlaneReport As New CWIMAQHistogramReport
    Dim MaskImage As New CWIMAQImage
    Dim Colors As Variant
    Dim I As Integer
    
    ' Find the histogram of a portion of the image in Viewer1
    ' defined by the regions on Viewer1.
    CWIMAQVision1.RegionsToMask MaskImage, CWIMAQViewer1.Regions
    
    'Compute the histogram for each color plane
    CWIMAQVision1.ColorHistogram3 CWIMAQViewer1.Image, cwimaqColorFormatRGB, , RedPlaneReport, GreenPlaneReport, BluePlaneReport, MaskImage
    
    'Draw the histogram results to a picture control
    ReDim Colors(0 To 255) As OLE_COLOR
    
    For I = 0 To 255
        Colors(I) = RGB(I, 0, 0)
    Next I
    DrawHistogramResults Picture1, RedPlaneReport(1).Histogram, Colors
    
    For I = 0 To 255
        Colors(I) = RGB(0, I, 0)
    Next I
    DrawHistogramResults Picture2, BluePlaneReport(1).Histogram, Colors
    
    For I = 0 To 255
        Colors(I) = RGB(0, 0, I)
    Next I
    DrawHistogramResults Picture3, GreenPlaneReport(1).Histogram, Colors
End Sub

'Draw the histogram results to a picture control
Private Sub DrawHistogramResults(Picture As PictureBox, Histogram As Variant, Optional ColorArray As Variant)
    Dim I As Long
    Dim N As Long
    Dim Width As Long
    Dim Height As Long
    Dim MaxCount As Long
    
    If IsMissing(ColorArray) Then
        ReDim ColorArray(0 To 255) As OLE_COLOR
        For N = 1 To 255
            ColorArray(N) = RGB(N, N, N)
        Next N
    End If
    
    'Find the peak
    MaxCount = 0
    If Not IsMissing(Histogram) Then
        For N = 1 To 255
            If Histogram(N) > Histogram(MaxCount) Then
                MaxCount = N
            End If
        Next N
        MaxCount = Histogram(MaxCount)
    End If
        
    'If there are no results, exit the routine
    If MaxCount = 0 Then Exit Sub
    
    'Clear the picture
    Picture.Cls
    
    'Compute the width and height of the picturebox control, in pixels
    Picture.ScaleMode = vbPixels
    Width = Picture1.ScaleWidth
    Height = Picture1.ScaleHeight
    
    'Draw a line the appropriate height and color for each pixel found.
    For I = 0 To Width - 1
        N = (I * 256 / Width)
        Picture.Line (I, Height * (1 - Histogram(N) / MaxCount))-(I, Height), ColorArray(N)
    Next I
End Sub