CreateFeatureMask Method

CreateFeatureMask Method (McPoints)

Description

Creates either an McImage or an McBitMask mask of foreground pixels for selected features.

Return Type

A Variant value.

Either an McImage or an McBitMask mask of foreground pixels for the selected features.

Syntax

object.CreateFeatureMask ([eControlFlags], [Selector], [vrectBounds], [varImage])

The CreateFeatureMask Method syntax has these parts:

Part	Description
object	An expression evaluating to an object of type McPoints.
eControlFlags	Optional. A mcFeatureMaskFlags enumeration, as described in settings. Flags that control what is returned.
Selector	Optional. A Variant value. An empty variant, a single negative value, a single index value, or an array of zero or more index values (negative index values are legal but will be ignored). If the Selector argument is a non-negative scalar value, then a bit mask of the indicated feature from the collection is created. If the Selector argument argument is missing or any negative scalar value, then a bit mask of all features is created. If Selector is an array, then zero or positive values are treated as indices into the features collection, negative values are legal but ignored. In this case, bit mask will consist of only the selected features. Index values greater or equal to the Count property are illegal.
vrectBounds	Optional. A Variant value. If given, A LONGRECT or a length-4 array (in the order left, top, right, bottom) giving the bounds for the created bit mask. Foreground bits that fall outside of these bounds are clipped.
varImage	Optional. A Variant value. an optional source for the image data. If supplied this must be an McImage instance or one of the legal arguments for the McImages.Item property. If this argument is not supplied (i.e., is VT_EMPTY or VT_ERROR), then this McFeatures must have an ancestor McImage, which is used as the source for the image bounds.

Settings

The settings for eControlFlags are:

Constant		Value	Description
	mcfmfNoFlags	0	no flag bits
	mcfmfReturnMaskImage	0	A McImage instance is returned. This McImage is a mcImageQuickTypes of mciqtGray (that is 8-bit monochrome), where each pixel is 0xff for a foreground bit and 0x00 for a background bit of the mask.
	mcfmfReturn8BitLabeledImage	1	A McImage instance is returned. This McImage is an mcImageQuickTypes of mciqtGray (that is 8-bit monochrome), where each pixel is a value from 0x1 through 0xFF labeling connected sets of foreground bits of the mask. The pixel value is an index for the first 255 connected sets (the value cycles from 1-255 thereafter see mcfmfReturn16BitLabeledImage and mcfmfReturnMcBitMask for how to deal with counts larger than 255)
	mcfmfReturn16BitLabeledImage	2	A McImage instance is returned. This McImage is an mcImageQuickTypes of mciqtGray16 (that is 16-bit monochrome), where each pixel is a value from 0x0001 through 0xFFFF labeling connected sets of foreground bits of the mask. The pixel value is an index for the first 65535 connected sets (see mcfmfReturn8BitLabeledImage for cases known to have fewer than 255 connected regions).
	mcfmfReturnMcBitMask	4	A McBitMask instance is created and returned. This instance holds a copy of a scan list for the foreground regions.
	mcfmfUseFeatureBoundsAsDefault	16	if the vrectBounds argument is missing, then the bounds of the returned image or scan list will be the bounds of the selected features (an error is generated if no features are selected). Without this argument or the mcfmfUseAoiBoundsAsDefault flag, the default mask bounds are those of the whole parent image (if any) or of the optional varImage argument (if any). Any supplied vrectBounds, overrides this flag.
	mcfmfUseAoiBoundsAsDefault	32	if the vrectBounds argument is missing and the mcfmfUseFeatureBoundsAsDefault flag is not set, then the bounds of the returned image or scan list will be the bounds of the parent McImage.Aoi (if any) or of the optional varImage argument's Aoi (if any). Any supplied vrectBounds, overrides this flag.
	mcfmfAddMaskImageToCollection	256	if McImage creation is done, the new image is added to the collection. If not set, the new image is not part of the Images collection; the image will not be visible unless the mcfmfMakeMaskImageVisible flag bit is set.
	mcfmfDisplayMaskImage	512	if McImage creation is done, the new image is displayed in a new window. If not set, the new image is not immediately displayed. It may be displayed later by adding it to the collection (mcfmfAddMaskImageToCollection) and then setting its Visible property True. Setting this bit effectively forces on mcfmfAddMaskImageToCollection.
	mcfmfForceConnect8	4096	If set, sub-regions are counted and labeled using an 8-connected (rather than a 4-connected) test. If not set, then the OptionFlags' mcofConnect8 bit is used to determine the test.
	mcfmfForceConnect4	8192	If set, sub-regions are counted and labeled using a 4-connected (rather than an 8-connected) test. If not set, then the OptionFlags' mcofConnect8 bit is used to determine the test.
	mcfmfForceXorOnMerge	65536	If set, foreground bits of overlapping features are combined using an Xor operation (rather than an Or operation). If not set, then the features' Status mcfsfXorOnMerge bit is used to determine the merge method.
	mcfmfForceOrOnMerge	131072	If set, foreground bits of overlapping features are combined using an Or operation (rather than an Xor operation). If not set, then the features' Status mcfsfXorOnMerge bit is used to determine the merge method.
	mcfmfDefaultFlags	0	default is an undisplayed image, not part of the collection or displayed, with bounds of those of any parent image or varImage argument. The the features' Status mcfsfXorOnMerge bit is used to determine the merge method (Xor or Or) for overlapping features.

Remarks

This method converts all or selected features into a bit mask. Foreground bits are set under and interior (for McRegions) to the selected features. For McRegions, if there are any holes in the union bit mask (i.e., the McRegions.Holes property has a non-zero Count), then those holes will also appear in the bit mask result.

By default, a simple binarized 8-bit monochrome mask McImage is created, where foreground bits have value 255 and background bits have value 0. Flags passed in the eControlFlags argument can be used to create either an 8-bit or 16-bit labeled McImage (that is one where foreground bits are marked with a value labeling connected sets of foreground bits, or blobs). Or the result may be an McBitMask object; if an McBitMask object is created, it will be a child of the McFeatures that created it.

If multiple features are selected for inclusion in the bit mask, then overlapping features must be combined in some way. The supported combine modes are to OR bits together or the XOR bits together. By default the combine operator is OR, but this may be changed by the mcofDefaultXorOnMerge OptionFlags or for a given feature by the mcfsfXorOnMerge FeatureStatusFlags. Both of these flags may be overridden by the eControlFlags mcfmfForceXorOnMerge or mcfmfForceOrOnMerge flags.

If a labeled McImage or McBitMask is created, then the labeling of connected foreground blobs may be done using an 8-connected or a 4-connected test. By default, the connection test is determined by the presence of the mcofConnect8 OptionFlags (8-connected if it is set, 4-connected otherwise). This may be overridden by the eControlFlags mcfmfForceConnect8 or mcfmfForceConnect4 flags. Note that if the mcofKeepRegionsAsUnion OptionsFlag is set for McRegions, then the mcofConnect8 OptionFlags controls how the individual sub-region features are identified for selection; the eControlFlags has no effect on this, only on the labeling of the resulting bit mask.

The bounds of the created result are the same as the vrectBounds argument, if it is given. If that argument is not given, then the McFeatures must be associated with a parent image or the optional varImage argument must be given, so that the bounds can be determined from the image bounds (unless the eControlFlags argument mcfmfUseFeatureBoundsAsDefault flag is set, in which case the bounds of the selected features are used as the result bounds).