Matrox ActiveMIL 8.0 - Shipping Notes

May 24, 2005
Copyright © 2005 by Matrox Electronic Systems Ltd. All rights reserved.

The Matrox Imaging ActiveX Controls (ActiveMIL) are a collection of ActiveX controls encapsulating an extensive set of optimized image processing operations (point-to-point, statistics, filtering, morphology and geometric transforms), blob analysis, code reading and writing, edge analysis, pattern matching, measurement, calibration, and character recognition.

Contents

  1. Getting started
  2. Supported environments
  3. What's new in ActiveMIL 8.0?
    • General Section
    • Control Specific Section
  4. Upgrading an existing project to ActiveMIL 8.0
  5. Changes from ActiveMIL 7.5 to ActiveMIL 8.0
  6. Changes from ActiveMIL 7.1 to ActiveMIL 7.5
  7. On-line documentation
  8. Deploying ActiveMIL applications (Redistribution)
  9. Obtaining additional help
  10. Environment specific notes
    • Visual C++ .NET
    • Visual Basic .NET
  11. Outstanding issues
    • ActiveMIL Controls issues
    • Documentation errata
    • Other issues

Getting started

  • Use the Matrox Intellicam interactive program to perform a grab and experiment with settings of your frame grabber before running the ActiveMIL examples.
  • Run the ActiveMIL demos found under Start\All Programs\Matrox Imaging\ActiveMIL\Demos. These demos run independently and show the basics of building an ActiveMIL application in Visual Basic .NET.
  • Run the ActiveMIL examples using the interactive example launcher found under Start\All Programs\Matrox Imaging\Example Launcher. By default, this utility will run all the examples in a predefined order. The "Edit" button can be used to open any example in the target environment's IDE, allowing you to view and edit the code and the controls in design-time. The "Change Defaults" button in example launcher allows you to interactively change the system type, image sizes, digitizer (camera) and display formats used in the examples.

[Contents]

Supported environments

The following tables outline the combinations of operating systems, development environments, and Matrox Imaging hardware supported by ActiveMIL.

Operating System / Development Environments

 | Windows XP | Windows 2000
Microsoft Visual Studio .NET | Yes | Yes

*Other development environments, and other operating systems are not officially supported by Matrox.

Operating System / Matrox Imaging Hardware

 | Windows XP | Windows 2000
Matrox Meteor-II/Standard | Yes | Yes
Matrox Meteor-II/Multi-Channel | Yes | Yes
Matrox Meteor-II/1394 | Yes | Yes
Matrox Meteor-II/Digital | Yes | Yes
Matrox Meteor-II/Camera Link | Yes | Yes
Matrox Genesis | Yes | Yes
Matrox Genesis-LC | Yes | Yes
Matrox Orion | Yes | Yes
Matrox Corona-II | Yes | Yes
Matrox CronosPlus | Yes | Yes
Matrox Helios New | Yes | Yes
Matrox Morphis New | Yes | Yes
Matrox Solios New | Yes | Yes
Matrox Odyssey* New | Yes | Yes
Matrox Iris New | No | No

* Multiple processing is not supported on Matrox Odyssey with this release.
Note that Matrox Cronos, Matrox Pulsar-LC, Matrox Pulsar, Matrox Meteor, Matrox Corona-LC and Matrox Corona are no longer supported.

[Contents]

What's new in ActiveMIL 8.0?

General Section

  • Default settings

    Some ActiveMIL-Lite controls have allocation properties that can now be set to amilDefault (ActiveMILDefaultConstants). By doing so, the property will be set to the value specified in MILConfig.

  • Saving Stream

    The new LoadStream method, SaveStream method, and StreamSize property, added to the controls listed below, support the writing of the stream to a single file.

    • Calibration
    • Code
    • EdgeFinder
    • Measurement
    • ModelFinder
  • Get Multiple Results

    Multiple results can be inquired with a single call to the Results.GetMultiple method.
    Look for Results.GetMultiple in the following controls:

    • BlobAnalysis
    • CharacterRecognition
    • Code
    • EdgeFinder
    • ImageProcessing
    • Measurement
    • ModelFinder
    • PatternMatching
  • UserBits

    The API of UserBits has been completely redesigned:

    • System Control
      • Old
        • UserBits property
      • New
        • ControlUserBits method
        • ControlUserBitsWithMask method
        • InquireUserBits method
        • InquireUserBitsWithMask method
        • UserBitsCount property
    • Digitizer Control
      • Old
        • UserBit# properties
      • New
        • UserBits property
        • UserBitChangedEvent property
        • UserBitChanged event
  • Infinite Impulse Response

    Added support for recursive Infinite Impulse Response (IIR) filtering as a predefined kernel:

    • ImageProcessing Control
      • Kernels.Item.FilterMode property
      • Kernels.Item.FilterSmoothness property
      • Kernels.Item.FilterOperation property
      • Kernels.Item.FilterType property
      • Deriche method
      • Shen method
    • Measurement Control
      • Markers.Item.FilterSmoothness property
      • Markers.Item.FilterType property
  • Draw

    Added support for drawing multiple items at once:

    • Measurement Control
      • Results.Draw method
      • Markers.Draw method
    • ModelFinder Control
      • Models.Draw method
      • Results.Draw method
    • PatternMatching Control
      • Results.Draw method
  • LUT

    Added support for minimum and maximum LUT pixel values in the following controls:

    • Display Control
      • LUT.MaximumPixelValue property
      • LUT.MinimumPixelValue property
    • Image Control
      • LUT.MaximumPixelValue property
      • LUT.MinimumPixelValue property

  • Support for new Matrox frame grabbers.

    • Support for Matrox Helios has been added.
    • Support for Matrox Morphis has been added.
    • Support for Matrox Solios has been added.
  • Removed support for MFC wrapper classes

    Wrapper class support is being phased out. Native COM is the only way to use ActiveMIL with Visual C++. For information on how to convert your project to Native COM, refer to the 'Using ActiveMIL with Microsoft Visual C++ (Native COM)' chapter in the ActiveMIL User Guide.

  • Operating system information.

    • Windows 98, ME and NT 4.0 are no longer supported.
    • ActiveMIL 8.0 supports Windows 2000 and XP.

Control Specific Section

  • Application Control

The new properties available for the Application control are:

  • AvailabelSystems.Item.SystemDescriptor property
  • AvailabelSystems.Item.SystemName property
  • NonPagedMemory property
  • ResultsValidation property
  • Timer.SynchronizationMode property
  • Version property
  • BlobAnalysis Control

SaveRunInformationEnabled returns or sets whether to save run information.

  • Calibration Control

The Calibration control requires an OwnerSystem on which to allocate its resources. Use the OwnerSystem or the OwnerSystemName property to modify you current applications, otherwise they will not run.

  • CharacterRecognition Control
  • Results.Strings.Item.Length returns the length of the resulting string.
  • The search angle range has been widened.
  • Code Control
  • Added support for the following code types:
    • codeCompositeCode
    • codeCode93
    • codeEAN8
    • codeMicroPDF417
    • codePharmaCode
    • codeQRCode
    • codeRSSCode

  • Added quality estimation:
    Use the VerifyCode method to verify if the code quality meets your standards. The verification results are returned in the properties of the Results.VerificationGrade property.
  • You can increase the decoding speed or the accuracy by modifying the following features:
    • ScanlineHeight property
    • ScanlineStep property
    • SubType property
    • Timeout property
  • Digitizer Control
  • Added support for camera locking:
    • CameraLock event
    • CameraLockEvent property
    • CameraLockSensitivity property
    • CameraUnlockSensitivity property
  • Added support for camera presence:
    • CameraPresent event
    • CameraPresentEvent property
    • IsCameraPresent property
  • Added support for exposure signals format:
    • Exposure1Format property
    • Exposure2Format property
  • Added support for line events:
    • GrabLine event
    • GrabLineEvent property
    • GrabLineEnd event
    • GrabLineEndEvent property
  • Added support for synchronization of two digitizers:
    • SynchronizeOnGrabEnd property
    • SynchronizeOnGrabStart property
  • Added support for grabbing:
    • GrabAbort method
    • GrabContinuousEndTrigger property
    • GrabPeriod property
    • UseVoltageReference property
  • Added support for multiple buffering:
    • MultipleBuffering property
    • ProcessModifiedImage event
  • Other new properties:
    • Bayer property
    • InputFilter property
    • TriggerFormat property
  • Display Control

The new methods and properties available for the Display control are:

  • ClearOverlay method
  • CenterDisplay property
  • FillDisplay property
  • InterpolationMode property
  • NoTearing property
  • SelectedLUT property

  • EdgeFinder Control
  • Added support for new extraction filters:
    • ExtractionFilter.Kernel property
    • ExtractionFilter.Mode property
    • ExtractionFilter.OverscanType property
    • ExtractionFilter.OverscanValue property
    • ExtractionFilter.Power property
    • ExtractionScale property
  • Added support for timeout:
    • Timeout property
    • Results.TimeoutEnd property
  • Added support for getting vertices’ corresponding edge or edgels, in a chain approximation:
    • Results.Item.Vertices.Item.ChainIndex property
    • Results.Item.Vertices.Item.EdgelIndex property
  • Added support to get the width and height of the image from which the edges were extracted:
    • Results.SizeX property
    • Results.SizeY property
  • Added support for new edge features:
    • Circle
      • FeatureList.CircleFit property
      • Results.Item.CircleFitCenterX property
      • Results.Item.CircleFitCenterY property
      • Results.Item.CircleFitCoverage property
      • Results.Item.CircleFitError property
      • Results.Item.CircleFitRadius property
    • Ellipse
      • FeatureList.EllipseFit property
      • Results.Item.EllipseFitCenterX property
      • Results.Item.EllipseFitCenterY property
      • Results.Item.EllipseFitMajorAxis property
      • Results.Item.EllipseFitMinorAxis property
      • Results.Item.EllipseFitAngle property
      • Results.Item.EllipseFitError property
      • Results.Item.EllipseFitCoverage property
    • Line
      • FeatureList.LineFit property
      • Results.Item.LineFitA property
      • Results.Item.LineFitB property
      • Results.Item.LineFitC property
      • Results.Item.LineFitError property
  • Added support for moment elongation angle:
    • FeatureList.MomentElongationAngle property
    • FeatureList.GeneralFeret.RelativeToMomentElongationAngle property
    • Results.Item.MomentElongationAngle property
  • Other new methods and properties:
    • FillGapParameters.Candidate property
    • ModificationCount property
    • NearestNeighbors property
    • PutEdgeResults method
    • Results.CalculateStat method
    • Results.Put method
  • GraphicContext control
  • The new properties available for the GraphicContext control are:
    • LineSegments property
    • Dots property
  • Image Control
  • Added support for overscaning:
    • AllocationOverscanSize property
    • FastOverscanEnabled property
  • Added support for minimum and maximum pixel value:
    • MinimumPixelValue property
    • MaximumPixelValue property
  • Added support for memory mapping and location:
    • MappingToHostMemoryEnabled property
    • OnBoardMemoryLocation property
  • Other new methods and properties:
    • ChildRegion.Move method
    • GammaCorrectionExponents property
  • ImageProcessing Control
  • Added support for statistics:
    • CalculateStats method
    • Results.Stats property
  • The WaterShed method has changed to use a new improved and faster internal algorithm.
    To apply the old algorithm, set the WaterShedAlgorithm property to impMethod2.
    • impMethod1 (Default) : new watershed method; faster and highly recommended.
    • impMethod2 : old watershed method.

  • Measurement Control

  • The following search region box properties have been added to the Results.Item, Results.Item.Edge1, and Results.Item.Edge2 properties:
    • Results.Item.BoxCornerBottomLeftX property
    • Results.Item.BoxCornerBottomLeftY property
    • Results.Item.BoxCornerBottomRightX property
    • Results.Item.BoxCornerBottomRightY property
    • Results.Item.BoxCornerTopLeftX property
    • Results.Item.BoxCornerTopLeftY property
    • Results.Item.BoxCornerTopRightX property
    • Results.Item.BoxCornerTopRightY property
    • * Also applies to Results.Item.Edge1 and Results.Item.Edge2 *
  • ModelFinder Control
  • Added support for filtering mode:
    • FilterMode property
    • KernelDepth property
    • KernelWidth property
  • Added support for new model types:
    • Models.AddFromMerge method
    • Models.AddFromResult method
    • Models.AddDiamondModel method
    • Models.AddTriangleModel method
    • Models.Item.SyntheticDefinition.Diamond property
    • Models.Item.SyntheticDefinition.Triangle property
  • Added support for determining the parameters used when drawing a model:
    • Models.Item.DrawingParameters property
    • Results.DrawingParameters property
  • Added support for returning the angle of the chained edgel:
    • Models.Item.Chains.Item.Edgels.Item.Angle property
    • Results.Item.ModelChains.Item.Edgels.Item.Angle property
    • Results.TargetChains.Item.Edgels.Item.Angle property
    • Results.Item.TargetChains.Item.Edgels.Item.Angle property
    • Results.Item.ModelChains.Item.Edgels.Item.Angle property
  • Added image definition settings:
    • Models.Item.ImageDefinition.DataDepth
    • Models.Item.ImageDefinition.DataType
    • Models.Item.ImageDefinition.NumberOfBands
  • Other new methods and properties:
    • UndoPreprocessing method
    • Models.ItemAtLabel property
    • Models.LastLevel property
    • Models.SearchPositionEnabled property
    • Results.ModelAdditionCompatible property
    • Results.TimeOutEnd property
  • PatternMatching Control
  • SearchMode property returns or sets the search mode when the MultipleModelMode property is set to true.
  • The Results.Get method has a new ResultType: patModelIndex. This ResultType returns the indices of the occurrences.
  • System Control
  • Added support for overscanning:
    • AllocationOverscanSize property
    • FastOverscanImage property
  • Added support for serial ports:
    • SerialPorts property
    • SerialPortData event
  • Added support for asynchronous function:
    • AsynchronousCallSupport property
  • Added support for multithreading
    • MultithreadSupport property
  • Other new properties:
    • NumberofCRTControllers property
    • SystemDescriptor property
    • SystemName property
    • WatchDog property
  • Threading Control

The new threading control allows you to allocate ActiveMIL thread contexts and synchronization events.
Use the threading control to allocate a selectable thread on a specified multi-threaded ActiveMIL system.
This allows you to synchronize the execution of ActiveMIL calls on an on-board processor.

[Contents]

Upgrading an existing project to ActiveMIL 8.0

This section contains important information for users upgrading to ActiveMIL 8.0.

  • All development environments

    After the installation of ActiveMIL 8.0, open your project in your development environment and compile it.

  • Visual C++ with Native COM support (only for ActiveMIL 2.1 or older)

    The variant parameter of the following methods should be changed to a VARIANT* using the '&' operator. If you do not make this change and call one of the methods listed below, a compilation error will inform you that there is no conversion between VARIANT and VARIANT*. Affected methods are:

    • Calibration.Results.Get,
    • CharacterRecognition.Results.Get,
    • Code.Results.Get,
    • Image.Get,
    • Image.GetLine,
    • ImageProcessing.PolarParameters.CalculatePolarSize,
    • ImageProcessing.PolarParameters.CalculateRectangularSize,
    • ImageProcessing.Results.Get,
    • ImageProcessing.WarpParameters.WarpLUT.Get,
    • Measurement.Results.Get,
    • PatternMatching.Results.Get,
    • All of the LUT.Get methods.

[Contents]

Changes from ActiveMIL 7.5 to ActiveMIL 8.0

  • Application Control

    The new Threading control replaced the Application.ControlThread method. The Threading control allows you to allocate ActiveMIL thread contexts and events that help you synchronize the execution of ActiveMIL calls.

  • Calibration Control

    The CalibrationPoints.RemoveAll method is no longer supported. Instead, use the CalibrationPoints.Remove method with the Index set to calAll.

  • Digitizer Control

    The following digitizer properties are not supported anymore:

    • ExposureBypass
    • GrabHaltOnNextField
    • InputSignalPresent
    • InputSignalSource
    • LUTPalette

    The following properties are no longer a Long expression. They have been changed to a Double expression:

    • BlackReference
    • WhiteReference

  • Display Control

    The following properties are no longer a Long expression. They have been changed to a Double expression:

    • PanX
    • PanY
    • ZoomX
    • ZoomY

    The X and Y parameters of the Pan and Zoom methods have also been changed to a Double. Note that negative numbers are no longer supported. You should use decimal values to zoom out.

    The following display properties are not supported anymore:

    • DirectImage
    • DirectWriting
    • OverlayDestructive
    • OverlayFlicker
    • OverlayKeyCondition
    • OverlayLUTEnabled
    • OverlayLUT

  • EdgeFinder Control

    You can now use the method Results.Get with an index or a label value.

  • Image Control

    The Control method has the following modifications:

    • imWindowDCAlloc control has been renamed to imDCAlloc
    • imWindowDCFree control has been renamed imDCFree
    • imMapImageToHost is no longer supported

    The Picture property is no longer supported since it cannot be used in Visual Basic.Net.

  • ImageProcessing Control

    The new OverscanMode parameter, allowing you to enable or disable overscanning, has been added to the following methods:

    • EdgeDetect
    • EdgeDetect1
    • EdgeDetect2
    • HorizontalEdge
    • LaplacianEdge1
    • LaplacianEdge2
    • Sharpen1
    • Sharpen2
    • Smooth
    • VerticalEdge

    The WarpParameters.WarpLUT.Get method has 2 new parameters:

    • Format specifies the data format to use to save the data.
    • Band specifies the color band to copy.

    The Watershed method has 2 new parameters:

    • LabeledMarker specifies whether the marker image is a labeled marker image.
    • FillSource specifies whether to fill all local basins of a valid catchment basin in the source image.

  • ModelFinder Control

    The number of parameters of the method Models.AddEdgeModel has increased. Four "double" optional parameters (OffsetX, OffsetY, SizeX, SizeY) were added to specify a region of EdgeFinder Results to be used as a new model. Applications using this method in Visual Basic .NET 2003 or in Visual Basic 6.0 only need to be recompiled. For Visual C++ applications, these parameters need to be added in the code before recompilation since optional parameters are not supported.

    The Models.Item.SearchRegion property has been replaced with Models.Item.Position properties. The old Models.Item.SearchRegion property was misleading in giving the impression that a child region was extracted, when in fact, it was defining a region in witch the model position was expected to be found. For this reason, it has been replaced.

  • PatternMatching Control

    FindOrientation method and patOrientation model type (Models.Item.ModelType property) are no longer supported. Note that searching at an angle (with or without patCircularOverscan) is still fully supported
    This affects the following properties and functions:

    • FindOrientation
    • Models.Add
    • Models.AddAutomatic
    • Models.Item.ModelType
    • Results.Get
    • Results.Item.Orientation

    Models.Item.ExportDontCareImage and Models.Item.ExportImage methods are no longer supported. Use the Models.Item.Draw method with patDrawDontCares or patDrawImage instead.

  • System Control

    The properties GrabInDisplay.LiveGrabNoTearing and GrabInDisplay.LastGrabInTrueImage were moved to the digitizer.

    The following properties are no longer a String expression:

    • BoardType has been changed to a SysBoardTypeConstants expression
    • ProcessingSystemType has been changed to a SysSystemTypeConstants expression
    • SystemType has been changed to a SysSystemTypeConstants expression and is now read only. To change the type of system, use the SystemDescriptor property.

    The following properties are not supported anymore:

    • GrabInDisplay
    • MMXEnabled
    • NumberOfDisplays
    • PhysicalAddressOverlay
    • PhysicalAddressUnderlay
    • SSEEnabled

  • Support for MFC wrapper classes has been removed

Refer to the 'Using ActiveMIL with Microsoft Visual C++ (Native COM)' chapter in the ActiveMIL User Guide for an explanation on how to convert an existing project using wrapper classes to use Native COM.

  • Support for Visual studio.NET has been added

  • Support for Visual Studio 6.0 and Visual Basic 6.0 has been removed

    If you have no choice but to continue working in these environments, add the Wizard and AddIns to your IDE by doing the following (note that it is not officially supported):

    Visual Studio 6.0

    1. Copy the ActiveMIL Application Wizard (...\Matrox Imaging\ActiveMil\Containers\VStudio6\VC++\libraries\AMILAppWizard.awx) into the Template directory of Visual Studio 6.0 (...\Microsoft Visual Studio\Common\MSDev98\Template\)
    2. Copy the ActiveMIL AddIn (...\Matrox Imaging\ActiveMil\Containers\VStudio6\VC++\libraries\Amilvc.dll) into the AddIns directory of Visual Studio 6.0 (...\Common\MSDev98\AddIns\)
    3. Register the ActiveMIL AddIn from within the Visual Studio 6.0 directory (regsvr32 ...\Common\MSDev98\AddIns\Amilvc.dll)

    Visual Basic 6.0

    1. Copy the ActiveMIL AddIn (...\Matrox Imaging\ActiveMil\Containers\VStudio6\VBasic\Libraries\AMILVB.dll) into the AddIns directory of Visual Studio 6.0 (...\Common\MSDev98\AddIns\)
    2. Register the ActiveMIL AddIn from within the Visual Studio 6.0 directory (regsvr32 ...\Common\MSDev98\AddIns\Amilvb.dll)
    3. Add a key named AMILVB.Connect to your registry under [HKEY_CURRENT_USER\Software\Microsoft\Visual Basic\6.0\Addins]
    4. 				Add the following strings and dword under this key:
"FriendlyName"="Matrox ActiveMIL VB Add-in"
"SatelliteDllName"="YOUR_PATH_TO_VISUAL_STUDIO\\Common\\MSDev98\\AddIns\\AMILVB.dll"
"Description"="Adds commands and controls to allow better integration of
                ActiveMIL in Visual Basic"
"LoadBehavior"= dword:00000003

[Contents]

Changes from ActiveMIL 7.1 to ActiveMIL 7.5

  • New Support for Matrox CronosPlus

    The new Matrox imaging CronosPlus is now supported.

  • Support for Matrox Cronos has been removed

  • The Meteor-II/1394 driver now supports IIDC Version 1.30

  • ModelFinder Control

    The Models.Item.Chains.Item.Pixels property has been renamed to the Models.Item.Chains.Item.Edgels property. Subsequently, a collection of edgels refers to a collection of ModelFinderEdgel objects. These changes were made to be more precise and to be consistent with the new EdgeFinder control. Programs that were build with the old names do not require a recompilation. However, if you modify your code, failure to make the name change will result in compilation errors.

  • PatternMatching Control

    Angular search is no longer supported on the Matrox Genesis.

[Contents]

On-line documentation

The complete on-line documentation provided with ActiveMIL can be found under Start\All Programs\Matrox Imaging\ActiveMIL\Documentation\ActiveMIL Help. The documentation contains five majors sections:

  • ActiveMIL User Guide contains general information on ActiveMIL. It is designed to help you quickly learn the basics of building Imaging applications with ActiveMIL. The chapters that are relevant to your application should be read before attempting to browse through the control reference section.
  • ActiveMIL Reference contains detailed information on all properties, methods, and events of all ActiveMIL controls.
  • ActiveMIL Board-Specific Notes contain general board-specific information. Note that board-specific information regarding a specific property, method, or event is integrated into their reference topics.
  • ActiveMIL Glossary contains a list of difficult or specialized terms with their definitions.
  • ActiveMIL ReadMe file contains the last minute shipping notes.

[Contents]

Deploying ActiveMIL applications (Redistribution)

Refer to the 'Distribution and licensing' chapter in the ActiveMIL User Guide.

Note for Visual Basic Users:

We do not provide dependency files (DEP files) for use with Visual Basic's setup wizard because this tool does not allow for the installation of Matrox frame grabber drivers.

[Contents]

Obtaining additional help

The following sources should be checked for additional information when it is needed:

  • The on-line documentation.
  • Our web site at www.matrox.com/imaging.
  • The Matrox Imaging Developers' Forum at http://www.matrox.com/imaging/support/dev_forum/.

[Contents]

Environment specific notes

This section contains information specific to a given development environment. Although ActiveMIL strives to be environment-independent, each environment is implemented differently and this sometimes causes problems for ActiveMIL.

Note: You must have at least Visual Studio .NET 2003 with Microsoft .NET Framework 1.1 Service Pack 1 (SP1).

Visual C++ .NET

The procedure for starting a new ActiveMIL C++ project under Visual Studio .NET is similar to the procedure for Visual C++ 6.0. For more information, please refer to the 'Using the MFC Application template to create an application (Visual C++)' section in the 'Introduction' chapter and to the 'Using the ActiveMIL MFC Application template to create an application (Visual C++)' chapter in the ActiveMIL User.

Known bugs

  • Property pages are not accessible through the context menu of MFC and Win32 applications. You must use the Property Pages button on the Properties window. This seems to be a Visual Studio .NET 2003 issue.

    Visual Basic .NET

    Using arrays more efficiently

    The marshalling of arrays between the Microsoft .NET managed environment and the ActiveMIL controls can be time consuming. This is because arrays are not passed directly to the ActiveMIL controls. Instead, arrays are copied to unmanaged memory, a call to ActiveMIL is made, and then the arrays are copied back to managed memory. To avoid all this copying, ActiveMIL provides the MArrayRef class. Arrays wrapped in an object of this type are passed directly. The following table shows approximate timings*:

    Normal | MArrayRef | Ratio
    one band | Image.Get | 18 ms | 1 ms | 18 times better
    Image.Put | 13 ms | 1 ms | 13 times better
    all bands | Image.Get | 168 ms | 2 ms | 84 times better
    Image.Put | 94 ms | 2 ms | 47 times better
    * Timings were obtained on a computer with Pentium IV 3GHz and 1GB of RAM.

    This class is included in the Matrox.ActiveMIL.Utility.dll assembly, found in the "Matrox Imaging\ActiveMil\Containers\VStudio.NET" directory of the Matrox Imaging installation CD.

    Example of usage:

    // Visual Basic .NET example

' Normal array declaration
Dim Array(AxMImage1.SizeX, AxMImage1.SizeY) As Byte

' The array is wrapped in a MArrayRef class before passing. This pins
' the array memory so that the garbage collector does not move it.
Dim ArrayRef As MArrayRef = New Matrox.ActiveMIL.Utility.MArrayRef(Array)

' When calling the ActiveMIL method, the MArrayRef.GetSafeArray method must be used
AxMImage1.Get(ArrayRef.GetSafeArray(), ImFormatConstants.imFormatDefault, _
               ImBandConstants.imAllBands, 0, 0, AxMImage1.SizeX, AxMImage1.SizeY)

' After the call is made, you can call the Dispose function to unpin the array memory.
' If Dispose is not called, the array will get unpinned when the MArrayRef object
' gets collected by the garbage collector.
ArrayRef.Dispose()

    Known bugs

    • There is a known problem with the For Each...Next statements in some of our collections. This bug results the following error message:

      An unhandled exception of type 'System.ExecutionEngineException' occurred in custommarshalers.dll

      If you get this error, use a For...Next statement as a workaround.

    • The using statement cannot be used with ActiveMIL controls. Do not confuse the using statement with the using directive. Refer to MSDN for more information.

    [Contents]

    Outstanding issues

    This section describes any limitations, or problems that exist in the current ActiveMIL release. The tags [VB.NET] and [VC] implly that the note only applies to Visual Basic or Visual C++, respectively. If the tag is followed by a number, the note is specific to that version of the development environment. If there is no tag, the note applies to all development environments.

    ActiveMIL Controls issues

    • PatternMatching Control

      Models loaded from a file

      • If a pattern matching model is loaded from file created using a MIL or Matrox Inspector with the number of occurrences set to "all", ActiveMIL sets the number of occurrences to 10.
    • DigitizerControl

      1394 camera format 7

      • Some 1394 cameras support digitizer formats represented by the string "xXx data_format_7_z". In order to use these formats, one should implement the following code.

        [VB.NET]

        Const M_1394_BANDWIDTH_FLAG = &H800

Public Function M_1394_BANDWIDTH(ByVal percent As Integer) As Integer
   If (percent > 0) And (percent <= 100) Then
      Return (M_1394_BANDWIDTH_FLAG Or percent)
   Else
      Throw New System.Exception("invalid bandwidth value")
   End If
End Function

AxMDigitizer1.InitializationFlag = M_1394_BANDWIDTH(10)

        [VC]

        #define M_1394_BANDWIDTH_FLAG 0x00000800L
#define M_1394_BANDWIDTH(percent) ( (((long) percent > 0) && ((long) percent <= 100)) ? (M_1394_BANDWIDTH_FLAG | ((long) percent)) : 0 )

m_Digitizer1->InitializationFlag = M_1394_BANDWIDTH(10);

    Documentation errata

    • Reference Guide

      • ModelFinder Control

        Models.SearchPositionEnabled

        • The remark about the nominal position should be: "Set the nominal position of the search for each model using the Models.Item(ModelIndex).Position.X and Models.Item(ModelIndex).Position.Y properties. If you do not specify a nominal position when this property is set to False, ActiveMIL will not be able to locate any occurrences and no errors will be returned."

    Other issues

    • Control are visible at run-time

      [VB.NET] ActiveMIL controls dropped on a .NET form will be visible at runtime, unless you set the Visible property to false.

    • The control stays in an error state

      On certain systems, stopping your debugging process by pressing the Stop-Debugging button or by using the keyboard shortcut Shift-F5 while your Dialog or Form is open, causes the control to stay in an error state at design-time. To correct the situation, close the Dialog or Form and re-open it.

    • Properties that refer to another ActiveMIL control

      [VB.NET] For all properties that refer to another ActiveMIL control (for example, the Image property of the Digitizer control). you can use the Visual Basic Nothing statement to confirm that the property is not currently associated with a control.

    [Contents]