IMcGraphObjBitmapMaskBitmap Method

Sub MaskBitmap ( 
	<OptionalAttribute> MaskBitmapSource As Object,
	Optional Frame As Integer = -1,
	Optional MaskOptionFlags As mcGraphObjMaskBitmapOptions = mcGraphObjMaskBitmapOptions.mcgmboNone,
	<OptionalAttribute> SourceRect As Object,
	<OptionalAttribute> DestOffset As Object
)

'This is McGraphObjBitmapSamples.bas

Option Explicit

'Note: the BoneBig.jpg example image is a good one for most of these examples
Private Function uLoadExampleImage(Optional strImage As String = "BoneBig.jpg") As Boolean
    If MsgBox("Open example image?", vbYesNo) = vbYes Then
        Images.Open Path + "Images\" + strImage
    End If 'user wants to open an example image
    'Else leave the ActiveImage alone
    If ActiveImage Is Nothing Then
        MsgBox "There is no ActiveImage, so the example cannot run."
    Else
        Output.Show "Output"
        Output.Clear
        ActiveImage.RegionFeatures.Reset
        ActiveImage.LineFeatures.Reset
    End If
    uLoadExampleImage = ActiveImage Is Nothing
End Function 'uLoadExampleImage

'This function gets a bit mask of thresholded regions within the AOI
' of the ActiveImage that are larger than 200 pixels in size
Private Function fGetBitMaskFromBigRegions() As McBitMask
    With ActiveImage
        .RegionFeatures.Threshold.Execute 'get some regions
        Dim selBigOnes As McObject
        Set selBigOnes = McOpGT(.RegionFeatures.mRgnArea, 200)  'larger than 200 pixels
        Dim myBitMask As McBitMask
        Set myBitMask = .RegionFeatures.CreateFeatureMask(mcfmfReturnMcBitMask, selBigOnes, .Aoi.BoundingRect)
        Output.PrintMessage "The mask of big regions has " & myBitMask.BlobCount & " blobs."
        Output.PrintMessage "It is " & myBitMask.Width & " wide by " & myBitMask.Height & " high."
        Set fGetBitMaskFromBigRegions = myBitMask
    End With 'ActiveImage
End Function 'fGetBitMaskFromBigRegions

'Show a color McImage as a McGraphObjBitmap on the AnnotationOverlay.
'Make part of the color range of the displayed bitmap be transparent.
'
Public Sub ShowColorMcImageAsBitmap()
    Windows.CloseAll 'start with a clean plate
    Dim mySrcImage As McImage
        'ColorBlk.tif goes from 0-255 Red top to bottom, 255-0 Blue
        'top to bottom and 0-255 Green, left to right.
    Set mySrcImage = Images.Open(Path + "Images\ColorBlk.tif")
        'Set a circular AOI covering the whole color block
    ActiveImage.Aoi.SetEllipse 0, 127.5, 127.5, 255, 255
    ActiveWindow.Position = Array(410, 10) 'move it to the right

        'Open an underlying grayscale image
    Images.Open (Path + "Images\BoneBig.jpg")
    ActiveWindow.Position = Array(5, 10)
        'Show ColorBlk.tif on top of BoneBig.jpg as a McGraphObjBitmap
        'Note that the overlay shows in color even though BoneBig is monochrome
    With ActiveImage.AnnotationOverlay
        Dim myBM As McGraphObjBitmap
        Set myBM = .Add("McGraphObjBitmap")
        myBM.SetPosition 10, 10
        myBM.SetBitmap mySrcImage
        myBM.NotifyCreationComplete
        MsgBox "The whole circular AOI of the ColorBlk bitmap should show now."
            'Make part of the bitmap's colors to be transparent
        myBM.TransparentColorRange = Array(&H404000, &HC0C0FF) 'Red 0-FF, Green 40-FF, Blue 40-FF hex
        MsgBox "A block in the middle of the ColorBlk should be transparent"
            'Make the whole bitmap translucent
        myBM.Opacity = 50 'percent opaque
        MsgBox "The ColorBlk circle, with its hole, should be translucent."
            'Now place a second, reduced copy, ignoring the Aoi
        Set myBM = .Add("McGraphObjBitmap")
        myBM.SetPosition 270, 10
        myBM.ShowRectangle = True 'show a rectangular border
        myBM.SetBitmap mySrcImage, McActiveFrame, mcgboIgnoreAoi, , Array(100, 100)
        myBM.NotifyCreationComplete
            'Place a third, full size copy of only a portion of the source image
        Set myBM = .Add("McGraphObjBitmap")
        myBM.SetPosition 270, 130
        myBM.ShowRectangle = True 'show border
        myBM.SetBitmap mySrcImage, McActiveFrame, , Array(10, 10, 109, 109)
        myBM.NotifyCreationComplete
            'Finally, place a fourth, reduced copy of just the AOI
        Set myBM = .Add("McGraphObjBitmap")
        myBM.SetPosition 270, 280
        myBM.SetBitmap mySrcImage, McActiveFrame, , , Array(100, 100)
        myBM.NotifyCreationComplete

        MsgBox "Three reduced or selected pieces of the ColorBlk have been added." + vbCrLf + _
            "Images will close when you press OK."
    End With
    mySrcImage.Close 'close the ColorBlk source McImage
    ActiveImage.Modified = False
    ActiveImage.Close 'close test image
End Sub 'ShowColorMcImageAsBitmap

'Show a monochrome McImage as a McGraphObjBitmap on the AnnotationOverlay.
'Some examples of masking of transparency are shown, and then it
'manipulates the pseudo-coloring and opacity of the bitmap by setting
'the palette.
'
Public Sub ShowMonoMcImageAsBitmapWithPalette()
    Windows.CloseAll 'start with a clean plate
    Output.Show ("Output")
    Output.Clear
    Dim mySrcImage As McImage
        'GrayBlk.tif goes from 0 (black) on the top line to 255 on the bottom line
    Set mySrcImage = Images.Open(Path + "Images\GrayBlk.tif")
        ' pseudo-color, GrayBlk.tif
    Dim pscnew As New McPseudoColor
    With pscnew
        .Size = 256
        pscnew.Visible = True
            'Get a Yellow color spectrum as a LUT Variant.  We will use it later
        .ColorSpectrum = mccsYellow
        Dim YellowPseudocolorLUT As Variant
        YellowPseudocolorLUT = .GetLUTForImageType(mySrcImage.Type)
            'now set the spectrum to HSI Blue to Red and attach it to GrayBlk.tif
        pscnew.ColorSpectrum = mccsBlueRed
    End With 'pscNew McPseudoColor
    mySrcImage.AttachPseudoColor pscnew
    ActiveWindow.Position = Array(20, 20)
    MsgBox "GrayBlk.tif should show as a pseudocolored McImage."

        'Open a color image to underly our bitmap
    Images.Open (Path + "Images\NUCSTAIN.TIF")
    ActiveWindow.Position = Array(10, 10)
        'Show the pseudocolored GrayBlk.tif on top of NUCSTAIN.TIF as a McGraphObjBitmap
    With ActiveImage.AnnotationOverlay
            'Show a 1/2 size version of GrayBlk.tif without the pseudocoloring
        Dim myBM1 As McGraphObjBitmap
        Set myBM1 = .Add("McGraphObjBitmap")
        With myBM1
            .SetPosition 350, 30 'show in upper-right of NUCSTAIN
            .ShowRectangle = True
            .BorderColor = vbCyan 'cyan border
            .SetBitmap mySrcImage, -1, mcgboNone, , Array(128, 128)
                'without the mcgboApplyColorCorrection OptionFlags, we don't keep the pseudocoloring
            .NotifyCreationComplete
            'Note that by supplying a destination size to SetBitmap that required rescaling,
            'the bitmap is made a true color image (not indexed).
            If .PaletteCount = 0 Then
                'This is the case here
                Output.PrintMessage "Bitmap 1 is a true-color image; the Palette will be Empty."
            Else
                Output.PrintMessage "The bitmap is a indexed-color image; the Palette can be assigned to."
            End If
        End With 'bitmap 1

            'Show a full version of GrayBlk.tif with the pseudocoloring
        Dim myBM2 As McGraphObjBitmap
        Set myBM2 = .Add("McGraphObjBitmap")
        With myBM2
            .SetPosition 20, 20 'show in upper-left of NUCSTAIN
            .ShowRectangle = True
            .BorderColor = vbMagenta 'magenta border
            .SetBitmap mySrcImage, -1, mcgboApplyColorCorrection
                'mcgboApplyColorCorrection above, means that we keep the pseudocoloring
            .NotifyCreationComplete
            'Note that by not supplying a destination size to SetBitmap,
            'the bitmap is kept as an indexed-color bitmap, allowing the Palette property to be used.
            If .PaletteCount = 0 Then
                'This is the case here
                Output.PrintMessage "The bitmap is a true-color image; the Palette will be Empty."
            Else
                'This is the case here
                Output.PrintMessage "Bitmap 2 is a indexed-color image; the Palette can be assigned to."
            End If
        End With 'bitmap 2
        mySrcImage.Close 'we no longer need the bitmap source GrayBlk.tif McImage
        MsgBox "Two GrayBlk bitmaps should show: one big and pseudocolored, the other small and not."

            'Now create a circular mask for the small gray bitmap1
        Dim mcregionsT As McRegions, mcimgMaskT As McImage
        Set mcregionsT = CreateOperator("McRegions") 'a global McRegions (i.e., no parent McImage)
            'just one cicle covering the whole small bitmap with a McImage mask
        mcregionsT.SetEllipse -1, 63.5, 63.5, 127, 127
        Set mcimgMaskT = mcregionsT.CreateFeatureMask(mcfmfReturnMaskImage Or mcfmfUseFeatureBoundsAsDefault)
        myBM1.MaskBitmap mcimgMaskT 'apply the circular mask
        myBM1.ShowRectangle = False 'turn off the border
        Set mcimgMaskT = Nothing
        MsgBox "The small, gray bitmap should now be a circle."

            'clear the circular mask & set it all to transparent
        myBM1.MaskBitmap Empty, -1, mcgmboMissingIsMultiplierByte
        myBM1.ShowRectangle = True 'turn on the border
        MsgBox "The small, gray bitmap should now be a transparent square."

            'Now create a McBitMask mask with two ellipses
        mcregionsT.SetEllipse -1, 30, 30, 52, 52
        mcregionsT.SetEllipse 1, 97, 30, 52, 52

        Dim mcbitmaskT As McBitMask
        Set mcbitmaskT = mcregionsT.CreateFeatureMask(mcfmfReturnMcBitMask Or mcfmfUseFeatureBoundsAsDefault)
        myBM1.MaskBitmap mcbitmaskT, , , , Array(4, 70) 'apply the circular mask in the bottom, lighter part
        MsgBox "The small, gray bitmap should now have two light circles in the lower half of the square."
            'Set up option flags to scale Opacity to 60 percent
        Dim myOptionFlags As mcGraphObjBitmapOptions
        myOptionFlags = (60& * mcgmboMaskMultiplierByteShift) + (100& * mcgmboMaskDivisorByteShift)
        myBM1.MaskBitmap mcbitmaskT, -1, myOptionFlags, , Array(4, 4)  'apply the 2 circles mask
        MsgBox "The small bitmap should now be have 4 circles, the two upper ones being translucent."
            'Cleanup masking stuff
        Set mcbitmaskT = Nothing
        Set mcregionsT = Nothing
            'Get rid of the small, gray bitmap1; we don't need it for the rest of the example
        myBM1.Remove

            'Make part of the big bitmap's colors to be transparent using the Palette
        With myBM2
                'Make top 1/3 of bitmap 2 transparent
            Dim mcobjPalette As McObject
            Set mcobjPalette = McObjectTemp(.Palette(True)) 'get current palette as a McObject
                'Note that we set the Palette ExposeAsRGBQUAD argument True to get Alpha values
            mcobjPalette.SelectedMcObject(McOpFillIn(0&, .PaletteCount / 3)).OpSelfAndBits &HFFFFFF
            .Palette(True) = mcobjPalette 'Set the new Alpha values, keeping the old pseudocoloring
            MsgBox "The top third of the pseudocolored bitmap should be transparent."
                'Make opacity follow gray value
            'mcobjPalette still holds the current Palette as RGBQUAD values
            mcobjPalette.OpSelfAndBits &HFFFFFF 'clear all Alpha bytes to zero
                'Or in a ramp from 0-255 into the Alpha (high order) byte of the Palette
            mcobjPalette.OpSelfOrBits McOpFillIn(0&, .PaletteCount).OpSelfLeftShift(24)
            .Palette(True) = mcobjPalette 'Set the new Alpha values, keeping the old pseudocoloring
            MsgBox "The pseudocolored bitmap should get progressively more transparent towards its top."
                'Now set a new peudocoloring, keeping the same transparency for each color index.
                'We use the Yellow pseudocoloring LUT we created earlier
            .Palette(False) = YellowPseudocolorLUT 'Set the color values, keeping the old Alpha values
            MsgBox "The the pseudocoloring should change, but it should still get progressively more transparent towards its top." + vbCrLf + _
                "Image will close when you press OK."
        End With 'bitmap 2

    End With ' AnnotationOverlay
    ActiveImage.Modified = False
    ActiveImage.Close 'close test image
End Sub 'ShowMonoMcImageAsBitmapWithPalette

'Show a JPG image in a file 1) as a scaled McGraphObjBitmap and 2) as a sub-selected,
'scaled and rotated McGraphObjBitmap.
'
Public Sub ShowImageFileAsScaledBitmap()
    Dim strFile As String
    strFile = Path & "Images\nikon-e950.jpg" 'An 800 by 600 image
    Images.Add "BlankImage", 500, 200 'smaller than image size
    ActiveWindow.Position = Array(10, 10)

    With ActiveImage.AnnotationOverlay
        Dim myBM As McGraphObjBitmap
            'Show an image from a JPG file at 1/4 size.
        Set myBM = ActiveImage.AnnotationOverlay.Add("McGraphObjBitmap")
        myBM.SetPosition 10, 25
        myBM.SetBitmap strFile, -1, mcgboApplyColorCorrection, , Array(200, 150) 'quarter size
        myBM.NotifyCreationComplete 'done with first image
            'Now show a sub-portion of the same image, scaled and rotated
        Set myBM = ActiveImage.AnnotationOverlay.Add("McGraphObjBitmap")
        myBM.SetPosition 260, 25
        myBM.AngleOfRotation = -25 'make cannon point flatter
        myBM.ShowRectangle = True 'show a border
        myBM.BorderColor = &HFF00FF 'in magenta
        myBM.SetBitmap strFile, -1, mcgboApplyColorCorrection, Array(300, 25, 750, 400), Array(200, 150)
        myBM.NotifyCreationComplete 'done with whole image
    End With
    ActiveImage.Modified = False
    MsgBox "Image will close when you press OK."
    ActiveImage.Close

End Sub 'ShowImageFileAsScaledBitmap

'Threshold bright regions in an AOI, then capture a McBitMask of the
'larger regions and show it as a McGraphObjBitmap underneath the
'displayed region boundaries.
'
Public Sub ShowBitMaskOfAoi()
    If uLoadExampleImage Then Exit Sub
    ActiveWindow.Position = Array(10, 10)
    ActiveImage.Aoi.SetBox -1, 20, 20, 302, 250
        'Threshold and get bit mask of big regions in the AOI
    Dim myBitMask As McBitMask
    Set myBitMask = fGetBitMaskFromBigRegions
    If myBitMask.BlobCount = 0 Then
        Output.PrintMessage "No regions were found."
        Exit Sub
    End If 'no regions found
    'ELSE we have at least one blob to show

    Dim rectBitMask As LONGRECT
    rectBitMask = myBitMask.BoundsRect
    With ActiveImage.RegionFeatures.AutoDisplayOverlay
        Dim myBM As McGraphObjBitmap
        Set myBM = .Add("McGraphObjBitmap")
        With myBM
            .SetPosition rectBitMask.Left, rectBitMask.Top
            .FillColor = vbCyan   'cyan.  Set FillColor before the SetBitmap call
            .SetBitmap myBitMask, -1, mcgboZeroIsTransparent Or mcgboApplyColorCorrection
            'Above, mcgboApplyColorCorrection makes forground bits have the FillColor
            .NotifyCreationComplete
        End With 'myBM
        .MoveToBack myBM 'Make bitmap display 1st, so region bounds will be on top of it
        MsgBox "Large regions should be filled with cyan.  Small regions are not filled."
        myBM.FillColor = vbBlue 'change fill color
        MsgBox "Large regions should be filled with blue" + vbCrLf + _
            "Image will close when you press OK."
    End With 'ActiveImage.RegionFeatures.AutoDisplayOverlay
    ActiveImage.Modified = False
    ActiveImage.Close
End Sub 'ShowBitMaskOfAoi


'Place a translucent, reduced image from the clipboard into the AnnotationOverlay
'
Public Sub PlaceClipboardBitmapIntoAnnotation()
    If uLoadExampleImage Then Exit Sub
    ActiveWindow.Position = Array(10, 10)
        'Check to see if an image or bitmap is already on the clipboard
    If Not ActiveImage.AnnotationOverlay.IsActionAvailable(mcgoaBitmapOnClipboard) Then
        Dim imgT As McImage
        Set imgT = Images.Open(Path + "Images\colorblk.tif", mcicfNotVisible + mcicfNoAddToCollection)
        imgT.Aoi.SetEllipse 0, 127.5, 127.5, 255, 255 'a circular AOI covering whole color block
        imgT.Display.EditCopy mcwcftMcImageAoi 'copy the image to the clipboard
        Set imgT = Nothing 'we are done with this temporary image
    End If 'there is no bitmap on the clipboard, so we put one there

    With ActiveImage.AnnotationOverlay
        Dim myBM As McGraphObjBitmap
        Set myBM = .Add("McGraphObjBitmap")
        With myBM
            .SetPosition 50, 40
                'Place clipboard circular AOI, stretched horizonatlly into an ellipse
            .SetBitmapFromClipboard mcgboApplyColorCorrection, , Array(150, 120)
            .Opacity = 60 'make it partially translucent
            .NotifyCreationComplete
        End With 'myBM
        MsgBox "A small, translucent image from the clipboard should appear in the image." + vbCrLf + _
            "Image will close when you press OK."
        .RemoveAll 'clear the AnnotationOverlay
        'clear the image from the clipboard by copying something else there
        .EditCopy 'this will clear the image from the clipboard
    End With 'ActiveImage.AnnotationOverlay
    ActiveImage.Modified = False
    ActiveImage.Close
End Sub 'PlaceClipboardBitmapIntoAnnotation