-------------------------------------------------------------------------------
Matrox Imaging Library (MIL) 10 SP4
Release Notes (lastminute)
October, 2020
(c) Copyright Matrox Electronic Systems Ltd., 1992-2020
-------------------------------------------------------------------------------
This file presents last minute information that did not make it into the
MIL help, except for last minute hardware-specific information.
For hardware-specific information, see the release note specific for your
driver. The information found in this file overrides your formally documented
material.
-------------------------------------------------------------------------------
Contents
1. Installation / Uninstallation
2. License generation
3. Mcode
3.1 McodeGrade
4. Mmod
4.1 Mmod can define a model from a graphic list
4.2 MmodFind
5. Mpat
5.1 Mpat can define a model from a graphic list
6. Mreg
6.1 Troubleshooting HDR
7. MIL_UNIQUE_ID can be used in C++ to manage the lifetime of a MIL_ID
8. Matrox Intellicam limitations
9. MilPerfViewer
10. Retrieving the serial numbers of the WIBU-Systems dongles
11. PDF MIL Release Notes
-------------------------------------------------------------------------------
1. Installation / Uninstallation
- Windows' automatic 8.3 file name creation needs to be enabled in order for
the MIL installer to access the temp folder when the user name contains a
space. This option allows Windows to create short file/folder name aliases
for ones with long names for programs, such as the MIL installer, that
don't support spaces in the file/folder names. Alternatively, the MIL
installer needs to run from a user account that belongs to the
administrators group and has no spaces in it. Note that the same applies
for uninstalling MIL.
-------------------------------------------------------------------------------
2. License generation
- Selecting "MIL development" as the "License Type" to "Generate" is not
supported. A MIL development license comes as a USB dongle included
in the MIL development package.
------------------------------------------------------------------------------
3. Mcode
3.1 McodeGrade
- McodeGrade can now also grade Data Matrix code types according to
the Semi T10-0701 specification. Although this has been documented
in the reference, it has yet to be documented in the user guide.
For technical code information, refer to "SEMI T10-0701 (Reapproved 0618)
Test Method for the Assessment of 2D Data Matrix Direct Mark Quality"
------------------------------------------------------------------------------
4. Mmod
Note, the information below has been added to the reference, but has not been
fully integrated into the user guide.
4.1 Mmod can define a model from a graphic list
- If you want to define a model from a rotated bounding box, you can now
draw a rotated rectangle in a 2D graphic list and pass that graphic
list to MbufSetRegion to associate it with the source image; then, call
MmodDefine with M_IMAGE as the model type, the source image buffer
as Param1, and M_DEFAULT for the remaining parameters. An error will be
generated if the ROI is only in raster format (M_RASTER) or a
non-rectangular shape.
4.2 MmodFind
- MmodFind now supports search regions at an angle
for M_SHAPE_CIRCLE, M_SHAPE_ELLIPSE, M_SHAPE_RECTANGLE
and M_SHAPE_SEGMENT. Regions at an angle can be set
using MmodControl with M_ANGLE_REGION, using MmodControl
with M_SEARCH_POSITION_FROM_GRAPHIC_LIST, or using a target
image buffer associated with a rectangular M_VECTOR ROI
(set with MbufSetRegion).
------------------------------------------------------------------------------
5. Mpat
Note, the information below has been added to the reference, but has not been
fully integrated into the user guide.
5.1 Mpat can define a model from a graphic list
- If you want to define a model from a rotated bounding box, you can now
draw a rotated rectangle in a 2D graphic list and pass that graphic
list to MbufSetRegion to associate it with the source image; then, call
MpatDefine with M_REGULAR_MODEL as the model type, the source image
buffer as Param1, and M_DEFAULT for the remaining parameters. An error
will be generated if the ROI is only in raster format (M_RASTER) or a
non-rectangular shape.
------------------------------------------------------------------------------
6. Mreg
6.1 Troubleshooting HDR
M_HDR_STATUS value below 1.0
-------------------------------
Problem
When reading the M_ HDR_STATUS value with MregGetResult, the value is
below 1.0. The ratio obtained represents the ratio of input images that
were successfully processed by Simple HDR.
Solution
When the result is below 1.0, this can mean one of the following issues:
1. The input images are not in the correct order. The input images need
to be added in the order of darkest details to the brightest details.
There are many ways to achieve this, which can be:
* Use a different exposure time from the first picture to the next,
starting with the longest exposure to the shortest exposure. This approach
is limited by the time available to take the necessary pictures.
* Use a different lighting level from the brightest to the darkest. In this
case, great attention must be paid to the shadows and reflections which can
reduce the quality of the HDR image.
* Use a different aperture from the largest aperture (smallest number) to
the smallest (largest number). This approach will cause variations in the
focal length. It will cause a blurriness in the resulting HDR image.
* Use a different ISO setting from the most sensitive (largest number) to
the least sensitive (smallest number). This approach will cause a varying
level of noise in the resulting HDR image.
2. The level of visible details is not consistent from one input image to
the next. For example, a series of images are taken of a checkerboard in
black and white. The images show a strong level of detail for blacks and
whites, with little detail in the shades of gray in between. This can cause
a difficulty in merging the middle images. This can be mitigated by adding
a reference gray scale in the image. This allows every input image to meet
the minimum level of detail to contribute.
3. The exposure steps are too short resulting in images that are very similar
to their neighbors. When this happens, the colors of the photographed object
can override the level of brightness perceived by Simple HDR, causing it to
mark some input images as bad. A less than perfect value can be acceptable in
this situation, since the next input images will probably be able to merge
correctly with the current HDR image. It becomes a problem when multiple
adjacent images have been rejected.
4. The exposure steps are too long resulting in images that have few details
in common. This will result in an HDR image that has no details in the
brightest area. When this happens, the subsequent input images will keep
failing until the end of the series is reached.
5. M_FUSION_LOW_THRESHOLD and M_FUSION_HIGH_THRESHOLD are too aggressive and
cause a loss of details. These values are meant to eliminate pixels with
incorrect values due to the design of the sensor or camera. This includes
saturated pixels that are saturated with too much light giving washed out
details (M_FUSION_HIGH_THRESHOLD). This also includes underexposed pixels
where the resulting value is more representative of the electrical noise
level than the amount of light received. These phenomena do not limit
themselves to the minimum and maximum values that the image buffer can hold;
it can be a range of values at both ends.
6. M_FUSION_COVERAGE is too high for the series of input images used. When
using more than 2 input images, we cannot expected the same merge area for
each image. The merge area will be smaller and move across the HDR image to
follow the progression from darkest details to the brightest. In this case,
it is best to set it to the minimum value that yields acceptable improvement
in the detail level of the HDR image.
Image status M_HDR_IMAGE_LIMITED_TO_SINGLE_COLOR
------------------------------------------------------------------
Problem
The number of colors in the current HDR image is reduced to a single color
within the merge area.
Possible solutions:
*Reduce the exposure step between input images to increase the size of the
merge area.
*Try less stringent values for M_FUSION_LOW_THRESHOLD, M_FUSION_HIGH_THRESHOLD.
Image status M_HDR_INSUFFICIENT_COLOR_DEPTH
---------------------------------------------------------
Problem
The number of colors available in the merge area of the added file is
insufficient.
Possible solutions:
*Improve the dynamic range of each input image by making sure that it uses the
full range of colors available with the image type used.
*Try less stringent values for M_FUSION_LOW_THRESHOLD, M_FUSION_HIGH_THRESHOLD.
Image status M_HDR_INSUFFICIENT_CONTRIBUTION
----------------------------------------------------------
Problem
The added image does not increase the dynamic range already present in the
current HDR image.
Possible solutions:
*Verify the order of the input images to make sure that they are in the proper
sequence.
*Increase the exposure step between the input images to better differentiate them.
*Add a color scale in the picture to provide a reference when the subject has
few colors that have a high contrast between them.
Image status M_HDR_MERGE_AREA_GAIN_INCORRECT
-------------------------------------------------------------
Problem
The gain to be applied to the input image is less than 1.
Possible solution:
*Verify the order of the input images to make sure that they are in the proper
sequence.
Image status M_HDR_MERGE_AREA_SIZE_INSUFFICIENT
--------------------------------------------------------------
Problem
The calculated common area where the pixel values are between M_FUSION_LOW_THRESHOLD
and M_FUSION_HIGH_THRESHOLD, on both the current HDR image and the image being added,
is below the threshold specified with M_FUSION_COVERAGE.
Possible solutions:
*Reduce the exposure step between each input image to increase the size of the merge
area.
*Improve the dynamic range of each input image by making sure that it uses the full
range of colors available with the image type used.
*Try less stringent values for M_FUSION_LOW_THRESHOLD, M_FUSION_HIGH_THRESHOLD and
M_FUSION_COVERAGE.
Blockiness appears in the resulting HDR image
---------------------------------------
Problem
When looking at the output image, black or white blocks can be seen in the image.
Solution
In the case of black boxes, the values M_FUSION_LOW_THRESHOLD and
M_TONE_MAPPING_LOW_THRESHOLD need to be validated. One of them could have a value
too high, causing the suppression of key pixels in the end result.
The M_FUSION_LOW_THRESHOLD value should only be high enough to eliminate noise on
black pixels in the input images.
In the case of white boxes, the values M_FUSION_HIGH_THRESHOLD and
M_TONE_MAPPING_HIGH_THRESHOLD need to be validated. One of them could have a value
too low, causing the suppression of key pixels in the end result.
The M_FUSION_LOW_THRESHOLD value should only be low enough to eliminate saturated
pixels in the input images.
The M_TONE_MAPPING_LOW_THRESHOLD and M_TONE_MAPPING_HIGH_THRESHOLD should only be
used to remove unneeded pixel intensity levels to provide a better intensity
resolution to the subject of the image.
Another potential cause for blockiness can occur with M_TONE_MAPPING_COEFFICIENT.
If the value used is too aggressive toward 0.0 or 1.0, blockiness can appear. This
is caused by the difference in intensity resolution between the source images and
the tone-mapped resulting image. For example, if an object in the image uses a range
of 40 shades of gray out a possible 256 (8bit) and gets mapped to a range of 160
shades of gray, the color transitions will look blocky due the increased step between
each color displayed. No post-processing is applied to the result to minimize this
effect within Simple HDR. Most likely, other details in the image will see their
intensity resolution compressed to make room, giving a "flat" appearance.
Darker areas look flat with few details.
---------------------------------------------
Problem
Darker areas in the image have significantly fewer details than expected along with
severe blocking and banding.
Solution
This situation is mainly caused by an incorrect order of the input images. The correct
order is starting with the picture where the darkest details are most defined to the
picture where the brightest details are most defined. In the case where the exposure
changes from one image to the next, the correct order is from the longest exposure to
the shortest exposure.
Resulting image is too dark or too bright
------------------------------------------
Problem
The resulting image is too dark or too bright.
Solution
M_TONE_MAPPING_COEFFICIENT controls the distribution of the pixel intensities during
the tone mapping between the HDR image and the end image. It can range from 0.0 to 1.0.
A higher value will lower the overall brightness by giving more intensity range to the
brighter details. A lower value will increase the overall brightness by giving more
intensity range to the darker details.
------------------------------------------------------------------------------
7. MIL_UNIQUE_ID can be used in C++ to manage the lifetime of a MIL_ID
- You can now pass M_UNIQUE_ID to the last parameter of any
M...Alloc function, instead of a pointer to a MIL_ID, to obtain a
MIL_UNIQUE_..._ID object instead of a MIL_ID as the return value.
MIL_UNIQUE_..._ID objects are available in C++ only, and are used to
manage the lifetime of a MIL_ID; the MIL_UNIQUE_..._ID object's
destructor will automatically call the appropriate M...Free function.
Each module has its own type of MIL_UNIQUE_..._ID, based on the name
of the module. For example:
- Mapp: MIL_UNIQUE_APP_ID
- Mbuf: MIL_UNIQUE_BUF_ID
- Mdig: MIL_UNIQUE_DIG_ID
- Mdisp: MIL_UNIQUE_DISP_ID
- M... : MIL_UNIQUE_..._ID
Each type is built from a class template call MIL_UNIQUE_ID, which
has an interface similar to that of the C++ std::unique_ptr. To see
the class definition and the overloads, you can look at the header
file directly (miluniqueid.h).
A MIL_UNIQUE_..._ID object can be passed to any function expecting a
MIL_ID.
------------------------------------------------------------------------------
8. Matrox Intellicam limitations
- When using Matrox Intellicam to grab images from a camera, the frame
rate displayed might be lower than the actual grab rate, especially
when grabbing at high frame rates. To obtain the grab rate, you should
grab into an image that does not have a display attribute.
Note that when grabbing into an image without a display attribute,
the frame rate might still be lower than the grab rate due to
limitations of the hardware being used.
- An exception can occur when using Matrox Intellicam with a Camera Link
camera accessed using the GenICam CLProtocol, and you try modifying the
DCF while the feature browser is open. To modify the DCF, ensure the
feature browser is not open.
- An exception can occur when using Matrox Intellicam with a GigE Vision
camera, and you try clicking on "Dump State to DCF" in the "Camera
Configuration" tab of the DCF. This occurs when one of the parameters is
bigger then 255 bytes (typically LUTs). To prevent the exception, delete
those parameters before saving the DCF.
-------------------------------------------------------------------------------
9. MilPerfViewer
- When using MilPerfViewer (Matrox Performance Monitor) under a non
US-English operating system, it is possible that you are not able to see
Matrox performance counters. In such cases, it is possible to use the
Microsoft PerfMon utility to see the Matrox performance counters.
------------------------------------------------------------------------------
10. Retrieving the serial number of a WIBU-Systems dongle
- To retrieve the serial number of the nth WIBU-Systems dongle, call
MappInquire with M_KEY_SERIAL_NUMBER + n, where n must be a number
within the following range: 0 <= n < MappInquire(M_NUMBER_OF_KEYS). MIL
returns the serial number as a string.
- M_NUMBER_OF_KEYS is an inquire type, in MappInquire, that returns the
number of keys detected.
-------------------------------------------------------------------------------
11. PDF MIL Release Notes
- If you are using the 64-bit version of Windows 7 with
Internet Explorer 10, you might encounter an issue that prevents you from
opening MIL Release Notes that redirect you to a PDF file. If this is the
case, try using a previous version of Internet Explorer (IE8 or IE9) or
contact Matrox Imaging support.