Analyzing Images

Analysis Image Properties

The model above shows basic McImage properties needed for quantitative image analysis.  As illustrated below, several of these elements are available as application global properties or collections.

Access to the image to be analyzed can be through the Images collection or by the ActiveImage (that is, the image being displayed in the foreground McWindow; i.e., the ActiveWindow).

'Example: Make Images(0) the ActiveImage
Set ActiveImage = Images(0)

Calibrations

Many analysis operations can compute results in calibrated units.  A spatial calibration is an instance of a McSpatialCalib object, and describes the relationship between the horizontal and vertical size of a pixel and calibrated units.  Spatial calibrations are used automatically for appropriate histogram and measurement calculations if the McImage.SpatialCalibration property is assigned a McSpatialCalib instance.  If the McImage.SpatialCalibration is assigned Nothing, then all spatial calculations are made assuming that each pixel is one unit, named a "Pixel", in both width and height.

Likewise, an intensity calibration is an instance of a McIntensityCalib object, and describes the relationship between the raw luminance value of pixel and calibrated units.   Intensity calibrations are used automatically for appropriate histogram and measurement calculations if the McImage.IntensityCalibration property is assigned a McIntensityCalib instance.  If the McImage.IntensityCalibration is assigned Nothing, then all spatial calculations are made assuming that each pixel luminance value is one intensity unit.

Available spatial and intensity calibrations are stored in the SpatialCalibs and IntensityCalibs collections, respectively.

 'Example: Set the spatial calibration of the active ActiveImage
Set ActiveImage.SpatialCalibration = SpatialCalibs("Microscope 2")

Area of Interest (AOI)

The McImage.Aoi property is a McRegions object that is used to restrict many operations to only those pixels that are under or interior to the region feature(s) that make up this property.   An AOI can consist of one or more region-defining features, rectanglar, elliptical or polygonal.  If the Aoi object has a Count of zero then the entire image is assumed to be the AOI.

The AOI restricts virtually all image processing operations, but it also can restrict some operations relevant to image data analysis.  In particular, by default the McHistogram and McThreshold objects (both discussed below) restrict their results to pixels under any AOI on their working McImage.

A list of named McRegions areas-of-interest is maintained in the AoiList collection.  The McImage.Aoi property always exists (i.e., it is never Nothing), and it is a read-only property, so to change it you cannot just assign a new McRegions object from the AoiList.  Instead you need to use the CopyFrom method to import an AOI's features from the AoiList.

' Set the ActiveImage AOI from the AoiList to one named "BigRect"
ActiveImage.Aoi.CopyFrom AoiList("BigRect")

Histogram

Much of most basic image data analysis starts (and often ends) with a histogram of pixel luminances or color channel intensities.

A McHistogram object exposes methods and properties for extracting and analyzing luminance and/or color channel histograms.  Two instances of this class are predefined: the McImage.Histogram property and the McThreshold.Histogram property.  The McImage.Histogram property returns information about the intensity distribution of the image, while the McThreshold.Histogram property is used by the McThreshold object to automatically compute foreground thresholds based on an image histogram.

By default, the histogram computations are restricted by the McImage.Aoi  and for mult-frame images they include all frames in the McImage.ActiveFrameRange.  For color images, the default behavior is to compute a histogram for each color channel.  The McHistogram object is quite flexible however, and it can be set up to compute an intensity or HSI histogram for color images (by setting the Interpretation property), and it can be set up to ignore the Aoi and/or the ActiveFrameRange (by setting the mode property).

By default histograms are not calibrated by intensity or spatially, but one or both of these calibrations can be taken into account by setting the the mode property appropriately.

Features

Most image analysis is based on a "features of interest" model of the image.  A "feature of interest" or just "feature" is a point, line (or polyline) or a bounded region.  The feature may identify some pixel(s) of an image that are of interest (i.e., the feature may be thought of as overlying image pixels and marking those under it as of interest).  Or the aspects of feature(s) themselves may be of interest (e.g., a region's area or perimeter, the distance between two points, the length of a line, etcetera).  Even when analysis is based only on measure(s) intrinsitic to a feature (such as region area), the shape and placement of the feature usually relates to some aspect of image pixel luminance or color (e.g., a point might mark the tip of someone's nose in a picture), but this is not necessarily always the case, and indeed it is possible to analyze features that are completely independent of any image, so long as operations that require image pixel luminance values are avoided.

The features object model is built upon a McFeatures base class.  No McFeatures object is ever directly created, instead one of three derived object types can be created: McRegions, McLines and McPoints.  Each of these object types can hold zero, one or many individual region, line/polyline or point features, respectively.    Most feature related methods and properties are common to all three types of features and so are defined as part of the McFeatures base class.  Some McRegions-only methods are also defined (e.g., SetBox ).

' Treat the McImage.Aoi (a McRegions) as a McFeatures
Dim AoiMcFeatures As McFeatures
Set AoiMcFeatures = ActiveImage.Aoi
Debug.Print "The Aoi feature count is " & AoiMcFeatures.Count

McFeatures Spatial Calibration

As mentioned above, a McFeatures-derived object is allowed to exist independent of any McImage, so long as operations that require access to image pixels are avoided.  But size still makes perfect sense independent of an image, and certain methods and many measurements compute spatially calibrated results.  To make this possible for McFeatures without a parent McImage, the McFeatures.SpatialCalibration property can be set.  If this property is not set (or is set to Nothing) then any McImage.SpatialCalibration is used if there is an ancestor McImage.  In the example below, a global McRegions is created (global means one without any McImage parent) using the CreateOperator method, an elliptical feature is created, a spatial calibration is set and the area is measured.

' Calibrate a global McFeatures
Dim GlobalMcR As McRegions
Set GlobalMcR = CreateOperator("McRegions")
' set feature 0 as a 200 by 50 pixel ellipse centered at pixel 150,150
GlobalMcR.SetEllipse 0, 150,150,200,50,0
GlobalMcR.SpatialCalibration = SpatialCalibs("Some Calibration")
Debug.Print "The calibrated ellipse area is " & GlobalMcR.mRgnArea(0)

Displaying Features

McFeatures can be automatically displayed in a McGraphOverlay (see Displaying Images and Overlays).  Each instance of the McFeatures-derived objects McRegions, McLines and McPoints can automatically display their features on an overlay created in their own private DisplayOverlays collection.  Normally only one such overlay is used for feature display,   McFeatures.AutoDisplayOverlay, and you rarely need to access it, because feature display is done for you automatically.

When you create a McFeatures-based object, automatic feature display is turned off by default.  To turn it on you must set the McFeatures.AutoDisplay  True.   The predefined McFeatures, such as the McImage.Aoi and McImage.RegionFeatures (see next section) have automatic display turned on by default.

' Make a copy of the AOI and display its features as yellow filled regions
Dim AoiCopy As McRegions
Set AoiCopy = ActiveImage.Aoi.Duplicate
' turn on auto feature display
AoiCopy.AutoDisplay = True
' now change the colors to yellow and fill the regions
Dim displayedObjs As McDisplayedObjects
Set displayedObjs = AoiCopy.DisplayedObjects
displayedObjects.SetColors &H00FFFF&, mcdoscSetAllColors
displayedObjects.SetFillStyle mcgfsBorderFill

As illustrated in the example above, once features are being displayed, the displayed McGraphObj objects that are showing each individual feature can be manipulated as a group via the McFeatures.DisplayedObjects property.  The DisplayedObjects property is a McDisplayedObjects collection and has methods to set display colors, styles and labels in a group.

Predefined and Created McFeatures

Each McImage is initialized with four empty, predefined McFeatures-based objects.  The McImage  Aoi and RegionFeatures properties are McRegions, the LineFeatures property is a McLines and the PointFeatures property is a McPoints.  These predefined objects are all set up to automatically display any feature(s) created in them.  By default, the Aoi shows in green, while the others show in red.

The predefined McFeatures-based objects may be adequate for your analysis needs.  The Aoi should be reserved for area-of-interest representations, but the others have no predefined uses and may be used as the normal target for feature analyses.  For example, most of the sample code uses these pre-defined objects.  However, if you are creating a application that is to be used by others, it is normally better to create your own working McFeatures, so that user macros don't interfere with your application.

If other McFeatures-based objects need to be created for analysis, storage or backup, then there are several ways to accomplish the creation.  The easiest is to just use the McFeatures.Duplicate method to make a copy of some existing object.  An object created in this way will be unnamed and have the same parent McImage as the duplicated object.

' Make a copy of the LineFeatures
Dim LinesCopy As McLines
Set LinesCopy = ActiveImage.LineFeatures.Duplicate

The other approach to creating McFeatures-based objects is to use the CreateOperator method.  With this method, a McFeatures-based object may be created with a particular  McImage parent or, rarely, as a global object without any parent (illustrated in an earlier example).  The created object may be given a name, and if it is named, then it will become a property of the parent McImage (but not all McImages).  Features in objects created in this way are initially not visible, but can be made so (see the earlier "Displaying Features" section).

' Create a McRegions as a named property of one McImage
Dim AoiStorage As McRegions
Set AoiStorage = CreateOperator("McRegions", ActiveImage, "MyAoiStorage")
' named operators stay alive, so we can set AoiStorage to Nothing
Set AoiStorage = Nothing
' now use the created McRegions
ActiveImage.MyAoiStorage.CopyFrom ActiveImage.Aoi

Regions







  

Much feature analysis is done on objects of type McRegions.  These objects expose properties that allow creation of region features and also measurements upon those features.

Creating Region Features

Region features can be created programatically either individually or by copying or merging features from another McRegions object.  Regions can also be created by the user.  And finally, they can be automatically detected based on pixel luminance values by the McTheshold object exposed by the McRegions.Threshold property.

A number of McFeatures and McRegions methods create or change individual region features.  For example, the SetBox method creates a rectangular feature, while the SetEllipse method creates an elliptical or circular feature.  The Merge method appends features from another McRegions object.

' set feature 0 as a 50 pixel diameter circle centered at pixel 150,150
ActiveImage.RegionFeatures.SetEllipse 0, 150,150,50,50,0
' set feature 1 as a 11 by 11 rectangle

		
ActiveImage.RegionFeatures.SetBox 1, 15,15,25,25

		
' append all of the Aoi features

		
ActiveImage.RegionFeatures.Merge ActiveImage.Aoi

		
Debug.Print "Total feature count is now = " & Str(ActiveImage.RegionFeatures.Count)

		
Turn on recording or look at the Audit window, and then create Aoi features with 
			the AOI toolbar to see examples of programatic creation of 
				McRegions features.

		
Region features are created by the user by starting the appropriate tool on 
			the McRegions object's display overlay 
			(see Displaying Images and Overlays).

		
' Start tool to allow the user to create polygon features in the RegionFeatures object

		
ActiveImage.RegionFeatures.AutoDisplayOverlay.SelectTool "", "McGraphObjPoly"

		
Probably the most common way that McRegions features 
			are created for analysis is by the McTheshold
			object exposed by the McRegions.Threshold
			property.  This object compares each pixel against luminance or color 
			threshold values and assigns pixels within those values as foreground and other 
			pixels as background.  Foreground pixels that form connected regions are 
			then made into individual features.  The McTheshold
			object is capable of automatically determining a reasonable pair of intensity 
			threshold values based on the histogram of the image AOI (for this computation, 
				McTheshold uses its private Histogram property, 
			not the McImage.Histogram property).

		
' Automatically create regions around brighter pixels within the AOI

		
ActiveImage.RegionFeatures.Threshold.AutoFindPhase = mcfpBrightest

		
ActiveImage.RegionFeatures.Threshold.Execute

		
Debug.Print "Count of bright regions found was " & Str(ActiveImage.RegionFeatures.Count)

		
Region Measurements

		
McRegions objects expose a large number of 
			measurements.  In most cases there is one measurement result per region 
			feature, exposed as a one-dimensional or two-dimensonal array.  Some of 
			these measurements depend on image pixels under the feature (e.g., 
				mDensity or mClumpiness), 
			others depend only on the feature boundary and/or position (e.g., 
				mRgnArea or mPerimeter).  
			Those results that are a fixed length array of values for each region feature 
			(e.g., maRgnDiameters) result 
			in a 2-dimensional array for all features.  Results that are a 
			varible length array of values for each feature ((e.g., 
				mvRgnBranchLengths) result in a 1-dimensional array of Variants, where 
			each Variant is the varying-length array result for one feature.  Some 
			measurements relate to "holes" (e.g., mHoleArea); 
			these measurements will only give meaningful results if the region features 
			have been created by the the McRegions.Threshold
			property.

		
All McRegions measurement properties are 
			instances of the McMeasure class or a 
			class derived from it (e.g., McFractalDimension), 
			and they all have names starting with lower-case "m".  Since McMeasure.Value is 
			the default property explicit reference to the Value
			array can usually be skipped (e.g., "mRgnArea" and "mRgnArea.Value" are usually 
			interchangable in macros, as in the next example).

		
' Show the total area of all AOI features

		
Debug.Print "Total AOI area = " & Str(McSum(ActiveImage.Aoi.mRgnArea))

		
The example above uses the McSum array 
			operator to sum the elements of the computed mRgnArea.Value array. 
			McSum is one of many useful 
			array operators provided by the McOMGlobal
			global object.  These array operators are both simpler to use and 
			much faster than the equivalent VBA macro loop code.  The array 
			operators can take variants or McObject instances 
			holding numeric values as input.  The McObject
			instances are the more efficient data packages.  And 
				McMeasure  objects can also expose their results as a 
				McObject  as the McMeasure.ValueMcObject property.  
			Thus the following version of the above example would run a bit faster because 
			a data conversion would be avoided.  For complex and repetitive 
			computations on measurements, the time savings can be considerable.

		
' Show the total area of all AOI features using the ValueMcObject

		
Debug.Print "Total AOI area = " & Str(McSum(ActiveImage.Aoi.mRgnArea.ValueMcObject))

		
Some measurements do not return numeric results, but instead return a 
				McFeatures result.  For example, the 
				mpRgnCentroidAsPoint measurement exposes the region features' 
			centroids as a McPoints object. 

		
Note that the second letter after the "m" gives a clue as to what type of 
			measurement result will be returned: nothing for a scalar, one-value-per 
			feature measurement, "a" for a fixed length array, "v" for variable-length 
			arrays, "p" for a McPoints, "l" for a 
				McLines and "r" for a McRegions.  
			Region measurement names all have "Rgn" following these leading 
			characters.

		
Points and Lines

		
Feature analysis may also be done on objects of type McPoints
			and McLines.  Like 
				McRegions, these objects are derived from the 
				McFeatures base class and expose properties that allow creation of 
			point and line features and also measurements about those features. Again you 
			may use the pre-defined the LineFeatures property 
			(a McLines) and the 
				PointFeatures property (a McPoints). 
			or you may use the McFeatures.Duplicate method 
			to make a copy of some existing object. And the 
				CreateOperator method can also be used as illustrated earlier. 
			Finally, some measurements will return a McPoints
			or McLines as the result of the measurement 
			(e.g., the   
				McRegions measurement mpRgnCentoidAsPoint
			yields a McPoints object as its value).

		
Regions are usually created by the McRegions.Threshold
			property as illustrated earlier, and similarly there are 
				McLines.Threshold and 
			McPoints.Threshold
			properties which can be used to detect points or lines based on connected sets 
			of foreground pixels (AKA blobs). Since there are many ways to convert a blob 
			into a point or a line, the McFeatures.SetFromMaskMethod
			allows you to specify how this is to be done. For example, the following will 
			create line features that traverse blobs of foreground pixels aligned along 
			their principal axis (the major axis of an equivalent ellipse):

		
' Automatically create lines from blobs of brighter pixels within the AOI

		
ActiveImage.SetFromMaskMethod = mcsfmmLinesMajorAxisAlignedAvg

		
ActiveImage.LineFeatures.Threshold.AutoFindPhase = mcfpBrightest

		
ActiveImage.LineFeatures.Threshold.Execute

		
Debug.Print "Count of lines found was " & Str(ActiveImage.LineFeatures.Count)

		
Frequently point and line features need to be created directly from a macro. 
			To do this, you specify the coordinates with the 
				McFeatures.SetFeaturePoints
			method.  For a 
				McPoints, you can optionally create a whole set of points with one 
			call, but for McLines (or 
				McRegions polygon boundaries) you must supply an array of coordinates 
			for each feature you want to add.

		
Naturally, McPoints and McLines also 
			have measurement properties.  The point-measurements have names like 
				mPtDensity or maPtLocationXY, 
			while the line measurements have names like mLnLength,
			maLnPositionXY or 
				mlLnChordAsLine.  The same naming convention is used as for region 
			measurements, namely a lower-case "m" followed by a possible second lower-case 
			letter denoting how the results are presented, followed by "Pt" for point 
			measurements or "Ln" for line measurements.

		
Reference Features

		

			

				

					

						

						

						

						
							
				

			

		

		
Most measurements relate only to the features of one McFeatures object 
			and possibly to the luminance values of pixels in its ancestor 
				McImage.  However, some analyses cannot be done with just one 
			feature in isolation, but instead require examining the relationship between a 
			feature and some reference feature.  In IQL, measurements of this type are 
			properties of a McRefFeatures operator, 
			which was created for just this purpose.  The key property of this 
			class is the ReferenceFeature property, 
			which as the name implies indicates the reference McFeatures object 
			against which measurements will be made.

		
A McRefFeatures operator is always an 
			immediate child of some McFeatures object.  Measurement 
			values are computed for each of the parent features against the reference 
			feature.  For example, the mRefDistance computes 
			the distance between the "position" of each of its parent features to the 
			"position" of its associated feature in the 
				ReferenceFeature, if there is only one reference feature, then it is 
			used as the reference for all of the parent features.

		
Each of the three derived classes has one predefined 
				McRefFeatures property named "Reference" (McPoints.Reference,
			McLines.Reference
			and McRegions.Reference).  
			This is sufficient for reference measurements between the parent features and 
			one reference feature, but if other reference features are required then 
				CreateOperator or McRefFeatures.Duplicate
			can be used to make them (see example).

		
'Show the distance from McRegions features to a reference point and a reference line position

		
With ActiveImage

		
'Create a single reference point feature

		
.PointFeatures.SetFeaturePoints -1, Array(300, 400)

		
'Create a single reference line feature 

		
.LineFeatures.Reset .LineFeatures.SetFeaturePoints 0, Array(10, 150, 200, 10)

		
 

		
'Use the predefined Reference property

		
Set .RegionFeatures.Reference.ReferenceFeature = ActiveImage.PointFeatures

		
 

		
'Use Duplicate to create an independent McRefFeatures

		
Dim myRegionToLineRef As McRefFeatures

		
Set myRegionToLineRef = .RegionFeatures.Reference.Duplicate

		
Set myRegionToLineRef.ReferenceFeature = .LineFeatures

		
  

		
Output.PrintMessage "There are" + Str(.RegionFeatures.Count) + " region features." + vbCrLf + _

		
"Distance from Centroids to ref point = " & _ McToText(.RegionFeatures.Reference.mRefDistance) & vbCrLf & _

		
"Distance from Centroids to ref line = " & _ McToText(myRegionToLineRef.mRefDistance)

		
End With

		
Selectors

		
Many methods of the McFeatures, 
				McMeasure, McObject and 
				McOMGlobal objects recognize "selector" arguments.  As the 
			name implies, a selector is used to select a subset-of-interest from some 
			larger array.  A selector is an integral array that has positive index 
			values representing selected, or true, array elements and negative, -(index+1), 
			values representing unselected, or false, array elements.   As 
			illustrated in the example below, a number of McOMGlobal methods 
			either create selectors (e.g. McOpLT) 
			or manipulate them logically (e.g., McOpNOT).  
			McFeatures methods then can take these selector arguments to pull out only 
			features of interest for some operations (e.g., see the accesses to the 
				McFeatures.DisplayedObjects
			property in the example below). 

		
The following example illustrates many of the image analysis issues we have 
			discussed.  It creates McRegions features 
			in the predefined McImage.RegionFeatures property 
			using the McRegions.Threshold
			property.  It then measures the areas of those regions, and uses 
				McOMGlobal  array operators to compute selectors that 
			differentiate small and large region features.  Finally, the selectors are 
			passed to the DisplayedObjects property 
			to get "small" and "large" subsets of the feature display objects, and these 
			are then manipulated separately to give small and large regions different a 
			display appearance, including a different text label on each region feature.

		
' Create some new region features

		
ActiveImage.RegionFeatures.Threshold.IntensityMin = 128

		
ActiveImage.RegionFeatures.Threshold.IntensityMax = 255

		
ActiveImage.RegionFeatures.Threshold.Execute

		
 

		
' Measure the areas of the thresholded regions

		
Dim varAreas, varMeanArea

		
varAreas = ActiveImage.RegionFeatures.mRgnArea

		
varMeanArea = ActiveImage.RegionFeatures.mRgnArea.Mean

		
 

		
Debug.Print "There are " + Str(ActiveImage.RegionFeatures.mRgnArea.Count) + _

		
" selected regsions. The mean Area is: " + McToText(varMeanArea, "%.2f")

		
 

		
'Get selectors for small areas and for not small (large) areas

		
Dim selSmallAreas, selLargeAreas

		
selSmallAreas = McOpLT(varAreas, varMeanArea)

		
selLargeAreas = McOpNOT(selSmallAreas)

		
 

		
'Select the small area region's displayed objects

		
Dim mdobjsSmall As McDisplayedObjects

		
Set mdobjsSmall = ActiveImage.RegionFeatures.DisplayedObjects(selSmallAreas)

		
' fill the small objects interiors

		
mdobjsSmall.SetFillStyle = mcgfsBorderFill

		
' Now label the small regions in yellow, using the default font

		
mdobjsSmall.SetLabelText "%d:Sm", mcsltDisplayFeatureIndex + mcsltLabelCenter, &HFFFF&

		
 

		
' Add a text label to large area regions

		
Dim mdobjsLarge As IDisplayedObjects

		
Set mdobjsLarge = ActiveImage.RegionFeatures.DisplayedObjects(selLargeAreas)

		
 

		
' Now label the large regions with the border color, using a different font

		
Dim imcgraphobjTemplate As McGraphObj

		
Set imcgraphobjTemplate = s_mcgraphoverlayToUse.Template("McGraphObj", mcgtStandardAutoDisplay)

		
Dim ifontdispLabel As IFontDisp

		
Set ifontdispLabel = imcgraphobjTemplate.LabelObject.Font

		
ifontdispLabel.Name = "Courier New"

		
ifontdispLabel.Size = 20

		
ifontdispLabel.Bold = True

		
 

		
mdobjsLarge.SetLabelText "%d:Lg", _

		
mcsltDisplayFeatureIndex + mcsltCopyBorderColor + mcsltLabelTopleft, , ifontdispLabel