Matrox ActiveMIL 7.1 – Shipping Notes

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. 


Contents

  1. Getting started

  2. Supported environments

  3. What's new in ActiveMIL 7.0?

  4. Upgrading an existing project to ActiveMIL 7.0

  5. What's changed between ActiveMIL 7.0 and ActiveMIL 7.1

  6. What's changed between ActiveMIL 2.0 and ActiveMIL 2.1

  7. Online documentation
  8. Deploying ActiveMIL applications (Redistribution)
  9. Obtaining additional help
  10. Environment specific notes
    1. Visual Basic 6.0
    2. Visual C++ 6.0
    3. Visual Studio .NET
    4. Borland (Delphi and C++ Builder)
  11. Outstanding issues
    1. ActiveMIL Controls issues
    2. Documentation errata
    3. Other issues

Getting started

[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 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.

[Contents]


What's new in ActiveMIL 7.0?

[Contents]


Upgrading an existing project to ActiveMIL 7.0

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

[Contents]


What's changed between ActiveMIL 7.0 and ActiveMIL 7.1?

[Contents]


What's changed between ActiveMIL 2.0 and ActiveMIL 2.1?

This section contains important information for users upgrading from ActiveMIL 2.0.

[Contents]


Online documentation

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.

[Contents]


Deploying ActiveMIL applications (Redistribution)

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.

[Contents]


Obtaining additional help

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

[Contents]


Environment specific notes

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.

  1. Visual Basic 6.0

    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

  2. Visual C++ 6.0

    Starting with version 2.1, there are 3 ways to use ActiveMIL from Visual C++:

    1. Using Native COM access classes.

      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:

      • Fully exploits ActiveMIL's ultra-fast dual interface.
      • Allows properties to be accessed without individual 'Get' and 'Set' functions. Properties are treated like data members of a C++ class (for example, you can type: Image->SizeX = 640, instead of Image.SetSizeX(640)). This makes the syntax simpler to read, and is more consistent with the concept of a property.
      • Properties and methods are fully typed, that is, properties and method parameters that are enumerations are bound to those enumerations. Other access methods make these items of type long.

      More information is available in the chapter titled, Using ActiveMIL with Microsoft Visual C++ (Native COM) of the ActiveMIL User Guide.

    2. Using the ActiveMIL wrapper classes built by Matrox.

      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:

      • Allows for optional parameters in methods.
      • Collection items can be accessed implicitly, without using the .Item property.

       

    3. Using native MFC class-wizard-generated wrapper classes.

      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:

      • No constants are generated at all.
      • The controls must be re-imported for each new version of ActiveMIL.  If this is not done, new features will not be available.

       

  3. Visual Studio .NET

    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.

    1. Visual C++ .NET

      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".

        • To add the header and library directories globally, use the "Tools->Options" menu, "Projects->VC++ Directories" options page, and set the "Show directories for" to "Include files" for the include path and "Library files" for the library directories.
        • To add header and library directories for a single project, use the "Project->Properties" menu, "Configuration Properties->C/C++->General" settings page, and add the include and library paths in the "Additional Include Directories".

      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.

        • You might want to create a new tab in the toolbox to contain all ActiveMIL controls; right click on the toolbox and choose "Add Tab".
        • To add the ActiveMIL controls, right click on the toolbox and choose "Customize Toolbox…". Under the COM Components tab, select all ActiveMIL controls and press OK.

      3.      Add the required ActiveMIL controls to the MFC dialog box.

        • If the controls have been added to the toolbox: select the controls from the toolbox and drop them on the dialog.
        • If the controls have not been added to the toolbox: right click on the dialog and select "Insert ActiveX control…" from the pop-up menu.

      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.

        • Include the header file of the control for which you want to declare a variable (for example: #include "Image.h").
        • Add the variable declaration in the dialog's class definition (for example: CImage m_Image1).

      2.      In the implementation file of the dialog class containing the ActiveMIL control.

        • Link the variable to the ActiveMIL control on the dialog; this is done by adding a call to the DDX_CONTROL function in the DoDataExchange method of the dialog class (for example: DDX_Control(pDX, IDC_IMAGE1, m_Image1) ).

      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:

      • Closing a dialog resource does not correctly release the ActiveMIL controls; therefore, when reopening this dialog resource the ActiveMIL System control will not be able to allocate the resources of your imaging board, since they were not properly released. For the imaging board resources to reallocate, you will need to restart Microsoft Visual Studio .NET.
      • Deleting an ActiveMIL control does not correctly release it. Even though it becomes invisible, it can still be referenced by other controls, and can cause an error. If this happens you will need to restart Microsoft Visual Studio .NET.
      • Bugs that occur when setting properties with the property browser:
        • Properties that can take a value or a constant cannot be set properly using the property browser (for example the Code.ImageThreshold property can take a value or the constant "codeDefault"). To set these properties, use the property pages instead.
        • If the modification of a property of an ActiveMIL control generates errors in other ActiveMIL controls, a dialog will appear with the error message "Invalid property value". Expand the Details pane for more information on the error; typically the property value is not really invalid. For example, changing the ActiveMIL System control's name will generate errors on the controls that are connected to it, but in this case the new name is not really invalid. To correct the error, the other control's OwnerSystem property must be changed to the new System control.
      • Property pages are not refreshed after a property value is changed. This causes many problems, as in the following cases:
        • Interactively setting regions using the interactive button doesn't work properly.
        • When setting the features of the BlobAnalysis.FeatureList property, the feature tree doesn't show the selected features immediately. To determine the selected features, use the value specified by the "Feature state" combo box; to determine all selected features refer to the "History" property page.
        • The BlobAnalysis filters and sorting keys descriptions are not refreshed when changing their parameters.
        • The Calibration calibration points are not refreshed when changing their parameters.
      • Context sensitive help does not work, please use help from the start menu "Start/Programs/Matrox Imaging/ActiveMIL/ActiveMIL Help".

    2. Visual Basic .NET and Visual C# .NET

      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".

      2.   To add the ActiveMIL controls, right click on the toolbox and choose "Customize Toolbox…". Under the COM Components tab, select all ActiveMIL controls and press OK.

      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".

      2.   In the solution explorer, right click the "References" item and select the "Add Reference…" menu item.

      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:

      • When the controls are dropped on the Windows Form for the first time, they are transparent. When the Windows Form is reloaded they will display correctly.
      • Bugs that occur when setting properties with the property browser.
        • When browsing the properties, a pop-up window will appear asking for a value. This window should not appear at that time, press the "cancel" button to close the window.
        • Properties in the property browser do not get updated when changing another property that affects them. For example, when changing the ParentImage property of the Image control, many properties become inherited from the parent image; these don't get updated immediately as they should.
        • Properties that can take a value or a constant cannot be set properly using the property browser. An example of this is the Code.ImageThreshold property that can take a value or the constant "codeDefault". To set these properties, use the property pages instead.
        • Properties that are shown in the property browser and which do not present any value are usually unsupported in the current context. Trying to change the value of these properties will display an error message: "NullReferenceException: Object reference not set to an instance of an object".
      • While working in design-time, references are sometimes kept on the System control, which prevents the resources of your imaging board from being allocated. If this happens you will need to restart Microsoft Visual Studio .NET.
      • When the system control is placed in a tab control, the tab will never load correctly, leaving the hourglass cursor. This problem is alleviated if you put the system control back on the form.
      • Some ActiveMIL property and method names clash with names in the System.Windows.Forms.AxHost class; when imported, they are automatically renamed with the prefix "Ctl". These name clashes only occur when using controls that have been dropped on a Windows Form, because controls that are created at run-time do not derive from the AxHost class. Here are a few examples of names that clash:
        • The "Name" property of each control has been renamed "CtlName".
        • The "ShowPropertyPages" method of each control has been renamed "CtlShowPropertyPages".
        • The "GraphicContext.Text" method has been renamed "GraphicContext.CtlText".
      • Context sensitive help does not work, please use help from the start menu "Start/Programs/Matrox Imaging/ActiveMIL/ActiveMIL Help".

      Bugs that occur at run-time:

      • ActiveMIL error messages cannot be retrieved using the Message property of the System.Runtime.InteropServices.COMException class.
      • All ActiveMIL controls created at run-time should be created on the same thread.

       

  4. Borland (Delphi / C++ Builder)

    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:

    1. Click Component | Import ActiveX Control.  Select all ActiveMIL controls.  Change the suggested name to T<MIL>Object (Many ActiveMIL control names clash with Borland name like System and TImage).  Important: the base controls (from MIL.OCX) must be imported last; the project will not compile if this procedure is not followed.
    2. Remove the Name property from all generated wrapper classes (if you don't do this and change the control's name in the object inspector, the environment will not change the name used in code).
    3. When setting object references (for example, Display.Image), you must use the right-hand-side's ControlInterface property.  For example, to change the image displayed, you would type:

    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;

     

    [Contents]


    Outstanding issues

    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.

    ActiveMIL Controls issues

    Documentation errata

  5. Other issues

    [Contents]