Matrox ActiveMIL 2.1 – Shipping Notes

May 3, 2000
Copyright © 2000 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 matching, blob analysis, gauging, OCR, and bar and matrix code recognition. OEMs and integrators use ActiveMIL to accelerate the development of machine vision, medical imaging, and image analysis applications.

Device-independent ActiveMIL uses the power of today's Intel CPUs incorporating MMX and SSE technologies if present or, if your application requires dedicated or additional processing power, ActiveMIL works with the Matrox Genesis family of image processors. ActiveMIL is completely compatible with the Matrox Imaging Library 6.1 (MIL). Both tools can be used in any applications, if required.

Contents

1. Getting Started

2. Supported Environments

3. What's New

4. What's Changed

5. Online Documentation
6. Deploying ActiveMIL Applications (Redistribution) 
7. Obtaining Additional Help
8. Environment Specific Notes
   1. Visual Basic
   2. Visual C++
   3. Borland (Delphi and C++ Builder)
9. Outstanding Issues

Getting Started

• Use the Intellicam interactive program to grab and experiment with your board before running the ActiveMIL examples.
• Run the ActiveMIL demos found under Start\Matrox Imaging Products\ActiveMIL\Demos.  These demos are free-running and show the basics of building an ActiveMIL application in Visual Basic.
• Run the examples by using the interactive example launcher found under Start\Matrox Imaging Products\ActiveMIL\ActiveMIL Examples. 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 to allow editing or viewing the code and controls in design-time. The system type, image sizes, digitizer (camera) and display formats that the examples use can all be changed interactively from within the example launcher, by clicking the "Change Property Defaults" button.

[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

*Other environments are not officially supported by Matrox.

**Multiple monitor windows desktop (multi-head) is not supported with Windows 98 or Window 2000 in this release.

Operating System / Matrox Imaging Hardware

Click on a board label in the table below to access board-specific release notes.  Links to board that have not been installed will not work.

*Matrox Pulsar-LC and Matrox Meteor are no longer supported.

[Contents]

What's New?

• All Controls

  All ActiveMIL controls now support dual interfaces, a technology that allows faster access to ActiveX controls.  This change is generally  transparent to the user.  Most of ActiveMIL's overhead is removed when access occurs through its dual interfaces.  See the environment specific notes below for more information.

  The ResultsModified event is fired when the results of a control are modified.

  The ShowPropertyPages method can be called at runtime to display a control's property pages.

  Delphi is now able to import all ActiveMIL controls without generating errors.  Custom wrapper classes from Matrox are no longer necessary.

   

• System Control

  UserBits property

  • When using a 4Sight, a collection of user bits is available.

  SSEEnabled property

  • This property gives control over the use of SSE opcodes to accelerate processing.

   

• Digitizer Control

  Control and Inquire methods

  • Support for native 1394 settings.

  Calibration property

  • This property is used to associate a Calibration control to the digitizer.

   

• Image Control

  CopyToClipboard and PasteFromClipboard methods

  • These methods allow easy access to the Windows clipboard.

  Picture property

  • This property exposes the image as a standard 'Picture' object, allowing better integration in Visual Basic.

  Load method

  • Calling this method with no filename will display a standard Windows open dialog box for selecting a filename.

  Calibration property

  • This property is used to associate a Calibration control to the image.

  CalibrationInfo property

  • This property is used to specify calibration information for the given image.

      

• Code Control

  CodeType property

  • Support for CODABAR, BC412, and PDF417.

  ErrorCorrectionType property

  • Support for ECC200 and reed solomon 0 to 8.

  DotSpacing property

  • New property used to specify the dot spacing for data matrix codes.

   

• Blob Analysis Control

  The amount of memory used for the result collection has been drastically reduced.  The access speed has also been increased dramatically.

  FillHoles, ExtractHoles, EraseBorderBlobs and Reconstruct methods

  • Lattice parameter that defaults to blob8Connected.

   

• Measurement Control

  Results.Orientation property.

  • This property now replaces the Results(Index).Orientation, Results(Index).Edge1.Orientation, and Results(Index).Edge2.Orientation properties.

   

• Image Processing Control

  ZoneOfInfluence method

  • The default DistanceTransform is now impChessBoard, which is faster than impChamfer34, which was the previous default value.

   

• Calibration Control

  This is a new control that exposes the advanced calibration functionality built into Matrox's imaging processing algorithms.  There is a new example called MCalibration that demonstrates the use of this control.

[Contents]

What's Changed?

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

• All Controls

  The 'm' prefix on all constants is replaced with a module specific prefix (in lowercase).  For example, mNormalized is now patNormalized.  The versions with 'm' prefixes still exsist, 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

  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) form: "MIL.Object".  For example, in VB, to create an Image control dynamically at runtime, you would pass the string "MIL.Image" to CreateObject.  Visual C++ users are not affected by this, unless they used the COM function CLSIDFromProgID. Note that the ActiveMIL add-in for VB will automatically change to the new form 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 can also be 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 refered to at runtime as always.

  In previous versions of ActiveMIL, properties that represent references to other 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 application code as setting either property will work.  For example, the following two statements are equivalent (the first form is faster, however):

  • Digitizer.Image = MyImage
  • Digitizer.ImageName = MyImage.Name

   

• System Control

  SystemType property modified for Meteor II product.

  • This property now returns "Meteor_II" and "Meteor_II_Dig" instead of "Meteor2" and "Meteor2Dig", repectively.

  BoardType property modified for Meteor II product

  • MeteorIIStd => Meteor_II_Std
  • MeteorIIMC => Meteor_II_MC
  • MeteorIIDig => Meteor_II_Dig
  • MeteorIIWithMJPEGModule => Meteor_II_WithCompressionModule
  • MeteorIIMCWithMJPEGModule => Meteor_II_MCWithCompressionModule

  GrabInDisplay.PseudoWhenOverlapped property

  • This property has been renamed to GrabInDisplay.PseudoLiveGrab.

   

• Measurement Control

  Results(Index).Orientation, Results(Index).Edge1.Orientation, Results(Index).Edge2.Orientation properties

  • These properties were removed and replaced with Results.Orientation property.

   

• Display Control

  DeviceNumber property

  • This property now defaults to the value of dispDefault.  Windowed displays do not require device numbers, so setting the device number to dispDefault is sufficient.

  Image property

  • Changing the image being displayed has been optimized.

   

• Digitizer Control

  SendTrigger method

  • This method now accepts a parameter to specify type of trigger to send (digGrabTrigger, digTimer1Trigger, digTimer2Trigger).  If the parameter is omitted, the method will use its old default (digGrabTrigger).

[Contents]

Online Documentation

Complete on-line documentation is provided with ActiveMIL. It can be found under Start\Matrox Imaging Products\ActiveMIL\ActiveMIL Help.  The documentation contains three 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 Control Reference contains detailed information on all properties, methods, and events of all ActiveMIL controls. Note that context sensitive jumps are available from all supported development environments to this section.
• Additional Information contains sections describing the document conventions, a glossary, and descriptions of available Matrox Imaging hardware products.

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) 

The following options are available to deploy applications that use ActiveMIL:

• Using the Master Setup's Redistribution option.
• Installing manually. Please refer to the file " \Matrox\mil\doc\redist.txt" on the original MIL/ActiveMIL CD for instructions.

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:

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

[Contents]

Environment Specific Notes

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

1. Visual Basic

   As described in What's Changed, the constants groups names' have changed.  This could affect your code if you Dim'ed variables as the group (i.e. Dim GrabMode As GrabModeConstants).  The 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 Dim'ed variables using 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 (i.e. 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 Dim as a variable of type I<control>, and set it equal to the Object property of an ActiveMIL control.  For example,

   Dim DirectDigtizer As MIL.IDigitizer

   Set DirectDigtizer = Digitizer1.Object ' assuming that 'Digitizer1' is on the form

    

2. Visual C++

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

   1. Using the ActiveMIL wrapper classes built by Matrox.

      This was the only method that could be used in previous versions.  This method should be used if  source-level compatibility is required with code written to previous versions of ActiveMIL.  This method does not use the fast dual interfaces.  When you use the 'Add ActiveMIL to Project' and select 'MFC class wizard classes' it this method that is used.  Currently, the examples are written using this method.

      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.

       

   2. Using native COM access classes.

      With this method, the built in support for COM is used in conjunction with the MFC ActiveX support. 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 will be mapped to _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 top level controls are also of type C<Control>, as with the wrapper classes discussed aboved.

      This access method has the following advantages over the others:

      • Fully exploits ActiveMIL's ultra-fast dual interfaces.
      • 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 (unlike the other access methods which make these items of type long).

       

   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. 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 versions 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 tag [VB] means the note only applies to Visual Basic and [VC] to Visual C++. 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.

• It may happen that the help window incorrectly believes it is maximized, and refuses to resize itself.
• If a pattern matching model is loaded from file, and it originated from a MIL or Inspector model with the number of occurrences set to "all", ActiveMIL will set the number of occurrences to 10.
• In the Image Control's FileInquire method, inquiring about the frame rate or aspect ratio of a file will result in a value truncated to the nearest integer value.
• The documentation incorrectly states that there is a property called MilID in the ImageProcessing's WarpLUT object (ImageProcessing.WarpParameters.WarpLUTs); this is not the case.

[Contents]