April 26, 2002
Copyright © 2002 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 functions for image processing (point-to-point, statistics, filtering, morphology and geometric transforms), pattern recognition, blob analysis, measurement, OCR, and bar and matrix code recognition.
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 | Windows NT 4.0 Service Pack 6a | Windows Me | Windows 98, Second Edition | |
Microsoft Visual C/C++ 6.0 Service Pack 5* | Yes | Yes | Yes | Yes | Yes |
Microsoft Visual Basic 6.0 Service Pack 5* | Yes | Yes | Yes | Yes | Yes |
Microsoft Visual Studio .NET | No** | No** | No** | No*** | No*** |
*Other environments, and other operating systems are not officially supported by Matrox.
** ActiveMIL does not support Microsoft Visual Studio .NET. There are many
limitations and problems. For more details, see Visual Studio .NET section.
*** Those operating system are not supported by Microsoft.
Operating System / Matrox Imaging Hardware
Click on a board label in the table below to access board-specific release notes. Links to boards that have not been installed will not work.
Windows XP | Windows 2000 | Windows NT 4.0 Service Pack 6a | Windows Me | Windows 98, Second Edition | |
Matrox Meteor-II/Standard | Yes | Yes | Yes | Yes | Yes |
Matrox Meteor-II/Multi-Channel | Yes | Yes | Yes | Yes | Yes |
Matrox Meteor-II/1394 | Yes | Yes | Yes | Yes | No |
Matrox Meteor-II/Digital | Yes | Yes | Yes | No | No |
Matrox Meteor-II/Camera Link | Yes | Yes | Yes | No | No |
Matrox Genesis | Yes | Yes | Yes | No | No |
Matrox Genesis-LC | Yes | Yes | Yes | No | No |
Matrox Orion | Yes | Yes | Yes | Yes | Yes |
Matrox Corona-II | Yes | Yes | Yes | Yes | Yes |
New Matrox Cronos | Yes | Yes | No | Yes | Yes |
Note that Matrox Pulsar-LC, Matrox Pulsar, Matrox Meteor, Matrox Corona-LC and Matrox Corona are no longer supported.
The new ActiveMIL ModelFinder control uses geometric characteristics to help solve machine vision problems such as alignment, measurement, and inspection. The ModelFinder control provides complete support for calibration. Searches are performed in the calibrated real-world such that, even without physically correcting your images, complex distortions do not affect performance, and results can be returned in real-world units.
MMultipleDocument: This example illustrates how to build an MDI application with ActiveMIL using Visual Basic or Visual C++. The application can create new images, load existing ones, as well as save and grab new images from a camera or other input device.
MModelFinder: This example defines models and searches for them in a target image using geometric characteristics.
The ShowPropertyPages method can be called at run-time to display a control's property pages.
The following properties are no longer supported: DualScreenMode, RGBModuleNumber, GrabInDisplay.ForcePseudoInNonUnderlayDisplays and GrabInDisplay.Tracking.
CameraColorLockEnabled property
CameraLockEnabled property
CameraLockSensitivity property
CameraLock event and CameraLockEvent property
CameraPresent event and CameraPresentEvent property
CameraUnlockSensitivity property
Exposure1ClockFrequency and Exposure2ClockFrequency properties
Exposure1ClockSource and Exposure2ClockSource properties
InterpolationMode property
IsCameraLocked property
IsCameraPresent property
UserBit9 and UserBit10 properties
ScaleQuality property
SerialPort.Channel property
GrabFailCheck and GrabFailRetryNumber properties are deprecated and are no longer supported.
The term "non-windowed mode" is no longer used, and has been replaced by the term: "auxiliary display".
An auxiliary display refers to a display without a windowed border on a dedicated screen and encompasses display using the encoder. Refer to the
"Display" chapter in the ActiveMIL User Guide.
ActiveMIL and ActiveMIL-Lite can use the high resolution auxiliary display functionality provided with Matrox Corona-II, Matrox Genesis, Matrox Orion, Matrox 4Sight-II, or Matrox Millennium G400/G450.
ActiveMIL and ActiveMIL-Lite can allocate an auxiliary display with an encoded video format. This functionality is provided with a Matrox Corona-II, Matrox Orion, Matrox 4Sight-II, or Matrox Millennium G450.
A list of the VCFs supported when using the second CRT controller of a Millenium G400/G450 can be found in the
Matrox Imaging\Drivers\VGA\VCF directory.
Important Note:
It is possible to have more than one auxiliary display. Note however that only one auxiliary display is possible per graphics controller.
When using the second CRT controller of a Millennium G400/G450, the auxiliary display feature is only available when the primary output is in 32-bit display resolution (true color), and the secondary output in a 32-bit VCF.
SyncType property
HardwarePan and HardwareZoom properties are deprecated and are no longer supported.
ContentModifed event
ContentModifedEvent property
Bayer method
WhiteBalanceCoefficients property
JPEG2000Algorithm object
Results.Draw method
CodeType property
EscapeSequence property
Save and Load methods
UsePresearch property
Binarize method
WarpParameters.WarpLUT.MilID property
Markers(MarkerIndex).Draw and Results(ResultOccurrenceIndex).Draw, Results(ResultOccurrenceIndex).Edge1.Draw and Results(ResultOccurrenceIndex).Edge2.Draw methods.
Models(ModelIndex).Draw, Results(ResultOccurrenceIndex).Draw methods.
Models(ModelIndex).SearchAlgorithm.CoarseSearchAcceptance property
Models(ModelIndex).SearchAlgorithm.ExtraCandidates property
TargetCaching property
This section contains important information for users upgrading to ActiveMIL 7.0.
After the installation of ActiveMIL 7.0, open your project in your development environment and compile it.
The variant parameter of the following methods should be changed to a VARIANT* by using the '&' operator. If you do not make this change, you will get a compile error stating that there is no conversion between VARIANT and VARIANT* when you call any of the following: Calibration.Results.Get, CharacterRecognition.Results.Get. Code.Results.Get, ImageProcessing.Results.Get, ImageProcessing.PolarParameters.CalculateRectangularSize ImageProcessing.PolarParameters.CalculatePolarSize ImageProcessing.WarpParameters.WarpLUT.Get, Image.Get, Image.GetLine, Measurement.Results.Get, PatternMatching.Results.Get and all the LUT.Get methods.
The new new Matrox imaging cronos is now suppported.
This section contains important information for users upgrading from ActiveMIL 2.0.
The 'm' prefix on all constants have been replaced by a module-specific prefix (in lowercase). For example, mNormalized is now patNormalized. Constants with 'm' prefixes still exist, but have been moved to groups called "<module>OldConstants". The following table shows the prefixes used by each control:
Application | System | Image | Digitizer | Display | Graphic Context | |
app | sys | im | dig | disp | gra | |
Image Processing | Pattern Matching | Blob Analysis | Character Recognition | Code | Calibration | Measurement |
imp | pat | blob | ocr | code | cal | meas |
Model Finder * | Region Of Interest | AVI File Handler | ||||
mod | roi | avi |
* new in ActiveMIL 7.0
All groups of constants are now prefixed with a module-specific value. For example, GrabModeConstants is now DigGrabModeConstants, and ModelTypeConstants is now PatModelTypeConstants.
The ProgIDs of all controls are changed to a new (and final) syntax: "MIL.Object". For example, to create an Image control dynamically at run-time in VB, you would pass the string "MIL.Image" to CreateObject. Visual C++ users are not affected by this change, unless they used the COM function CLSIDFromProgID. Note that the ActiveMIL add-in for VB will automatically change to the new syntax once the project is loaded and re-compiled.
The controls that make up the LITE portion of ActiveMIL are re-packaged into a single file (MIL.OCX), which also incorporates the old MILOCX.DLL. The property pages are now separated from their controls, and exist in the COM DLL MILPropertyPages.DLL. This allows an ActiveMIL application to be deployed without all the extra code required to support property pages. User interface elements are also separated from their controls because they are contained in the COM DLL MILUserInterface.DLL. All these changes mean that ActiveMIL's footprint is drastically reduced. With 2.0, deploying an ActiveMIL-Lite application required at least 2 MB of disk space, while version 2.1 (with all its new features and speed optimizations) requires less than 900 KB.
None of the read-only properties appear in design-time property browsers anymore. This occurs as a side-effect of some of our optimizations. This means that the list of properties in most controls is considerably shorter (and easier to scroll through). Note that the properties still exist, and can be referred to at run-time as always.
In previous versions of ActiveMIL, properties that represent references to another control (for example, Digitizer.Image) used a hybrid type. To set the property, a string representing the control's name was used, but when 'getting' the property value, an object was returned. This scheme, while completely legal, caused many environments to have problems importing ActiveMIL controls. To solve this problem, a new family of properties was created using the form <Property>Name (for example, Digitzer.ImageName). The Name version is of type string, and the normal property is of type object. This change should not affect your application code since setting either property will work. For example, the following two statements are equivalent (the first form is faster, however):
SystemType property modified for Meteor II product.
BoardType property modified for Meteor II product
GrabInDisplay.PseudoWhenOverlapped property
Results(ResultOccurrenceIndex).Orientation, Results(ResultOccurrenceIndex).Edge1.Orientation, Results(ResultOccurrenceIndex).Edge2.Orientation properties
DeviceNumber property
Image property
SendTrigger method
Complete on-line documentation is provided with ActiveMIL. It can be found under Start\Programs\Matrox Imaging Products\ActiveMIL\ActiveMIL Help. The documentation contains four majors sections:
Note to Microsoft Visual C++ Users:
From any code window (.CPP or .H file), the ActiveMIL context sensitive help works using the CTRL-F1 key instead of the F1 key. To use this feature, the MIL and ActiveMIL VC++ Add-Ins must be enabled. These Add-Ins are automatically installed but are not enabled by default. To enable the Matrox VC++ Add-Ins in Visual C++, use the property pages under Tools\Customize\Add-ins and Macro files.
See Chapter 17: Distribution and licensing in the ActiveMIL User Guide
Note to Visual Basic Users:
We do not provide dependency files (DEP files) for use with Visual Basic's setup wizard because this tool is not able to handle installation of our board level drivers.
The following sources should be checked for additional information when it is needed:
This section contains information specific to a given environment. Although ActiveMIL strives to be environment independent, each environment is implemented differently and this sometimes causes problems for ActiveMIL.
As described in What's changed between ActiveMIL 2.0 and ActiveMIL 2.1 , the constants' group names have changed. This could affect your code if you declared variables as a group using the Dim statement (that is, Dim GrabMode As GrabModeConstants). The ActiveMIL add-in will automatically scan and modify your code the first time you load your project, so make sure the add-in is enabled. The module names have also changed, so if your code has variables that use the syntax "Dim <Var> As <Module>.<Item>", those instances will also be changed by the add-in.
To take advantage of the dual interfaces now implemented in ActiveMIL, you must modify your code slightly. By default, Visual Basic will use dual interfaces in sub-objects only (that is Image.LUT), but not in top-level controls. To work around this limitation, ActiveMIL implements secondary interfaces on all controls that allow direct access from Visual Basic. To use these, you must declare your variable of type I<control> using the Dim statement, and set it equal to the Object property of an ActiveMIL control. For example,
Dim DirectDigitizer As MIL.IDigitizer
Set DirectDigitizer = Digitizer1.Object ' assuming that 'Digitizer1' is on the form
Starting with version 2.1, there are 3 ways to use ActiveMIL from Visual C++:
Native COM can be used in conjunction with either the MFC ActiveX support or Windows API. Starting with version 6.0 of Visual C++, COM objects can be used directly, without the need for explicit wrapper classes. The ActiveMIL controls and objects are built from _com_ptr_t templates (see MSDN, for more information on this built-in class). The individual interface names have the form I<Object>Ptr (for example, the Digitizer control is IDigitizerPtr). Note that controls that are on an MFC dialog are also of type C<Control>, as with the wrapper classes discussed below. Currently, the examples are written using Native COM.
This access method has the following advantages over the others:
More information is available in the chapter titled, Using ActiveMIL with Microsoft Visual C++ (Native COM) of the ActiveMIL User Guide.
Only ActiveMIL wrapper classes could be used in previous versions. Wrapper classes should be used if source-level compatibility is required with code written with previous versions of ActiveMIL. Wrapper classes do not use a direct interface. When you use the 'Add ActiveMIL to Project' button and select 'MFC class wizard classes', ActiveMIL wrapper classes are used.
This access method has the following advantages over the others:
This method involves manually importing each ActiveMIL control into the Visual C++ environment. This is accomplished by selecting Project | Add To Project | Components and Controls from the menu.
There is no real reason to use this method. It has the following disadvantages over the other two methods:
The usage of ActiveMIL with Visual Studio .NET is not currently supported by Matrox Imaging. At the time of release there were still many problems and limitations; however, support for Visual Studio .NET will be available in the near future.
If you require using ActiveMIL with Visual Studio .NET right away, the following information will be a quick primer on how to start new projects. Note that a listing of bugs and limitations that you might encounter is included in the section; the majority of issues deal the design-time functionality of ActiveMIL.
Starting a new ActiveMIL C++ project under Visual Studio .NET follows a similar procedure as under Visual C++ 6.0. Please refer to chapter 18 of ActiveMIL's user guide, "Using ActiveMIL with Microsoft Visual C++ (Native COM)", for more information about ActiveMIL controls.
Preliminary steps
Before building a
Visual C++ .NET project using ActiveMIL controls, these steps must be
completed:
1. The ActiveMIL header and library directories
must be properly
set. They can both be entered globally or for a single project. An
appropriate include
path should resemble the following: "D:\Program Files\Matrox Imaging\ActiveMIL\Containers
\VC++\include". Likewise, an appropriate library path should point to the location of the
ActiveMIL controls, for example, "D:\Program Files\Matrox
Imaging\ActiveMIL\controls".
2.
Add ACTIVEMIL_IN_PROJECT and ACTIVEMIL_USE_COM_CLASS to each project's
preprocessor definitions. Use the "Project->Properties" menu,
"Configuration Properties->C/C++->Preprocessor" settings page,
"Preprocessor Definitions".
3. In
projects where ActiveMIL controls are only created at
run-time, the ACTIVEMIL_WIN32_ONLY preprocessor definition can also be
added. Doing so will prevent the declaration of unnecessary classes.
Using design-time
In order to build an
application using the design-time capabilities of ActiveMIL, such as the
property pages, the controls need to be dropped onto an MFC dialog. To do so
follow these steps:
1.
Open the MFC
dialog from the resource view.
2. (Optional) Add the ActiveMIL controls to the Visual Studio .NET toolbox.
3. Add the required ActiveMIL controls to the MFC dialog box.
To access the ActiveMIL
controls on the form at run-time, they need to be associated with a member
variable. The standard way of doing this would be to use the "Add Variable…"
command, but we won’t use it for two reasons. First, it automatically
generates a wrapper, which we don’t want to use since it doesn’t take
advantage of the native COM capabilities of the Visual C++ compiler.
Secondly, the wrapper generation process doesn’t work. Instead, we will
link the ActiveMIL controls to variables manually, by adding a few lines of
code:
1. In the header file of the dialog class containing the ActiveMIL control.
2. In the implementation file of the dialog class containing the ActiveMIL control.
Using run-time only
For projects in which the ActiveMIL controls are only created at run-time, include the header files of the controls for which you want to declare variables (for example: #include "Image.h"). As mentioned in the preliminary steps, the ACTIVEMIL_WIN32_ONLY preprocessor definition should be added in the project settings to prevent the declaration of unnecessary classes.
For more information on creating ActiveMIL objects at run-time, please refer to the "Run-time object declaration" topic in chapter 18 of the ActiveMIL user guide.
Known bugs
Bugs that occur at design-time:
Using design-time
To use the design-time capabilities of ActiveMIL, the controls need to be dropped onto a Windows Form (a class deriving from the System.Windows.Forms.Form class). First, you must add the ActiveMIL controls to the Visual Studio .NET toolbox by following these steps:
1. You might want to create a new tab in the toolbox that will contain all ActiveMIL controls. To do so, right click on the toolbox and choose "Add Tab".
Once the ActiveMIL controls have been added to the toolbox they can they can be selected and dropped onto the Windows Form. After the control has been dropped, the property browser and property pages can be used to customize the application. The controls can be accessed at run-time by using the variable that was added to the Windows Form class declaration.
VS.NET automatically generates two interop assemblies and adds them to the project references when an ActiveMIL control is dropped on a Windows Form. These interop assemblies act as a bridge between the managed code and the ActiveMIL controls. They contain metadata describing all classes, interfaces and events of the controls; these can be viewed using the object browser "View->Other Windows->Object Browser" menu.
Using run-time only
For projects in which the ActiveMIL controls are only created at run-time, the controls need to be added to the project references before they can be created. Follow these steps to do so:
1. Open the "Solution Explorer" window using the menu "View->Solution Explorer".
3. Under the "COM" tab select the required ActiveMIL controls. Note that all ActiveMIL Lite controls (Application, System, Image, Digitizer, Display, GraphicContext) are grouped in the "ActiveMIL Base Controls" component.
When adding the ActiveMIL controls to the projects references, VS.NET automatically generates an interop assembly. This interop assembly acts as a bridge between the managed code and the ActiveMIL controls. It contains metadata describing all classes, interfaces and events of the controls; these can be viewed using the object browser "View->Other Windows->Object Browser" menu.
As shown in the following example, the Application control needs to be created first. Other controls are then created using the Application control's CreateObject method. The CreateObject method ensures proper initialization of the ActiveMIL controls.
// Visual C# .NET example // declaration of ActiveMIL objects MIL.Application Application1; MIL.System System1; MIL.Image Image1; MIL.Display Display1; // creation of the ActiveMIL Application control Application1 = new MIL.Application(); // creation of other ActiveMIL controls System1 = (MIL.System)Application1.CreateObject("MIL.System", false); System1.SystemType = "Meteor_II"; System1.Allocate(); Image1 = (MIL.Image)Application1.CreateObject("MIL.Image", true); Display1 = (MIL.Display)Application1.CreateObject("MIL.Display", false); Display1.DisplayType = MIL.DispDisplayTypeConstants.dispUserWindow; Display1.UserWindow = (int)panel1.Handle; Display1.Allocate();
Known bugs
Bugs that occur at design-time:
Bugs that occur at run-time:
Borland environments are not officially supported, but quick tests have shown that parts of ActiveMIL will work in these environments. Only version 5.0 of both environments were tested.
Follow these steps to use ActiveMIL in a Borland environment:
MyDisplay.Image := MyImage.ControlInterface
In C++ builder, you must also explicitly cast the right hand side expression to IDispatch*. For example,
MyDisplay->Image = (IDispatch*) MyImage->ControlInterface;
This section describes any limitations, or problems that exist in the current release. The tags [VB] and [VC] mean the note only applies to Visual Basic or Visual C++, respectively. If a number follows the tag, the note is specific to that version of the environment. If nothing is mentioned, the note applies to all environments.
FileInquire Method
Models loaded from a file
ApplyFilter method
Bayer method
Control method
Save method
Load method
ForegroundPixelValue property
FastFourierTransform method
The code snippet on the usage of type BSTR should read like this:
// Set the SystemType using BSTR BSTR SystemType = SysAllocString(L"VGA"); m_System1->SystemType = SystemType; SysFreeString(SystemType); // Get the SystemType using BSTR SystemType = SysAllocString(m_System1->SystemType); SysFreeString(SystemType);
The code snippet on the usage of Win32's SAFEARRAY should read like this:
// ... // [removed] // The SAFEARRAY object will be wrapped into a VARIANT because the Get method // needs the array to be passed as a 'VARIANT *'. // Create the VARIANT containing the array. VARIANT ArrayVariant; VariantInit(&ArrayVariant); V_VT(&ArrayVariant) = VT_ARRAY | VT_UI1; V_ARRAY(&ArrayVariant) = psa; // From now on the SAFEARRAY will be managed by the VARIANT psa = NULL; // [removed] // ...
[VB] For all properties that refer to another ActiveMIL control (for example, the Image property of the Digitizer control). you can use the Visual Basic Is Nothing statement to confirm that the property is currently not associated with a control.