Click or drag to resize

IMcImageCreateRegionAccessEx Method

Create a McRegionAccess interface for pixel access, where access may be read-only, write-only or read-write.

Namespace:  MediaCy.IQL.Engine
Assembly:  MediaCy.IQL.Engine (in MediaCy.IQL.Engine.dll) Version: 10.0.6912.0
Syntax
VB
Copy
Function CreateRegionAccessEx ( 
	<OptionalAttribute> Type As Object,
	Optional Channel As Integer = -1,
	Optional Frame As Integer = -2,
	<OptionalAttribute> RegionRect As Object,
	Optional AccessMode As mcRegionAccessMode = mcRegionAccessMode.mcramReadWrite
) As McRegionAccess

Parameters

Type (Optional)
Type: SystemObject
If given, Type of pixel values different from the image Type. For instance, to set/get 16 bit pixel values to/from an 8 bit image, pass the constant mciqtGray16 or an equivalent IMcImageType interface. By default if Type is missing or Empty, the pixel values will be exposed in the native format of the image. If the Type is monochrome and the image is RGB or BGR, then the cast to monochrome will be a simple average of the source color channels. Use CreateRegionAccessEx to get a weighted monochrome cast (which can be enabled with the mcramUseWeightedMonoCast AccessMode bit).
Channel (Optional)
Type: SystemInt32
If given, for multi-channel images, where each pixel has one value per channel, specifies which channel value (starting with channel 0, e.g. Red for mciqtRGB) is to be set/read. By default, if channel = -1, all channel values are considered. When given as a non-negative channel index, the McRegionAccess Get* and Put* methods effectively access the given Channel as a monochrome array of pixels.
Frame (Optional)
Type: SystemInt32
If given, the 0-based frame index of the frame to be accessed. Other allowed values are McActiveFrame and McLastFrame. McActiveFrame is the default.
RegionRect (Optional)
Type: SystemObject
If given, a LONGRECT or an array of four values in the order left, top, right, bottom giving the rectangle to be accessed. If not given, then the whole image is accessed (i.e., left and top are zero while right is Width-1 and bottom is Height-1).
AccessMode (Optional)
Type: MediaCy.IQL.EnginemcRegionAccessMode
If given, specifies whether pixel access will be read-only, write-only or read-write (mcramReadWrite is the default). For mcramReadOnly AccessMode, any attempt to write to pixels will result in an error. Similarly, for mcramWriteOnly AccessMode, any attempt to read pixels is an error. The main advantage of specifying the AccessMode is for mcramWriteOnly access to a non-native (i.e., cast) Type. In this case, the initial forward cast of pixels from the native image Type to the requested McRegionAccess.Type can be skipped, thereby potentially saving substantial time. If mcRegionAccessMode.mcramUnsignedGetFlag set in the AccessMode parameter, then McRegionAccess.GetPixel, GetLine and GetArea will return only unsigned integral types.

Return Value

Type: McRegionAccess
A new McRegionAccess instance allowing AccessMode pixel access to pixels of the given Type in the given Frame for the given Channel within the given limits.
Remarks
This method creates a McRegionAccess instance with specified access to pixels. The older CreateRegionAccess method only supports read-write access, CreateRegionAccessEx also allows specification of the region-of-interest as an array or LONGRECT rather than as four separate values as does the older CreateRegionAccess method. A McRegionAccess instance gives full control over access to pixel values. For simple pixel access, use GetPixel / PutPixel, GetLine / PutLine, GetArea / PutArea. The source Type.MinCastingLuminance and Type.MaxCastingLuminance can be set by assigning to the CastingSourceRange property. CastingSourceRange is always reset to its default value (RangeMin to RangeMax) after any call to CreateRegionAccessEx.
Examples
VB
Copy
Imports MediaCy.IQL.Operators

Public Module McRegionAccess_Examples

Public Sub McRegionAccessCopy()
        If ThisApplication.ActiveImage Is Nothing Then
            'load demo image
            Dim imgDemo As McImage
            imgDemo = ThisApplication.Images.Open( ThisApplication.Path(mcPathType.mcptSampleImages) + "Count And Size\Spots.tif")
            imgDemo.Aoi.SetEllipse( -1, 120,120,100,80) 'set an Aoi
        End If
        'Copy the pixels within the ActiveImage.Aoi to a new image, having
        'the same size as the bounds as the ActiveImage.Aoi
        Dim srcImage As McImage = ThisApplication.ActiveImage

            'get src McRegionAccess for bounds of Aoi
        Dim srcRA As McRegionAccess
        srcRA = srcImage.Aoi.AccessMaskedImageData

            'create destination image of correct size
        Dim lW, lH As Integer
        lW = srcRA.Width
        lH = srcRA.Height
        Dim newImg As McImage
        newImg = ThisApplication.Images.Add("MyAoiCopy", lW, lH, 1, srcImage.Type, mcImageCreateFlags.mcicfNoInit)

            'get destination McRegionAccess
        Dim destRA As McRegionAccess
        destRA = newImg.CreateRegionAccess

            'use src Aoi as destination RegionMask
        destRA.RegionMask = srcImage.Aoi

            'Adjust RegionMask registration offset
        Dim lLeft As Integer, lTop As Integer, lRight As Integer, lBottom As Integer
        srcImage.Aoi.GetBounds lLeft, lTop, lRight, lBottom
        destRA.SetRegionMaskOffset lLeft, lTop
            'Above, RegionMaskOffset is set so that the Left,Top of the
            'srcImage.Aoi maps onto 0,0 of the destination image

            'In this example, src should use FastAccess if possible
        srcRA.FastAccess = True ' this will not interfere with the destRA.PutArea
            'region masking, because the src image is different than the dest

            'Copy block of pixels from src to dest
        Dim varArea As Object
        srcRA.GetArea varArea 'get block of src pixels
        destRA.PutArea varArea 'put the block, doing region masking
End Sub 'McRegionAccessCopy

''example demonstrates using of McRegionAccess.GetArea/PutArea method
''on multi-frame images
''the main code is located in frmMosaic.frm
''the demo creates a mosaic image of a sequence and allows navigating through
''sequence by clicking on frame of interest
'Sub MosaicDemo()
'    'load demo image
'    Images.Open (Path & "Images\Heart.seq")
'    'open Mosaic form as modeless dialog
'    frmMosaic.Show False
'End Sub
'

End Module 'McRegionAccess_Examples
See Also