app

Mapp functions

Example | Availability
There are no examples containing app().
Available in MIL-Lite

Available in MIL
Synopsis
The functions prefixed with Mapp make up the Application module. The Application module allows you to initialize and control the execution environment for a MIL application. The module provides, among other things, integrated debugging services, a high-performance timer for benchmarking, portable threads and event handling, and automatic system resource compensation for processing and memory operations.
Functions
  • MappAlloc
  • MappAllocDefault
  • MappControl
  • MappFree
  • MappFreeDefault
  • MappGetError
  • MappGetHookInfo
  • MappHookFunction
  • MappInquire
  • MappTimer


MappAlloc

See Also | Example | Availability | MappAllocDefault
User Guide:
Allocating an application and its systems
Preparing for graphics
Multi-threading

Reference:
MappControl
MappFree
MappGetError
channel_switch.c
dtkobjecttracking.c
mdiggrabmultiple.c
mdigmultdestination.c
mdigmultformat.c
mdigprocessmultiple.c
mdispwindow.c
met2_1394serialbus.c
mgenlc.c
mmet2dig.c
muart.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Allocate a MIL application.
Syntax
MIL_ID MappAlloc(
long InitFlag,
MIL_ID *ApplicationIdPtr
)
Description

This function allocates a MIL application. A MIL application must be allocated prior to using any other MIL functions.

In multi-thread environments, if an application is allocated in the main thread, it is shared by all threads. When this is the case, Mapp...() function calls from any thread apply to all threads, unless specifically localized to that thread by specifying M_THREAD_CURRENT when calling the function. However, if a new MIL application is allocated within a thread, using MappAlloc(), this thread will be isolated from the shared application and all application controls and hooks will be independent. For example, turning off error printing in a secondary thread, using MappControl(), will not affect the printing of errors in the original shared application. Likewise, calling MappControl() with M_PRINT_DISABLE from the main thread, will not affect the application of a secondary thread. You must free the allocated application (MappFree()) in the thread in which it was allocated.

Note, upon the first allocation of a MIL application in a thread, a default system (M_SYSTEM_HOST) is automatically allocated. This default Host system can be used in MIL function calls by specifying M_DEFAULT_HOST wherever a system identifier is required.

In addition, a default graphics context is also allocated upon allocation of a MIL application. This default graphics context can be used in MIL graphic function calls by specifying M_DEFAULT wherever a graphics context identifier is required. In multi-thread applications, a default graphics context is allocated for each thread to avoid inter-thread interference.

Parameters
InitFlag

Specifies the type of initialization to perform on the MIL application. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default initialization. During the allocation of the application, reported error messages are displayed.  Specifies the default initialization ...

  Open   Collapse  M_QUIET

 Suppresses the displaying of error messages during the allocation of the application.  Suppresses the displaying of error messages during the allocation of the application.

 ApplicationIdPtr

 Specifies the address of the variable in which the application identifier is to be written.  Since the MappAlloc() function also returns the application identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier. After allocating an application, we recommend that you check if the operation was successful, using MappGetError(), or by verifying that the application identifier returned is not M_NULL.

Return value

 The returned value is the application identifier. If allocation fails, M_NULL is returned as the identifier.

THREAD CURRENT PRINT DISABLE SYSTEM HOST  DEFAULT QUIET


MappAllocDefault

See Also | Example | Availability | MappAlloc | MappControl
User Guide:
Before you start
Allocating an application and its systems
Allocating and displaying an image buffer
Grabbing images
Overview
Preparing for graphics
Cameras and video sources
Grabbing
Displaying

Reference:
MappAlloc
MappFreeDefault
MsysAlloc
dtkaddconstantmain.c
dtkremap.c
dtksyncasyncfunctionsmain.c
mappstart.c
mblob.c
mbufbayercolorfilter.c
mbufcolor.c
mcal.c
mcode.c
mdblgrab.c
mdigautofocus.c
mdigdoublebuffering.c
mdiggrab.c
mdiggrabsequence.c
mdighook.c
mdigprocess.c
mdigsubtract.c
mdispoverlay.c
mdispselect.c
mdispwindowleveling.c
medge.c
mfunc.c
mgbfocus.c
mgrabbayer.c
mheliosconcurent.c
mimconvolve.c
mimfft.c
mimhistogram.c
mimmorphic.c
mimperimeter.c
mimpolar.c
mimprocessing.c
mimsegment.c
mimwarp.c
mmeas.c
mmod.c
mmodeltracking.c
mmorphisjpeg2000.c
mnatfct.c
mnatgen.c
mocr.c
mpat.c
mstr.c
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Allocate default MIL objects.
Syntax
void MappAllocDefault (
long InitFlag,
MIL_ID *ApplicationIdPtr,
MIL_ID *SystemIdPtr,
MIL_ID *DisplayIdPtr,
MIL_ID *DigIdPtr,
MIL_ID *ImageBufIdPtr
)
Description

MappAllocDefault() is implemented as a macro. This macro can allocate and set up the requested MIL objects using the defaults specified during allocation and using MILConfig. This macro can allocate and initialize a MIL application, and allocate the default MIL system. On this system, it can allocate the default digitizer and display, and allocate and clear a default displayable image buffer.

The installation customizes the default setup. After installation, if you want to review or change the default settings of MappAllocDefault(), use MilConfig.

Note, if allocating the default digitizer and the default DCF, selected using MilConfig, is for a 3-band color (RGB) camera, then the default image buffer will be 3-band if allocated; otherwise, it will be 1-band if allocated. The size of a default image buffer, unless the user specifies, is 640 x 480, in pixels.

Note, upon execution of this function, a default graphics context is automatically allocated. This default graphics context can be used in MIL function calls by specifying M_DEFAULT wherever a graphics context identifier is required.

When you have finished using the allocated MIL objects, you must free them using MappFreeDefault(). With multiple threads, you must free the allocated application (using MappFreeDefault()) in the thread in which it was allocated.

Parameters
InitFlag

Specifies the type of initialization setup to perform and is used principally to initialize the default system. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_COMPLETE

 Performs a complete initialization of the MIL environment: initializes MIL to its default state and downloads on the default system any required resident software. At least one complete initialization is necessary after you power-up your system.  Performs a complete initialization of the MIL environment: initializes MIL to its default state and downloads on the default system any required resident software ...

  Open   Collapse  M_PARTIAL

 Initializes MIL to its default state, but does not download any resident software on the default system.  Initializes MIL to its default state, but does not download any resident software on the default system ...

M_PARTIAL should only be selected if the required resident software has already been downloaded. This option is particularly useful when debugging since resident software generally needs to be downloaded once after power-up (or rebooting the system) and the downloading process can take a substantial amount of initialization time on certain systems.

  Open   Collapse  M_SETUP

 Sets InitFlag to one of the above, based on the default state requested during installation or using MilConfig.  Sets InitFlag to one of the above, based on the default state requested during installation or using MilConfig.

 ApplicationIdPtr

 Specifies the address of the variable in which to write the application identifier.  Upon execution of this function, the application is allocated and its identifier returned. Instead of using MappAllocDefault(), you can use MappAlloc() to allocate an application. Note, an application must be allocated in order to allocate any other object in MIL.

 SystemIdPtr

 Specifies the address of the variable in which to write the system identifier.  Upon execution of this function, the default system is allocated and its identifier returned. Instead of using MappAllocDefault(), you can use MsysAlloc() to allocate a system. MappAlloc() will also allocate a default Host system. Note, a system must be allocated in order to allocate any other objects on it (display, digitizer or data buffers).

 DisplayIdPtr

 Specifies the address of the variable in which to write the identifier of the default display.  If this parameter is set to M_NULL, a display is not allocated; otherwise, the default display is allocated and its identifier returned.

 DigIdPtr

 Specifies the address of the variable in which to write the identifier of the default digitizer.  If this parameter is set to M_NULL, a digitizer is not allocated; otherwise, the default digitizer is allocated and its identifier returned.

 ImageBufIdPtr

 Specifies the address of the variable in which to write the identifier of the default image buffer.  If this parameter is set to M_NULL, an image buffer is not allocated; otherwise, the default image buffer is allocated and its identifier returned. It is then cleared and displayed on the system's display screen.

Examples

 For example, a typical setup for Matrox Odyssey board in its power-up state with one input device (RS-170 camera) and one default image buffer (full-screen size) selected on the default display is:

MappAllocDefault(M_COMPLETE, &Application, &System, &Display, &Digitizer, &ImageBuffer);

 If, for example, you don't need to acquire data from the camera but want to perform the rest of the above setup, you would make the following call:

MappAllocDefault(M_COMPLETE, &Application, &System, &Display, M_NULL, &ImageBuffer);

PARTIAL  COMPLETE  PARTIAL  SETUP


MappControl

See Also | Example | Availability | MappAllocDefault | MappFree
User Guide:
Error reporting

Reference:
MappGetError
mdiggrabsequence.c
mdighook.c
mdigprocess.c
mdigprocessmultiple.c
mdispoverlay.c
mgbfocus.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Control an application environment setting.
Syntax
void MappControl (
long ControlType,
long ControlValue
)
Description

This function controls the settings of a MIL application environment. These setting include printing error messages, function, and function parameters to the screen, parameter checking, as well as on-board memory and processing compensation modes.

In multi-thread environments, an MappControl() call applies to all application threads running MIL, unless specifically limited to the calling thread by adding M_THREAD_CURRENT to the ControlType parameter. When you override settings for a specific thread, a subsequent call to change those settings from any other thread will not change the settings. For example, if you enable trace printing for a particular thread, that thread will ignore calls from other threads that try to change trace printing setting. Note that any thread created by the current thread will utomatically inherit all the current thread's settings, but it will not inherit this exclusivity.

Parameters
ControlType

Specifies the type of application environment setting to control.

See the Parameter associations section for possible values.

ControlValue

Specifies the setting's new value.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_ERROR |  | Sets whether the printing of error messages to screen is enabled. Sets whether the printing of error messages to screen is enabled ...
 | M_PRINT_DISABLE | Disables printing of error messages. If error printing is disabled, you can still check for error, using MappGetError().
 | M_PRINT_ENABLE | Enables printing of error messages. This is the default value.
Open Collapse M_MEMORY |  | Sets whether on-board memory compensation on the Host is enabled. On-board memory compensation allows memory to be allocated on Host when a system has insufficient memory to perform that memory allocation. Sets whether on-board memory compensation on the Host is enabled ...
 | M_COMPENSATION_DISABLE | Disables on-board memory compensation. If the memory available is insufficient for the allocation, an error is generated.
 | M_COMPENSATION_ENABLE | Enables on-board memory compensation. This is the default value.
Open Collapse M_PARAMETER |  | Sets whether the checking of parameters is enabled. Sets whether the checking of parameters is enabled ...
 | M_CHECK_DISABLE | Disables checking of parameters. Note, if parameter checking is disabled (for example, to accelerate an application), unpredictable behavior can be expected when passing invalid parameters to a function.
 | M_CHECK_ENABLE | Enables checking of parameters. This is the default value.
Open Collapse M_PROCESSING |  | Sets whether the Host should compensate for processes that cannot be performed on-board due to board-specific limitations. Sets whether the Host should compensate for processes that cannot be performed on-board due to board-specific limitations ...
 | M_COMPENSATION_DISABLE | Disables on-board processing compensation. If an operation cannot be performed by the system's on-board processor, an error is generated.
 | M_COMPENSATION_ENABLE | Enables on-board processing compensation. If an operation cannot be performed by the system's on-board processor, it will be performed by the Host. This is the default value.
Open Collapse M_TRACE |  | Sets whether the printing of function names and parameters is enabled. When trace printing is enabled, a pop-up window containing this information appears at the start and end of each MIL function executed. Note that, if enabled, this ControlValue is synchronous. Sets whether the printing of function names and parameters is enabled ...
 | M_PRINT_DISABLE | Disables printing of function names and parameters. This is the default value.
 | M_PRINT_ENABLE | Enables printing of function names and parameters.

[Combination constants]

The value below can be added to the ControlType parameter.

Open Collapse Value Description
Open Collapse M_THREAD_CURRENT

 Limits the effect of the ControlType setting to the current thread.  Limits the effect of the ControlType setting to the current thread.

THREAD CURRENT   ERROR PRINT DISABLE
                      PRINT ENABLE MEMORY  COMPENSATION DISABLE
                      COMPENSATION ENABLE
                      PARAMETER CHECK DISABLE
                      CHECK ENABLE
                      PROCESSING COMPENSATION DISABLE
                      COMPENSATION ENABLE
                      TRACE PRINT DISABLE
                      PRINT ENABLE
                      THREAD CURRENT


MappFree

See Also | Example | Availability | MappControl | MappFreeDefault
User Guide:
Allocating an application and its systems

Reference:
MappAlloc
MappAllocDefault
MappFreeDefault
channel_switch.c
dtkobjecttracking.c
mdiggrabmultiple.c
mdigmultformat.c
mdigprocessmultiple.c
mdispwindow.c
met2_1394serialbus.c
mgenlc.c
mmet2dig.c
muart.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Free a MIL application.
Syntax
void MappFree (
MIL_ID ApplicationId
)
Description

This function deallocates a MIL application previously allocated with MappAlloc().

When freeing a MIL application, you must free it in the thread in which it was allocated. Also, in a given thread, MappFree() must be the last MIL function called; no other MIL function can be executed in a thread after a call to this function. Prior to freeing a MIL application, ensure that all systems, buffers, displays, and digitizers allocated in the thread are freed.

Note, if you use MappAllocDefault() to allocate the default MIL application, you must use MappFreeDefault() to free the application.

Parameter
ApplicationId

Specifies the application to free.


MappFreeDefault

See Also | Example | Availability | MappFree | MappGetError
User Guide:
Allocating an application and its systems

Reference:
MappAllocDefault
dtkaddconstantmain.c
dtkremap.c
dtksyncasyncfunctionsmain.c
mappstart.c
mblob.c
mbufbayercolorfilter.c
mbufcolor.c
mcal.c
mcode.c
mdblgrab.c
mdigautofocus.c
mdigdoublebuffering.c
mdiggrab.c
mdiggrabsequence.c
mdighook.c
mdigprocess.c
mdigsubtract.c
mdispoverlay.c
mdispselect.c
mdispwindowleveling.c
medge.c
mfunc.c
mgbfocus.c
mgrabbayer.c
mheliosconcurent.c
mimconvolve.c
mimfft.c
mimhistogram.c
mimmorphic.c
mimperimeter.c
mimpolar.c
mimprocessing.c
mimsegment.c
mimwarp.c
mmeas.c
mmod.c
mmodeltracking.c
mmorphisjpeg2000.c
mnatfct.c
mnatgen.c
mocr.c
mpat.c
mstr.c
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Free default MIL objects.
Syntax
void MappFreeDefault (
MIL_ID ApplicationId,
MIL_ID SystemId,
MIL_ID DisplayId,
MIL_ID DigId,
MIL_ID ImageBufId
)
Description

MappFreeDefault() is implemeted as a macro. This macro frees the default MIL objects that were allocated with the MappAllocDefault() macro. You must free the allocated application (MappAllocDefault()) in the thread in which it was allocated.

Parameters
ApplicationId

Specifies the identifier of the application to free.

SystemId

Specifies the identifier of the system to free.

DisplayId

Specifies the identifier of the display to free. If set to M_NULL, no display is freed.

DigId

Specifies the identifier of the digitizer to free. If set to M _NULL, no digitizer is freed.

ImageBufId

Specifies the identifier of the image buffer to free. If set to M_NULL, no buffer is freed.


MappGetError

See Also | Example | Availability | MappFreeDefault | MappGetHookInfo
User Guide:
Error reporting
Multi-threading

Reference:
MappControl
MbufAlloc1d
MbufAlloc2d
MbufAllocColor
mappstart.c
mgbfocus.c
mmodeltracking.c
mpat.c
Available in MIL-Lite

Available in MIL
Synopsis
Get error codes and related information.
Syntax
long MappGetError (
long ErrorType,
void *ErrorPtr
)
Description

This function obtains current or global application error codes, subcodes, messages, submessages, function codes, and function names. This function allows you to check for errors after each MIL function call or to get the first error that occurred after a series of MIL function calls.

A typical use of this function is to check whether a buffer allocation call was successful (MbufAllocColor(), MbufAlloc1d(), and MbufAlloc2d()) or to see if a function returns an error.

This function can also be used to obtain information about a detected error when error-reporting to the screen has been disabled using MappControl().

Parameters
ErrorType

Specifies the type of error information to read. This parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the ErrorPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_CURRENT | Returns the error code returned by the last function call. The current-error code is reset to M_NULL_ERROR before each MIL function call and is set to a specific error code when an error occurs during the execution of a function. Returns the error code returned by the last function call ...
Open Collapse M_CURRENT_FCT | Returns the unique value associated with the last function called, when it returns an error. Returns the unique value associated with the last function called, when it returns an error.
Open Collapse M_CURRENT_SUB_1 | Returns the first error subcode returned by the last function call. Returns the first error subcode returned by the last function call ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_CURRENT_SUB_2 | Returns the second error subcode returned by the last function call. Returns the second error subcode returned by the last function call ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_CURRENT_SUB_3 | Returns the third error subcode returned by the last function call. Returns the third error subcode returned by the last function call ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_CURRENT_SUB_NB | Returns the number of error subcodes associated with the last function called, when it returns an error. Returns the number of error subcodes associated with the last function called, when it returns an error.
Open Collapse M_GLOBAL | Returns the error code of the first error that has occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL). This value is reset to M_NULL_ERROR after each MappGetError() call with this setting. Returns the error code of the first error that has occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL) ...
Open Collapse M_GLOBAL_FCT | Returns the unique value associated with the first error-generating function since the last call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the unique value associated with the first error-generating function since the last call to MappGetError() (with ErrorType set to M_GLOBAL).
Open Collapse M_GLOBAL_SUB_1 | Returns the first error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the first error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL) ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_GLOBAL_SUB_2 | Returns the second error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the second error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL) ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_GLOBAL_SUB_3 | Returns the third error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the third error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL) ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_GLOBAL_SUB_NB | Returns the number of error subcodes associated with the first error that occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the number of error subcodes associated with the first error that occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL).

[Combination constants]

The following value can be added to all the ErrorType parameters except M_CURRENT_SUB_NB and M_GLOBAL_SUB_NB:

Open Collapse Value | Description
Open Collapse M_MESSAGE | Writes the error message associated with the specified error type, or the function name associated with a function code, to the address specified by the ErrorPtr parameter. The error/function code is still returned by MappGetError(), but it is not written to the address specified by ErrorPtr. Writes the error message associated with the specified error type, or the function name associated with a function code, to the address specified by the ErrorPtr parameter ...
 |  | ErrorPtr info Data type: array of type MIL_TEXT_CHAR Array size: When reporting an error message or function name, the array must be at least M_ERROR_MESSAGE_SIZE (128) characters in size.

[Combination constants]

In multi-thread environments, an MappGetError() call returns information either with the first error-returning function of the current thread or, if there no errors in the current thread, it checks for errors in the other MIL running threads. To return only errors in the current thread, add the following value to the ErrorType parameter:

Open Collapse Value | Description
Open Collapse M_THREAD_CURRENT | Returns only errors in the current thread. Returns only errors in the current thread.

[Combination constants]

The following value can be added to all the ErrorType parameters.

Open Collapse Value | Description
Open Collapse M_SYNCHRONOUS | Forces the function to wait for all pending calls to complete before continuing. Forces the function to wait for all pending calls to complete before continuing.
ErrorPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type MIL_TEXT_CHAR
  • long

Specifies the address in which to write the requested information.

The MappGetError() function also returns the error/function code; if you don't want to get an error message or function name, you can set this parameter to M_NULL.

Return value
The returned value is the requested error/function code. If the error code is read and it is equal to M_NULL_ERROR, no error has occurred.
GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL CURRENT SUB NB GLOBAL SUB NB CURRENT CURRENT FCT CURRENT SUB 1 CURRENT SUB 2 CURRENT SUB 3 CURRENT SUB NB GLOBAL GLOBAL FCT GLOBAL SUB 1 GLOBAL SUB 2 GLOBAL SUB 3 GLOBAL SUB NB MESSAGE THREAD CURRENT SYNCHRONOUS


MappGetHookInfo

See Also | Example | Availability | MappGetError | MappHookFunction
Reference:
MappGetError
MappHookFunction
There are no examples containing MappGetHookInfo().
Available in MIL-Lite

Available in MIL
Synopsis
Get information about a hooked event.
Syntax
long MappGetHookInfo (
MIL_ID EventId,
long InfoType,
void *UserVarPtr
)
Description

This function retrieves information about the event that caused the hook-handler function to be called. This function should only be called within the scope of an application hook-handler function call (see MappHookFunction()).

Note that functions hooked to an event execute on a distinct thread. This permits the functions to run asynchronously from the operation that fired the event and from functions hooked to other events. Although there is a small queue to permit a certain amount of overlap, hooked functions should not take longer to execute than the period in which two of their associated events can occur. You cannot determine the instance of the event that fired the function, and even if this were possible, this information would generally not be very useful. Typically, a hooked function performs the minimum number of operations required and, if necessary, performs longer processes by launching other threads.

Parameters
EventId

Specifies the application event identifier received by the hook-handler function. See MappHookFunction() for more information.

InfoType

Specifies the type of information to get.

If the hook-handler function was called due to an M_ERROR_CURRENT event type, the InfoType parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_CURRENT | Returns the error code returned by the last function call. The current-error code is reset to M_NULL_ERROR before each MIL function call and is set to a specific error code if an error occurs while trying to execute the function. Returns the error code returned by the last function call ...
Open Collapse M_CURRENT_SUB_1 | Returns the first error subcode returned by the last function call. Returns the first error subcode returned by the last function call ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_CURRENT_SUB_2 | Returns the second error subcode returned by the last function call. Returns the second error subcode returned by the last function call ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_CURRENT_SUB_3 | Returns the third error subcode returned by the last function call. Returns the third error subcode returned by the last function call ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_CURRENT_SUB_NB | Returns the number of error subcodes associated with the last function called, when it returns an error. Returns the number of error subcodes associated with the last function called, when it returns an error.

If the hook-handler function was called due to an M_ERROR_GLOBAL event type, the InfoType parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_GLOBAL | Returns the error code of the first error that has occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL). This value is reset to M_NULL_ERROR after each MappGetError() call with this setting. Returns the error code of the first error that has occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL) ...
Open Collapse M_GLOBAL_FCT | Returns the unique value associated with the first error-generating function since the last call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the unique value associated with the first error-generating function since the last call to MappGetError() (with ErrorType set to M_GLOBAL).
Open Collapse M_GLOBAL_SUB_1 | Returns the first error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the first error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL) ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_GLOBAL_SUB_2 | Returns the second error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the second error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL) ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_GLOBAL_SUB_3 | Returns the third error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the third error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL) ... Note, when there is no error, the error subcode is set to M_NULL_ERROR.
Open Collapse M_GLOBAL_SUB_NB | Returns the number of error subcodes associated with the first error that occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL). Returns the number of error subcodes associated with the first error that occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL).

If the hook-handler function was called due to an M_ERROR_CURRENT, M_TRACE_START, or M_TRACE_END event type, the InfoType parameter can be set to the value below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_CURRENT_FCT | Returns the unique value associated to the last function called when it returns an error (for M_ERROR_CURRENT), just started (for M_TRACE_START), or just ended (for M_TRACE_END). Returns the unique value associated to the last function called when it returns an error (for M_ERROR_CURRENT), just started (for M_TRACE_START), or just ended (for M_TRACE_END).

If the hook-handler function was called due to an M_TRACE_START or M_TRACE_END event type, the InfoType parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_PARAM_NB

Returns the number of parameters associated with the MIL function called. Returns the number of parameters associated with the MIL function called.

Open Collapse M_PARAM_TYPE

Returns the data type of the specified parameter of the MIL function called. Returns the data type of the specified parameter of the MIL function called ...

UserVarPtr info

Return values:
M_TYPE_ARRAY_ID_PTR | The specified parameter is an array of type MIL_ID. Note that this data type is invalid after exiting the hook-handler function. For future use, copy and save it.
M_TYPE_CHAR | The specified parameter is of type char.
M_TYPE_DOUBLE | The specified parameter is of type double.
M_TYPE_FILENAME | The specified parameter is of type filename. Note that this data type is invalid after exiting the hook-handler function. For future use, copy and save it.
M_TYPE_INT64 | The specified parameter is of type integer.
M_TYPE_LONG | The specified parameter is of type long.
M_TYPE_MIL_ID | The specified parameter is of type MIL_ID.
M_TYPE_PTR | The specified parameter is a pointer. Note that this data type is invalid after exiting the hook-handler function. For future use, copy and save it.
M_TYPE_SHORT | The specified parameter is of type short.
M_TYPE_STRING | The specified parameter is an array of type MIL_TEXT_CHAR. Note that this data type is invalid after exiting the hook-handler function. For future use, copy and save it.
Open Collapse M_PARAM_VALUE

Returns the value of the specified parameter of the MIL function called. Returns the value of the specified parameter of the MIL function called ...

UserVarPtr info

Data type:

  • long
  • short
  • char
  • double
  • MIL_ID
  • MIL_INT64
  • MIL_TEXT_PTR
  • void pointer

[Combination constants]

The following must be added to M_PARAM_TYPE and M_PARAM_VALUE:

Open Collapse Value | Description
Open Collapse Value >= 1 | Specifies the number of the parameter for which to retrieve the information. This value must be a positive integer, and should not exceed the number of parameters associated with the MIL function call (M_PARAM_NB). Specifies the number of the parameter for which to retrieve the information ...

[Combination constants]

The value below can be added to all the above values, except: M_CURRENT_SUB_NB, M_GLOBAL_SUB_NB, M_PARAM_NB, M_PARAM_TYPE, and M_PARAM_VALUE.

Open Collapse Value | Description
Open Collapse M_MESSAGE | Returns the error message instead of the error code, or the function name instead of the function code. Returns the error message instead of the error code, or the function name instead of the function code ...
 |  | UserVarPtr info Data type: array of type MIL_TEXT_CHAR Array size: The array must be at least M_ERROR_MESSAGE_SIZE (128) characters in size.
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type MIL_TEXT_CHAR
  • char
  • double
  • long
  • short
  • MIL_ID
  • MIL_INT64
  • MIL_TEXT_PTR
  • a pointer of type void

Specifies the address in which to write the requested information. Note that, when getting parameter values (MappGetHookInfo() with M_PARAM_VALUE), the UserVarPtr parameter should be of the same data type as value of the selected parameter.

Return value
The returned value is M_NULL if successful; a non M_NULL value on error, without logging any errors in the application.
ERROR CURRENT ERROR GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL ERROR CURRENT TRACE START TRACE END ERROR CURRENT TRACE START TRACE END TRACE START TRACE END PARAM TYPE PARAM VALUE PARAM NB CURRENT SUB NB GLOBAL SUB NB PARAM NB PARAM TYPE PARAM VALUE PARAM VALUE CURRENT CURRENT SUB 1 CURRENT SUB 2 CURRENT SUB 3 CURRENT SUB NB GLOBAL GLOBAL FCT GLOBAL SUB 1 GLOBAL SUB 2 GLOBAL SUB 3 GLOBAL SUB NB CURRENT FCT PARAM NB PARAM TYPE PARAM VALUE MESSAGE


MappHookFunction

See Also | Example | Availability | MappGetHookInfo | MappInquire
User Guide:
Error reporting

Reference:
MappGetError
MappGetHookInfo
There are no examples containing MappHookFunction().
Available in MIL-Lite

Available in MIL
Synopsis
Hook a function to an event.
Syntax
void MappHookFunction(
long HookType,
MAPPHOOKFCTPTR HookHandlerPtr,
void *UserDataPtr
)
Description

This function allows you to attach or detach a user-defined function to a specified application event. Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.

Note that functions hooked to an event execute on a distinct thread. This permits the functions to run asynchronously from the operation that fired the event and from functions hooked to other events. Although there is a small queue to permit a certain amount of overlap, hooked functions should not take longer to execute than the period in which two of their associated events can occur. You cannot determine the instance of the event that fired the function, and even if this were possible, this information would generally not be very useful. Typically, a hooked function performs the minimum number of operations required and, if necessary, performs longer processes by launching other threads.

You can hook more than one function to an event by making separate calls to MappHookFunction() for each function that you want to hook. MIL automatically chains and keeps an internal list of all these hooked functions. When a function is hooked, this new function is added to the end of the list. When the event happens, all user-defined functions in the list will be executed in the same order that they were hooked to the event. You can also remove any function from the list; in this case, MIL preserves the order of the remaining functions in the list.

You can obtain information concerning the event, using MappGetHookInfo(), and take appropriate action before returning control to the application.

In multi-thread environments, an MappHookFunction() call hooks or unhooks the function specified by HookHandlerPtr to all application threads running MIL, unless specifically limited to the calling thread.

This function is typically used to trap errors that occur in an application, without checking every MIL function execution with MappGetError(), or to detect the start or end of certain MIL functions.

Parameters
HookType

Specifies the event type. This parameter can be set to one of the following values.

Open Collapse Value Description
Open Collapse M_ERROR_CURRENT

 Calls the hook-handler function each time an error occurs.  Calls the hook-handler function each time an error occurs ...

 Note that you could end up with infinite recursion if the MIL function generating an error is called within the hook function.

  Open   Collapse  M_ERROR_FATAL

 Calls the hook-handler function before a fatal-error occurs.  Calls the hook-handler function before a fatal-error occurs.

  Open   Collapse  M_ERROR_GLOBAL

 Calls the hook-handler function when the first error occurs in a series of MIL calls.  Calls the hook-handler function when the first error occurs in a series of MIL calls ...

 Note that you could end up with infinite recursion if the MIL function generating an error is called within the hook function.

  Open   Collapse  M_TRACE_END

 Calls the hook-handler function at the end of each MIL function.  Calls the hook-handler function at the end of each MIL function ...

 When setting the HookType parameter to M_TRACE_END, the only MIL function that can be called in a hook function is MappGetHookInfo(), otherwise infinite recursion will occur.

  Open   Collapse  M_TRACE_START

 Calls the hook-handler function at the start of each MIL function.  Calls the hook-handler function at the start of each MIL function ...

 When setting the HookType parameter to M_TRACE_START, the only MIL function that can be called in a hook function is MappGetHookInfo(), otherwise infinite recursion will occur.

      [Combination constants]

 The value below can be added to the HookType parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_UNHOOK

 Detaches (that is, unhooks) the hook-handler function.  Detaches (that is, unhooks) the hook-handler function.

      [Combination constants]

 You can use MappHookFunction() to hook or unhook the function to application threads running MIL. To do so, add the value below to the HookType parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_THREAD_CURRENT

 Limits the hooking or unhooking of the function to the calling thread. For example, to call the hook-handler function only for errors occurring in the current thread, specify M_ERROR_CURRENT + M_THREAD_CURRENT as the HookType parameter.  Limits the hooking or unhooking of the function to the calling thread ...

 HookHandlerPtr

 Specifies the address of the function that should be called when an event occurs.

 The hook-handler function, pointed to by HookHandlerPtr, must be declared as follows:

long MFTYPE HookHandler(
long HookType,

MIL_ID EventId,

void MPTYPE *UserDataPtr

        )

HookType

 Type of event hooked.

EventId

 Event identifier to pass to MappGetHookInfo() when inquiring about the hooked event.

UserDataPtr

 Specifies the user data pointer passed to MappHookFunction().

 Upon successful completion, the hook-handler function should return M_NULL. Note, MFTYPE and MAPPHOOKFCTPTR are reserved MIL predefined types for functions and data pointers, respectively.

 UserDataPtr

 Specifies the address of the user data that you want to make available to the hook-handler function.  This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if user data is not required.

Return value

 The original prototype of this function has been kept for backwards compatibility. However, because of the current chaining method, the function always returns null.

TRACE END TRACE START ERROR CURRENT THREAD CURRENT  ERROR CURRENT  ERROR FATAL ERROR GLOBAL TRACE END TRACE START UNHOOK THREAD CURRENT


MappInquire

See Also | Example | Availability | MappHookFunction | MappTimer
User Guide:
Protecting your own MIL software application using a Matrox hardware fingerprint

Reference:
MsysAlloc
mdiggrabsequence.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Orion
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Inquire about an application setting.
Syntax
long MappInquire (
long InquireType,
void *UserVarPtr
)
Description

This function inquires about the specified application setting.

Parameters
InquireType

Specifies the type of application setting about which to inquire. This parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_CURRENT_APPLICATION

Returns the identifier of the current MIL application, if any. Returns the identifier of the current MIL application, if any ...

UserVarPtr info

Data type: MIL_ID

Return values:
MIL application identifier | Identifier of current MIL application.
0 | No application is allocated. Note that no error is generated.
Open Collapse M_ERROR

Returns the error printing mode. Returns the error printing mode ...

UserVarPtr info

Return values:
M_PRINT_DISABLE, M_PRINT_ENABLE (details)
Open Collapse M_INSTALLED_SYSTEM_COUNT

Returns the number of different system types installed (during MIL installation). Returns the number of different system types installed (during MIL installation).

Open Collapse M_INSTALLED_SYSTEM_DESCRIPTOR + n

Returns the descriptor of system type n, where n is a number between 0 and the value returned by M_INSTALLED_SYSTEM_COUNT. The descriptor can be passed to MsysAlloc() to allocate the system. Returns the descriptor of system type n, where n is a number between 0 and the value returned by M_INSTALLED_SYSTEM_COUNT ...

UserVarPtr info

Data type: array of type MIL_TEXT_CHAR
Array size: The size of the array must be large enough to store the entire system descriptor.

Return values:
M_SYSTEM_CORONA_II, M_SYSTEM_CRONOSPLUS, M_SYSTEM_DEFAULT, M_SYSTEM_GENESIS, M_SYSTEM_HELIOS, M_SYSTEM_HOST, M_SYSTEM_IRIS, M_SYSTEM_METEOR_II, M_SYSTEM_METEOR_II_1394, M_SYSTEM_METEOR_II_CL, M_SYSTEM_METEOR_II_DIG, M_SYSTEM_MORPHIS, M_SYSTEM_ODYSSEY, M_SYSTEM_ORION, M_SYSTEM_SOLIOS (details)
Open Collapse M_INSTALLED_SYSTEM_DESCRIPTOR_SIZE

Returns the size of the descriptor string of a system; use M_INSTALLED_SYSTEM_DESCRIPTOR + n to get the descriptor string of system type n. Returns the size of the descriptor string of a system; use M_INSTALLED_SYSTEM_DESCRIPTOR + n to get the descriptor string of system type n.

Open Collapse M_INSTALLED_SYSTEM_PRINT_NAME + n

Returns a string with the printable name of the system type (for example, Matrox Helios). Returns a string with the printable name of the system type (for example, Matrox Helios) ...

UserVarPtr info

Data type: array of type MIL_TEXT_CHAR
Array size: The size of the array must be large enough to store the entire printable name of the system.

Open Collapse M_INSTALLED_SYSTEM_PRINT_NAME_SIZE

Returns the size of the printable name of a system; use M_INSTALLED_SYSTEM_PRINT_NAME + n to get the printable name of the system type n. Returns the size of the printable name of a system; use M_INSTALLED_SYSTEM_PRINT_NAME + n to get the printable name of the system type n.

Open Collapse M_LICENSE_MODULES

Returns the modules for which there is a valid license. The value returned will be a bitwise combination of the following. Returns the modules for which there is a valid license. The value returned will be a bitwise combination of the following ...

UserVarPtr info

Return values:
M_LICENSE_BLOB | Blob analysis license.
M_LICENSE_CAL | Calibration license.
M_LICENSE_CODE | Code read/write license.
M_LICENSE_DEBUG | Debugger license.
M_LICENSE_EDGE | Edge Finder license.
M_LICENSE_IM | Image processing license.
M_LICENSE_JPEG2000 | JPEG2000 license.
M_LICENSE_JPEGSTD | JPEG license.
M_LICENSE_LITE | MIL-Lite license.
M_LICENSE_MEAS | Measurement license.
M_LICENSE_MOD | Model Finder license.
M_LICENSE_OCR | OCR license.
M_LICENSE_PAT | Pattern matching license.
M_LICENSE_STR | String Reader license
Open Collapse M_MEMORY

Returns the memory compensation mode. Returns the memory compensation mode ...

UserVarPtr info

Return values:
M_COMPENSATION_DISABLE, M_COMPENSATION_ENABLE (details)
Open Collapse M_NON_PAGED_MEMORY_FREE

Returns the amount of free non-paged memory, in bytes. Returns the amount of free non-paged memory, in bytes.

Open Collapse M_NON_PAGED_MEMORY_SIZE

Returns the amount of the non-paged memory (DMA) reserved for MIL, in bytes. Returns the amount of the non-paged memory (DMA) reserved for MIL, in bytes.

Open Collapse M_NON_PAGED_MEMORY_USED

Returns the amount of non-paged memory being used, in bytes. Returns the amount of non-paged memory being used, in bytes.

Open Collapse M_PARAMETER

Returns the parameter checking mode. Returns the parameter checking mode ...

UserVarPtr info

Return values:
M_CHECK_DISABLE, M_CHECK_ENABLE (details)
Open Collapse M_PROCESSING

Returns the processing compensation mode. Returns the processing compensation mode ...

UserVarPtr info

Return values:
M_COMPENSATION_DISABLE, M_COMPENSATION_ENABLE (details)
Open Collapse M_TRACE

Returns the trace printing mode. Returns the trace printing mode ...

UserVarPtr info

Return values:
M_PRINT_DISABLE, M_PRINT_ENABLE (details)
Open Collapse M_VERSION

Returns the version of the MIL library. Returns the version of the MIL library ...

UserVarPtr info

Data type: double

[Combination constants]

In multi-thread environments, you can inquire about an application setting from any thread; however, to inquire the status of a thread-specific setting, add the value below to M_ERROR, M_MEMORY, M_PARAMETER, M_PROCESSING, M_TRACE.

Open Collapse Value | Description
Open Collapse M_THREAD_CURRENT | Specifies that data to be returned should relate to the current thread. Specifies that data to be returned should relate to the current thread.

When inquired and present, the requested system fingerprint is returned. If that specific fingerprint is not present, 0 is returned. For more information about system fingerprints, see the Protecting your own MIL software application using a Matrox hardware fingerprint section in Chapter 24: Distribution and licensing.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_CORONA_II_FINGERPRINT | Returns the hardware fingerprint of the Matrox Corona-II board. Returns the hardware fingerprint of the Matrox Corona-II board. | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Open Collapse M_CRONOSPLUS_FINGERPRINT | Returns the hardware fingerprint of the Matrox CronosPlus board. Returns the hardware fingerprint of the Matrox CronosPlus board. |  | b |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Open Collapse M_ETHERNET_FINGERPRINT | Returns the hardware fingerprint of the Ethernet component. Returns the hardware fingerprint of the Ethernet component. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_HARD_ID_KEY_FINGERPRINT | Returns the hardware fingerprint of the hardware identification key component. Returns the hardware fingerprint of the hardware identification key component. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_HELIOS_FINGERPRINT | Returns the hardware fingerprint of the Matrox Helios board. Returns the hardware fingerprint of the Matrox Helios board. |  |  |  | d | e |  |  |  |  |  |  |  |  |  |  |  |  |
Open Collapse M_IRIS_FINGERPRINT | Returns the hardware fingerprint of the Matrox Iris. Returns the hardware fingerprint of the Matrox Iris. |  |  |  |  |  | f |  |  |  |  |  |  |  |  |  |  |  |
Open Collapse M_MATROX_BOARD_FINGERPRINT | Returns the hardware fingerprint of the first Matrox frame grabber with an EEPROM, found in the computer. Note that if the computer has more than one Matrox frame grabber, there is no guarantee which fingerprint will be returned. Returns the hardware fingerprint of the first Matrox frame grabber with an EEPROM, found in the computer ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_METEOR_II_1394_FINGERPRINT | Returns the hardware fingerprint of the Matrox Meteor-II /1394 board. Returns the hardware fingerprint of the Matrox Meteor-II /1394 board. |  |  |  |  |  |  | g |  |  |  |  |  |  |  |  |  |  |
Open Collapse M_MORPHIS_FINGERPRINT | Returns the hardware fingerprint of the Matrox Morphis board. Returns the hardware fingerprint of the Matrox Morphis board. |  |  |  |  |  |  |  |  |  |  |  | l |  |  |  |  |  |
Open Collapse M_ODYSSEY_FINGERPRINT | Returns the hardware fingerprint of the Matrox Odyssey board. Returns the hardware fingerprint of the Matrox Odyssey board. |  |  |  |  |  |  |  |  |  |  |  |  | m | n | o |  |  |
Open Collapse M_ORION_FINGERPRINT | Returns the hardware fingerprint of the Matrox Orion board. Returns the hardware fingerprint of the Matrox Orion board. |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
Open Collapse M_SOLIOS_FINGERPRINT | Returns the hardware fingerprint of the Matrox Solios board. Returns the hardware fingerprint of the Matrox Solios board. |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | q | r
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type MIL_TEXT_CHAR
  • double
  • long
  • MIL_ID

Specifies the address in which to write the requested information.

Since the MappInquire() function also returns the requested information, you can set this parameter to M_NULL.

Return value
The returned value is the requested system information cast to long.
ERROR MEMORY PARAMETER PROCESSING TRACE CURRENT APPLICATION INSTALLED SYSTEM PRINT NAME n INSTALLED SYSTEM PRINT NAME SIZE ERROR LICENSE MODULES MEMORY INSTALLED SYSTEM DESCRIPTOR n INSTALLED SYSTEM DESCRIPTOR SIZE NON PAGED MEMORY FREE NON PAGED MEMORY SIZE NON PAGED MEMORY USED INSTALLED SYSTEM COUNT PARAMETER PROCESSING TRACE VERSION THREAD CURRENT CORONA II FINGERPRINT CRONOSPLUS FINGERPRINT ETHERNET FINGERPRINT HARD ID KEY FINGERPRINT HELIOS FINGERPRINT IRIS FINGERPRINT MATROX BOARD FINGERPRINT METEOR II 1394 FINGERPRINT MORPHIS FINGERPRINT ODYSSEY FINGERPRINT ORION FINGERPRINT SOLIOS FINGERPRINT


MappTimer

See Also | Example | Availability | MappInquire
Reference:
channel_switch.c
dtkaddconstantmain.c
dtkobjecttracking.c
dtksyncasyncfunctionsmain.c
mdigdoublebuffering.c
mdiggrabsequence.c
mdighook.c
mdigmultdestination.c
mdigmultformat.c
mimconvolve.c
mmod.c
mmodeltracking.c
mmorphisjpeg2000.c
mpat.c
mstr.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Control a setting of a MIL timer and read the MIL timer.
Syntax
double MappTimer (
long ControlType,
double *TimePtr
)
Description

This function sets the specified control for a MIL timer or reads the MIL timer. There is a different MIL timer for each thread of the application and one global MIL timer for the application. By default, the MIL timer that is set and read is the timer of the current thread. However, you can set and read the global timer by adding M_GLOBAL to the ControlType parameter.

This function is useful for benchmarking operations in a MIL application. The timer resolution varies according to the hardware and operating system used.

Note that MIL functions run at a slower speed during debug mode. Therefore, once you are done debugging your application, you should compile in release mode to achieve maximum processing speed.

Parameters
ControlType

Specifies the control to exert on the MIL timer. It can be set to one of the following:

Open Collapse Value Description
Open Collapse M_TIMER_READ

 Reads the time (in sec) of the MIL timer since the last reset. Note that the time read takes into account (subtracts) the µsec (microseconds) needed to execute M_TIMER_READ.  Reads the time (in sec) of the MIL timer since the last reset ...

  Open   Collapse  M_TIMER_RESET

 Resets the MIL timer to zero.  Resets the MIL timer to zero.

  Open   Collapse  M_TIMER_RESOLUTION

 Reads the MIL timer resolution, in seconds.  Reads the MIL timer resolution, in seconds.

  Open   Collapse  M_TIMER_WAIT

 Waits for the specified period of time (in sec) before returning.  Waits for the specified period of time (in sec) before returning.

      [Combination constants]

 The following value can be added to any of the ControlType parameter setttings.

Open Collapse Value | Description
Open Collapse M_SYNCHRONOUS | Forces the function to wait for all pending calls of the current thread to complete before continuing. Forces the function to wait for all pending calls of the current thread to complete before continuing.

      [Combination constants]

 In a MIL application, there is only one global MIL timer that is accessible by all MIL threads. To control and access the global MIL timer, you can add the following value:

  Open   Collapse  Value
Description

  Open   Collapse   M_GLOBAL

 Executes the requested timer operation using the global MIL timer.  Executes the requested timer operation using the global MIL timer ...

 If used with M_SYNCHRONOUS, the global MIL timer will wait for all pending calls of the current thread to complete before continuing.

 TimePtr

 Specifies the address of the variable in which to store the timer information produced by the M_TIMER_READ or M_TIMER_RESOLUTION controls.  Since the MappTimer() also returns the requested information when M_TIMER_READ or M_TIMER_RESOLUTION are selected, you can set this parameter to M_NULL.

 For M_TIMER_RESET, set TimePtr to M_NULL.

 For M_TIMER_WAIT, TimePtr specifies the address of the variable from which to read the timer information.

Return value

 For M_TIMER_READ and M_TIMER_RESOLUTION, the returned value is cast to double. For M_TIMER_RESET and M_TIMER_WAIT, this function returns 0.0.

GLOBAL TIMER READ SYNCHRONOUS TIMER READ TIMER RESOLUTION TIMER READ TIMER RESOLUTION TIMER RESET TIMER WAIT TIMER READ TIMER RESOLUTION TIMER RESET TIMER WAIT  TIMER READ  TIMER RESET  TIMER RESOLUTION TIMER WAIT  SYNCHRONOUS GLOBAL


blob

Mblob functions

Example | Availability
There are no examples containing blob().
Not available in MIL-Lite

Available in MIL
Synopsis
The functions prefixed with Mblob make up the Blob Analysis module. The Blob Analysis module allows you to identify connected regions of pixels (blobs) within an image, and then calculate selected features of these blobs. The Blob Analysis module can measure a wide assortment of blob features, such as the blob area, perimeter, Feret diameter at a given angle, minimum bounding box, and center of gravity. The module also allows you to perform some image processing operations, such as reconstructing or eliminating blobs.
Functions
  • MblobAllocFeatureList
  • MblobAllocResult
  • MblobCalculate
  • MblobControl
  • MblobDraw
  • MblobFill
  • MblobFree
  • MblobGetLabel
  • MblobGetNumber
  • MblobGetResult
  • MblobGetResultSingle
  • MblobGetRuns
  • MblobInquire
  • MblobLabel
  • MblobReconstruct
  • MblobSelect
  • MblobSelectFeature
  • MblobSelectFeret
  • MblobSelectMoment


MblobAllocFeatureList

See Also | Example | Availability | MblobAllocResult
User Guide:
Steps to performing blob analysis
Making feature extractions

Reference:
MblobCalculate
MblobFree
MblobSelectFeature
MblobSelectFeret
MblobSelectMoment
MsysAlloc
mblob.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a blob analysis feature list.
Syntax
MIL_ID MblobAllocFeatureList (
MIL_ID SystemId,
MIL_ID *FeatureListIdPtr
)
Description

This function allocates a feature list. The feature list holds the feature(s) to be calculated by MblobCalculate(). You must specify which feature(s) to calculate, using MblobSelectFeature(), MblobSelectFeret(), and MblobSelectMoment(). Immediately after allocation, no features are selected in the feature list. When the feature list is no longer required, release it, using MblobFree().

Parameters
SystemId

Specifies the system on which to allocate the feature list.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 FeatureListIdPtr

 Specifies the address of the variable in which the feature list identifier will be written.  Since the MblobAllocFeatureList() function also returns the feature list identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the feature list identifier that you will use to select features to be calculated.

 DEFAULT HOST


MblobAllocResult

See Also | Example | Availability | MblobAllocFeatureList | MblobCalculate
User Guide:
Steps to performing blob analysis

Reference:
MblobControl
MblobFree
MblobGetLabel
MblobGetResult
MblobGetResultSingle
MblobGetRuns
MsysAlloc
mblob.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a blob analysis result buffer.
Syntax
MIL_ID MblobAllocResult (
MIL_ID SystemId,
MIL_ID *BlobResIdPtr
)
Description

This function allocates a result buffer used to store blob analysis results.

Each blob creates a separate result entry in the blob analysis result buffer. You can retrieve blob analysis results from a result buffer, using MblobGetResult() or MblobGetResultSingle(). Use the latter to obtain results for a single blob. For more specific results, you can call MblobGetLabel() and MblobGetRuns(). When the result buffer is no longer required, release it, using MblobFree().

Parameters
SystemId

Specifies the system on which to allocate the result buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 BlobResIdPtr

 Specifies the address of the variable in which the blob analysis result buffer identifier is to be written.  Since the MblobAllocResult() function also returns the blob analysis result buffer identifier, you can set this parameter to M_NULL.

 The default processing modes for the result buffer are as follows:

  Open   Collapse  Value
Description

  Open   Collapse  M_BLOB_IDENTIFY

 The default value is M_INDIVIDUAL.  The default value is M_INDIVIDUAL.

  Open   Collapse  M_FOREGROUND_VALUE

 The default value is M_NONZERO.  The default value is M_NONZERO.

  Open   Collapse  M_IDENTIFIER_TYPE

 The default value is M_GRAYSCALE.  The default value is M_GRAYSCALE.

  Open   Collapse  M_LATTICE

 The default value is M_8_CONNECTED.  The default value is M_8_CONNECTED.

  Open   Collapse  M_NUMBER_OF_FERETS

 The default value is 8.  The default value is 8.

  Open   Collapse  M_PIXEL_ASPECT_RATIO

 The default value is 1.0.  The default value is 1 ...

 Use MblobControl() to change these values if necessary.

Return value

 The returned value is a blob analysis result buffer identifier that you will use in calculations and results inquiry.

INDIVIDUAL NONZERO GRAYSCALE 8 CONNECTED  DEFAULT HOST   BLOB IDENTIFY
 FOREGROUND VALUE
 IDENTIFIER TYPE LATTICE
 NUMBER OF FERETS
 PIXEL ASPECT RATIO


MblobCalculate

See Also | Example | Availability | MblobAllocResult | MblobControl
User Guide:
Steps to performing blob analysis
Selecting blobs
Making feature extractions
Finding the blob location
Moments

Reference:
MblobAllocFeatureList
MblobAllocResult
MblobControl
MblobSelect
MblobSelectFeature
MblobSelectFeret
MblobSelectMoment
mblob.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Perform blob analysis calculations.
Syntax
void MblobCalculate (
MIL_ID BlobIdentImageId,
MIL_ID GrayImageId,
MIL_ID FeatureListId,
MIL_ID BlobResId
)
Description

This function calculates the features specified in the given feature list for all currently included blobs in the blob identifier image and stores results in the specified result buffer. Features are added to the feature list with MblobSelectFeature(), MblobSelectFeret(), and MblobSelectMoment(). Specific blobs can be selected using MblobSelect().

Calculations on binary features (such as M_AREA) are performed using only the BlobIdentImageId parameter. If a grayscale feature (such as M_MAX_PIXEL) is to be calculated, an image buffer must be specified for the GrayImageId parameter. In this case, the blob identifier image will be used to identify the blobs and the pixel values in the grayscale image are used to calculate the features. Note that the blob identifier image and the grayscale image must be the same size.

If several calls are made to MblobCalculate() with the same image and result buffer, features calculated in one call remain in the result buffer and are not recalculated in subsequent calls. However, if you then use a result buffer with different images or if you change its processing mode with MblobControl(), any results already in the buffer become invalid and will be discarded. Therefore, it is more efficient to use a result buffer exclusively in one processing mode with one blob identifier image (or one identifier/grayscale image pair if grayscale features are needed).

All features are calculated in the image coordinate system. If the blob identifier image is associated with a calibration object, you can retrieve results in real-world or in pixel units. However, if your image has distortion that cannot be neglected, you should transform the image before calculating your features. When calculated in pixel units, the pixel aspect ratio, specified with MblobControl(), is taken into account horizontally. Results are returned in units of "pixel height" since the pixel width is adjusted to be equal to the pixel height. Note, all positional results are relative to the top-left pixel in the target image or the origin of the world-coordinate system if the image is calibrated.

Parameters
BlobIdentImageId

Specifies the blob identifier image that will be used in calculations. The blob identifier image identifies each blob as a group of touching pixels in the current foreground state (zero or non-zero, depending on the value assigned to M_FOREGROUND_VALUE processing mode in MblobControl()). The current M_LATTICE processing mode (also set with MblobControl()), determines when to consider pixels as touching. The blob identifier image must be an unsigned, single band, packed binary, 8-bit or 16-bit grayscale image buffer.

If the identifier image has previously been binarized so that it contains only two extreme values (0 and 1 for 1-bit images, 0 and 0xff for 8-bit images, and 0 and 0xffff for 16-bit images), blob analysis can be performed a little faster. However, you must first change the M_IDENTIFIER_TYPE to M_BINARY, using MblobControl(), to let MIL know that the identifier image has only two states.

Depending on the M_BLOB_IDENTIFICATION mode (set with MblobControl()), MblobCalculate() either treats each blob individually (M_INDIVIDUAL), groups all blobs together (M_WHOLE_IMAGE), or groups blobs according to their actual pixel value in the blob identifier image (M_LABELED).

GrayImageId

Specifies the grayscale image (not a binary buffer) that will be used to calculate grayscale features. If this parameter is set to M_NULL, grayscale features, such as M_SUM_PIXEL, cannot be calculated. This parameter is ignored when calculating only binary type features. The grayscale image must be a single band, 8-bit or 16-bit unsigned grayscale image buffer.

FeatureListId

Specifies the identifier of the feature list buffer, previously allocated with MblobAllocFeatureList(), that specifies the feature(s) to calculate.

BlobResId

Specifies the identifier of a blob analysis result buffer, previously allocated with MblobAllocResult(), in which to store calculated results.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The blob analysis result buffer (BlobResId) must be allocated on the same system as the feature list buffer (FeatureListId). If it is not, an error will occur.

Remark
  • Note that this function is optimized for packed binary buffers.
AREA MAX PIXEL FOREGROUND VALUE LATTICE IDENTIFIER TYPE BINARY BLOB IDENTIFICATION INDIVIDUAL WHOLE IMAGE LABELED SUM PIXEL


MblobControl

See Also | Example | Availability | MblobCalculate | MblobDraw
User Guide:
Steps to performing blob analysis
Adjusting blob analysis processing controls
The area and perimeter
Dimensions

Reference:
MblobAllocResult
MblobCalculate
MblobFill
MblobGetLabel
MblobGetRuns
MblobInquire
MblobLabel
MblobSelectFeature
mblob.c
Not available in MIL-Lite

Available in MIL
Synopsis
Control a blob analysis processing control setting.
Syntax
void MblobControl (
MIL_ID BlobResId,
long ControlType,
double ControlValue
)
Description

This function changes a processing control associated with the specified blob analysis result buffer. This function is normally called immediately after allocating a blob analysis result buffer, using MblobAllocResult(), but can be called later (in which case, already calculated results are discarded). If not called, default processing controls and values are used in calculations.

Note that you can use MblobInquire() to inquire about specific processing controls associated with a blob analysis result buffer.

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer.

ControlType

Specifies the processing setting to control.

See the Parameter associations section for possible values.

ControlValue

Specifies the setting required for the control for the processing setting.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

Open Collapse ControlType Description
ControlValue
Open Collapse M_BLOB_IDENTIFICATION

Sets whether to calculate features for each blob, or to treat groups of blobs as single blobs and calculate the features of the blobs. Sets whether to calculate features for each blob, or to treat groups of blobs as single blobs and calculate the features of the blobs ...

M_INDIVIDUAL

Specifies that all blobs are measured individually.

This is the default value.
M_LABELED

Specifies that blobs with the same label value are grouped together.

M_WHOLE_IMAGE

Specifies that all blobs are grouped together.

Open Collapse M_FOREGROUND_VALUE

Sets which pixel values are considered to be in the foreground. Sets which pixel values are considered to be in the foreground ...

M_NONZERO

Specifies the blobs consisting of non-zero pixels.

This is the default value.
M_ZERO

Specifies the blobs consisting of zero pixels.

Open Collapse M_IDENTIFIER_TYPE

Sets the values that non-zero pixels in the image can have. Sets the values that non-zero pixels in the image can have ...

If the identifier image is already binarized (for example, pixel values for an 8-bit image are either 0 or 0xff), you can change the identifier type to M_BINARY to calculate features faster.

M_BINARY

Specifies that non-zero pixels must have the maximum value of the buffer (for example, 0xff for an 8-bit image).

M_GRAYSCALE

Specifies that non-zero pixels can have any value.

This is the default value.
Open Collapse M_LATTICE

Sets the image lattice for blob analysis. Sets the image lattice for blob analysis ...

M_4_CONNECTED

Specifies that each pixel has 4 neighbors.

M_8_CONNECTED

Specifies that each pixel has 8 neighbors.

This is the default value.
Open Collapse M_NUMBER_OF_FERETS

Sets the number of Feret angles to be used when calculating a Feret feature. Sets the number of Feret angles to be used when calculating a Feret feature ...

M_MAX_FERETS

Specifies the maximum number of Feret angles.

M_MIN_FERETS

Specifies the minimum number of Feret angles.

Value

Specifies the number of Feret angles. The value must be between M_MIN_FERETS and M_MAX_FERETS, inclusive.

The first Feret angle used is always 0°, and the difference between successive angles is 180° / number of Ferets.

The default value is 8.

Open Collapse M_PIXEL_ASPECT_RATIO

Sets the pixel aspect ratio of the image(s). Sets the pixel aspect ratio of the image(s) ...

Value

Specifies the pixel width/pixel height.

The default value is 1.0.

Open Collapse M_SAVE_RUNS

Sets whether to save run information when calling MblobCalculate(). Sets whether to save run information when calling MblobCalculate() ...

M_DISABLE

Does not save run information. Disabling saves time when performing the first call to MblobCalculate() and reduces the memory requirements for the result buffer. However, you cannot use MblobFill(), MblobGetLabel(), MblobGetRuns(),or MblobLabel(). In addition, you cannot calculate the chained pixels feature (M_CHAINS), using MblobSelectFeature().

M_ENABLE

Saves run information. Calls to MblobCalculate() will save run information from the blob identifier image in the result buffer.

This is the default value.

BINARY MIN FERETS MAX FERETS CHAINS BLOB IDENTIFICATION INDIVIDUAL LABELED WHOLE IMAGE FOREGROUND VALUE NONZERO ZERO IDENTIFIER TYPE BINARY GRAYSCALE LATTICE 4 CONNECTED 8 CONNECTED NUMBER OF FERETS MAX FERETS MIN FERETS PIXEL ASPECT RATIO SAVE RUNS DISABLE ENABLE


MblobDraw

See Also | Example | Availability | MblobControl | MblobFill
User Guide:
Making feature extractions

Reference:
MblobCalculate
MblobControl
MgraAlloc
mblob.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Draw specific blob features in the destination image buffer.
Syntax
void MblobDraw(
MIL_ID GraphContId,
MIL_ID ResultId,
MIL_ID DestImageId,
long Operation,
long Label,
long ControlFlag
)
Description

This function draws specific blob features, which were calculated with MblobCalculate(), in the destination buffer. This function can draw multiple features at a time.

Parameters
GraphContId

Specifies the graphics context to use. This parameter should be set to one of the following:

Value | Description
M_DEFAULT | Specifies to use the default graphics context.
MIL graphics context identifier | Specifies a valid graphics context identifier, which you have allocated using MgraAlloc().
ResultId

Specifies the identifier of the blob analysis result buffer from which to retrieve the features to draw.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The blob analysis result buffer (ResultId) must be allocated on the same system as the graphics context (GraphContId). If it is not, an error will occur.

DestImageId

Specifies the identifier of the destination image buffer in which to draw. You can also choose to annotate an image non-destructively, by drawing into its display's overlay buffer.

Operation

Specifies the type of operation to perform. The Operation values in the table below can be added together to draw multiple features at a time. For example, to draw both the result occurrence position and active edges, you would specify M_DRAW_BLOBS_CONTOUR + M_DRAW_HOLES + M_DRAW_POSITION as the Operation parameter.

Open Collapse Value Description
Open Collapse M_DRAW_AXIS

 Draws a cross at the blobs' center of gravity, respecting the principal and secondary axes. Note that to perform this operation, one feature among M_AXIS_PRINCIPAL_ANGLE or M_AXIS_SECONDARY_ANGLE must have been calculated using the binary definition.  Draws a cross at the blobs' center of gravity, respecting the principal and secondary axes ...

  Open   Collapse  M_DRAW_BLOBS

 Draws the blobs. Note that to perform this operation, runs must have been previously saved by using MblobControl() with M_SAVE_RUNS set to M_ENABLE.  Draws the blobs ...

  Open   Collapse  M_DRAW_BLOBS_CONTOUR

 Draws the external outline of the blobs.  Draws the external outline of the blobs ...

 Note that to perform this operation, runs must have been previously saved using MblobControl() with M_SAVE_RUNS set to M_ENABLE. Also note that when using MblobControl() with M_BLOB_IDENTIFICATION set to either M_WHOLE_IMAGE or M_LABELED, both the blob and hole contours will be drawn when performing this operation.

  Open   Collapse  M_DRAW_BOX

 Draws the bounding box of each blob.  Draws the bounding box of each blob ...

 Note that to perform this operation, the M_BOX and M_CENTER_OF_GRAVITY features must be calculated.

  Open   Collapse  M_DRAW_BOX_CENTER

 Draws a cross at the center of the blobs' bounding box.  Draws a cross at the center of the blobs' bounding box ...

 Note that to perform this operation, the M_BOX and M_CENTER_OF_GRAVITY features must be calculated.

  Open   Collapse  M_DRAW_CENTER_OF_GRAVITY

 Same as M_DRAW_POSITION.  Same as M_DRAW_POSITION.

  Open   Collapse  M_DRAW_FERET_MAX

 Draws the blobs' maximum Feret diameter, using an H-type line (|-|), centered at the blobs' position, at the maximum Feret diameter's angle.  Draws the blobs' maximum Feret diameter, using an H-type line (|-|), centered at the blobs' position, at the maximum Feret diameter's angle ...

 Note that to perform this operation, the following features must be calculated: M_BOX, M_FERET_MAX_DIAMETER, and M_FERET_MAX_ANGLE.

  Open   Collapse  M_DRAW_FERET_MIN

 Draws the blobs' minimum Feret diameter, using an H-type line (|-|), centered at the blobs' position, at the minimum Feret diameter's angle.  Draws the blobs' minimum Feret diameter, using an H-type line (|-|), centered at the blobs' position, at the minimum Feret diameter's angle ...

 Note that to perform this operation, the following features must be calculated: M_BOX, M_FERET_MIN_DIAMETER, and M_FERET_MIN_ANGLE.

  Open   Collapse  M_DRAW_HOLES

 Draws the holes of the blobs. Note that to perform this operation, runs must have been previously saved by using MblobControl() with M_SAVE_RUNS set to M_ENABLE and one feature among M_BOX_X_MIN, M_BOX_X_MAX, M_BOX_Y_MIN, or M_BOX_Y_MAX must have been calculated.  Draws the holes of the blobs ...

  Open   Collapse  M_DRAW_HOLES_CONTOUR

 Draws the outline of the blobs' holes.  Draws the outline of the blobs' holes ...

 Note that to perform this operation, runs must have been previously saved using MblobControl() with M_SAVE_RUNS set to M_ENABLE. Also note that when using MblobControl() with M_BLOB_IDENTIFICATION set to either M_WHOLE_IMAGE or M_LABELED, both the blob and hole contours will be drawn when performing this operation.

  Open   Collapse  M_DRAW_POSITION

 Draws a cross at the center of gravity of the blobs. Note that to perform this operation, M_CENTER_OF_GRAVITY must have been calculated using the binary definition.  Draws a cross at the center of gravity of the blobs ...

 Label

 Specifies the label of the blob or blobs to draw and can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_ALL_BLOBS.  Same as M_ALL_BLOBS.

  Open   Collapse  M_ALL_BLOBS

 Draws all blobs.  Draws all blobs.

  Open   Collapse  M_EXCLUDED_BLOBS

 Draws all currently excluded blobs.  Draws all currently excluded blobs.

  Open   Collapse  M_INCLUDED_BLOBS

 Draws all currently included blobs.  Draws all currently included blobs.

  Open   Collapse  Value

 Draws the blob with the specified blob label value.  Draws the blob with the specified blob label value.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

DRAW BLOBS CONTOUR DRAW HOLES DRAW POSITION AXIS PRINCIPAL ANGLE AXIS SECONDARY ANGLE SAVE RUNS ENABLE DRAW POSITION BOX FERET MAX DIAMETER FERET MAX ANGLE BOX FERET MIN DIAMETER FERET MIN ANGLE SAVE RUNS ENABLE BOX X MIN BOX X MAX BOX Y MIN BOX Y MAX CENTER OF GRAVITY SAVE RUNS ENABLE BLOB IDENTIFICATION WHOLE IMAGE LABELED BOX CENTER OF GRAVITY ALL BLOBS     DRAW AXIS  DRAW BLOBS  DRAW BLOBS CONTOUR  DRAW BOX  DRAW BOX CENTER  DRAW CENTER OF GRAVITY DRAW FERET MAX  DRAW FERET MIN DRAW HOLES  DRAW HOLES CONTOUR  DRAW POSITION  DEFAULT ALL BLOBS  EXCLUDED BLOBS  INCLUDED BLOBS


MblobFill

See Also | Example | Availability | MblobDraw | MblobFree
User Guide:
Selecting blobs
Making feature extractions
Blob reconstruction

Reference:
MblobCalculate
MblobSelect
There are no examples containing MblobFill().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox CronosPlus
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Draw blobs that meet a specified fill criterion.
Syntax
void MblobFill(
MIL_ID BlobResId,
MIL_ID DestImageBufId,
long Criterion,
long Value
)
Description

This function draws, in an image, those blobs that meet a specified fill criterion with the specified fill value.

This function is often used to remove unwanted (excluded or deleted) blobs from the identifier image (by drawing them with the background color), or to highlight included blobs in a different color. Therefore, an appropriate destination image is the blob identifier image (or a copy of it) associated with the result buffer, or another image buffer that has been cleared.

MblobCalculate() must have been called prior to using this function.

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer.

DestImageBufId

Specifies the identifier of the destination image buffer. This must be a single band, packed binary, 8, or 16-bit unsigned buffer. Note, this buffer need not be the same size as the original identifier image used to calculate the blobs.

[All except Matrox Genesis]

Note that 1-bit (packed binary) destination buffers are not processed by the Genesis.

Criterion

Specifies which blobs to draw with the specified value. This parameter can be set to one of the following values:

Open Collapse Value Description
Open Collapse M_ALL_BLOBS

 Draws all blobs with the specified fill value.  Draws all blobs with the specified fill value.

  Open   Collapse  M_EXCLUDED_BLOBS

 Draws all currently excluded blobs with the specified fill value.  Draws all currently excluded blobs with the specified fill value.

  Open   Collapse  M_INCLUDED_BLOBS

 Draws all currently included blobs with the specified fill value.  Draws all currently included blobs with the specified fill value.

      [Combination constants]

[All except
        Matrox Genesis]

 The value below can be added to the Criterion parameter:

  Open   Collapse  Value
Description

  Open   Collapse  M_CONTOUR

 Specifies that only the blob's borders should be filled.  Specifies that only the blob's borders should be filled ...

M_CONTOUR uses the coordinates obtained from chained pixels to draw the borders; therefore, if you have already calculated M_CHAINS with MblobCalculate(), M_CONTOUR will operate faster.

 The status of the blobs (included or excluded) is taken from the blob analysis result buffer. By default, all blobs in the result buffer are included for future operations. To change the status of a blob, use MblobSelect().

 Value

 Specifies the value with which to fill the blobs that meet the specified criterion. If the destination buffer is binary, this value must be 0 or 1.

Remark

  •  Note that this function is optimized for packed binary buffers.
    •

CHAINS    ALL BLOBS EXCLUDED BLOBS  INCLUDED BLOBS  CONTOUR


MblobFree

See Also | Example | Availability | MblobFill | MblobGetLabel
Reference:
MblobAllocFeatureList
MblobAllocResult
mblob.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free the blob analysis result buffer or the feature list.
Syntax
void MblobFree(
MIL_ID BlobId
)
Description

This function deletes the specified blob analysis result buffer or feature list and releases any memory associated with it.

Parameter
BlobId

Specifies the identifier of the blob analysis result buffer or feature list buffer to free. The buffer must have been successfully allocated, using MblobAllocResult() or MblobAllocFeatureList(), prior to calling this function.


MblobGetLabel

See Also | Example | Availability | MblobFree | MblobGetNumber
User Guide:
Steps to performing blob analysis
Moments

Reference:
MblobCalculate
MblobGetResultSingle
MblobSelect
There are no examples containing MblobGetLabel().
Not available in MIL-Lite

Available in MIL
Synopsis
Get the label value of a blob at a specified position.
Syntax
long MblobGetLabel(
MIL_ID BlobResId,
long XPos,
long YPos,
long *LabelVarPtr
)
Description

This function gets the label value of a specified blob. Label values are used, for example, to obtain calculation results for single blobs (MblobGetResultSingle()). Blob label values must have been generated by calling MblobCalculate().

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer where the labels are stored. Note, this function cannot obtain the label values of blobs that have been deleted from the result buffer with MblobSelect().

XPos

Specifies the X-coordinate of the blob.

YPos

Specifies the Y-coordinate of the blob.

LabelVarPtr

Specifies the address of the variable in which to write the label value. If there is no blob at the specified location, the blob has been deleted, or if the blob's XPos and YPos lie outside the original identifier image, M_NULL is returned instead of the label value. Also, since MblobGetLabel() returns the label value, you can set this parameter to M_NULL.

Return value
The returned value is the label value of the specified blob.


MblobGetNumber

See Also | Example | Availability | MblobGetLabel | MblobGetResult
User Guide:
Steps to performing blob analysis

Reference:
MblobCalculate
MblobGetResult
MblobSelect
mblob.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the number of currently included blobs.
Syntax
long MblobGetNumber(
MIL_ID BlobResId,
long *CountVarPtr
)
Description

This function reads the number of currently included blobs from the specified blob analysis result buffer. All blobs are included unless their status is changed, using MblobSelect(). Included blobs will be included in future operations and result retrievals.

This function must be used to determine the number of blob results that will be returned by MblobGetResult().

A call to MblobCalculate() must have been made prior to using this function.

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer.

CountVarPtr

Specifies the address of the variable in which to write the count. Since MblobGetNumber() also returns the number of selected blobs, you can set this parameter to M_NULL.

Return value
The returned value is the number of included blobs in the specified result buffer.


MblobGetResult

See Also | Example | Availability | MblobGetNumber | MblobGetResultSingle
User Guide:
Steps to performing blob analysis
Making feature extractions
Location, length and number of runs

Reference:
MblobCalculate
MblobControl
MblobGetNumber
mblob.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get results for a feature of the included blobs, from a blob result buffer.
Syntax
void MblobGetResult(
MIL_ID BlobResId,
long Feature,
void *TargetArrayPtr
)
Description

This function retrieves the results for a specified feature for all included blobs, from the blob analysis result buffer.

If the blob identifier image is associated with a calibration object, you can retrieve results in real-world or in pixel units, unless otherwise specified. When returned in pixel units, the pixel aspect ratio, specified with MblobControl(), is taken into account horizontally. In this case, results are returned in units of "pixel height" since the pixel width is adjusted to be equal to the pixel height. Note, all positional results are relative to the top-left pixel in the target image or the origin of the world-coordinate if the image is calibrated.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set TargetArrayPtr to M_NULL. When this parameter is set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when you pass the parameter an array instead. You must ensure that the array is sufficiently large to hold the current and previously queued results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer from which to get results.

Feature

Specifies the feature for which to retreive results. The specified feature must have already been calculated with MblobCalculate().

To retrieve the result for a grayscale feature, select one of the following:

Unless otherwise specified, the following values require that you pass the TargetArrayPtr parameter the address of an array of type double (with a size of the number of currently included blobs. This number can be obtained, using MblobGetNumber().) .

Open Collapse Value | Description
Open Collapse M_AREA | Returns the number of foreground pixels in each blob (holes are not counted). Returns the number of foreground pixels in each blob (holes are not counted).
Open Collapse M_BOX_X_MAX | Returns the extreme right X-coordinate of each blob. Returns the extreme right X-coordinate of each blob.
Open Collapse M_BOX_X_MIN | Returns the extreme left X-coordinate of each blob. Returns the extreme left X-coordinate of each blob.
Open Collapse M_BOX_Y_MAX | Returns the extreme bottom Y-coordinate of each blob. Returns the extreme bottom Y-coordinate of each blob.
Open Collapse M_BOX_Y_MIN | Returns the extreme top Y-coordinate of each blob. Returns the extreme top Y-coordinate of each blob.
Open Collapse M_BREADTH | Returns a measure of the true breadth of each blob. Returns a measure of the true breadth of each blob.
Open Collapse M_COMPACTNESS | Returns the compactness of each blob. Returns the compactness of each blob.
Open Collapse M_CONVEX_PERIMETER | Returns an approximation of the perimeter of the convex hull of each blob. Returns an approximation of the perimeter of the convex hull of each blob.
Open Collapse M_ELONGATION | Returns a value that is equal to M_LENGTH / M_BREADTH of each blob. Returns a value that is equal to M_LENGTH / M_BREADTH of each blob.
Open Collapse M_EULER_NUMBER | Returns the number of blobs - number of holes. This value is more useful if calculated using the M_WHOLE_IMAGE processing mode instead of the M_INDIVIDUAL processing mode. Returns the number of blobs - number of holes ...
Open Collapse M_FERET_ELONGATION | Returns a measure of the shape of each blob. It is equal to M_FERET_MAX_DIAMETER / M_FERET_MIN_DIAMETER. Returns a measure of the shape of each blob ...
Open Collapse M_FERET_MAX_ANGLE | Returns the angle at which the maximum Feret diameter is found for each blob. The value is in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis. Returns the angle at which the maximum Feret diameter is found for each blob ...
Open Collapse M_FERET_MAX_DIAMETER | Returns the largest Feret diameter found after checking a certain number of angles. Returns the largest Feret diameter found after checking a certain number of angles.
Open Collapse M_FERET_MEAN_DIAMETER | Returns the average of the Feret diameters at the angles checked for each blob. Returns the average of the Feret diameters at the angles checked for each blob.
Open Collapse M_FERET_MIN_ANGLE | Returns the angle at which the minimum Feret diameter is found. The value is in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis. Returns the angle at which the minimum Feret diameter is found ...
Open Collapse M_FERET_MIN_DIAMETER | Returns the smallest Feret diameter found after checking a certain number of angles. Returns the smallest Feret diameter found after checking a certain number of angles.
Open Collapse M_FERET_X | Returns the dimension of the minimum bounding box of each blob, in the horizontal direction. Returns the dimension of the minimum bounding box of each blob, in the horizontal direction.
Open Collapse M_FERET_Y | Returns the dimension of the minimum bounding box of each blob, in the vertical direction. Returns the dimension of the minimum bounding box of each blob, in the vertical direction.
Open Collapse M_FIRST_POINT_X | Returns (along with M_FIRST_POINT_Y) a unique point for each blob, that is always on the perimeter of the blob. The X-coordinate is that of the left-most pixel on the top-most line of the blob. Returns (along with M_FIRST_POINT_Y) a unique point for each blob, that is always on the perimeter of the blob ...
Open Collapse M_FIRST_POINT_Y | Returns (along with M_FIRST_POINT_X) a unique point for each blob, that is always on the perimeter of the blob. The Y-coordinate is that of the top-most line of the blob. Returns (along with M_FIRST_POINT_X) a unique point for each blob, that is always on the perimeter of the blob ...
Open Collapse M_GENERAL_FERET | Returns the Feret diameter at the specified angle. Returns the Feret diameter at the specified angle.
Open Collapse M_GENERAL_MOMENT | Returns the moment calculation. Returns the moment calculation.
Open Collapse M_INTERCEPT_0 | Returns the number of times a transition from background to foreground (not vice versa) occurs in the horizontal direction for the entire blob. In other words, it is equal to the number of times the neighborhood configuration [B, F] occurs in a blob, where B is a background pixel and F is a foreground pixel. Returns the number of times a transition from background to foreground (not vice versa) occurs in the horizontal direction for the entire blob ...
Open Collapse M_INTERCEPT_45 | Returns the number of times that the neighborhood configuration [image] occurs in a blob, where F is a foreground pixel, B is a background pixel and a dot can be any pixel value. Returns the number of times that the neighborhood configuration [image] occurs in a blob, where F is a foreground pixel, B is a background pixel and a dot can be any pixel value.
Open Collapse M_INTERCEPT_90 | Returns the number of times that the neighborhood configuration [image] occurs in a blob. Returns the number of times that the neighborhood configuration [image] occurs in a blob.
Open Collapse M_INTERCEPT_135 | Returns the number of times that the neighborhood configuration [image] occurs in a blob. Returns the number of times that the neighborhood configuration [image] occurs in a blob.
Open Collapse M_LABEL_VALUE | Returns the label value for each blob in an image. This is a positive integer (>= 1) that is unique for each blob. Returns the label value for each blob in an image ...
Open Collapse M_LENGTH | Returns a measure of the true length of each blob, although it is only accurate for certain object types (for example, long thin ones) because it is derived from the perimeter (P) and area (A) assuming that P = 2(length + breadth) and A = length x breadth. Returns a measure of the true length of each blob, although it is only accurate for certain object types (for example, long thin ones) because it is derived from the perimeter (P) and area (A) assuming that P = 2(length + breadth) and A = length x breadth.
Open Collapse M_NUMBER_OF_CHAINED_PIXELS | Returns the number of chained pixels for each blob. Returns the number of chained pixels for each blob.
Open Collapse M_NUMBER_OF_HOLES | Returns the number of holes in each blob. Holes that intersect the edge of the image are not counted (they might not be holes). This value is equal to 1 - M_EULER_NUMBER and is therefore a true hole count if calculated using the M_INDIVIDUAL processing mode. Returns the number of holes in each blob ...
Open Collapse M_NUMBER_OF_RUNS | Returns the total number of runs in each blob. Returns the total number of runs in each blob.
Open Collapse M_PERIMETER | Returns the total length of edges in each blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized (inside corners are counted as 1.414, rather than 2.0). A single pixel blob (area = 1) has a perimeter of 4.0. Returns the total length of edges in each blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized (inside corners are counted as 1.414, rather than 2.0) ...
Open Collapse M_ROUGHNESS | Returns a measure of how rough a blob is and is equal to M_PERIMETER / M_CONVEX_PERIMETER. A smooth convex blob will have the minimum roughness of 1.0. Returns a measure of how rough a blob is and is equal to M_PERIMETER / M_CONVEX_PERIMETER ...
Open Collapse M_X_MAX_AT_Y_MAX | Returns the maximum X-coordinate at the maximum Y-coordinate of the blob. Returns the maximum X-coordinate at the maximum Y-coordinate of the blob.
Open Collapse M_X_MIN_AT_Y_MIN | Returns the minimum X-coordinate at the minimum Y-coordinate of the blob. Returns the minimum X-coordinate at the minimum Y-coordinate of the blob.
Open Collapse M_Y_MAX_AT_X_MIN | Returns the maximum Y-coordinate at the minimum X-coordinate of the blob. Returns the maximum Y-coordinate at the minimum X-coordinate of the blob.
Open Collapse M_Y_MIN_AT_X_MAX | Returns the minimum Y-coordinate at the maximum X-coordinate of the blob. Returns the minimum Y-coordinate at the maximum X-coordinate of the blob.

To retrieve the result for a grayscale feature, select one of the following. Results for these features are only available if both a blob identifier image and a grayscale image were passed to MblobCalculate() (and the features were selected for calculation).

Unless otherwise specified, the following values require that you pass the TargetArrayPtr parameter the address of an array of type double (with a size of the number of currently included blobs. This number can be obtained using MblobGetNumber().) .

Open Collapse Value | Description
Open Collapse M_MAX_PIXEL | Returns the maximum pixel value found in each blob. Returns the maximum pixel value found in each blob.
Open Collapse M_MEAN_PIXEL | Returns the mean pixel value in each blob. Returns the mean pixel value in each blob.
Open Collapse M_MIN_PIXEL | Returns the minimum pixel value found in each blob. Returns the minimum pixel value found in each blob.
Open Collapse M_SIGMA_PIXEL | Returns the standard deviation of pixel values in each blob. Returns the standard deviation of pixel values in each blob.
Open Collapse M_SUM_PIXEL | Returns the sum of all pixel values in each blob. Returns the sum of all pixel values in each blob.
Open Collapse M_SUM_PIXEL_SQUARED | Returns the sum of the squares of each pixel value in each blob. Returns the sum of the squares of each pixel value in each blob.

To retrieve the result for a feature that has two different definitions (a binary and a grayscale definition), select one of the following values. If you did not provide both a blob identifier image and a grayscale image, only the binary version was calculated. If you did provide a grayscale image, both versions were calculated, unless otherwise specified. To specify which result to retrieve, see the combination values below. If both versions were calculated and no version is specified, then the grayscale version of the feature is retrieved.

Unless otherwise specified, the following values require that you pass the TargetArrayPtr parameter the address of an array of type double (with a size of the number of currently included blobs (MblobGetNumber()).) .

Open Collapse Value Description
Open Collapse M_AXIS_PRINCIPAL_ANGLE

Returns the angle at which each blob has the least moment of inertia. For elongated blobs, it is aligned with the longest axis. The result is always between -90° and +90°, measured in a counter-clockwise direction from the positive X-axis. Returns the angle at which each blob has the least moment of inertia ...

When the blob identifier image is calibrated, this feature is calculated in calibrated units, otherwise it is calculated in pixel units.

Open Collapse M_AXIS_SECONDARY_ANGLE

Returns the angle perpendicular to M_AXIS_PRINCIPAL_ANGLE of each blob. It is always between -90° and +90°. Returns the angle perpendicular to M_AXIS_PRINCIPAL_ANGLE of each blob ...

Open Collapse M_CENTER_OF_GRAVITY_X

Returns the X-position of the center of gravity of each blob. Returns the X-position of the center of gravity of each blob.

Open Collapse M_CENTER_OF_GRAVITY_Y

Returns the Y-position of the center of gravity of each blob. Returns the Y-position of the center of gravity of each blob.

Open Collapse M_MOMENT_CENTRAL_Xn_Ym

Returns the calculation of central moments for each blob. Returns the calculation of central moments for each blob ...

Results are only available in pixel units.

Open Collapse M_MOMENT_Xn_Ym

Returns the calculation of ordinary moments for each blob. Returns the calculation of ordinary moments for each blob ...

Results are only available in pixel units.

[Combination constants]

You can add one of the following values to the Feature parameter only for those features that have two definitions, and both versions have been calculated.

Open Collapse Value | Description
Open Collapse M_BINARY | Returns the result for the binary version of the selected feature. Returns the result for the binary version of the selected feature.
Open Collapse M_GRAYSCALE | Returns the result for the grayscale version of the selected feature. Returns the result for the grayscale version of the selected feature ... This is the default value.

[Combination constants]

The values below can be added to the Feature parameter to cast the requested results to a required data type. For example, M_AREA + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_CHAR | Casts the requested results to a char. Casts the requested results to a char ...
 |  | TargetArrayPtr info Data type: array of type char Array size: Number of currently included blobs (MblobGetNumber()).
Open Collapse M_TYPE_DOUBLE | Casts the requested results to a double. Casts the requested results to a double ... This is the default value.
 |  | TargetArrayPtr info Data type: array of type double Array size: Number of currently included blobs (MblobGetNumber()).
Open Collapse M_TYPE_FLOAT | Casts the requested results to a float. Casts the requested results to a float ...
 |  | TargetArrayPtr info Data type: array of type float Array size: Number of currently included blobs (MblobGetNumber()).
Open Collapse M_TYPE_LONG | Casts the requested results to a long. Casts the requested results to a long ...
 |  | TargetArrayPtr info Data type: array of type long Array size: Number of currently included blobs (MblobGetNumber()).
Open Collapse M_TYPE_SHORT | Casts the requested results to a short. Casts the requested results to a short ...
 |  | TargetArrayPtr info Data type: array of type short Array size: Number of currently included blobs (MblobGetNumber()).
TargetArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type char
  • array of type double
  • array of type float
  • array of type long
  • array of type short

Specifies the address of the array in which to write results. Each blob creates a separate result entry. Only results for blobs that are currently included are obtained.

You can set this parameter to M_NULL to put the result request on the local queue of the result buffer.

LENGTH BREADTH WHOLE IMAGE INDIVIDUAL FERET MAX DIAMETER FERET MIN DIAMETER FIRST POINT Y FIRST POINT X EULER NUMBER INDIVIDUAL PERIMETER CONVEX PERIMETER AXIS PRINCIPAL ANGLE TYPE LONG AREA BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN BREADTH COMPACTNESS CONVEX PERIMETER ELONGATION EULER NUMBER FERET ELONGATION FERET MAX ANGLE FERET MAX DIAMETER FERET MEAN DIAMETER FERET MIN ANGLE FERET MIN DIAMETER FERET X FERET Y FIRST POINT X FIRST POINT Y GENERAL FERET GENERAL MOMENT INTERCEPT 0 INTERCEPT 45 INTERCEPT 90 INTERCEPT 135 LABEL VALUE LENGTH NUMBER OF CHAINED PIXELS NUMBER OF HOLES NUMBER OF RUNS PERIMETER ROUGHNESS X MAX AT Y MAX X MIN AT Y MIN Y MAX AT X MIN Y MIN AT X MAX MAX PIXEL MEAN PIXEL MIN PIXEL SIGMA PIXEL SUM PIXEL SUM PIXEL SQUARED AXIS PRINCIPAL ANGLE AXIS SECONDARY ANGLE CENTER OF GRAVITY X CENTER OF GRAVITY Y MOMENT CENTRAL Xn Ym MOMENT Xn Ym BINARY GRAYSCALE TYPE CHAR TYPE DOUBLE TYPE FLOAT TYPE LONG TYPE SHORT


MblobGetResultSingle

See Also | Example | Availability | MblobGetResult | MblobGetRuns
User Guide:
Steps to performing blob analysis
Moments
Location, length and number of runs

Reference:
MblobCalculate
MblobControl
MblobGetLabel
MblobGetNumber
MblobGetResult
MblobSelect
There are no examples containing MblobGetResultSingle().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Orion
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Get results for a feature of a single blob.
Syntax
void MblobGetResultSingle(
MIL_ID BlobResId,
long LabelVal,
long Feature,
void *TargetVarPtr
)
Description

This function retrieves the result for a specified feature, for a specific blob, from the blob analysis result buffer. The blob for which to obtain the result is determined by its label value.

If the blob identifier images is associated with a calibration object, you can retrieve results in real-world or in pixel units, unless otherwise specified. When returned in pixel units, the pixel aspect ratio, specified with MblobControl() with M_PIXEL_ASPECT_RATIO, is taken into account horizontally. In this case, results are returned in units of "pixel height" since the pixel width is adjusted to be equal to the pixel height. Note, all positional results are relative to the top-left pixel in the target image or the origin of the world-coordinate if the image is calibrated.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set TargetVarPtr to M_NULL. When this parameter is set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when you pass the parameter an array instead. You must ensure that the array is sufficiently large to hold the current and previously queued results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer from which to get the result.

LabelVal

Specifies the label value of the blob for which to get the result. The label value can be obtained, using MblobGetLabel() or MblobGetResult(). Note, you cannot obtain results for blobs that have been deleted from the result buffer, using MblobSelect().

Feature

Specifies the feature for which to retrieve results. The specified feature must have already been calculated with MblobCalculate().

To retrieve the result for a grayscale feature, select one of the following:

Unless otherwise specified, the following values require that you pass the TargetVarPtr parameter the address of an array of type double (with a size of the number of currently included blobs. This number can be obtained, using MblobGetNumber().) .

Open Collapse Value | Description | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_AREA | Returns the number of foreground pixels in each blob (holes are not counted). Returns the number of foreground pixels in each blob (holes are not counted). | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_BOX_X_MAX | Returns the extreme right coordinate of each blob. Returns the extreme right coordinate of each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_BOX_X_MIN | Returns the extreme left coordinate of each blob. Returns the extreme left coordinate of each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_BOX_Y_MAX | Returns the extreme bottom coordinate of each blob. Returns the extreme bottom coordinate of each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_BOX_Y_MIN | Returns the extreme top coordinate of each blob. Returns the extreme top coordinate of each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_BREADTH | Returns a measure of the true breadth of each blob. Returns a measure of the true breadth of each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_CHAIN_INDEX | Returns the indices which differentiate each chain's pixels within each blob. The blob's bordering chain is identified as index 1. Chained pixels that delimit holes in blobs are identified by subsequent indexes for each chain. Returns the indices which differentiate each chain's pixels within each blob ... | a | b |  | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_CHAIN_X | Returns the X-coordinate of each chained pixel in each blob, for all chains contained within the blob. Returns the X-coordinate of each chained pixel in each blob, for all chains contained within the blob ... Results are only available in pixel units. | a | b |  | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_CHAIN_Y | Returns the Y-coordinate of each chained pixel in each blob, for all chains contained within the blob. Returns the Y-coordinate of each chained pixel in each blob, for all chains contained within the blob ... Results are only available in pixel units. | a | b |  | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_COMPACTNESS | Returns the compactness of each blob. Returns the compactness of each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_CONVEX_PERIMETER | Returns an approximation of the perimeter of the convex hull of a blob. Returns an approximation of the perimeter of the convex hull of a blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_ELONGATION | Returns a value that is equal to M_LENGTH / M_BREADTH of each blob. Returns a value that is equal to M_LENGTH / M_BREADTH of each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_EULER_NUMBER | Returns the number of blobs - number of holes. This value is more useful for M_WHOLE_IMAGE than for M_INDIVIDUAL processing mode. Returns the number of blobs - number of holes ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FERET_ELONGATION | Returns a measure of the shape of a blob. It is equal to M_FERET_MAX_DIAMETER / M_FERET_MIN_DIAMETER. Returns a measure of the shape of a blob ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FERET_MAX_ANGLE | Returns the angle at which the maximum Feret diameter is found for each blob. The value is in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis. Returns the angle at which the maximum Feret diameter is found for each blob ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FERET_MAX_DIAMETER | Returns the largest Feret diameter found after checking a certain number of angles. Returns the largest Feret diameter found after checking a certain number of angles. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FERET_MEAN_DIAMETER | Returns the average of the Feret diameters at the angles checked for each blob. Returns the average of the Feret diameters at the angles checked for each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FERET_MIN_ANGLE | Returns the angle at which the minimum Feret diameter is found. The value is in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis. Returns the angle at which the minimum Feret diameter is found ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FERET_MIN_DIAMETER | Returns the smallest Feret diameter found after checking a certain number of angles. Returns the smallest Feret diameter found after checking a certain number of angles. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FERET_X | Returns the dimension of the minimum bounding box of each blob, in the horizontal direction. Returns the dimension of the minimum bounding box of each blob, in the horizontal direction. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FERET_Y | Returns the dimension of the minimum bounding box of each blob, in the vertical direction. Returns the dimension of the minimum bounding box of each blob, in the vertical direction. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FIRST_POINT_X | Returns (along with M_FIRST_POINT_Y) a unique point for each blob, that is always on the perimeter of the blob. The X-coordinate is that of the left-most pixel on the top-most line of the blob. Returns (along with M_FIRST_POINT_Y) a unique point for each blob, that is always on the perimeter of the blob ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_FIRST_POINT_Y | Returns (along with M_FIRST_POINT_X) a unique point for each blob, that is always on the perimeter of the blob. The Y-coordinate is that of the topmost line of the blob. Returns (along with M_FIRST_POINT_X) a unique point for each blob, that is always on the perimeter of the blob ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_GENERAL_FERET | Returns the Feret diameter at the specified angle. Returns the Feret diameter at the specified angle. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_GENERAL_MOMENT | Returns the moment calculation. Returns the moment calculation. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_INTERCEPT_0 | Returns the number of times a transition from background to foreground (not vice versa) occurs in the horizontal direction for the entire blob. In other words, it is equal to the number of times the neighborhood configuration [B, F] occurs in a blob, where B is a background pixel and F is a foreground pixel. Returns the number of times a transition from background to foreground (not vice versa) occurs in the horizontal direction for the entire blob ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_INTERCEPT_45 | Returns the number of times that the neighborhood configuration [image] occurs in a blob, where F is a foreground pixel, B is a background pixel and a dot can be any pixel value. Returns the number of times that the neighborhood configuration [image] occurs in a blob, where F is a foreground pixel, B is a background pixel and a dot can be any pixel value. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_INTERCEPT_90 | Returns the number of times that the neighborhood configuration [image] occurs in a blob. Returns the number of times that the neighborhood configuration [image] occurs in a blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_INTERCEPT_135 | Returns the number of times that the neighborhood configuration [image] occurs in a blob. Returns the number of times that the neighborhood configuration [image] occurs in a blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_LABEL_VALUE | Returns the label value for each blob in an image. This is a positive integer (>= 1) that is unique for each blob. Returns the label value for each blob in an image ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_LENGTH | Returns a measure of the true length of an object, although it is only accurate for certain object types (for example, long thin ones) because it is derived from the perimeter (P) and area (A) assuming that P = 2(length + breadth) and A = length x breadth. Returns a measure of the true length of an object, although it is only accurate for certain object types (for example, long thin ones) because it is derived from the perimeter (P) and area (A) assuming that P = 2(length + breadth) and A = length x breadth. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_NUMBER_OF_CHAINED_PIXELS | Returns the number of chained pixels for each blob. Returns the number of chained pixels for each blob. | a | b |  | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_NUMBER_OF_HOLES | Returns the number of holes in each blob. Holes that intersect the edge of the image are not counted (they might not be holes). This value is equal to 1 - M_EULER_NUMBER and is therefore a true hole count if calculated using the M_INDIVIDUAL processing mode. Returns the number of holes in each blob ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_NUMBER_OF_RUNS | Returns the total number of runs in each blob. Returns the total number of runs in each blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_PERIMETER | Returns the total length of edges in a blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized (inside corners are counted as 1.414, rather than 2.0). A single pixel blob (area = 1) has a perimeter of 4.0. Returns the total length of edges in a blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized (inside corners are counted as 1.414, rather than 2.0) ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_ROUGHNESS | Returns a measure of how rough each blob is and is equal to M_PERIMETER / M_CONVEX_PERIMETER. A smooth convex blob will have the minimum roughness of 1.0. Returns a measure of how rough each blob is and is equal to M_PERIMETER / M_CONVEX_PERIMETER ... | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_X_MAX_AT_Y_MAX | Returns the maximum X-coordinate at the maximum Y-coordinate of the blob. Returns the maximum X-coordinate at the maximum Y-coordinate of the blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_X_MIN_AT_Y_MIN | Returns the minimum X-coordinate at the minimum Y-coordinate of the blob. Returns the minimum X-coordinate at the minimum Y-coordinate of the blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_Y_MAX_AT_X_MIN | Returns the maximum Y-coordinate at the minimum X-coordinate of the blob. Returns the maximum Y-coordinate at the minimum X-coordinate of the blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_Y_MIN_AT_X_MAX | Returns the minimum Y-coordinate at the maximum X-coordinate of the blob. Returns the minimum Y-coordinate at the maximum X-coordinate of the blob. | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r

The following features require grayscale pixel values, and were calculated only if you provided a grayscale image.

Unless otherwise specified, the following values require that you pass the TargetVarPtr parameter the address of an array of type double (with a size of the number of currently included blobs. This number can be obtained using MblobGetNumber().) .

Open Collapse Value | Description
Open Collapse M_MAX_PIXEL | Returns the maximum pixel value found in a blob. Returns the maximum pixel value found in a blob.
Open Collapse M_MEAN_PIXEL | Returns the mean pixel value in a blob. Returns the mean pixel value in a blob.
Open Collapse M_MIN_PIXEL | Returns the minimum pixel value found in a blob. Returns the minimum pixel value found in a blob.
Open Collapse M_SIGMA_PIXEL | Returns the standard deviation of pixel values in a blob. Returns the standard deviation of pixel values in a blob.
Open Collapse M_SUM_PIXEL | Returns the sum of all pixel values in a blob. Returns the sum of all pixel values in a blob.
Open Collapse M_SUM_PIXEL_SQUARED | Returns the sum of the squares of each pixel value in a blob. Returns the sum of the squares of each pixel value in a blob.

To retrieve the result for a feature that has two different definitions (a binary and a grayscale definition), select one of the following values.

If you did not provide both a blob identifier image and a grayscale image, only the binary version was calculated. If you did provide a grayscale image, both versions were calculated, unless otherwise specified. To specify which result to retrieve, see the combination values below. If both versions were calculated and no version is specified, then the grayscale version of the feature is retrieved.

Unless otherwise specified, the following values require that you pass the TargetVarPtr parameter the address of an array of type double (with a size of the number of currently included blobs (MblobGetNumber())) .

Open Collapse Value | Description
Open Collapse M_AXIS_PRINCIPAL_ANGLE | Returns the angle at which each blob has the least moment of inertia. For elongated blobs, it is aligned with the longest axis. The result is always between -90° and +90°, measured in a counter-clockwise direction from the positive X-axis. When the blob identifier image is calibrated this feature is calculated in calibrated units; otherwise they are calculated in pixel units. Returns the angle at which each blob has the least moment of inertia ...
Open Collapse M_AXIS_SECONDARY_ANGLE | Returns the angle perpendicular to M_AXIS_PRINCIPAL_ANGLE. It is always between -90° and +90°. Returns the angle perpendicular to M_AXIS_PRINCIPAL_ANGLE ...
Open Collapse M_CENTER_OF_GRAVITY_X | Returns the X-position of the center of gravity of each blob. Returns the X-position of the center of gravity of each blob.
Open Collapse M_CENTER_OF_GRAVITY_Y | Returns the Y-position of the center of gravity of each blob. Returns the Y-position of the center of gravity of each blob.
Open Collapse M_MOMENT_CENTRAL_Xn_Ym | Returns the calculation of central moments for each blob. Returns the calculation of central moments for each blob ... Results are only available in pixel units.
Open Collapse M_MOMENT_Xn_Ym | Returns the calculation of ordinary moments for each blob. Returns the calculation of ordinary moments for each blob ... Results are only available in pixel units.

[Combination constants]

You can add one of the following values to the Feature parameter only for those features that have two definitions, and both versions have been calculated.

Open Collapse Value | Description
Open Collapse M_BINARY | Returns the result for the binary version of the selected feature. Returns the result for the binary version of the selected feature.
Open Collapse M_GRAYSCALE | Returns the result for the grayscale version of the selected feature. Returns the result for the grayscale version of the selected feature ... This is the default value.

[Combination constants]

The values below can be added to the Feature parameter to cast the requested results to a required data type. For example, M_AXIS_PRINCIPAL_ANGLE + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_CHAR | Casts the requested results to a char. Casts the requested results to a char ...
 |  | TargetVarPtr info Data type: array of type char Array size: Number of currently included blobs (MblobGetNumber()).
Open Collapse M_TYPE_DOUBLE | Casts the requested results to a double. Casts the requested results to a double ... This is the default value.
 |  | TargetVarPtr info Data type: array of type double Array size: Number of currently included blobs (MblobGetNumber()).
Open Collapse M_TYPE_FLOAT | Casts the requested results to a float. Casts the requested results to a float ...
 |  | TargetVarPtr info Data type: array of type float Array size: Number of currently included blobs (MblobGetNumber()).
Open Collapse M_TYPE_LONG | Casts the requested results to a long. Casts the requested results to a long ...
 |  | TargetVarPtr info Data type: array of type long Array size: Number of currently included blobs (MblobGetNumber()).
Open Collapse M_TYPE_SHORT | Casts the requested results to a short. Casts the requested results to ashort ...
 |  | TargetVarPtr info Data type: array of type short Array size: Number of currently included blobs (MblobGetNumber()).
TargetVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type char
  • array of type double
  • array of type float
  • array of type long
  • array of type short

Specifies the address in which to write the result retrieved from the blob analysis result buffer.

You can set this parameter to M_NULL to put the result request on the local queue of the result buffer.

PIXEL ASPECT RATIO LENGTH BREADTH WHOLE IMAGE INDIVIDUAL FERET MAX DIAMETER FERET MIN DIAMETER FIRST POINT Y FIRST POINT X EULER NUMBER INDIVIDUAL PERIMETER CONVEX PERIMETER AXIS PRINCIPAL ANGLE AXIS PRINCIPAL ANGLE TYPE LONG AREA BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN BREADTH CHAIN INDEX CHAIN X CHAIN Y COMPACTNESS CONVEX PERIMETER ELONGATION EULER NUMBER FERET ELONGATION FERET MAX ANGLE FERET MAX DIAMETER FERET MEAN DIAMETER FERET MIN ANGLE FERET MIN DIAMETER FERET X FERET Y FIRST POINT X FIRST POINT Y GENERAL FERET GENERAL MOMENT INTERCEPT 0 INTERCEPT 45 INTERCEPT 90 INTERCEPT 135 LABEL VALUE LENGTH NUMBER OF CHAINED PIXELS NUMBER OF HOLES NUMBER OF RUNS PERIMETER ROUGHNESS X MAX AT Y MAX X MIN AT Y MIN Y MAX AT X MIN Y MIN AT X MAX MAX PIXEL MEAN PIXEL MIN PIXEL SIGMA PIXEL SUM PIXEL SUM PIXEL SQUARED AXIS PRINCIPAL ANGLE AXIS SECONDARY ANGLE CENTER OF GRAVITY X CENTER OF GRAVITY Y MOMENT CENTRAL Xn Ym MOMENT Xn Ym BINARY GRAYSCALE TYPE CHAR TYPE DOUBLE TYPE FLOAT TYPE LONG TYPE SHORT


MblobGetRuns

See Also | Example | Availability | MblobGetResultSingle | MblobInquire
User Guide:
Steps to performing blob analysis
Moments
Location, length and number of runs

Reference:
MblobCalculate
MblobGetLabel
MblobGetResult
MblobGetResultSingle
MblobSelectFeature
There are no examples containing MblobGetRuns().
Not available in MIL-Lite

Available in MIL
Synopsis
Get the blob run-length encoding information.
Syntax
void MblobGetRuns(
MIL_ID BlobResId,
long LabelVal,
long ArrayType,
void *RunXPtr,
void *RunYPtr,
void *RunLengthPtr
)
Description

This function obtains the coordinate and length of each run (unbroken horizontal sequence of foreground pixels) in a specified blob, from the blob analysis result buffer. Prior to using this function, M_NUMBER_OF_RUNS must have been added to the feature list, using MblobSelectFeature(), and a call to MblobCalculate() must have been made.

The coordinate and length arrays must be large enough to hold information for all runs in the specified blob. The number of runs for a blob can be obtained, using MblobGetResult() or MblobGetResultSingle(). The number of runs, as well as the run-length encoding results, are given in raw pixel values and are not affected by the pixel aspect ratio.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set the RunXPtr, RunYPtr and RunLengthPtr parameters to M_NULL. When all these result parameters are set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when at least one result parameter is passed an array. You must ensure that the coordinate and length arrays are sufficiently large to hold all the requested results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer.

LabelVal

Specifies the label value of the blob for which to get run information. The label value for a blob can be obtained, using MblobGetLabel() or MblobGetResult(). You cannot obtain run-encoding information for blobs that have been deleted from the result buffer.

ArrayType

Sets the type of the arrays in which the coordinate and length of the runs for a blob will be returned. This parameter can be set to one of the following values:

The following values require that you pass the value listed in the data-type area to the specified parameter.

Open Collapse Value | Description
Open Collapse M_TYPE_CHAR | Returns an array of type char. Returns an array of type char ...
 |  | RunXPtr info Data type: array of type char Array size: Large enough to hold the number of currently included blobs.
Open Collapse M_TYPE_LONG | Returns an array of type long. Returns an array of type long ...
 |  | RunXPtr info Data type: array of type float Array size: Large enough to hold the number of currently included blobs.
Open Collapse M_TYPE_SHORT | Returns an array of type short. Returns an array of type short ...
 |  | RunXPtr info Data type: array of type short Array size: Large enough to hold the number of currently included blobs.
RunXPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type char
  • array of type float
  • array of type short

Specifies the address of the array in which to write the X-coordinate of the start (left-most pixel) of each run in the specified blob.

Note, you can set RunXPtr to M_NULL if the X-coordinate is not required.

RunYPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type char
  • array of type float
  • array of type short

Specifies the address of the array in which to write the Y-coordinate of the start of each run in the specified blob.

Note, you can set RunYPtr to M_NULL if the Y-coordinate is not required.

RunLengthPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type char
  • array of type float
  • array of type short

Specifies the address of the array in which to write the length of each run in the specified blob.

Note, you can set RunLengthPtr to M_NULL if the length of each run is not required.

NUMBER OF RUNS TYPE CHAR TYPE LONG TYPE SHORT


MblobInquire

See Also | Example | Availability | MblobGetRuns | MblobLabel
Reference:
MblobCalculate
MblobControl
MblobLabel
There are no examples containing MblobInquire().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Genesis

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Inquire about a blob analysis context.
Syntax
long MblobInquire(
MIL_ID BlobResId,
long InquireType,
void *UserVarPtr
)
Description

This function performs an inquiry on the specified processing feature associated with the blob analysis result buffer.

You can use MblobControl() to change a processing feature associated with a result buffer.

Parameters
BlobResId

Specifies the identifier of a blob analysis result buffer.

[Matrox Genesis]

This parameter can also specify the identifier of a feature list.

InquireType

Specifies the feature about which to inquire.

To inquire about the blob analysis result buffer features, this parameter can be set to one of the following values:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_BLOB_IDENTIFICATION

Returns the blob identification mode that was selected. Returns the blob identification mode that was selected ...

UserVarPtr info

Return values:
M_INDIVIDUAL, M_LABELED, M_WHOLE_IMAGE (details)
Open Collapse M_FOREGROUND_VALUE

Returns the pixel values that are considered to be in the foreground. Returns the pixel values that are considered to be in the foreground ...

UserVarPtr info

Return values:
M_NONZERO, M_ZERO (details)
Open Collapse M_IDENTIFIER_TYPE

Returns the values that the non-zero pixels in the image have. Returns the values that the non-zero pixels in the image have ...

UserVarPtr info

Return values:
M_BINARY, M_GRAYSCALE (details)
Open Collapse M_LATTICE

Returns the image lattice. Returns the image lattice ...

UserVarPtr info

Return values:
M_4_CONNECTED, M_8_CONNECTED (details)
Open Collapse M_MAX_LABEL

Returns the maximum label value given to any included blob in the result buffer. Returns the maximum label value given to any included blob in the result buffer ...

Label values for blobs are generated when a call to MblobCalculate() is made. The maximum label value is not necessarily the same as the total number of blobs because some label values might not be used, depending on the blob's shape. One of the uses for obtaining the maximum label value is to determine if an 8 or 16-bit image buffer is needed for MblobLabel().

Open Collapse M_NUMBER_OF_FERETS

Returns the number of Feret angles set to calculate a Feret feature. Returns the number of Feret angles set to calculate a Feret feature ...

UserVarPtr info

Return values:
M_MAX_FERETS, M_MIN_FERETS, Value (details)
Open Collapse M_OWNER_SYSTEM

Returns the identifier of the system on which the result buffer is allocated. Returns the identifier of the system on which the result buffer is allocated.

Open Collapse M_PIXEL_ASPECT_RATIO

Returns the pixel aspect ratio that you set for the image(s). Returns the pixel aspect ratio that you set for the image(s) ...

UserVarPtr info

Return values:
Please see MblobControl() with M_PIXEL_ASPECT_RATIO.

Open Collapse M_SAVE_RUNS

Returns whether the run information will be saved when calling MblobCalculate(). Returns whether the run information will be saved when calling MblobCalculate() ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

[Combination constants]

The values below can be added to the InquireType parameter to cast the requested information to the required data type. For example, M_BLOB_IDENTIFICATION + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_DOUBLE | Casts the requested information to a double. This is the default. Casts the requested information to a double ...
 |  | UserVarPtr info Data type: double
Open Collapse M_TYPE_LONG | Casts the requested information to a long. Casts the requested information to a long ...
 |  | UserVarPtr info Data type: long
[Combination constants]
[Matrox Genesis]

To inquire about an identifier when a blob analysis result buffer or a feature list identifier is specified, the following must be added to the InquireType parameter.

Open Collapse Value Description
Open Collapse M_NATIVE_ID

 Returns the Native Library identifier associated with the specified MIL blob result or feature list identifier.  Returns the Native Library identifier associated with the specified MIL blob result or feature list identifier.

 UserVarPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • double
    •

  • long
    •

 Specifies the address in which the inquiry result will be written.

Return value

 Returns the requested information, cast to a long.

BLOB IDENTIFICATION TYPE LONG   BLOB IDENTIFICATION FOREGROUND VALUE IDENTIFIER TYPE  LATTICE MAX LABEL NUMBER OF FERETS OWNER SYSTEM PIXEL ASPECT RATIO SAVE RUNS TYPE DOUBLE TYPE LONG NATIVE ID


MblobLabel

See Also | Example | Availability | MblobInquire | MblobReconstruct
User Guide:
Making feature extractions
Blob reconstruction

Reference:
MblobCalculate
MblobInquire
There are no examples containing MblobLabel().
Not available in MIL-Lite

Available in MIL
Synopsis
Draw a labeled image.
Syntax
void MblobLabel(
MIL_ID BlobResId,
MIL_ID DestImageBufId,
long Mode
)
Description

This function draws a labeled image in which each blob existing in the specified result buffer is represented with its own unique label value.

The label values are taken from the blob analysis result buffer. A call to MblobCalculate() must have been made to generate label values for an image. Blobs that have been deleted from the result buffer are not drawn.

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer.

DestImageBufId

Specifies the identifier of the destination (labeled) image buffer. This must be a single band, 8 or 16-bit unsigned buffer.

Note, this buffer need not be the same size as the original identifier image used to calculate the blobs, but must be 16 bits deep if the maximum label value exceeds 255. To determine if a 16-bit buffer is necessary, perform an M_MAX_LABEL inquiry, using MblobInquire(). The number of blobs alone does not tell you the maximum label value (label values are not necessarily contiguous).

Mode

Specifies whether or not to clear the destination image buffer before drawing the labeled image into it. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_CLEAR

 Clears the destination image buffer before placing the labeled image into it.  Clears the destination image buffer before placing the labeled image into it.

  Open   Collapse  M_NO_CLEAR

 Does not clear the destination image buffer before placing the labeled image into it (background pixels will be unchanged).  Does not clear the destination image buffer before placing the labeled image into it (background pixels will be unchanged).

MAX LABEL    CLEAR
 NO CLEAR


MblobReconstruct

See Also | Example | Availability | MblobLabel | MblobSelect
User Guide:
Custom morphological operations
Blob reconstruction

Reference:
MimErode
There are no examples containing MblobReconstruct().
Not available in MIL-Lite

Available in MIL
Synopsis
Reconstruct blobs (or blob holes) in an image buffer.
Syntax
void MblobReconstruct(
MIL_ID SrcImageBufId,
MIL_ID SeedImageBufId,
MIL_ID DestImageBufId,
long Operation,
long ProcMode
)
Description

This function copies (or reconstructs) blobs or blob holes from the source to the destination buffer, according to the specified operation and processing mode. By default, all non-zero pixels in the source buffer are considered to be part of a blob. Use the M_FOREGROUND_ZERO processing mode to inverse this behavior.

Parameters
SrcImageBufId

Specifies the identifier of the source image buffer. The source buffer must be a single band, packed binary, 8- or 16-bit unsigned buffer.

SeedImageBufId

Specifies the identifier of the image buffer to use as a seed image. The seed image buffer must be a single band, packed binary, 8- or 16-bit unsigned buffer.

A seed image is needed to perform an M_RECONSTRUCT_FROM_SEED type of operation. For any other operation type, set this parameter to M_NULL.

DestImageBufId

Specifies the identifier of the destination (processed blobs) image buffer. The destination buffer must be a single band, packed binary, 8- or 16-bit unsigned buffer.

Operation

Specifies the type of operation to perform. This parameter can be set to one of the following values:

Open Collapse Value Description
Open Collapse M_ERASE_BORDER_BLOBS

 All blobs that do not touch the borders of the source image are copied to the destination image buffer according to the selected processing mode. Pixels of the blobs that touch the border are replaced according to the selected processing mode.  All blobs that do not touch the borders of the source image are copied to the destination image buffer according to the selected processing mode ...

 Note that when the M_GRAYSCALE and M_FOREGROUND_ZERO processing modes are selected, the border blobs are filled with the average grayscale pixel value of the background. This operation is similar to a "border kill".

  Open   Collapse  M_EXTRACT_HOLES

 All holes within the blobs of the source buffer are copied to the destination buffer with their pixel values set to their corresponding blob's pixel values, according to the selected processing mode. A hole cannot touch any image border in order to be considered a hole.  All holes within the blobs of the source buffer are copied to the destination buffer with their pixel values set to their corresponding blob's pixel values, according to the selected processing mode ...

 Note that, in the M_GRAYSCALE processing mode, the pixel values of holes copied to the destination buffer are set to the blob's average grayscale pixel value in the source buffer. Also, when the M_GRAYSCALE and M_FOREGROUND_ZERO processing modes are selected, the blobs are filled with the average grayscale pixel value of the background.

  Open   Collapse  M_FILL_HOLES

 All blobs in the source buffer are copied to the destination buffer according to the selected processing mode, and those blobs with holes are filled according to the processing mode. A hole must not touch the border of the image in order to be considered a hole.  All blobs in the source buffer are copied to the destination buffer according to the selected processing mode, and those blobs with holes are filled according to the processing mode ...

 Note that when the M_GRAYSCALE processing mode is selected, holes are filled with the average grayscale pixel value of the corresponding blob.

  Open   Collapse  M_RECONSTRUCT_FROM_SEED

 All blobs in the source buffer that have at least one corresponding foreground seed pixel in the seed buffer are copied to the destination buffer, according to the selected processing mode. Blobs that are not seeded are replaced according to the selected processing mode.  All blobs in the source buffer that have at least one corresponding foreground seed pixel in the seed buffer are copied to the destination buffer, according to the selected processing mode ...

 Note that when the M_GRAYSCALE and M_FOREGROUND_ZERO processing modes are selected, blobs in the source image that are not seeded are filled with the average grayscale value of the background. Also, the value of the seed pixels must be strictly zero for this operation to be performed properly.

 Note that the seed image and the destination image must have identical dimensions.

 ProcMode

 Specifies the processing mode to use. This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default processing mode (which corresponds to M_BINARY + M_8_CONNECTED).  Specifies the default processing mode (which corresponds to M_BINARY + M_8_CONNECTED).

  Open   Collapse  Combination value

 Specifies that the processing mode is set using the values listed in the sets of combination constants below. If no value from a set is specified, the default is used. For example, specifying only M_GRAYSCALE + M_FOREGROUND_ZERO also specifies a processing mode with M_8_CONNECTED connectivity and no acceleration of blob reconstruction with seed images (M_SEED_PIXELS_ALL_IN_BLOBS).  Specifies that the processing mode is set using the values listed in the sets of combination constants below ...

      [Combination constants]

 The following values allow you to select how pixel values are set.

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Specifies that non-zero pixel values will be treated as ones (1) during processing, and the resulting non-zero pixels copied to the destination buffer will be set to the maximum value of that buffer (for example, 0xff for an 8-bit buffer). Note, in general, the M_BINARY processing mode is faster.  Specifies that non-zero pixel values will be treated as ones (1) during processing, and the resulting non-zero pixels copied to the destination buffer will be set to the maximum value of that buffer (for example, 0xff for an 8-bit buffer) ...

This is the default value.

  Open   Collapse  M_GRAYSCALE

 Specifies that the values of pixels copied to the destination buffer will be changed to the values of corresponding pixels in the source buffer.  Specifies that the values of pixels copied to the destination buffer will be changed to the values of corresponding pixels in the source buffer.

      [Combination constants]

 One of the following values can be added to the ProcMode parameter to select the type of connectivity (lattice).

  Open   Collapse  Value
Description

  Open   Collapse  M_4_CONNECTED

 Specifies that blobs are computed on a four connected lattice.  Specifies that blobs are computed on a four connected lattice.

  Open   Collapse  M_8_CONNECTED

 Specifies that blobs are computed on an eight connected lattice.  Specifies that blobs are computed on an eight connected lattice ...

This is the default value.

      [Combination constants]

 The following value can be added to the ProcMode parameter to select the value of the foreground pixels (this value is not set by default).

  Open   Collapse  Value
Description

  Open   Collapse  M_FOREGROUND_ZERO

 Specifies that the pixel values of blobs will consist of zero values and the pixels of the background will consists of non-zero values; that is, the inverse of the usual blob pixel value definition.  Specifies that the pixel values of blobs will consist of zero values and the pixels of the background will consists of non-zero values; that is, the inverse of the usual blob pixel value definition.

      [Combination constants]

 The following value can be added to the ProcMode parameter to accelerate blob reconstruction with seed images (this value is not set by default).

  Open   Collapse  Value
Description

  Open   Collapse  M_SEED_PIXELS_ALL_IN_BLOBS

 Optimizes the reconstruction process. Use this value in cases when all seed pixels in the seed buffer have corresponding blob pixels in the source buffer. This condition often exists when the seed buffer is an eroded (see MimErode()) version of the source buffer.  Optimizes the reconstruction process ...

Remark

  •  This function is optimized for packed binary buffers.
    •

FOREGROUND ZERO RECONSTRUCT FROM SEED GRAYSCALE FOREGROUND ZERO GRAYSCALE GRAYSCALE FOREGROUND ZERO GRAYSCALE GRAYSCALE FOREGROUND ZERO BINARY 8 CONNECTED GRAYSCALE FOREGROUND ZERO 8 CONNECTED SEED PIXELS ALL IN BLOBS BINARY     ERASE BORDER BLOBS
                 EXTRACT HOLES  FILL HOLES  RECONSTRUCT FROM SEED
                  DEFAULT  BINARY GRAYSCALE
                   4 CONNECTED 8 CONNECTED FOREGROUND ZERO SEED PIXELS ALL IN BLOBS


MblobSelect

See Also | Example | Availability | MblobReconstruct | MblobSelectFeature
User Guide:
Steps to performing blob analysis
Selecting blobs
Making feature extractions
Blob reconstruction

Reference:
MblobCalculate
MblobControl
MblobSelectFeature
MblobSelectFeret
MblobSelectMoment
mblob.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Select blobs for calculations and result retrieval.
Syntax
void MblobSelect(
MIL_ID BlobResId,
long Operation,
long SelectionCriterion,
long Condition,
double CondLow,
double CondHigh
)
Description

This function selects blobs that meet a specified criterion. These blobs will be included in or excluded from future operations (calculations or result retrieval), or deleted entirely from the result buffer. Selection criterion can be based on a calculated feature or on the current status of the blobs. MblobCalculate() must have been called at least once to call this function.

If this function is not called at least once, all blobs are included by default. If there is more than one call to this function, the effect of the calls is cumulative unless M_INCLUDE_ONLY or M_EXCLUDE_ONLY is specified as the operation to perform.

Once a blob has been excluded, it can normally be re-included only by specifying M_INCLUDE or M_INCLUDE_ONLY in a future call to this function (with the correct criterion). However, if you change the processing mode of a result buffer (with MblobControl()), or use the result buffer with different images (in a call to MblobCalculate()), all results in the buffer are discarded and all blobs are re-included.

Parameters
BlobResId

Specifies the identifier of the blob analysis result buffer to use in the blob selection process.

Operation

Specifies the operation to perform on the specified blobs. This parameter can be set to one of the following.

Open Collapse Value Description
Open Collapse M_DELETE

 Deletes blobs that meet the specified condition. M_DELETE affects only included blobs, unless otherwise stated by the SelectionCriterion parameter.  Deletes blobs that meet the specified condition ...

M_DELETE removes blobs permanently from the result buffer and, consequently, prevents these blobs from being re-included.

  Open   Collapse  M_EXCLUDE

 Excludes all blobs that meet the specified condition.  Excludes all blobs that meet the specified condition ...

M_EXCLUDE affects only the status of currently included blobs.

  Open   Collapse  M_EXCLUDE_ONLY

 Excludes only those blobs that meet the specified condition and includes all others.  Excludes only those blobs that meet the specified condition and includes all others ...

 The exclusion does not consider the present status of blobs (whether they are excluded), except for blobs that have been deleted (M_DELETE), unless otherwise stated by the SelectionCriterion parameter.

  Open   Collapse  M_INCLUDE

 Includes all blobs that meet the specified condition.  Includes all blobs that meet the specified condition ...

M_INCLUDE affects only the status of currently excluded blobs.

  Open   Collapse  M_INCLUDE_ONLY

 Includes only those blobs that meet the specified condition and excludes all others.  Includes only those blobs that meet the specified condition and excludes all others ...

 The inclusion does not consider the present status of blobs (whether they are included), except for blobs that have been deleted (M_DELETE), unless otherwise stated by the SelectionCriterion parameter.

 SelectionCriterion

 Specifies the feature to use as part of the selection criterion or the status of the blobs to affect.  See MblobSelectFeature(), MblobSelectFeret(), and MblobSelectMoment() for a full description of the features. The specified result buffer must already contain the results for the specified feature.

 To use as part of the criterion a feature that has only a binary definition, select one of the following.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_AREA

 Uses the number of foreground pixels in a blob (holes are not counted).  Uses the number of foreground pixels in a blob (holes are not counted).

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX_X_MAX

 Uses the extreme right coordinate of the bounding box of a blob.  Uses the extreme right coordinate of the bounding box of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX_X_MIN

 Uses the extreme left coordinate of the bounding box of a blob.  Uses the extreme left coordinate of the bounding box of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX_Y_MAX

 Uses the extreme bottom coordinate of the bounding box of a blob.  Uses the extreme bottom coordinate of the bounding box of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX_Y_MIN

 Uses the extreme top coordinate of the bounding box of a blob.  Uses the extreme top coordinate of the bounding box of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BREADTH

 Uses the breadth of a blob.  Uses the breadth of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_COMPACTNESS

 Uses the compactness feature.  Uses the compactness feature.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CONVEX_PERIMETER

 Uses the approximation of the perimeter of the convex hull of a blob.  Uses the approximation of the perimeter of the convex hull of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_ELONGATION

 Uses the elongation of a blob.  Uses the elongation of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_EULER_NUMBER

 Uses the number of blobs - number of holes.  Uses the number of blobs - number of holes.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_ELONGATION

 Uses the measure of the shape of a blob. It is equal to M_FERET_MAX_DIAMETER / M_FERET_MIN_DIAMETER.  Uses the measure of the shape of a blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MAX_ANGLE

 Uses the angle at which the maximum Feret diameter is found, in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis.  Uses the angle at which the maximum Feret diameter is found, in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MAX_DIAMETER

 Uses the largest Feret diameter found after checking a certain number of angles.  Uses the largest Feret diameter found after checking a certain number of angles.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MEAN_DIAMETER

 Uses the average Feret diameter at all the angles checked.  Uses the average Feret diameter at all the angles checked.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MIN_ANGLE

 Uses the angle at which the minimum Feret diameter is found, in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis.  Uses the angle at which the minimum Feret diameter is found, in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MIN_DIAMETER

 Uses the smallest Feret diameter found after checking a certain number of angles.  Uses the smallest Feret diameter found after checking a certain number of angles.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_X

 Uses the dimension of the minimum bounding box of a blob in the horizontal direction.  Uses the dimension of the minimum bounding box of a blob in the horizontal direction.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_Y

 Uses the dimension of the minimum bounding box of a blob in the vertical direction.  Uses the dimension of the minimum bounding box of a blob in the vertical direction.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FIRST_POINT_X

 Uses the x-coordinate of the top left-most pixel along the perimeter of a blob.  Uses the x-coordinate of the top left-most pixel along the perimeter of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FIRST_POINT_Y

 Uses the y-coordinate of the top left-most pixel along the perimeter of a blob.  Uses the y-coordinate of the top left-most pixel along the perimeter of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_GENERAL_FERET

 Uses the Feret diameter feature.  Uses the Feret diameter feature.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_GENERAL_MOMENT

 Uses the moment calculation.  Uses the moment calculation.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_INTERCEPT_0

 Uses the number of times a transition from background to foreground (not vice versa) occurs in the horizontal direction for the entire blob. In other words, it is equal to the number of times the neighborhood configuration [B, F] occurs in a blob, where B is a background pixel and F is a foreground pixel.  Uses the number of times a transition from background to foreground (not vice versa) occurs in the horizontal direction for the entire blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_INTERCEPT_45

 Uses the number of times that the neighborhood configuration   [image]  occurs in a blob, where F is a foreground pixel, B is a background pixel and a dot can be any pixel value.  Uses the number of times that the neighborhood configuration   [image]  occurs in a blob, where F is a foreground pixel, B is a background pixel and a dot can be any pixel value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_INTERCEPT_90

 Uses the number of times that the neighborhood configuration   [image]  occurs in a blob.  Uses the number of times that the neighborhood configuration   [image]  occurs in a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_INTERCEPT_135

 Uses the number of times that the neighborhood configuration   [image]  occurs in a blob.  Uses the number of times that the neighborhood configuration   [image]  occurs in a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_LABEL_VALUE

 Uses the label feature.  Uses the label feature.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_LENGTH

 Uses the measure of the true length of a blob.  Uses the measure of the true length of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_NUMBER_OF_CHAINED_PIXELS

 Uses the number of chained pixels in a blob.  Uses the number of chained pixels in a blob.

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_NUMBER_OF_HOLES

 Uses the number of holes in a blob.  Uses the number of holes in a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_NUMBER_OF_RUNS

 Uses the total number of runs in a blob.  Uses the total number of runs in a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_PERIMETER

 Uses the total length of edges in a blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized.  Uses the total length of edges in a blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_ROUGHNESS

 Uses the roughness feature.  Uses the roughness feature.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_X_MAX_AT_Y_MAX

 Uses the maximum X-coordinate at the maximum Y-coordinate of the blob.  Uses the maximum X-coordinate at the maximum Y-coordinate of the blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_X_MIN_AT_Y_MIN

 Uses the minimum X-coordinate at the minimum Y-coordinate of the blob.  Uses the minimum X-coordinate at the minimum Y-coordinate of the blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_Y_MAX_AT_X_MIN

 Uses the maximum Y-coordinate at the minimum X-coordinate of the blob.  Uses the maximum Y-coordinate at the minimum X-coordinate of the blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_Y_MIN_AT_X_MAX

 Uses the minimum Y-coordinate at the maximum X-coordinate of the blob.  Uses the minimum Y-coordinate at the maximum X-coordinate of the blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 To use as part of the criterion a feature that has only a grayscale definition, select one of the following. You can specify one of these features as part of your selection criterion only if both a blob identifier image and a grayscale image were passed to MblobCalculate() (and the features were selected for calculation).

  Open   Collapse  Value
Description

  Open   Collapse  M_MAX_PIXEL

 Uses the maximum pixel value in a blob.  Uses the maximum pixel value in a blob.

  Open   Collapse  M_MEAN_PIXEL

 Uses the mean pixel value in a blob.  Uses the mean pixel value in a blob.

  Open   Collapse  M_MIN_PIXEL

 Uses the minimum pixel value in a blob.  Uses the minimum pixel value in a blob.

  Open   Collapse  M_SIGMA_PIXEL

 Uses the standard deviation of pixel values in a blob.  Uses the standard deviation of pixel values in a blob.

  Open   Collapse  M_SUM_PIXEL

 Uses the sum of all pixel values in a blob.  Uses the sum of all pixel values in a blob.

  Open   Collapse  M_SUM_PIXEL_SQUARED

 Uses the sum of the squares of the pixel values in a blob.  Uses the sum of the squares of the pixel values in a blob.

 To use as part of the criterion a feature that has two different definitions (a binary and a grayscale definition), select one of the following.

 If you did not provide both a blob identifier image and a grayscale image to MblobCalculate(), only the binary version was calculated. If you did provide a grayscale image, both versions were calculated, unless otherwise specified. In the latter case, see combination values below to specify which to use as part of the criterion. If both versions were calculated and no version is specified, then the grayscale version of the feature is selected as criterion.

  Open   Collapse  Value
Description

  Open   Collapse  M_AXIS_PRINCIPAL_ANGLE

 Uses the feature specifying the angle at which a blob has the least moment of inertia.  Uses the feature specifying the angle at which a blob has the least moment of inertia.

  Open   Collapse  M_AXIS_SECONDARY_ANGLE

 Uses the feature specifying the angle perpendicular to M_AXIS_PRINCIPAL_ANGLE.  Uses the feature specifying the angle perpendicular to M_AXIS_PRINCIPAL_ANGLE.

  Open   Collapse  M_CENTER_OF_GRAVITY_X

 Uses the feature specifying the X-position of the center of gravity of a blob.  Uses the feature specifying the X-position of the center of gravity of a blob.

  Open   Collapse  M_CENTER_OF_GRAVITY_Y

 Uses the feature specifying the Y-position of the center of gravity of a blob.  Uses the feature specifying the Y-position of the center of gravity of a blob.

  Open   Collapse  M_MOMENT_CENTRAL_Xn_Ym

 Uses the feature specifying the calculation of central moments.  Uses the feature specifying the calculation of central moments ...

 Central moments have the syntax M_MOMENT_CENTRAL_Xn_Ym, and are defined as   [image], where pi = value of a pixel (always 1 for binary moments), xi = its X-coordinate and yi = its Y-coordinate. For central moments, coordinates are relative to each blob's center of gravity, as opposed to ordinary moments, which use coordinates that are relative to the image origin (top-left corner). Calculate higher moments by calling MblobSelectMoment().

  Open   Collapse  M_MOMENT_Xn_Ym

 Uses the feature specifying the calculation of ordinary moments.  Uses the feature specifying the calculation of ordinary moments ...

 Ordinary moments have the syntax M_MOMENT_Xn_Ym, and are defined as   [image], where pi = value of a pixel (always 1 for binary moments), xi = its X-coordinate and yi = its Y-coordinate. For ordinary moments, coordinates are relative to the image origin (top-left corner), as opposed to central moments, which use coordinates that are relative to each blob's center of gravity. Calculate higher moments by calling MblobSelectMoment().

      [Combination constants]

 The values below can be added to the SelectionCriterion parameter only for those features that have both a binary definition and a grayscale definition, and both versions have been calculated.

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Uses the binary version of the selected feature.  Uses the binary version of the selected feature.

  Open   Collapse  M_GRAYSCALE

 Uses the grayscale version of the selected feature.  Uses the grayscale version of the selected feature ...

This is the default value.

 To use as part of the selection criterion the current status of the blobs, set the SelectionCriterion parameter to one of the following values. For example, you can delete all currently excluded blobs from the list of blobs on which to operate.

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL_BLOBS

 Uses all blobs.  Uses all blobs.

  Open   Collapse  M_EXCLUDED_BLOBS

 Uses all excluded blobs.  Uses all excluded blobs.

  Open   Collapse  M_INCLUDED_BLOBS

 Uses all included blobs.  Uses all included blobs.

 Condition

 Specifies the condition for the blob selection.  This parameter must be set to one of the values below.

 When the selection criterion is based on a feature, you can specify one of the following conditions that use two limits (CondLow and CondHigh).

  Open   Collapse  Value
Description

  Open   Collapse  M_IN_RANGE

 Specifies that blobs with values for the specified feature in the range CondLow to CondHigh, inclusive, are included, excluded, or deleted from future operations on the specified result buffer.  Specifies that blobs with values for the specified feature in the range CondLow to CondHigh, inclusive, are included, excluded, or deleted from future operations on the specified result buffer.

  Open   Collapse  M_OUT_RANGE

 Specifies that blobs with values for the specified feature less than CondLow, or greater than CondHigh, are included, excluded, or deleted from future operations on the specified result buffer.  Specifies that blobs with values for the specified feature less than CondLow, or greater than CondHigh, are included, excluded, or deleted from future operations on the specified result buffer.

 When the selection criterion is based on a feature, you can specify one of the following conditions that use only one limit (CondLow).

  Open   Collapse  Value
Description

  Open   Collapse  M_EQUAL

 Specifies that blobs with values for the specified feature equal to CondLow are included, excluded, or deleted from future operations on the specified result buffer.  Specifies that blobs with values for the specified feature equal to CondLow are included, excluded, or deleted from future operations on the specified result buffer.

  Open   Collapse  M_GREATER

 Specifies that blobs with values for the specified feature greater than CondLow are included, excluded, or deleted from future operations on the specified result buffer.  Specifies that blobs with values for the specified feature greater than CondLow are included, excluded, or deleted from future operations on the specified result buffer.

  Open   Collapse  M_GREATER_OR_EQUAL

 Specifies that blobs with values for the specified feature greater than or equal to CondLow are included, excluded, or deleted from future operations on the specified result buffer.  Specifies that blobs with values for the specified feature greater than or equal to CondLow are included, excluded, or deleted from future operations on the specified result buffer.

  Open   Collapse  M_LESS

 Specifies that blobs with values for the specified feature less than CondLow are included, excluded, or deleted from future operations on the specified result buffer.  Specifies that blobs with values for the specified feature less than CondLow are included, excluded, or deleted from future operations on the specified result buffer.

  Open   Collapse  M_LESS_OR_EQUAL

 Specifies that blobs with values for the specified feature less than or equal to CondLow are included, excluded, or deleted from future operations on the specified result buffer.  Specifies that blobs with values for the specified feature less than or equal to CondLow are included, excluded, or deleted from future operations on the specified result buffer.

  Open   Collapse  M_NOT_EQUAL

 Specifies that blobs with values for the specified feature not equal to CondLow are included, excluded, or deleted from future operations on the specified result buffer.  Specifies that blobs with values for the specified feature not equal to CondLow are included, excluded, or deleted from future operations on the specified result buffer.

 When the selection criterion is based on the current status of blobs, set the Condition parameter to M_NULL.

 CondLow

 Specifies the lower limit of the selected condition.

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Specifies that this parameter is not applicable. Specify this value when and only when the selection criterion is based on the status of blobs.  Specifies that this parameter is not applicable ...

  Open   Collapse  Value

 Specifies the lower limit of the condition.  Specifies the lower limit of the condition.

 CondHigh

 Specifies the upper limit of the selected condition.

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Specifies that this parameter is not applicable. Specify this value when the condition uses only one limit or when the selection criterion is based on the status of blobs.  Specifies that this parameter is not applicable ...

  Open   Collapse  Value

 Specifies the upper limit of the condition.  Specifies the upper limit of the condition.

INCLUDE ONLY EXCLUDE ONLY INCLUDE INCLUDE ONLY DELETE DELETE EXCLUDE DELETE INCLUDE DELETE FERET MAX DIAMETER FERET MIN DIAMETER AXIS PRINCIPAL ANGLE MOMENT CENTRAL Xn Ym MOMENT Xn Ym   DELETE  EXCLUDE  EXCLUDE ONLY  INCLUDE  INCLUDE ONLY   AREA BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN BREADTH COMPACTNESS  CONVEX PERIMETER  ELONGATION  EULER NUMBER FERET ELONGATION FERET MAX ANGLE FERET MAX DIAMETER FERET MEAN DIAMETER  FERET MIN ANGLE FERET MIN DIAMETER FERET X FERET Y FIRST POINT X FIRST POINT Y  GENERAL FERET GENERAL MOMENT INTERCEPT 0  INTERCEPT 45  INTERCEPT 90  INTERCEPT 135  LABEL VALUE LENGTH NUMBER OF CHAINED PIXELS NUMBER OF HOLES NUMBER OF RUNS PERIMETER  ROUGHNESS X MAX AT Y MAX X MIN AT Y MIN Y MAX AT X MIN Y MIN AT X MAX MAX PIXEL  MEAN PIXEL  MIN PIXEL SIGMA PIXEL  SUM PIXEL SUM PIXEL SQUARED  AXIS PRINCIPAL ANGLE  AXIS SECONDARY ANGLE CENTER OF GRAVITY X CENTER OF GRAVITY Y MOMENT CENTRAL Xn Ym MOMENT Xn Ym BINARY GRAYSCALE ALL BLOBS EXCLUDED BLOBS INCLUDED BLOBS  IN RANGE OUT RANGE EQUAL GREATER GREATER OR EQUAL LESS LESS OR EQUAL NOT EQUAL  NULL   NULL


MblobSelectFeature

See Also | Example | Availability | MblobSelect | MblobSelectFeret
User Guide:
Steps to performing blob analysis
Making feature extractions
Dimensions
Moments

Reference:
MblobCalculate
MblobControl
MblobSelectMoment
mblob.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Select feature(s) to be calculated.
Syntax
void MblobSelectFeature(
MIL_ID FeatureListId,
long Feature
)
Description

This function selects the feature(s) to be calculated by MblobCalculate() when using the specified feature list.

Calculations for binary features are performed using the blob identifier image. Grayscale feature calculations are performed using both the blob identifier image and grayscale image. Features that have both binary and grayscale definitions are calculated using both the blob identifier image and the grayscale image (see MblobCalculate()).

All features are calculated in the image coordinate system. If the blob identifier image is associated with a calibration object, you can retrieve results in real-world or in pixel units. However, if your image has distortion that cannot be neglected, you should transform the image before calculating your features. When calculated in pixel units, the pixel aspect ratio, specified with MblobControl(), is taken into account horizontally. Results are returned in units of "pixel height" since the pixel width is adjusted to be equal to the pixel height. Note, all positional results are relative to the top-left pixel in the target image or the origin of the world-coordinate system if the image is calibrated.

Also, note that you can change the number of Feret angles, for those features requiring them in calculations, using MblobControl().

Parameters
FeatureListId

Specifies the identifier of the feature list buffer.

Feature

Specifies the feature to add to the feature list. To add several features, you must call this function for each feature you want to add to the list (certain commonly used groups of features can be selected in a single call).

The following group of features do not use grayscale pixel values; they are calculated using only the blob identifier image. Note that, unless otherwise stated, features can be calculated in either pixel or calibrated units.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_AREA

 Determines the number of foreground pixels in a blob (holes are not counted).  Determines the number of foreground pixels in a blob (holes are not counted).

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX_X_MAX

 Determines the extreme right coordinate of a blob.  Determines the extreme right coordinate of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX_X_MIN

 Determines the extreme left coordinate of a blob.  Determines the extreme left coordinate of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX_Y_MAX

 Determines the extreme bottom coordinate of a blob.  Determines the extreme bottom coordinate of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX_Y_MIN

 Determines the extreme top coordinate of a blob.  Determines the extreme top coordinate of a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BREADTH

 Determines a measure of the true breadth of an object, with the same advantages and disadvantages as M_LENGTH.  Determines a measure of the true breadth of an object, with the same advantages and disadvantages as M_LENGTH.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CHAIN_INDEX

 Determines the indices which differentiate each chain's pixels within a specified blob. The blob's bordering chain is identified as index 1. Chained pixels that delimit holes in blobs are identified by subsequent indexes for each chain.  Determines the indices which differentiate each chain's pixels within a specified blob ...

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CHAIN_X

 Determines the X-coordinate of each chained pixel in the specified blob, for all chains contained within the blob. Chained pixels always form a closed chain. This implies that the starting pixel in the chain is also the closing one. If your blob has regions which are 1 pixel wide, these pixels are chained twice, once in the forward direction and then in the opposite direction.  Determines the X-coordinate of each chained pixel in the specified blob, for all chains contained within the blob ...

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CHAIN_Y

 Determines the Y-coordinate of each chained pixel in the specified blob, for all chains contained within the blob. Chained pixels always form a closed chain. This implies that the starting pixel in the chain is also the closing one. If your blob has regions which are 1 pixel wide, these pixels are chained twice, once in the forward direction and then in the opposite direction.  Determines the Y-coordinate of each chained pixel in the specified blob, for all chains contained within the blob ...

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_COMPACTNESS

 Determines the minimum value for a circle (1.0) and is derived from the perimeter (p) and area (A). The more convoluted the shape, the greater the value. It is equal to   [image].  Determines the minimum value for a circle (1.0) and is derived from the perimeter (p) and area (A) ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CONVEX_PERIMETER

 Determines the approximation of the perimeter of the convex hull of a blob. It is derived from several Feret diameters; so, a larger number of Ferets gives a more accurate result.  Determines the approximation of the perimeter of the convex hull of a blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_ELONGATION

 Determines a value that is equal to M_LENGTH / M_BREADTH. It is similar to M_FERET_ELONGATION, except that it should be used for long thin objects.  Determines a value that is equal to M_LENGTH / M_BREADTH ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_EULER_NUMBER

 Determines the number of blobs - number of holes. This value is more useful for M_WHOLE_IMAGE than for M_INDIVIDUAL processing mode.  Determines the number of blobs - number of holes ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_ELONGATION

 Determines the measure of the shape of a blob. It is equal to M_FERET_MAX_DIAMETER / M_FERET_MIN_DIAMETER.  Determines the measure of the shape of a blob ...

 It is accurate for reasonably compact objects, but becomes less accurate for very elongated objects (because M_FERET_MIN_DIAMETER becomes less accurate). For very elongated objects, you should probably use M_ELONGATION.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MAX_ANGLE

 Determines the angle at which the maximum Feret diameter is found. The value is in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis.  Determines the angle at which the maximum Feret diameter is found ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MAX_DIAMETER

 Determines the largest Feret diameter found after checking a certain number of angles. More angles will give a more accurate result, but will take longer to calculate. However, the maximum Feret diameter is not very sensitive to the number of angles, and 8 usually gives an accurate result.  Determines the largest Feret diameter found after checking a certain number of angles ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MEAN_DIAMETER

 Determines the average Feret diameter at all the angles checked.  Determines the average Feret diameter at all the angles checked.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MIN_ANGLE

 Determines the angle at which the minimum Feret diameter is found. The value is in degrees, with positive values indicating a counter-clockwise displacement from the positive X-axis.  Determines the angle at which the minimum Feret diameter is found ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_MIN_DIAMETER

 Determines the smallest Feret diameter found after checking a certain number of angles. More angles will give a more accurate result, but will take longer to calculate. Even with the maximum number of angles (M_MAX_FERETS), this feature will not be very accurate for long thin blobs. However, you can get an accurate measure of the breadth of long thin blobs more quickly by using M_BREADTH.  Determines the smallest Feret diameter found after checking a certain number of angles ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_X

 Determines the dimension of the minimum bounding box of a blob in the horizontal direction; that is, M_BOX_X_MAX- M_BOX_X_MIN + 1.  Determines the dimension of the minimum bounding box of a blob in the horizontal direction; that is, M_BOX_X_MAX- M_BOX_X_MIN + 1.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FERET_Y

 Determines the dimension of the minimum bounding box of a blob in the vertical direction; that is, M_BOX_Y_MAX- M_BOX_Y_MIN + 1.  Determines the dimension of the minimum bounding box of a blob in the vertical direction; that is, M_BOX_Y_MAX- M_BOX_Y_MIN + 1.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FIRST_POINT_X

 Determines (along with M_FIRST_POINT_Y) a unique point for each object, that is always on the perimeter of the object. The X-coordinate is that of the left-most pixel on the top-most line of the object.  Determines (along with M_FIRST_POINT_Y) a unique point for each object, that is always on the perimeter of the object ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FIRST_POINT_Y

 Determines (along with M_FIRST_POINT_X) a unique point for each object, that is always on the perimeter of the object. The Y-coordinate is that of the topmost line of the object.  Determines (along with M_FIRST_POINT_X) a unique point for each object, that is always on the perimeter of the object ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_INTERCEPT_0

 Determines the number of times a transition from background to foreground (not vice versa) occurs in the horizontal direction for the entire blob. In other words, it is equal to the number of times the neighborhood configuration [B, F] occurs in a blob, where B is a background pixel and F is a foreground pixel.  Determines the number of times a transition from background to foreground (not vice versa) occurs in the horizontal direction for the entire blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_INTERCEPT_45

 Determines the number of times that the neighborhood configuration   [image]  occurs in a blob, where F is a foreground pixel, B is a background pixel and a dot can be any pixel value.  Determines the number of times that the neighborhood configuration   [image]  occurs in a blob, where F is a foreground pixel, B is a background pixel and a dot can be any pixel value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_INTERCEPT_90

 Determines the number of times that the neighborhood configuration   [image]  occurs in a blob.  Determines the number of times that the neighborhood configuration   [image]  occurs in a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_INTERCEPT_135

 Determines the number of times that the neighborhood configuration   [image]  occurs in a blob.  Determines the number of times that the neighborhood configuration   [image]  occurs in a blob.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_LABEL_VALUE

 Determines the label value for each blob in an image. This is a positive integer (>= 1) that is unique for each blob. This feature is always calculated; you do not need to select it.  Determines the label value for each blob in an image. This is a positive integer (>= 1) that is unique for each blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_LENGTH

 Determines the measure of the true length of an object, although it can only be applied to certain object types because it is derived from the perimeter (P) and area (A) assuming that P = 2(length + breadth) and A = length x breadth. It complements M_FERET_MAX_DIAMETER because it is accurate for different blob types (for example, long thin ones). Note, it is calculated much faster than the maximum Feret diameter.  Determines the measure of the true length of an object, although it can only be applied to certain object types because it is derived from the perimeter (P) and area (A) assuming that P = 2(length + breadth) and A = length x breadth ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_NUMBER_OF_CHAINED_PIXELS

 Determines the number of chained pixels for all blobs or a specified blob.  Determines the number of chained pixels for all blobs or a specified blob.

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_NUMBER_OF_HOLES

 Determines a value that is equal to the number of holes in a blob. Holes that intersect the edge of the image are not counted (they may not be holes). This value is equal to 1 - M_EULER_NUMBER and is therefore a true hole count only in M_INDIVIDUAL processing mode.  Determines a value that is equal to the number of holes in a blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_NUMBER_OF_RUNS

 Determines a value that is equal to the total number of runs in a blob. A run is defined as a horizontal string of consecutive foreground pixels.  Determines a value that is equal to the total number of runs in a blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_PERIMETER

 Determines the total length of edges in a blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized (inside corners are counted as 1.414, rather than 2.0). A single pixel blob (area = 1) has a perimeter of 4.0.  Determines the total length of edges in a blob (including the edges of any holes), with an allowance made for the staircase effect that is produced when diagonal edges are digitized (inside corners are counted as 1.414, rather than 2.0) ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_ROUGHNESS

 Determines a measure of how rough a blob is and is equal to M_PERIMETER / M_CONVEX_PERIMETER. A smooth convex object will have the minimum roughness of 1.0.  Determines a measure of how rough a blob is and is equal to M_PERIMETER / M_CONVEX_PERIMETER ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_X_MAX_AT_Y_MAX

 Determines the maximum X-coordinate at the maximum Y-coordinate of the blob. Together with M_BOX_Y_MAX, determines one of four contact points on the convex perimeter of the object.  Determines the maximum X-coordinate at the maximum Y-coordinate of the blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_X_MIN_AT_Y_MIN

 Determines the minimum X-coordinate at the minimum Y-coordinate of the blob. Together with M_BOX_Y_MIN, determines one of four contact points on the convex perimeter of the object.  Determines the minimum X-coordinate at the minimum Y-coordinate of the blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_Y_MAX_AT_X_MIN

 Determines the maximum Y-coordinate at the minimum X-coordinate of the blob. Together with M_BOX_X_MIN, determines one of four contact points on the convex perimeter of the object.  Determines the maximum Y-coordinate at the minimum X-coordinate of the blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_Y_MIN_AT_X_MAX

 Determines the minimum Y-coordinate at the maximum X-coordinate of the blob. Together with M_BOX_X_MAX, determines one of four contact points on the convex perimeter of the object.  Determines the minimum Y-coordinate at the maximum X-coordinate of the blob ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 The following features require grayscale pixel values, and can only be calculated if you provide a grayscale image.

  Open   Collapse  Value
Description

  Open   Collapse  M_MAX_PIXEL

 Determines the maximum pixel value found in a blob.  Determines the maximum pixel value found in a blob.

  Open   Collapse  M_MEAN_PIXEL

 Determines the mean pixel value in a blob. It is equal to M_SUM_PIXEL / M_AREA.  Determines the mean pixel value in a blob ...

  Open   Collapse  M_MIN_PIXEL

 Determines the minimum pixel value found in a blob.  Determines the minimum pixel value found in a blob.

  Open   Collapse  M_SIGMA_PIXEL

 Determines the standard deviation of pixel values in a blob. It is equal to   [image], where N = number of pixels and p = pixel value.  Determines the standard deviation of pixel values in a blob ...

  Open   Collapse  M_SUM_PIXEL

 Determines the sum of all pixel values in a blob.  Determines the sum of all pixel values in a blob.

  Open   Collapse  M_SUM_PIXEL_SQUARED

 Determines the sum of the squares of each pixel value in a blob.  Determines the sum of the squares of each pixel value in a blob.

 The following features have two different definitions: a binary definition, where all pixels are considered equal, and a grayscale, where pixels are weighted by their value in the gray image (the grayscale version is much slower to calculate). If you do not provide a grayscale image, only the binary version can be calculated. If you do provide a grayscale image, both versions are calculated.

  Open   Collapse  Value
Description

  Open   Collapse  M_AXIS_PRINCIPAL_ANGLE

 Determines the angle at which a blob has the least moment of inertia. For elongated blobs, it is aligned with the longest axis. The result is always between -90° and +90°, measured in a counter-clockwise direction from the positive X-axis. It is calculated as:

 When the blob identifier image is calibrated this feature is calculated in calibrated units; otherwise they are calculated in pixel units.  Determines the angle at which a blob has the least moment of inertia ...

  Open   Collapse  M_AXIS_SECONDARY_ANGLE

 Determines the angle perpendicular to M_AXIS_PRINCIPAL_ANGLE. It is always between -90° and +90°.  Determines the angle perpendicular to M_AXIS_PRINCIPAL_ANGLE ...

  Open   Collapse  M_CENTER_OF_GRAVITY_X

 Determines the X-position of the center of gravity of a blob. The grayscale version is M_MOMENT_X1_Y0 / M_SUM_PIXEL. The binary version uses M_AREA instead of M_SUM_PIXEL.  Determines the X-position of the center of gravity of a blob ...

  Open   Collapse  M_CENTER_OF_GRAVITY_Y

 Determines the Y-position of the center of gravity of a blob. The grayscale version is M_MOMENT_X0_Y1 / M_SUM_PIXEL. The binary version uses M_AREA instead of M_SUM_PIXEL.  Determines the Y-position of the center of gravity of a blob ...

  Open   Collapse  M_MOMENT_CENTRAL_Xn_Ym

 Determines the calculation of central moments.  Determines the calculation of central moments ...

 Central moments have the syntax M_MOMENT_CENTRAL_Xn_Ym, and are defined as   [image], where pi = value of a pixel (always 1 for binary moments), xi = its X-coordinate and yi = its Y-coordinate. For central moments, coordinates are relative to each blob's center of gravity, as opposed to ordinary moments, which use coordinates that are relative to the image origin (top-left corner). Calculate higher moments by calling MblobSelectMoment().

  Open   Collapse  M_MOMENT_Xn_Ym

 Determines the calculation of ordinary moments.  Determines the calculation of ordinary moments ...

 Ordinary moments have the syntax M_MOMENT_Xn_Ym, and are defined as   [image], where pi = value of a pixel (always 1 for binary moments), xi = its X-coordinate and yi = its Y-coordinate. For ordinary moments, coordinates are relative to the image origin (top-left corner), as opposed to central moments, which use coordinates that are relative to each blob's center of gravity. Calculate higher moments by calling MblobSelectMoment().

 The following values allow you to select groups of features in a single call.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_ALL_FEATURES

 Adds all features (except general Feret and general moment).  Adds all features (except general Feret and general moment).

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_BOX

 Adds all 4 box features plus X and Y Ferets.  Adds all 4 box features plus X and Y Ferets.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CENTER_OF_GRAVITY

 Adds both X and Y-coordinates of the center of gravity.  Adds both X and Y-coordinates of the center of gravity.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CHAINS

 Adds all 4 chain features. Note that the chain code is computed depending on the lattice and foreground values set with MblobControl().  Adds all 4 chain features ...

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CONTACT_POINTS

 Adds first point and other contact features (M_X_MIN_AT_Y_MIN, M_X_MAX_AT_Y_MAX, M_Y_MIN_AT_X_MAX and M_Y_MAX_AT_X_MIN).  Adds first point and other contact features (M_X_MIN_AT_Y_MIN, M_X_MAX_AT_Y_MAX, M_Y_MIN_AT_X_MAX and M_Y_MAX_AT_X_MIN).

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_NO_FEATURES

 Removes all features (except label value).  Removes all features (except label value).

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

 The values below can be added to the Feature parameter only for those features that have both a binary definition and a grayscale definition.

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Calculates the selected feature in the binary version only.  Calculates the selected feature in the binary version only.

  Open   Collapse  M_GRAYSCALE

 Calculates the selected feature in the grayscale version only.  Calculates the selected feature in the grayscale version only.

      [Combination constants]

[All except
        Matrox Genesis]

 To specify a feature as a sorting key for result retrieval, add one of the values below to the Feature parameter. Note that only one feature can be selected as the first, second, or third sorting key.

  Open   Collapse  Value
Description

  Open   Collapse  M_NO_SORT

 Removes the specified sorting key.  Removes the specified sorting key.

  Open   Collapse  M_SORTn_DOWN

 Specifies the feature as the nth sorting key (in descending order), where n stands for an integer between 1 and 3.  Specifies the feature as the nth sorting key (in descending order), where n stands for an integer between 1 and 3.

  Open   Collapse  M_SORTn_UP

 Specifies the feature as the nth sorting key (in ascending order), where n stands for an integer between 1 and 3.  Specifies the feature as the nth sorting key (in ascending order), where n stands for an integer between 1 and 3.

 For features that have both grayscale and binary definitions, the grayscale image is used as the sorting key by default. To override this default behavior, you must add M_BINARY to the feature selected as a sorting key (described earlier in this topic) prior to selecting the sorting key.

LENGTH LENGTH BREADTH FERET ELONGATION WHOLE IMAGE INDIVIDUAL FERET MAX DIAMETER FERET MIN DIAMETER FERET MIN DIAMETER ELONGATION MAX FERETS BREADTH BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN FIRST POINT Y FIRST POINT X FERET MAX DIAMETER EULER NUMBER INDIVIDUAL PERIMETER CONVEX PERIMETER BOX Y MAX BOX Y MIN BOX X MIN BOX X MAX SUM PIXEL AREA AXIS PRINCIPAL ANGLE SUM PIXEL AREA SUM PIXEL SUM PIXEL AREA SUM PIXEL MOMENT CENTRAL Xn Ym MOMENT Xn Ym X MIN AT Y MIN X MAX AT Y MAX Y MIN AT X MAX Y MAX AT X MIN BINARY   AREA BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN BREADTH CHAIN INDEX CHAIN X  CHAIN Y COMPACTNESS  CONVEX PERIMETER
                 ELONGATION  EULER NUMBER FERET ELONGATION FERET MAX ANGLE FERET MAX DIAMETER FERET MEAN DIAMETER
                 FERET MIN ANGLE FERET MIN DIAMETER FERET X FERET Y FIRST POINT X FIRST POINT Y  INTERCEPT 0  INTERCEPT 45  INTERCEPT 90  INTERCEPT 135  LABEL VALUE LENGTH NUMBER OF CHAINED PIXELS NUMBER OF HOLES NUMBER OF RUNS PERIMETER  ROUGHNESS X MAX AT Y MAX X MIN AT Y MIN Y MAX AT X MIN Y MIN AT X MAX MAX PIXEL  MEAN PIXEL  MIN PIXEL SIGMA PIXEL  SUM PIXEL SUM PIXEL SQUARED
                   AXIS PRINCIPAL ANGLE
                   AXIS SECONDARY ANGLE CENTER OF GRAVITY X CENTER OF GRAVITY Y MOMENT CENTRAL Xn Ym MOMENT Xn Ym ALL FEATURES BOX CENTER OF GRAVITY
                   CHAINS CONTACT POINTS
                   NO FEATURES BINARY GRAYSCALE NO SORT  SORTn DOWN  SORTn UP


MblobSelectFeret

See Also | Example | Availability | MblobSelectFeature | MblobSelectMoment
User Guide:
Steps to performing blob analysis
Making feature extractions
Dimensions

Reference:
MblobCalculate
MblobGetResult
MblobGetResultSingle
MblobSelectFeature
There are no examples containing MblobSelectFeret().
Not available in MIL-Lite

Available in MIL
Synopsis
Add Feret angle to the feature list.
Syntax
void MblobSelectFeret(
MIL_ID FeatureListId,
double Angle
)
Description

This function adds M_GENERAL_FERET at the specified angle to the feature list. The Feret diameter is then calculated at this angle, using MblobCalculate(). Results for this calculation can be obtained with MblobGetResult() or MblobGetResultSingle(), specifying M_GENERAL_FERET as the feature.

Parameters
FeatureListId

Specifies the identifier of the feature list buffer.

Angle

Specifies the angle, in degrees, to be used for calculating the general Feret. It overrides any previous angle specified for the general Feret in this feature list. Note, the Feret diameters at 0° and 90° are calculated more efficiently with MblobSelectFeature() (the features are called M_FERET_X and M_FERET_Y respectively).

To select the general Feret as a sorting key for the result retrieval, add the following sorting values to the Angle parameter:

Open Collapse Value Description
Open Collapse M_NO_SORT

 Removes the specified sorting key.  Removes the specified sorting key.

  Open   Collapse  M_SORTn_DOWN

 Specifies the feature as the nth sorting key (in descending order), where n stands for an integer between 1 and 3.  Specifies the feature as the nth sorting key (in descending order), where n stands for an integer between 1 and 3.

  Open   Collapse  M_SORTn_UP

 Specifies the feature as the nth sorting key (in ascending order), where n stands for an integer between 1 and 3.  Specifies the feature as the nth sorting key (in ascending order), where n stands for an integer between 1 and 3.

FERET X FERET Y   NO SORT SORTn DOWN  SORTn UP


MblobSelectMoment

See Also | Example | Availability | MblobSelectFeret
User Guide:
Steps to performing blob analysis
Making feature extractions
Moments

Reference:
MblobCalculate
MblobGetResult
MblobGetResultSingle
MblobSelectFeature
There are no examples containing MblobSelectMoment().
Not available in MIL-Lite

Available in MIL
Synopsis
Add specified moment to the feature list.
Syntax
void MblobSelectMoment(
MIL_ID FeatureListId,
long MomType,
long XMomOrder,
long YMomOrder
)
Description

Moment calculations other than those supported by MblobSelectFeature() must be specified with this function. This function adds the general moment with the specified parameters to the feature list. The general moment will be calculated by MblobCalculate(). Results for this calculation can be obtained by using MblobGetResult() or MblobGetResultSingle(), specifying M_GENERAL_MOMENT as the feature. Moments directly supported by MblobSelectFeature() (for example, M_MOMENT_X0_Y2) are calculated faster by selecting them through that function.

A call to this function overrides any previous values specified for M_GENERAL_MOMENT in the feature list.

Parameters
FeatureListId

Specifies the identifier of the feature list buffer.

MomType

Specifies the moment type. If the calculation is done on a binary image, only a binary version of the result is calculated. If you provide a grayscale image, both grayscale and binary versions are calculated.

This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_CENTRAL

 Specifies a central moment type.  Specifies a central moment type ...

 Central moments use coordinates relative to each blob's center of gravity, and are therefore independent of a blob's position within an image

  Open   Collapse  M_ORDINARY

 Specifies an ordinary moment type.  Specifies an ordinary moment type ...

 Ordinary moments are affected by the blob position because they use coordinates relative to the image origin (top-left corner).

      [Combination constants]

 As mentioned, if you provide a grayscale image, both grayscale and binary versions are calculated. However, if you want only one specific version of the results, you can combine the selected moment with one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Calculates only the binary version of the image.  Calculates only the binary version of the image.

  Open   Collapse  M_GRAYSCALE

 Calculates only the grayscale version of the image.  Calculates only the grayscale version of the image.

      [Combination constants]

 To select the general moment as a sorting key for the result retrieval, add the following sorting values to the MomType parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_NO_SORT

 Removes the specified sorting key.  Removes the specified sorting key.

  Open   Collapse  M_SORTn_DOWN

 Specifies the feature as the nth sorting key (in descending order), where n stands for an integer between 1 and 3.  Specifies the feature as the nth sorting key (in descending order), where n stands for an integer between 1 and 3.

  Open   Collapse  M_SORTn_UP

 Specifies the feature as the nth sorting key (in ascending order), where n stands for an integer between 1 and 3.  Specifies the feature as the nth sorting key (in ascending order), where n stands for an integer between 1 and 3.

 XMomOrder

 Specifies the X-order of the moment.  The X-order of the moment must be greater than or equal to 0.

 YMomOrder

 Specifies the Y-order of the moment.  The Y-order of the moment must be greater than or equal to 0.

GENERAL MOMENT GENERAL MOMENT   CENTRAL ORDINARY BINARY GRAYSCALE NO SORT SORTn DOWN  SORTn UP


buf

Mbuf functions

Example | Availability
There are no examples containing buf().
Available in MIL-Lite

Available in MIL
Synopsis
The functions prefixed with Mbuf make up the Buffer module. The Buffer module allows you to allocate and control data buffers (storage areas) that are typically operated on by functions of several MIL modules. These buffers include image buffers and lookup table (LUT) buffers. The Buffer module allows you to isolate regions of a buffer using child buffers, as well as copy required sequential or non-sequential regions or bit-planes of a buffer to another buffer. The module's copy functions are optimized to make the best possible use of available system resources to maximize transferring speed. The module can archive and retrieve buffer data in common storage formats (for example, TIFF and JPEG). It can also create, save, and load sequences in AVI format. The module allows you to compress and decompress images and sequences, supporting both lossy and lossless JPEG and JPEG2000 compression algorithms. Furthermore, the module allows you to convert images grabbed from a camera with a Bayer filter, into 3-band color images.
Functions
  • MbufAlloc1d
  • MbufAlloc2d
  • MbufAllocColor
  • MbufBayer
  • MbufChild1d
  • MbufChild2d
  • MbufChildColor
  • MbufChildColor2d
  • MbufChildMove
  • MbufClear
  • MbufControl
  • MbufControlNeighborhood
  • MbufControlRegion
  • MbufCopy
  • MbufCopyClip
  • MbufCopyColor
  • MbufCopyColor2d
  • MbufCopyCond
  • MbufCopyMask
  • MbufCreate2d
  • MbufCreateColor
  • MbufDiskInquire
  • MbufExport
  • MbufExportSequence
  • MbufFree
  • MbufGet
  • MbufGet1d
  • MbufGet2d
  • MbufGetArc
  • MbufGetColor
  • MbufGetColor2d
  • MbufGetHookInfo
  • MbufGetLine
  • MbufHookFunction
  • MbufImport
  • MbufImportSequence
  • MbufInquire
  • MbufLoad
  • MbufPut
  • MbufPut1d
  • MbufPut2d
  • MbufPutColor
  • MbufPutColor2d
  • MbufPutLine
  • MbufRestore
  • MbufSave
  • MbufTransfer


MbufAlloc1d

See Also | Example | Availability | MbufAlloc2d
User Guide:
Arithmetic with images
Custom spatial filters
Data buffers
Using buffers with the Bayer color filter
LUTs and data buffers
Palettes and output LUTs for windowed display (256-color)

Reference:
MappGetError
MbufControl
MbufFree
MbufInquire
MsysAlloc
MsysControl
dtkobjecttracking.c
dtkremap.c
mbufbayercolorfilter.c
mdispwindowleveling.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Allocate a 1D data buffer.
Syntax
MIL_ID MbufAlloc1d(
MIL_ID SystemId,
long SizeX,
long Type,
MIL_INT64 Attribute,
MIL_ID *BufIdPtr
)
Description

This function allocates a one-dimensional one-band data buffer on the specified system.

After allocating a buffer, we recommend that you check if the operation was successful, using MappGetError() or by verifying that the buffer identifier returned is not M_NULL.

When a buffer is no longer required, release it, using MbufFree().

Parameters
SystemId

Specifies the system on which to allocate the buffer. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 SizeX

 Specifies the buffer width. The units are determined by the selected buffer attribute.  For example, if the buffer has a LUT buffer attribute, specify the number of LUT entries to allocate.

 Type

 Specifies a combination of two values: the depth and type of the data.  Specify the depth of the buffer as one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  1

 Specifies a 1-bit (packed binary) buffer. Note that you cannot allocate a 1-bit LUT or kernel buffer.  Specifies a 1-bit (packed binary) buffer ...

  Open   Collapse  8

 Specifies an 8-bit buffer.  Specifies an 8-bit buffer.

  Open   Collapse  16

 Specifies a 16-bit buffer.  Specifies a 16-bit buffer.

  Open   Collapse  32

 Specifies a 32-bit buffer.  Specifies a 32-bit buffer.

      [Combination constants]

 You can add one of the following to the Type parameter to specify the data type. Supported data types depend on the specified depth.

  Open   Collapse  Value
Description

  Open   Collapse  M_FLOAT

 Specifies that the type of data is floating point. The valid data depth is 32 bits.  Specifies that the type of data is floating point ...

  Open   Collapse  M_SIGNED

 Specifies that the type of data is signed. The valid data depths are 8, 16, or 32 bits.  Specifies that the type of data is signed ...

  Open   Collapse  M_UNSIGNED

 Specifies that the type of data is unsigned. The valid data depths are 1, 8, 16, or 32 bits.  Specifies that the type of data is unsigned ...

This is the default value.

 Attribute

 Specifies the buffer usage.  MIL uses this information to determine where to allocate the buffer in physical memory. Set this parameter to one of the following values:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_ARRAY

 Allocates a buffer to store array type data. Note that some functions take an M_ARRAY buffer rather than a user-defined array.  Allocates a buffer to store array type data ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_IMAGE

 Allocates a buffer to store image data.  Allocates a buffer to store image data.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_KERNEL

MIL-lite with restriction (see remarks).

 Allocates a kernel buffer to store a custom filter for convolution functions.  Allocates a kernel buffer to store a custom filter for convolution functions ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The depth must be 8, 16, or 32-bit integer or floating-point.

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 Only three types of kernel buffers are supported: signed 8-bit, unsigned 8-bit, and signed 16-bit.

c

  Open   Collapse  M_LUT

 Allocates a buffer to store lookup table data.  Allocates a buffer to store lookup table data ...

 The valid data depths are 8, 16, or 32 bits.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_STRUCT_ELEMENT

MIL-lite with restriction (see remarks).

 Allocates a buffer to store structuring element data for morphology functions.  Allocates a buffer to store structuring element data for morphology functions ...

 The data depth must be 32-bit. If signed, the range is -32767 to +32767. If unsigned, the range is 0 to +32767.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

 When allocating an image buffer (M_IMAGE), you must also specify the intended purpose of this buffer by combining M_IMAGE with one or more of the following values:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_COMPRESS

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can hold compressed data. Note that a buffer with this attribute cannot have the M_SIGNED data type.  Specifies an image buffer that can hold compressed data ...

 When allocating buffers for operations that require a source and destination buffer, and one of the buffers has an M_COMPRESS attribute, the data will be compressed or decompressed depending on the attributes of the destination buffer. If both the source and destination buffers have M_COMPRESS specifiers but different compression types, the data will be re-compressed according to the settings of the destination buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_DISP

 Specifies an image buffer that can be displayed.  Specifies an image buffer that can be displayed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band display buffers with a depth greater than 16 bits cannot be allocated.

c

  Open   Collapse  M_GRAB

 Specifies an image buffer in which to grab data. This type of buffer is usually allocated in MIL-reserved, physically contiguous, non-paged memory.  Specifies an image buffer in which to grab data ...

 For Host buffers (M_HOST_MEMORY), the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of MIL-reserved, non-paged memory (specified at installation time or using MilConfig).

 For on-board buffers (M_ON_BOARD), maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of on-board memory.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band buffers with a depth of 8 or 16 bits (monochrome) can have an M_GRAB attribute.

a

c
d
e

h
i

m
n
o

q
r

 Single-band buffers with a depth of 8 bits can have an M_GRAB attribute.

b

f
g

j
k
l

p

  Open   Collapse  M_PROC

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can be processed.  Specifies an image buffer that can be processed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 For systems with on-board processors, the total number of M_PROC buffers is limited by the amount of on-board memory.

c
d
e

m
n
o

      [Combination constants]

[MIL-Lite with restriction]

 For an M_COMPRESS type of image buffer, one of the following values can be added to select the compression type. The image buffer's data depth dictates which compression type can be selected.

  Open   Collapse  Value
Description

  Open   Collapse  M_JPEG_LOSSLESS

 Specifies that the buffer will be used to hold JPEG lossless data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG lossless data ...

  Open   Collapse  M_JPEG2000_LOSSLESS

 Specifies that the buffer will be used to hold JPEG2000 lossless data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG2000 lossless data ...

  Open   Collapse  M_JPEG_LOSSLESS_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossless data in separate fields. The supported data formats are 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG lossless data in separate fields ...

  Open   Collapse  M_JPEG_LOSSY

 Specifies that the buffer will be used to hold JPEG lossy data the supported data format is 1-band 8-bit data. If no attribute is specified, M_JPEG_LOSSY is assumed.  Specifies that the buffer will be used to hold JPEG lossy data the supported data format is 1-band 8-bit data ...

This is the default value.

  Open   Collapse  M_JPEG2000_LOSSY

 Specifies that the buffer will be used to hold JPEG2000 lossy data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG2000 lossy data ...

  Open   Collapse  M_JPEG_LOSSY_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossy data in separate fields. The supported data format is 1-band 8-bit data.  Specifies that the buffer will be used to hold JPEG lossy data in separate fields ...

      [Combination constants]

 MIL automatically selects the most appropriate storage format according to the specified intended usage attribute. For general processing, MIL will convert the data when the function requires a different format. If the default storage format is not appropriate and you want to avoid conversion during a time critical operation, you can add a storage format and a location specifier.

 To specify a storage format for an image buffer, you can add one or more of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DIB

 Forces the buffer to be a DIB buffer. This ensures your buffer is stored with a DIB header. Use MbufInquire() with M_BITMAPINFO to return a pointer (LPBITMAPINFO) to the header of the MIL buffer.  Forces the buffer to be a DIB buffer ...

  Open   Collapse  M_DIRECTX

 Forces the buffer to be a DirectX surface.  Forces the buffer to be a DirectX surface.

  Open   Collapse  M_GDI

 Forces the buffer to be compatible with GDI.  Forces the buffer to be compatible with GDI ...

 When using a device context (using MbufControl() with M_DC_ALLOC) for drawing, the buffer should be internally stored in GDI format, and cannot be a child buffer.

      [Combination constants]

 To specify a location for an image buffer, you can add one of the following values:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_HOST_MEMORY

 Forces the buffer in Host memory.  Forces the buffer in Host memory ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

a
b

d
e
f
g
h
i
j
k
l

p
q
r

  Open   Collapse  M_MAPPABLE

 Forces the buffer to be allocated in non-paged memory that can be set in the address space of the process (Host memory). By default, however it is not mapped to Host memory (that is, by default the buffer will have a physical address, but not a Host address). Use MbufControl() with M_MAP to enable or disable the mapping to Host memory.  Forces the buffer to be allocated in non-paged memory that can be set in the address space of the process (Host memory) ...

 This setting is useful when dealing with many large buffers that cannot all be mapped in Host memory at the same time. By allocating a buffer as M_MAPPABLE, it can be mapped and unmapped as needed.

 Note that, if used with the M_PAGED attribute, an error will be generated.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OFF_BOARD

 Ensures that the buffer is not in on-board memory.  Ensures that the buffer is not in on-board memory ...

c
d
e
f

l
m
n
o

q
r

Specifics

 To ensure that an M_OFF_BOARD buffer can be used by the bus master transfer. The buffer must be allocated in non-paged memory (M_OFF_BOARD + M_NON_PAGED or M_HOST_MEMORY + M_NON_PAGED).

d
e

m
n
o

q
r

  Open   Collapse  M_ON_BOARD

 Forces the buffer in on-board memory.  Forces the buffer in on-board memory ...

a

c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

c

m
n
o

 By default, all on-board buffers are allocated in memory that is not mapped on the PCI bus. This unshared memory cannot be accessed by the Host or any system other than the one on which it was allocated. See combination values below (M_SHARED) to change this default behavior.

d
e
f

m
n
o

q
r

  Open   Collapse  M_VIDEO_MEMORY

 Forces the buffer in (off-screen) display memory of your graphics controller. Display memory is also referred to as video memory or frame buffer memory.  Forces the buffer in (off-screen) display memory of your graphics controller ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 You can add one of the following values when allocating an on-board image buffer (M_ON_BOARD).

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_FAST_MEMORY

 Forces the buffer in the G4 PowerPC fast-processing memory. This memory is L3 external cache. It must be enabled using the OdcMon utility before it can be used.  Forces the buffer in the G4 PowerPC fast-processing memory ...

 Matrox Odyssey Xpro has up to 2 Mbytes of memory available for fast processing. Any buffer allocated in fast memory must entirely fit within this memory. If it does not, the buffer will be allocated in ordinary processing memory instead.

 Use MbufInquire() with M_EXTENDED_FORMAT to establish if the buffer was allocated in fast processing memory.

 Fast processing memory is only accessible to the G4 PowerPC microprocessor and not to the Host, frame grabber module, or PA. Therefore, depending on the operation, allocating a buffer in fast processing memory might not accelerate processing.

 Note that M_GRAB and M_DISP are not supported with this attribute.

m
n
o

  Open   Collapse  M_SHARED

 Forces the buffer in processing memory that is mapped on the PCI bus.  Forces the buffer in processing memory that is mapped on the PCI bus ...

 Use MbufInquire() with M_HOST_ADDRESS to retrieve the address of the buffer.

d
e

m
n
o

q
r

Specifics

 Use the OdcConfig utility to establish the required amount of shared memory.

m
n
o

 Use the MilConfig utility to establish the required amount of shared memory.

d
e

q
r

      [Combination constants]

 To specify a type of memory, you can add one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_NON_PAGED

 Forces the buffer in MIL reserved, non-pageable memory.  Forces the buffer in MIL reserved, non-pageable memory.

  Open   Collapse  M_PAGED

 Forces the buffer in pageable memory.  Forces the buffer in pageable memory.

      [Combination constants]

 When allocating an M_PROC image buffer, you can add the following value to override the MsysControl() M_FAST_OVERSCAN_BUFFER system control setting and force the allocation of an overscan region. When this attribute is set, the setting of the M_ALLOCATION_OVERSCAN_SIZE system control determines the size of the overscan region and the M_FAST_OVERSCAN_BUFFER setting is ignored.

 Note that this attribute is only useful when added to a buffer on which you want to perform neighborhood processing operations.

  Open   Collapse  Value
Description

  Open   Collapse  M_FAST_OVERSCAN

 Specifies that the buffer is allocated with an overscan region, and the size of the region is determined by the M_ALLOCATION_OVERSCAN_SIZE setting of MsysControl().  Specifies that the buffer is allocated with an overscan region, and the size of the region is determined by the M_ALLOCATION_OVERSCAN_SIZE setting of MsysControl().

 BufIdPtr

 Specifies the address of the variable in which to write the buffer identifier.  Since the MbufAlloc1d() function also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the buffer identifier. If allocation fails, M_NULL is returned.

Remarks

  •  Note that MIL-Lite compression support, particularly for M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

  •  You can allocate an image buffer with an M_KERNEL, M_STRUCT_ELEMENT, or M_PROC attribute with MIL-Lite. However, these attributes are not required to work under MIL-Lite.
    •

ARRAY IMAGE IMAGE SIGNED COMPRESS COMPRESS HOST MEMORY GRAB ON BOARD GRAB GRAB GRAB PROC COMPRESS JPEG LOSSY BITMAPINFO DC ALLOC MAP MAPPABLE PAGED OFF BOARD OFF BOARD NON PAGED HOST MEMORY NON PAGED SHARED ON BOARD EXTENDED FORMAT GRAB DISP HOST ADDRESS PROC FAST OVERSCAN BUFFER ALLOCATION OVERSCAN SIZE FAST OVERSCAN BUFFER ALLOCATION OVERSCAN SIZE COMPRESS KERNEL STRUCT ELEMENT PROC  DEFAULT HOST        FLOAT SIGNED UNSIGNED  ARRAY IMAGE KERNEL LUT STRUCT ELEMENT COMPRESS DISP GRAB PROC JPEG LOSSLESS JPEG LOSSLESS INTERLACED  JPEG LOSSY JPEG2000 LOSSLESS JPEG2000 LOSSY JPEG LOSSY INTERLACED DIRECTX DIB GDI HOST MEMORY MAPPABLE OFF BOARD ON BOARD VIDEO MEMORY FAST MEMORY SHARED NON PAGED PAGED FAST OVERSCAN


MbufAlloc2d

See Also | Example | Availability | MbufAlloc1d | MbufAllocColor
User Guide:
Allocating and displaying an image buffer
Custom spatial filters
Custom morphological operations
Data buffers
Using buffers with the Bayer color filter
Displaying multiple buffers

Reference:
MappGetError
MbufControl
MbufFree
MbufInquire
MsysAlloc
MsysControl
dtkaddconstantaltivec.c
dtkaddconstantonlaltivec.c
dtkaddconstantpaslave.c
dtkobjecttracking.c
mblob.c
mdigautofocus.c
mdigdoublebuffering.c
mdiggrabmultiple.c
mdighook.c
mdigprocess.c
mdigprocessmultiple.c
mdigsubtract.c
mdispselect.c
mfunc.c
mgenlc.c
mgrabbayer.c
mheliosconcurent.c
mimconvolve.c
mimfft.c
mimmorphic.c
mimperimeter.c
mimwarp.c
mmet2dig.c
mmodeltracking.c
mocr.c
mthread.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Allocate a 2D data buffer.
Syntax
MIL_ID MbufAlloc2d(
MIL_ID SystemId,
long SizeX,
long SizeY,
long Type,
MIL_INT64 Attribute,
MIL_ID *BufIdPtr
)
Description

This function allocates a two-dimensional one-band data buffer on the specified system.

After allocating a buffer, we recommend that you check if the operation was successful, using MappGetError() or by verifying that the buffer identifier returned is not M_NULL.

When a buffer is no longer required, release it, using MbufFree().

Parameters
SystemId

Specifies the system on which to allocate the buffer. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 SizeX

 Specifies the buffer width. The units are determined by the selected buffer attribute.  For example, if the buffer has an image buffer attribute, specify the width in pixels.

 SizeY

 Specifies the buffer height. The units are determined by the selected buffer attribute.  For example, if the buffer has an image buffer attribute, specify the height in pixels.

 Type

 Specifies a combination of two values: the depth and type of the data.  Specify the depth of the buffer as one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  1

 Specifies a 1-bit (packed binary) buffer. Note that you cannot allocate a 1-bit LUT or kernel buffer.  Specifies a 1-bit (packed binary) buffer ...

  Open   Collapse  8

 Specifies an 8-bit buffer.  Specifies an 8-bit buffer.

  Open   Collapse  16

 Specifies a 16-bit buffer.  Specifies a 16-bit buffer.

  Open   Collapse  32

 Specifies a 32-bit buffer.  Specifies a 32-bit buffer.

      [Combination constants]

 You can add one the following to the Type parameter to specify the data type. Supported data types depend on the specified depth.

  Open   Collapse  Value
Description

  Open   Collapse  M_FLOAT

 Specifies that the type of data is floating point. The valid data depth is 32 bits.  Specifies that the type of data is floating point ...

  Open   Collapse  M_SIGNED

 Specifies that the type of data is signed. The valid data depths are 8, 16, or 32 bits.  Specifies that the type of data is signed ...

  Open   Collapse  M_UNSIGNED

 Specifies that the type of data is unsigned. The valid data depths are 1, 8, 16, or 32 bits.  Specifies that the type of data is unsigned ...

This is the default value.

 Attribute

 Defines the buffer usage.  MIL uses this information to determine where to allocate the buffer in physical memory. Set this parameter to one of the following values:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_ARRAY

 Allocates a buffer to store array type data. Note that some functions take an M_ARRAY buffer rather than a user-defined array.  Allocates a buffer to store array type data ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_IMAGE

 Allocates a buffer to store image data.  Allocates a buffer to store image data.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_KERNEL

MIL-lite with restriction (see remarks).

 Allocates a kernel buffer to store a custom filter for convolution functions.  Allocates a kernel buffer to store a custom filter for convolution functions ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The depth must be 8, 16, or 32-bit integer or floating-point.

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 Only three types of kernel buffers are supported: signed 8-bit, unsigned 8-bit, and signed 16-bit.

c

  Open   Collapse  M_LUT

 Allocates a buffer to store lookup table data.  Allocates a buffer to store lookup table data ...

 The valid data depths are 8, 16, or 32 bits.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_STRUCT_ELEMENT

MIL-lite with restriction (see remarks).

 Allocates a buffer to store structuring element data for morphology functions.  Allocates a buffer to store structuring element data for morphology functions ...

 The data depth must be 32-bit. If signed, the range is -32767 to +32767. If unsigned, the range is 0 to +32767.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

 When allocating an image buffer (M_IMAGE), you must also specify the intended purpose of this buffer by combining M_IMAGE with one or more of the following values:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_COMPRESS

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can hold compressed data. Note that a buffer with this attribute cannot have the M_SIGNED data type.  Specifies an image buffer that can hold compressed data ...

 When allocating buffers for operations that require a source and destination buffer, and one of the buffers has an M_COMPRESS attribute, the data will be compressed or decompressed depending on the attributes of the destination buffer. If both the source and destination buffers have M_COMPRESS specifiers but different compression types, the data will be re-compressed according to the settings of the destination buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_DISP

 Specifies an image buffer that can be displayed.  Specifies an image buffer that can be displayed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band display buffers with a depth greater than 16 bits cannot be allocated.

c

  Open   Collapse  M_GRAB

 Specifies an image buffer in which to grab data. This type of buffer is usually allocated in MIL-reserved, physically contiguous, non-paged memory.  Specifies an image buffer in which to grab data ...

 For Host buffers (M_HOST_MEMORY), the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of MIL-reserved, non-paged memory (specified at installation time or using MilConfig).

 For on-board buffers (M_ON_BOARD), maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of on-board memory.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band buffers with a depth of 8 or 16 bits (monochrome) can have an M_GRAB attribute.

a

c
d
e

h
i

m
n
o

q
r

 Single-band buffers with a depth of 8 bits can have an M_GRAB attribute.

b

f
g

j
k
l

p

  Open   Collapse  M_PROC

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can be processed.  Specifies an image buffer that can be processed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 For systems with on-board processors, the total number of M_PROC buffers is limited by the amount of on-board memory.

c
d
e

m
n
o

      [Combination constants]

[MIL-Lite with restriction]

 For an M_COMPRESS type of image buffer, one of the following values can be added to indicate the type of compressed data. The image buffer's data depth dictates which compression type can be selected.

  Open   Collapse  Value
Description

  Open   Collapse  M_JPEG_LOSSLESS

 Specifies that the buffer will be used to hold JPEG lossless data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG lossless data ...

  Open   Collapse  M_JPEG2000_LOSSLESS

 Specifies that the buffer will be used to hold JPEG2000 lossless data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG2000 lossless data ...

  Open   Collapse  M_JPEG_LOSSLESS_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossless data in separate fields. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG lossless data in separate fields ...

  Open   Collapse  M_JPEG_LOSSY

 Specifies that the buffer will be used to hold JPEG lossy data. The supported data formats is 1-band 8-bit data.  Specifies that the buffer will be used to hold JPEG lossy data ...

This is the default value.

  Open   Collapse  M_JPEG2000_LOSSY

 Specifies that the buffer will be used to hold JPEG2000 lossy data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG2000 lossy data ...

  Open   Collapse  M_JPEG_LOSSY_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossy data in separate fields. The supported data formats is 1-band 8-bit data.  Specifies that the buffer will be used to hold JPEG lossy data in separate fields ...

      [Combination constants]

 MIL automatically selects the most appropriate storage format according to the specified intended usage attribute. For general processing, MIL will convert the data when the function requires a different format. If the default storage format is not appropriate and you want to avoid conversion during a time critical operation, you can add a storage format and a location specifier.

 To specify a storage format for an image buffer, you can add one or more of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DIB

 Forces the buffer to be a DIB buffer. This ensures your buffer is stored with a DIB header. Use MbufInquire() with M_BITMAPINFO to return a pointer (LPBITMAPINFO) to the header of the MIL buffer.  Forces the buffer to be a DIB buffer ...

  Open   Collapse  M_DIRECTX

 Forces the buffer to be a DirectX surface.  Forces the buffer to be a DirectX surface.

  Open   Collapse  M_GDI

 Forces the buffer to be compatible with GDI.  Forces the buffer to be compatible with GDI ...

 When using a device context (using MbufControl() with M_DC_ALLOC) for drawing, the buffer should be internally stored in GDI format, and cannot be a child buffer.

      [Combination constants]

 To specify a location for an image buffer, you can add one of the following values:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_HOST_MEMORY

 Forces the buffer in Host memory.  Forces the buffer in Host memory ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

a
b

d
e
f
g
h
i
j
k
l

p
q
r

  Open   Collapse  M_MAPPABLE

 Forces the buffer to be allocated in non-paged memory that can be set in the address space of the process (Host memory). By default, however it is not mapped to Host memory (that is, by default the buffer will have a physical address, but not a Host address). Use MbufControl() with M_MAP to enable or disable the mapping to Host memory.  Forces the buffer to be allocated in non-paged memory that can be set in the address space of the process (Host memory) ...

 This setting is useful when dealing with many large buffers that cannot all be mapped in Host memory at the same time. By allocating a buffer as M_MAPPABLE, it can be mapped and unmapped as needed.

 Note that, if used with the M_PAGED attribute, an error will be generated.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OFF_BOARD

 Ensures that the buffer is not in on-board memory.  Ensures that the buffer is not in on-board memory ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 To ensure that an M_OFF_BOARD buffer can be used by the bus master transfer section of the board, the buffer must be allocated in non-paged memory (M_OFF_BOARD + M_NON_PAGED or M_HOST_MEMORY + M_NON_PAGED).

d
e

m
n
o

q
r

  Open   Collapse  M_ON_BOARD

 Forces the buffer in on-board memory.  Forces the buffer in on-board memory ...

a

c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

c

m
n
o

 By default, all on-board buffers are allocated in memory that is not mapped on the PCI bus. This unshared memory cannot be accessed by the Host or any system other than the one on which it was allocated. See combination values below (M_SHARED) to change this default behavior.

d
e
f

m
n
o

q
r

  Open   Collapse  M_VIDEO_MEMORY

 Forces the buffer in (off-screen) display memory of your graphics controller. Display memory is also referred to as video memory or frame buffer memory.  Forces the buffer in (off-screen) display memory of your graphics controller ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 You can add one of the following values when allocating an on-board image buffer (M_ON_BOARD).

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_FAST_MEMORY

 Forces the buffer in the G4 PowerPC fast-processing memory. This memory is L3 external cache. It must be enabled using the OdcMon utility before it can be used.  Forces the buffer in the G4 PowerPC fast-processing memory ...

 Matrox Odyssey Xpro has up to 2 Mbytes of memory available for fast processing. Any buffer allocated in fast memory must entirely fit within this memory. If it does not, the buffer will be allocated in ordinary processing memory instead.

 Use MbufInquire() with M_EXTENDED_FORMAT to establish if the buffer was allocated in fast processing memory.

 Fast processing memory is only accessible to the G4 PowerPC microprocessor and not to the Host, frame grabber module, or PA. Therefore, depending on the operation, allocating a buffer in fast processing memory might not accelerate processing.

 Note that M_GRAB and M_DISP are not supported with this attribute.

m
n
o

  Open   Collapse  M_SHARED

 Forces the buffer in processing memory that is mapped on the PCI bus.  Forces the buffer in processing memory that is mapped on the PCI bus ...

 Use MbufInquire() with M_HOST_ADDRESS to retrieve the address of the buffer.

d
e

m
n
o

q
r

Specifics

 Use the OdcConfig utility to establish the required amount of shared memory.

m
n
o

 Use the MiLConfig utility to establish the required amount of shared memory.

d
e

q
r

      [Combination constants]

 To specify a type of memory, you can add one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_NON_PAGED

 Forces the buffer in MIL-reserved, non-pageable memory.  Forces the buffer in MIL-reserved, non-pageable memory.

  Open   Collapse  M_PAGED

 Forces the buffer in pageable memory.  Forces the buffer in pageable memory.

      [Combination constants]

 When allocating an M_PROC image buffer, you can add the following value to override the MsysControl() M_FAST_OVERSCAN_BUFFER system control setting and force the allocation of an overscan region. When this attribute is set, the setting of the M_ALLOCATION_OVERSCAN_SIZE system control determines the size of the overscan region and the M_FAST_OVERSCAN_BUFFER setting is ignored.

 Note that this attribute is only useful when added to a buffer on which you want to perform neighborhood processing operations.

  Open   Collapse  Value
Description

  Open   Collapse  M_FAST_OVERSCAN

 Specifies that the buffer is allocated with an overscan region, and the size of the region is determined by the M_ALLOCATION_OVERSCAN_SIZE setting of MsysControl().  Specifies that the buffer is allocated with an overscan region, and the size of the region is determined by the M_ALLOCATION_OVERSCAN_SIZE setting of MsysControl().

 BufIdPtr

 Specifies the address of the variable in which to write the buffer identifier.  Since the MbufAlloc2d() function also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the buffer identifier. If allocation fails, M_NULL is returned.

Remarks

  •  Note that MIL-Lite compression support, particularly for M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

  •  You can allocate an image buffer with an M_KERNEL, M_STRUCT_ELEMENT, or M_PROC attribute with MIL-Lite. However, these attributes are not required to work under MIL-Lite.
    •

ARRAY IMAGE IMAGE SIGNED COMPRESS COMPRESS HOST MEMORY GRAB ON BOARD GRAB GRAB GRAB PROC COMPRESS BITMAPINFO DC ALLOC MAP MAPPABLE PAGED OFF BOARD OFF BOARD NON PAGED HOST MEMORY NON PAGED SHARED ON BOARD EXTENDED FORMAT GRAB DISP HOST ADDRESS PROC FAST OVERSCAN BUFFER ALLOCATION OVERSCAN SIZE FAST OVERSCAN BUFFER ALLOCATION OVERSCAN SIZE COMPRESS KERNEL STRUCT ELEMENT PROC  DEFAULT HOST         FLOAT SIGNED UNSIGNED  ARRAY IMAGE KERNEL LUT STRUCT ELEMENT COMPRESS DISP GRAB PROC JPEG LOSSLESS JPEG2000 LOSSLESS JPEG LOSSLESS INTERLACED  JPEG LOSSY JPEG2000 LOSSY JPEG LOSSY INTERLACED DIRECTX DIB GDI HOST MEMORY MAPPABLE OFF BOARD ON BOARD VIDEO MEMORY FAST MEMORY SHARED NON PAGED PAGED FAST OVERSCAN


MbufAllocColor

See Also | Example | Availability | MbufAlloc2d | MbufBayer
User Guide:
Allocating an application and its systems
Allocating and displaying an image buffer
Data buffers
Attribute
Controlling how color image buffers are stored
YUV buffers
LUTs and data buffers
Displaying multiple buffers
Dealing with color

Reference:
MappGetError
MbufAlloc1d
MbufAlloc2d
MbufControl
MbufFree
MbufInquire
MsysAlloc
MsysControl
channel_switch.c
mbufbayercolorfilter.c
mbufcolor.c
mdblgrab.c
mdiggrabsequence.c
mdigmultdestination.c
mdigmultformat.c
mdispoverlay.c
mdispwindow.c
mmorphisjpeg2000.c
odysseymultiboard.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Allocate a color data buffer.
Syntax
MIL_ID MbufAllocColor(
MIL_ID SystemId,
long SizeBand,
long SizeX,
long SizeY,
long Type,
MIL_INT64 Attribute,
MIL_ID *BufIdPtr
)
Description

This function allocates a data buffer with multiple color bands on the specified system. This type of buffer allows for the representation of color images (for example, RGB).

This function allocates buffers that have a two-dimensional surface for each specified color band. You can use MbufAlloc1d() and MbufAlloc2d() to create single band one- or two-dimensional data buffers, respectively.

After allocating a buffer, we recommend that you check if the operation was successful, using MappGetError(), or by verifying that the buffer identifier returned is not M_NULL.

When a buffer is no longer required, release it, using MbufFree().

Parameters
SystemId

Specifies the system on which to allocate the buffer. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 SizeBand

 Specifies the number of (x,y) surfaces (also called color bands) to allocate to the buffer.  Specify one band for each of the color components that the buffer needs to store (for example, monochrome images require one band; RGB color images require three color bands). This parameter can be set to any non-zero integer value. However, in general, only 1- and 3-band buffers are allowed.

 SizeX

 Specifies the buffer width. The units are determined by the selected buffer attribute.  For example, if the buffer has an image buffer attribute, width is specified in pixels.

 SizeY

 Specifies the buffer height. The units are determined by the selected buffer attribute.  For example, if the buffer has an image buffer attribute, height is specified in pixels.

 Type

 Specifies a combination of two values: data type and data depth per band.  Specify the depth of the buffer per band as one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  1

 Specifies a 1-bit (packed binary) buffer. Note, you cannot allocate a 1-bit (binary) LUT buffer.  Specifies a 1-bit (packed binary) buffer ...

  Open   Collapse  8

 Specifies an 8-bit buffer.  Specifies an 8-bit buffer.

  Open   Collapse  16

 Specifies a 16-bit buffer.  Specifies a 16-bit buffer.

  Open   Collapse  32

 Specifies a 32-bit buffer.  Specifies a 32-bit buffer.

      [Combination constants]

 You can add one of the following to the Type parameter to specify the data type. Supported data types depend on the specified depth.

  Open   Collapse  Value
Description

  Open   Collapse  M_FLOAT

 Specifies that the type of data is floating point. The valid data depth is 32 bits.  Specifies that the type of data is floating point ...

  Open   Collapse  M_SIGNED

 Specifies that the type of data is signed. The valid data depths are 8, 16, or 32 bits.  Specifies that the type of data is signed ...

  Open   Collapse  M_UNSIGNED

 Specifies that the type of data is unsigned. The valid data depths are 1, 8, 16, or 32 bits.  Specifies that the type of data is unsigned ...

This is the default value.

 Attribute

 Specifies the buffer usage.  MIL uses this information to determine where to allocate the buffer in physical memory. Set this parameter to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_IMAGE

 Allocates a buffer to store image data.  Allocates a buffer to store image data.

  Open   Collapse  M_LUT

 Allocates a buffer to store lookup table data.  Allocates a buffer to store lookup table data ...

 The valid data depths are 8, 16, or 32 bits and only the planar internal storage format is valid.

      [Combination constants]

 When allocating an image buffer (M_IMAGE), you must also specify the intended purpose of this buffer by combining M_IMAGE with one or more of the following values:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_COMPRESS

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can hold compressed data. Note that a buffer with this attribute cannot have the M_SIGNED data type.  Specifies an image buffer that can hold compressed data ...

 When allocating buffers for operations that require a source and destination buffer, and one of the buffers has an M_COMPRESS attribute, the data will be compressed or decompressed depending on the attributes of the destination buffer. If both the source and destination buffers have M_COMPRESS specifiers but different compression types, the data will be re-compressed according to the settings of the destination buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_DISP

 Specifies an image buffer that can be displayed.  Specifies an image buffer that can be displayed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band display buffers with a depth greater than 16 bits cannot be allocated. Three-band display buffers can only be allocated with 8 bits per band.

c

  Open   Collapse  M_GRAB

 Specifies an image buffer in which to grab data. This type of buffer is usually allocated in MIL-reserved, physically contiguous, non-paged memory.  Specifies an image buffer in which to grab data ...

 For Host buffers (M_HOST_MEMORY), the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of MIL-reserved, non-paged memory (specified at installation time or using MilConfig).

 For on-board buffers (M_ON_BOARD), the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of on-board memory.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band buffers with a depth of 8 or 16 bits (monochrome) and 3-band buffers with a depth of 8 bits (color) can have an M_GRAB attribute.

a

c
d
e

h
i

m
n
o

q
r

 Single-band or 3-band buffers, both with a depth of 8 bits can have an M_GRAB attribute.

b

f
g

j
k
l

p

  Open   Collapse  M_PROC

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can be processed.  Specifies an image buffer that can be processed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 For systems with on-board processors, the total number of M_PROC buffers is limited by the amount of on-board memory.

c
d
e

m
n
o

      [Combination constants]

[MIL-Lite with restriction]

 For an M_COMPRESS type of image buffer, one of the following values can be added to indicate the type of compressed data. The image buffer's data depth dictates which compression type can be selected.

  Open   Collapse  Value
Description

  Open   Collapse  M_JPEG_LOSSLESS

 Specifies that the buffer will be used to hold JPEG lossless data. The supported data formats are: 1-band, 8- or 16-bit data, and 3-band data in M_RGB24 or M_RGB48 format.  Specifies that the buffer will be used to hold JPEG lossless data ...

  Open   Collapse  M_JPEG2000_LOSSLESS

 Specifies that the buffer will be used to hold JPEG2000 lossless data. The supported data formats are: 1-band, 8- or 16-bit data, and 3-band, 8- or 16-bit data in M_RGB24 + M_PLANAR, M_RGB48 + M_PLANAR, or M_YUV24 + M_PLANAR format.  Specifies that the buffer will be used to hold JPEG2000 lossless data ...

  Open   Collapse  M_JPEG_LOSSLESS_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossless data in separate fields. The supported data formats are 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG lossless data in separate fields ...

  Open   Collapse  M_JPEG_LOSSY

 Specifies that the buffer will be used to hold JPEG lossy data. The supported data formats are: 1-band 8-bit data, and 3-band 8-bit data in M_RGB24, M_YUV24, M_YUV12, M_YUV9, M_YUV16 + M_PLANAR, or M_YUV16 + M_PACKED format.  Specifies that the buffer will be used to hold JPEG lossy data ...

This is the default value.

  Open   Collapse  M_JPEG2000_LOSSY

 Specifies that the buffer will be used to hold JPEG2000 lossy data. The supported data formats are: 1-band, 8- or 16-bit data, and 3-band, 8- or 16-bit data in M_RGB24, M_RGB48, M_YUV9, M_YUV12, M_YUV16 + M_PLANAR, or M_YUV24 format.  Specifies that the buffer will be used to hold JPEG2000 lossy data ...

  Open   Collapse  M_JPEG_LOSSY_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossy data in separate fields. The supported data formats are: 1-band 8-bit data, and 3-band 8-bit data in M_YUV16 + M_PACKED format.  Specifies that the buffer will be used to hold JPEG lossy data in separate fields ...

      [Combination constants]

 MIL automatically selects the most appropriate storage format according to the specified intended usage attribute. For general processing, MIL will convert the data when the function requires a different format. If the default storage format is not appropriate and you want to avoid conversion during a time critical operation, you can add a storage format, a location specifier, and a storage format specifier for color buffers.

 To specify a storage format for an image buffer, you can add one or more of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DIB

 Forces the buffer to be a DIB buffer. This ensures your buffer is stored with a DIB header. Use MbufInquire() with M_BITMAPINFO to return a pointer (LPBITMAPINFO) to the header of the MIL buffer.  Forces the buffer to be a DIB buffer ...

  Open   Collapse  M_DIRECTX

 Forces the buffer to be a DirectX surface.  Forces the buffer to be a DirectX surface.

  Open   Collapse  M_GDI

 Forces the buffer to be compatible with GDI.  Forces the buffer to be compatible with GDI ...

 When using a device context (using MbufControl() with M_DC_ALLOC) for drawing, the buffer should be internally stored in GDI format, and cannot be a child buffer.

      [Combination constants]

 To specify a storage format for color buffers, you can add one of the values below. Note that the buffer must be a color buffer. Also note that it might be slower to use buffers that have been forced with one of these attributes. Although there is no right or wrong storage format to use, certain operations are optimized for some formats.

  Open   Collapse  Value
Description

  Open   Collapse  M_PACKED

 Specifies that the buffer bands must be packed (color buffer only); that is, the pixel components are stored together (RGB RGB RGB ...). Typically, packed buffers are used for display (M_DISP). Note that it might be slower to process buffers with the M_PACKED attribute. Also, note that you cannot allocate a packed LUT buffer.  Specifies that the buffer bands must be packed (color buffer only); that is, the pixel components are stored together (RGB RGB RGB ...) ...

  Open   Collapse  M_PLANAR

 Specifies that the buffer bands must be planar (color buffer only); that is, each pixel is stored as three component planes (RRR... GGG... BBB...). Typically, planar buffers are used for processing (M_PROC).  Specifies that the buffer bands must be planar (color buffer only); that is, each pixel is stored as three component planes (RRR... GGG.. ...

      [Combination constants]

[All except
        Matrox Iris]

 To specify a specific packed or planar color buffer format, add one of the values below to either M_PACKED or M_PLANAR, respectively. Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_RGB24

 Specifies 24-bit color depth (RGB 8:8:8) packed or planar pixels.  Specifies 24-bit color depth (RGB 8:8:8) packed or planar pixels ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with planar (M_PLANAR) grab (M_GRAB) buffers.

a

c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

 This value can be used with packed (M_PACKED) grab (M_GRAB) buffers.

g

j
k

  Open   Collapse  M_YUV16

 Specifies YUV16 packed or planar (4:2:2) pixels.  Specifies YUV16 packed or planar (4:2:2) pixels ...

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with packed (M_PACKED) grab (M_GRAB) buffers.

a
b

d
e

k
l
m
n
o
p
q
r

 This value can be used with either packed (M_PACKED) or planar (M_PLANAR) grab (M_GRAB) buffers.

g

 Only available on the PC/104-Plus form factor (for M_PACKED buffers).

k

      [Combination constants]

[All except
        Matrox Iris]

 To specify a specific planar color buffer format, add one of the values below to M_PLANAR. Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_RGB3

 Specifies 3-bit color depth (RGB 1:1:1) planar pixels.  Specifies 3-bit color depth (RGB 1:1:1) planar pixels.

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_RGB48

 Specifies 48-bit color depth (RGB 16:16:16) planar pixels.  Specifies 48-bit color depth (RGB 16:16:16) planar pixels ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p

Specifics

 This value can be used with grab (M_GRAB) buffers.

c
d
e

m
n
o

  Open   Collapse  M_RGB96

 Specifies 96-bit color depth (RGB 32:32:32) planar pixels.  Specifies 96-bit color depth (RGB 32:32:32) planar pixels ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

c

  Open   Collapse  M_YUV9

 Specifies YUV9 planar pixels.  Specifies YUV9 planar pixels.

a
b

d
e

g
h
i
j
k
l

p
q
r

  Open   Collapse  M_YUV12

 Specifies YUV12 planar pixels.  Specifies YUV12 planar pixels ...

a
b

d
e

g
h
i
j
k
l

p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

  Open   Collapse  M_YUV24

 Specifies YUV24 planar pixels.  Specifies YUV24 planar pixels ...

a
b

d
e

g
h
i
j
k
l

p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

      [Combination constants]

[All except
        Matrox Genesis and Matrox Iris]

 To specify a specific packed color buffer format for an image buffer, you can add one of the values below to M_PACKED. Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_BGR24

 Specifies 24-bit color depth (BGR) packed pixels.  Specifies 24-bit color depth (BGR) packed pixels ...

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

a
b

g

j
k

m
n
o

 This value can be used with grab (M_GRAB) buffers only if a color DCF is used during the grab.

h
i

  Open   Collapse  M_BGR32

 Specifies 32-bit color depth (BGR) packed pixels.  Specifies 32-bit color depth (BGR) packed pixels ...

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

a
b

d
e

g

j
k

m
n
o
p
q
r

 This value can be used with grab (M_GRAB) buffers only if a color DCF is used during the grab.

h
i

  Open   Collapse  M_RGB15

 Specifies 16-bit color depth packed pixels (XRGB 1:5:5:5). Note that when accessing an M_RGB15 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0.  Specifies 16-bit color depth packed pixels (XRGB 1:5:5:5) ...

a
b

d
e

g

j
k
l

p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

  Open   Collapse  M_RGB16

 Specifies 16-bit color depth packed pixels (RGB 5:6:5). Note that when accessing an M_RGB16 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0.  Specifies 16-bit color depth packed pixels (RGB 5:6:5). Note that when accessing an M_RGB16 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0 ...

a
b

d
e

g

j
k
l

p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

 Only available on the PC/104-Plus form factor.

j
k

  Open   Collapse  M_YUV16_UYVY

 Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the UYVY order. For more information, see the YUV buffers section in
          Chapter 14: Specifying and managing your data buffers.  Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the UYVY order ...

a

g
h
i
j
k

p

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

  Open   Collapse  M_YUV16_YUYV

 Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the YUYV order. For more information, see the YUV buffers section in
          Chapter 14: Specifying and managing your data buffers.  Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the YUYV order ...

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

a
b

d
e

g

k
l
m
n
o
p
q
r

      [Combination constants]

 To specify a location for an image buffer, you can add one of the following values:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_HOST_MEMORY

 Forces the buffer in Host memory.  Forces the buffer in Host memory ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

a
b

d
e
f
g
h
i
j
k
l

p
q
r

  Open   Collapse  M_MAPPABLE

 Forces the buffer to be allocated in non-paged memory that can be set in the address space of the process (Host memory). By default, however it is not mapped to Host memory (that is, by default the buffer will have a physical address, but not a Host address). Use MbufControl() with M_MAP to enable or disable the mapping to Host memory.  Forces the buffer to be allocated in non-paged memory that can be set in the address space of the process (Host memory) ...

 This setting is useful when dealing with many large buffers that cannot all be mapped in Host memory at the same time. By allocating a buffer as M_MAPPABLE, it can be mapped and unmapped as needed.

 Note that, if used with the M_PAGED attribute, an error will be generated.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OFF_BOARD

 Ensures that the buffer is not in on-board memory.  Ensures that the buffer is not in on-board memory ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 To ensure that an M_OFF_BOARD buffer can be used by the bus master transfer section of the board, the buffer must be allocated in non-paged memory (M_OFF_BOARD + M_NON_PAGED or M_HOST_MEMORY + M_NON_PAGED).

d
e

m
n
o

q
r

  Open   Collapse  M_ON_BOARD

 Forces the buffer in on-board memory.  Forces the buffer in on-board memory ...

a

c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

c

m
n
o

 By default, all on-board buffers are allocated in memory that is not mapped on the PCI bus. This unshared memory cannot be accessed by the Host or any system other than the one on which it was allocated. See combination values (M_SHARED) below to change this default behavior.

d
e
f

m
n
o

q
r

  Open   Collapse  M_VIDEO_MEMORY

 Forces the buffer in (off-screen) display memory of your graphics controller. Display memory is also referred to as video memory or frame buffer memory.  Forces the buffer in (off-screen) display memory of your graphics controller ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 You can add one of the following values when allocating an on-board image buffer (M_ON_BOARD).

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_FAST_MEMORY

 Forces the buffer in the G4 PowerPC fast-processing memory. This memory is L3 external cache. It must be enabled using the OdcMon utility before it can be used.  Forces the buffer in the G4 PowerPC fast-processing memory ...

 Matrox Odyssey Xpro has up to 2 Mbytes of memory available for fast processing. Any buffer allocated in fast memory must entirely fit within this memory. If it does not, the buffer will be allocated in ordinary processing memory instead.

 Use MbufInquire() with M_EXTENDED_FORMAT to establish if the buffer was allocated in fast processing memory.

 Fast processing memory is only accessible to the G4 PowerPC microprocessor and not to the Host, frame grabber module, or PA. Therefore, depending on the operation, allocating a buffer in fast processing memory might not accelerate processing.

 Note that M_GRAB and M_DISP are not supported with this attribute.

m
n
o

  Open   Collapse  M_SHARED

 Forces the buffer in processing memory that is mapped on the PCI bus.  Forces the buffer in processing memory that is mapped on the PCI bus ...

 You can use MbufInquire() with M_HOST_ADDRESS to retrieve the address of the buffer.

d
e

m
n
o

q
r

Specifics

 Use the OdcConfig utility to establish the required amount of shared memory.

m
n
o

 Use the MILConfig utility to establish the required amount of shared memory.

d
e

q
r

      [Combination constants]

[All except
        ]

 To specify a type of memory, either paged or non-paged, you can add one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_NON_PAGED

 Forces the buffer in MIL-reserved, non-pageable memory.  Forces the buffer in MIL-reserved, non-pageable memory.

  Open   Collapse  M_PAGED

 Forces the buffer in pageable memory.  Forces the buffer in pageable memory.

      [Combination constants]

 When allocating an M_PROC image buffer, you can add the following value to override the MsysControl() M_FAST_OVERSCAN_BUFFER system control setting and force the allocation of an overscan region. When this attribute is set, the setting of the M_ALLOCATION_OVERSCAN_SIZE system control determines the size of the overscan region and the M_FAST_OVERSCAN_BUFFER setting is ignored.

 Note that this attribute is only useful when added to a buffer on which you want to perform neighborhood processing operations.

  Open   Collapse  Value
Description

  Open   Collapse  M_FAST_OVERSCAN

 Specifies that the buffer is allocated with an overscan region, and the size of the region is determined by the M_ALLOCATION_OVERSCAN_SIZE setting of MsysControl().  Specifies that the buffer is allocated with an overscan region, and the size of the region is determined by the M_ALLOCATION_OVERSCAN_SIZE setting of MsysControl().

 BufIdPtr

 Specifies the address of the variable in which to write the buffer identifier.  Since the MbufAllocColor() function also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the buffer identifier. If allocation fails, M_NULL is returned.

Remarks

  •  Note that MIL-Lite compression support, particularly for M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

  •  You can allocate an image buffer with an M_KERNEL, M_STRUCT_ELEMENT, or M_PROC attribute with MIL-Lite. However, these attributes are not required to work under MIL-Lite.
    •

IMAGE IMAGE SIGNED COMPRESS COMPRESS HOST MEMORY GRAB ON BOARD GRAB GRAB GRAB PROC COMPRESS RGB24 RGB48 RGB24 YUV24 YUV12 YUV9 YUV16 PLANAR YUV16 PACKED YUV16 PACKED RGB24 PLANAR RGB48 PLANAR YUV24 PLANAR RGB24 RGB48 YUV9 YUV12 YUV16 PLANAR YUV24 BITMAPINFO DC ALLOC DISP PACKED PROC PACKED PLANAR GRAB PLANAR GRAB PACKED GRAB PACKED GRAB PACKED PLANAR GRAB PACKED PLANAR GRAB GRAB GRAB GRAB GRAB PACKED GRAB GRAB GRAB GRAB GRAB RGB15 PACKED GRAB RGB16 PACKED GRAB GRAB GRAB MAP MAPPABLE PAGED OFF BOARD OFF BOARD NON PAGED HOST MEMORY NON PAGED SHARED ON BOARD EXTENDED FORMAT GRAB DISP HOST ADDRESS PROC FAST OVERSCAN BUFFER ALLOCATION OVERSCAN SIZE FAST OVERSCAN BUFFER ALLOCATION OVERSCAN SIZE COMPRESS KERNEL STRUCT ELEMENT PROC  DEFAULT HOST          FLOAT SIGNED UNSIGNED  IMAGE LUT COMPRESS DISP GRAB PROC JPEG LOSSLESS JPEG LOSSLESS INTERLACED  JPEG LOSSY JPEG LOSSY INTERLACED JPEG2000 LOSSLESS JPEG2000 LOSSY DIB DIRECTX GDI PACKED PLANAR  RGB24  YUV16 RGB3  RGB48  RGB96  YUV9  YUV12 YUV24 BGR24  BGR32  RGB15  RGB16  YUV16 UYVY YUV16 YUYV HOST MEMORY MAPPABLE OFF BOARD ON BOARD VIDEO MEMORY FAST MEMORY SHARED NON PAGED PAGED  FAST OVERSCAN


MbufBayer

See Also | Example | Availability | MbufAllocColor | MbufChild1d
User Guide:
Using buffers with the Bayer color filter

Reference:
MbufAlloc1d
MbufAlloc2d
MbufPut1d
MbufPut2d
MdigControl
mbufbayercolorfilter.c
mgrabbayer.c
Available in MIL-Lite

Available in MIL
Synopsis
Decode the color information of a single-band, Bayer color-encoded image.
Syntax
void MbufBayer(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
MIL_ID CoefOrExpId,
long ControlFlag
)
Description

This function converts a single-band, Bayer color-encoded image into a 1- or 3-band image. This function can also perform white balance correction and gamma correction on the image, if the appropriate coefficients and exponents are provided, respectively. In addition, the function can also perform color correction on the image if the adaptive algorithm is used to decode the image (the demosaicing process).

Color correction, white balance correction and then gamma correction operations are performed on the intermediate RGB values recovered by the demosaicing process (before being converted into the proper destination format).

Note that you can use MbufBayer() to automatically calculate the appropriate white balance correction coefficients. To do so, specify a Bayer color-encoded source image that in reality should be a uniform shade of gray that is not too saturated, and add M_WHITE_BALANCE_CALCULATE to the ControlFlag parameter. Alternatively, you could fill an array with custom values, and then load these values (in order) into the MIL array MbufPut1d() or MbufPut2d(). The order of the data in the array is important. For more information, see the Correcting the white balance of your Bayer images subsection in the Using buffers with the Bayer color filter section in Chapter 14: Specifying and managing your data buffers.

Ensure that the image was grabbed under the same lighting conditions as subsequent source images. After converting the image and calculating the appropriate coefficients, the coefficients are written to the specified MIL array buffer and the converted image is then corrected using these automatically calculated coefficients.

For more information on Bayer color-encoded images, the conversion, and the actual equations used to perform white balance and gamma correction, see the Using buffers with the Bayer color filter section in Chapter 14: Specifying and managing your data buffers.

Note that if the scale of the image is changed (using MdigControl() with M_GRAB_SCALE...) to a value other than 1 prior to grabbing a Bayer image, the Bayer image will not be converted property; some of the Bayer pattern is lost during the scaling process, rendering color recovery impossible.

Parameters
SrcImageBufId

Specifies the identifier of the source image buffer. To achieve maximum conversion performance, the source image buffer should be an unsigned one-band image buffer. If you specify a 3-band buffer, only the first band will be used.

DestImageBufId

Specifies the identifier of the destination image buffer. The results of the white balance correction, gamma correction and color correction are saturated, if necessary, according to identifier the bit depth of the destination.

The destination buffer should be either monochrome, or a 3-band color buffer in one of the following formats:

  • Any RGB color buffer format + M_PLANAR.
  • M_BGR32 + M_PACKED.
  • M_YUV16_YUYV (equivalent to M_YUV16 + M_PACKED).

When you convert the image using the adaptive algorithm, it is recommended that you use a planar RGB buffer (any RGB color buffer format + M_PLANAR). The other destination formats mentioned above can be used, but require an extra conversion operation that increases processing time.

CoefOrExpId

Specifies whether white balance correction and gamma correction are performed, and the coefficients and exponents used to perform these corrections, respectively. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Performs no white balance or gamma correction on the source image; only the conversion is performed.  Performs no white balance or gamma correction on the source image; only the conversion is performed.

  Open   Collapse  MIL array buffer identifier

 Specifies the MIL array buffer which contains the coefficients and exponents to perform the corrections.  Specifies the MIL array buffer which contains the coefficients and exponents to perform the corrections ...

 The buffer must be allocated with MbufAlloc1d() or MbufAlloc2d(), as a single-band 32-bit floating-point buffer with an M_ARRAY attribute and a 3x1 or 6x1 dimension. If a 3x1 MIL array buffer is specified, no gamma correction is performed.

 The first 3 elements in the MIL array buffer specify the coefficients to perform the white balance correction on the intermediate red, green, and blue bands, respectively. If you add M_WHITE_BALANCE_CALCULATE to the ControlFlag parameter, these three elements are overwritten with the coefficients that are automatically calculated. Note that white balance correction coefficients must be positive.

 The next 3 elements, if any, specify the exponents to perform the gamma correction on the intermediate red, green, and blue bands, respectively. Note that the gamma correction exponents must be positive, are typically in the range of 0.0 to 1.0, and are most commonly specified as 0.4.

 ControlFlag

 Identifies the Bayer pattern to use in the conversion, and specifies whether the white balance correction coefficients will be calculated.  This parameter can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_BAYER_BG

 Uses the Bayer pattern that has the top-left pixel as the blue component and the next pixel as the green component. That is, pixel [0,0] is blue, pixel [1,0] is green and pixel [1,1] is red in the source image.  Uses the Bayer pattern that has the top-left pixel as the blue component and the next pixel as the green component ...

  Open   Collapse  M_BAYER_GB

 Uses the Bayer pattern that has the top-left pixel as the green component and the next pixel as the blue component. That is, pixel [0,0] is green, pixel [1,0] is blue and pixel [0,1] is red in the source image.  Uses the Bayer pattern that has the top-left pixel as the green component and the next pixel as the blue component ...

  Open   Collapse  M_BAYER_GR

 Uses the Bayer pattern that has the top-left pixel as the green component and the next pixel as the red component. That is, pixel [0,0] is green, pixel [1,0] is red and pixel [0,1] is blue in the source image.  Uses the Bayer pattern that has the top-left pixel as the green component and the next pixel as the red component ...

  Open   Collapse  M_BAYER_RG

 Uses the Bayer pattern that has the top-left pixel as the red component and the next pixel as the green component. That is, pixel [0,0] is red, pixel [1,0] is green and pixel [1,1] is blue in the source image.  Uses the Bayer pattern that has the top-left pixel as the red component and the next pixel as the green component ...

      [Combination constants]

 The value below can be added to the ControlFlag parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_WHITE_BALANCE_CALCULATE

 Determines the 3 coefficients required to white balance the source image, and writes these coefficients into the CoefOrExpId array. Note that to use M_WHITE_BALANCE_CALCULATE, the source image must be a uniform shade of gray that is not too saturated.  Determines the 3 coefficients required to white balance the source image, and writes these coefficients into the CoefOrExpId array ...

      [Combination constants]

 By default, the bilinear interpolation demosaicing algorithm is used. You can override this default by adding the following value to the ControlFlag parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_ADAPTIVE

 Specifies to use the adaptive demosaicing algorithm for the conversion process. By using this algorithm, false colors and the zipper effect are minimized.  Specifies to use the adaptive demosaicing algorithm for the conversion process ...

      [Combination constants]

 You can add the following value to M_ADAPTIVE to perform a color correction on the image.

  Open   Collapse  Value
Description

  Open   Collapse  M_COLOR_CORRECTION

 Specifies that a color correction is performed to further eliminate false colors.  Specifies that a color correction is performed to further eliminate false colors.

WHITE BALANCE CALCULATE PLANAR BGR32 PACKED YUV16 YUYV
                 YUV16 PACKED PLANAR ARRAY WHITE BALANCE CALCULATE WHITE BALANCE CALCULATE ADAPTIVE    DEFAULT   BAYER BG BAYER GB BAYER GR BAYER RG WHITE BALANCE CALCULATE ADAPTIVE COLOR CORRECTION


MbufChild1d

See Also | Example | Availability | MbufBayer | MbufChild2d
User Guide:
Manipulating and controlling certain data buffer areas

Reference:
MbufChildColor2d
MbufFree
There are no examples containing MbufChild1d().
Available in MIL-Lite

Available in MIL
Synopsis
Allocate a 1D child data buffer.
Syntax
MIL_ID MbufChild1d(
MIL_ID ParentBufId,
long OffX,
long SizeX,
MIL_ID *BufIdPtr
)
Description

This function allocates a one-dimensional child data buffer within the specified, previously allocated parent data buffer. If the parent buffer is multi-band, this function allocates a multi-band child buffer; the child is allocated within the specified one-dimensional region in each color band. To allocate a child in one specific band, or specifically in all bands, use MbufChildColor2d() instead of MbufChild1d().

The child buffer is not allocated its own memory space; it remains part of the parent buffer. Therefore, any modification to the child buffer affects the parent and vice versa. Note, a parent buffer can have several child buffers.

A child buffer is considered a data buffer in its own right, and can be used in the same circumstances as its parent buffer. A child buffer inherits its type and attributes from the parent buffer.

When this buffer is no longer required, it can be released using MbufFree().

Parameters
ParentBufId

Specifies the identifier of the parent buffer.

OffX

Specifies the offset of the child buffer relative to the parent buffer's top-left pixel. The offset must be within the width of the parent buffer.

SizeX

Specifies the width of the child buffer.

BufIdPtr

Specifies the address of the variable in which the child buffer identifier is to be written. Since the MbufChild1d() function also returns the child buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value
The returned value is the child buffer identifier. If allocation fails, M_NULL is returned.


MbufChild2d

See Also | Example | Availability | MbufChild1d | MbufChildColor2d
User Guide:
Manipulating and controlling certain data buffer areas
Displaying multiple buffers

Reference:
MbufChildColor2d
MbufFree
channel_switch.c
mbufcolor.c
mcode.c
mgrabbayer.c
mimfft.c
mimmorphic.c
mimpolar.c
mimwarp.c
mocr.c
mpat.c
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Allocate a child buffer within a specific region of a parent buffer.
Syntax
MIL_ID MbufChild2d(
MIL_ID ParentBufId,
long OffX,
long OffY,
long SizeX,
long SizeY,
MIL_ID *BufIdPtr
)
Description

This function allocates a two-dimensional child buffer within a region of the specified, previously allocated data buffer. If the parent buffer is multi-band, this function allocates a multi-band child buffer; the child is allocated within the specified region in each color band. To allocate a child region in one specific band, or specifically in all bands, use MbufChildColor2d() instead of MbufChild2d().

The child buffer is not allocated its own memory space; it remains part of the parent buffer. Any modification to the child buffer affects the parent and vice versa. Note, a parent buffer can have several child buffers.

A child buffer is considered a data buffer in its own right, and can be used in the same circumstances as its parent buffer. A child buffer inherits its type and attributes from the parent buffer.

When this buffer is no longer required, it can be released, using MbufFree().

Parameters
ParentBufId

Specifies the identifier of the parent buffer.

OffX

Specifies the horizontal pixel offset of the child buffer's top-left pixel, relative to the parent buffer's top-left pixel. The given offset must be within the width of the parent buffer.

OffY

Specifies the vertical pixel offset of the child buffer's top-left pixel, relative to the parent buffer's top-left pixel. The given offset must be within the height of the parent buffer.

SizeX

Specifies the width of the child buffer.

SizeY

Specifies the height of the child buffer.

BufIdPtr

Specifies the address of the variable in which the child buffer identifier is to be written. Since the MbufChild2d() function also returns the child buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value
The returned value is the child buffer identifier. If allocation fails, M_NULL is returned.


MbufChildColor2d

See Also | Example | Availability | MbufChild2d | MbufChildColor
User Guide:
Manipulating and controlling certain data buffer areas

Reference:
MbufFree
There are no examples containing MbufChildColor2d().
Available in MIL-Lite

Available in MIL
Synopsis
Allocate a child data buffer within a color parent buffer.
Syntax
MIL_ID MbufChildColor2d(
MIL_ID ParentBufId,
long Band,
long OffX,
long OffY,
long SizeX,
long SizeY,
MIL_ID *BufIdPtr
)
Description

This function allocates a child data buffer within the specified, previously allocated, color parent data buffer. It selects a two-dimensional region in one or all of the color bands of the parent data buffer and allocates the region as a child of that buffer.

The child buffer is not allocated its own memory space; it remains part of the parent buffer. Therefore, any modification to the child buffer affects the parent and vice versa. Note, a parent buffer can have several child buffers.

A color child buffer is considered a data buffer in its own right. It can be used in the same circumstances as its parent buffer. A child buffer inherits its type and attributes from the parent buffer.

When this buffer is no longer required, release it, using MbufFree().

Parameters
ParentBufId

Specifies the identifier of the parent buffer.

[MIL only]

The parent buffer cannot have an M_COMPRESS attribute unless the Band parameter is set to M_ALL_BANDS.

Band

Specifies the color band of the parent data buffer from which to allocate the child data buffer. The specified color band should be valid in the parent buffer.

The Band parameter can be set to one of the following values:

Open Collapse Value Description
Open Collapse M_ALL_BANDS

 Specifies all color bands (for RGB, HLS, and YUV parent buffers). That is, M_ALL_BANDS allocates a child buffer with the same number of bands as the parent buffer  Specifies all color bands (for RGB, HLS, and YUV parent buffers) ...

  Open   Collapse  M_BLUE

 Specifies the blue color band (for RGB parent buffers).  Specifies the blue color band (for RGB parent buffers).

  Open   Collapse  M_GREEN

 Specifies the green color band (for RGB parent buffers).  Specifies the green color band (for RGB parent buffers).

  Open   Collapse  M_HUE

 Specifies the hue band (for HLS parent buffers).  Specifies the hue band (for HLS parent buffers).

  Open   Collapse  M_LUMINANCE

 Specifies the luminance band (for HLS parent buffers).  Specifies the luminance band (for HLS parent buffers).

  Open   Collapse  M_RED

 Specifies the red color band (for RGB parent buffers).  Specifies the red color band (for RGB parent buffers).

  Open   Collapse  M_SATURATION

 Specifies the saturation band (for HLS parent buffers).  Specifies the saturation band (for HLS parent buffers).

  Open   Collapse  M_U

 Specifies the U band (for YUV parent buffers). Note that the dimensions of the child buffer must not exceed the dimensions of the U band of the parent.  Specifies the U band (for YUV parent buffers) ...

  Open   Collapse  M_V

 Specifies the V band (for YUV parent buffers). Note that the dimensions of the child buffer must not exceed the dimensions of the V band of the parent.  Specifies the V band (for YUV parent buffers) ...

  Open   Collapse  M_Y

 Specifies the Y band (for YUV parent buffers).  Specifies the Y band (for YUV parent buffers).

  Open   Collapse  Value

 Specifies the index of the band to use. Valid index values are from 0 to (number of bands of the buffer - 1). Band 0 corresponds to: the red band (for RGB parent buffers), the hue band (for HLS parent buffers), and the Y band (for YUV parent buffers). Band 1 corresponds to: the green band (for RGB parent buffers), the saturation band (for HLS parent buffers) , and the U band (for YUV parent buffers). Band 2 corresponds to: the blue band (for RGB parent buffers), the luminance band (for HLS parent buffers), and the V band (for YUV parent buffers).  Specifies the index of the band to use ...

 OffX

 Specifies the horizontal offset of the child buffer, relative to the parent buffer's top-left pixel.  The offset must be within the width of the parent buffer.

 OffY

 Specifies the vertical offset of the child buffer, relative to the parent buffer's top-left pixel.  The offset must be within the height of the parent buffer.

 SizeX

 Specifies the width of the child buffer.

 SizeY

 Specifies the height of the child buffer.

 BufIdPtr

 Specifies the address of the variable in which the child buffer identifier is to be written.  Since the MbufChildColor2d() function also returns the child buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the child buffer identifier. If allocation fails, M_NULL is returned.

COMPRESS ALL BANDS ALL BANDS   ALL BANDS BLUE  GREEN  HUE LUMINANCE RED SATURATION U V Y


MbufChildColor

See Also | Example | Availability | MbufChildColor2d | MbufChildMove
User Guide:
Manipulating and controlling certain data buffer areas
Displaying multiple buffers
Processing

Reference:
MbufChildColor2d
MbufFree
mbufcolor.c
Available in MIL-Lite

Available in MIL
Synopsis
Allocate a color-band child data buffer within a color parent buffer.
Syntax
MIL_ID MbufChildColor(
MIL_ID ParentBufId,
long Band,
MIL_ID *BufIdPtr
)
Description

This function allocates a child data buffer within the specified, previously allocated, color parent data buffer. It selects one of the color bands of the data buffer and allocates the band as a child of that buffer.

The child buffer is not allocated its own memory space; it remains part of the parent buffer. Therefore, any modification to the child buffer affects the parent and vice versa. Note, a parent buffer can have several child buffers.

A color child buffer is considered a data buffer in its own right. It can be any color band of its parent buffer, and can be used in the same circumstances as its parent buffer. A child buffer inherits its type and attributes from the parent buffer.

To allocate a child in one specific band, or specifically in all bands, use MbufChildColor2d() instead of MbufChildColor().

When this buffer is no longer required, release it, using MbufFree().

Parameters
ParentBufId

Specifies the identifier of the parent buffer.

[MIL only]

The parent buffer cannot have an M_COMPRESS attribute.

Band

Specifies the color band of the parent data buffer from which to allocate the child data buffer. The specified color band should be valid in the parent buffer.

The Band parameter can be set to one of the values below.

Open Collapse Value Description
Open Collapse M_BLUE

 Specifies the blue color band (for RGB parent buffers).  Specifies the blue color band (for RGB parent buffers).

  Open   Collapse  M_GREEN

 Specifies the green color band (for RGB parent buffers).  Specifies the green color band (for RGB parent buffers).

  Open   Collapse  M_HUE

 Specifies the hue band (for HLS parent buffers).  Specifies the hue band (for HLS parent buffers).

  Open   Collapse  M_LUMINANCE

 Specifies the luminance band (for HLS parent buffers).  Specifies the luminance band (for HLS parent buffers).

  Open   Collapse  M_RED

 Specifies the red color band (for RGB parent buffers).  Specifies the red color band (for RGB parent buffers).

  Open   Collapse  M_SATURATION

 Specifies the saturation band (for HLS parent buffers).  Specifies the saturation band (for HLS parent buffers).

  Open   Collapse  M_U

 Specifies the U band (for YUV parent buffers).  Specifies the U band (for YUV parent buffers).

  Open   Collapse  M_V

 Specifies the V band (for YUV parent buffers).  Specifies the V band (for YUV parent buffers).

  Open   Collapse  M_Y

 Specifies the Y band (for YUV parent buffers).  Specifies the Y band (for YUV parent buffers).

  Open   Collapse  Value

 Specifies the index of the band to use. Valid index values are from 0 to (number of bands of the buffer - 1). Band 0 corresponds to: the red band (for RGB parent buffers), the hue band (for HLS parent buffers), and the Y band (for YUV parent buffers). Band 1 corresponds to: the green band (for RGB parent buffers), the saturation band (for HLS parent buffers) , and the U band (for YUV parent buffers). Band 2 corresponds to: the blue band (for RGB parent buffers), the luminance band (for HLS parent buffers), and the V band (for YUV parent buffers).  Specifies the index of the band to use ...

 BufIdPtr

 Specifies the address of the variable in which the child buffer identifier is to be written.  Since the MbufChildColor() function also returns the child buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the child buffer identifier. If allocation fails, M_NULL is returned.

COMPRESS   BLUE
 GREEN
 HUE LUMINANCE RED SATURATION U V Y


MbufChildMove

Example | Availability | MbufChildColor | MbufClear
There are no examples containing MbufChildMove().
Available in MIL-Lite

Available in MIL
Synopsis
Move and resize a child buffer within the parent buffer.
Syntax
void MbufChildMove(
MIL_ID BufferID,
long OffsetX,
long OffsetY,
long SizeX,
long SizeY,
long ControlFlag
)
Description

This function moves and resizes a child buffer within the parent buffer.

Parameters
BufferID

Specifies the identifier of the child buffer to move and/or resize.

OffsetX

Specifies the new X-offset.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default value. The default is the current X-offset of the child buffer.  Specifies the default value ...

  Open   Collapse  Value

 Specifies the X-coordinate, in pixels.  Specifies the X-coordinate, in pixels.

 OffsetY

 Specifies the new Y-offset.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default value. The default is the current Y-offset of the child buffer.  Specifies the default value ...

  Open   Collapse  Value

 Specifies the Y-coordinate, in pixels.  Specifies the Y-coordinate, in pixels.

 SizeX

 Specifies the new width.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default value. The default is the current width of the child buffer.  Specifies the default value ...

  Open   Collapse  Value

 Specifies the number of pixels in the horizontal direction.  Specifies the number of pixels in the horizontal direction.

 SizeY

 Specifies the new height.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default value. The default is the current height of the child buffer.  Specifies the default value ...

  Open   Collapse  Value

 Specifies the number of pixels in the vertical direction.  Specifies the number of pixels in the vertical direction.

 ControlFlag

 This parameter is reserved for future use. Set this parameter to M_DEFAULT.

  DEFAULT   DEFAULT   DEFAULT   DEFAULT


MbufClear

See Also | Example | Availability | MbufChildMove | MbufControl
User Guide:
Processing calibrated images
Annotating the displayed image non-destructively
Preparing for graphics

Reference:
MgraClear
channel_switch.c
dtkobjecttracking.c
mbufbayercolorfilter.c
mbufcolor.c
mdigautofocus.c
mdiggrabmultiple.c
mdiggrabsequence.c
mdighook.c
mdigmultdestination.c
mdigmultformat.c
mdigprocess.c
mdigprocessmultiple.c
mdigsubtract.c
mdispoverlay.c
mdispselect.c
mdispwindow.c
mgenlc.c
mgrabbayer.c
mheliosconcurent.c
mimfft.c
mimmorphic.c
mimwarp.c
mmet2dig.c
mmorphisjpeg2000.c
mocr.c
mthread.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Clears a buffer to a specified color.
Syntax
void MbufClear(
MIL_ID DestImageBufId,
double Color
)
Description

This function clears the entire specified buffer to the specified color.

To clear a 16-bit or 32-bit multi-band buffer to a color value, use MgraClear().

Parameters
DestImageBufId

Specifies the identifier of the buffer to clear.

Color

Specifies the grayscale or RGB color value with which to clear the buffer. Set this parameter to one of the values below.

Open Collapse Value Description
Open Collapse M_RGB888(
long Red,
long Green,
long Blue
)

Sets an RGB value used to clear an 8-bit 3-band buffer to an RGB color. Sets an RGB value used to clear an 8-bit 3-band buffer to an RGB color ...

Parameters
Red

Specifies the red value of an RGB value.

Green

Specifies the green value of an RGB value.

Blue

Specifies the blue value of an RGB value.

Open Collapse Value

 Specifies a grayscale value used to clear the 1-band or multi-band buffer.  Specifies a grayscale value used to clear the 1-band or multi-band buffer ...

 If the destination buffer is 3-band, this value will be replicated in each band.


MbufControl

See Also | Example | Availability | MbufClear | MbufControlRegion
User Guide:
Mapping a data buffer to user-allocated memory
Annotating the displayed image non-destructively
Palettes and output LUTs for windowed display (256-color)
General steps
Controlling a JPEG compression
JPEG2000
Improving results
Working with tables
Data manipulation with multiple systems
Integrating native functions with MIL code

Reference:
MbufControlRegion
MbufHookFunction
MbufInquire
MdispLut
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
mdiggrabsequence.c
mdispoverlay.c
mdispwindowleveling.c
mfunc.c
mnatfct.c
mnatgen.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Iris
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Synopsis
Control a specified data buffer setting.
Syntax
void MbufControl(
MIL_ID BufId,
long ControlType,
double ControlValue
)
Description

This function allows you to control a specified data buffer setting.

Parameters
BufId

Specifies the identifier of the buffer to control.

ControlType

Specifies the buffer setting to control.

See the Parameter associations section for possible values.

ControlValue

Specifies the value needed for the setting.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

Open Collapse ControlType Description
ControlValue
Open Collapse M_ASSOCIATED_LUT

Sets whether to associate or disassociate a LUT buffer with the specified image buffer. The image buffer must be a 1-band 8-bit buffer. Sets whether to associate or disassociate a LUT buffer with the specified image buffer ...

M_DEFAULT

Disassociates a LUT buffer from the image buffer.

MIL LUT buffer identifier

Associates a LUT buffer with the image buffer. If and when the image buffer is selected to a windowed display, the required changes occur to produce the display effect of the LUT, unless the display is also associated with a custom LUT (MdispLut()). For windowed displays, MIL indirectly programs the physical output LUTs with the image's associated LUT (through the use of a Windows palette).

Open Collapse M_DC_ALLOC

Allocates a device context (DC) for drawing. Determine the DC handle (HDC) using MbufInquire() with the M_DC_HANDLE inquire type. When using this control type, the buffer should be internally stored in M_GDI format, and cannot be a child buffer. No MIL operation can be done between a device context allocation and free, therefore you should use the device context for a short period of time. Allocates a device context (DC) for drawing ...

M_DEFAULT

Implements the default behavior.

Open Collapse M_DC_FREE

Frees a device context (DC). Frees a device context (DC) ...

M_DEFAULT

Implements the default behavior.

Open Collapse M_MAP

Maps or unmaps the buffer to the memory address space of the process. Note that, to use this control, the buffer must be allocated with the M_MAPPABLE attribute. Maps or unmaps the buffer to the memory address space of the process ...

M_DISABLE

Unmaps the buffer from the address space of the process. This sets the buffer's Host address to M_NULL.

This is the default value.
M_ENABLE

Maps the buffer to the address space of the process. This associates the buffer with a logical Host address.

Open Collapse M_MAX

Sets the maximum pixel value possible in the buffer. Pixel values larger than the maximum value will result in undetermined effects upon display. Sets the maximum pixel value possible in the buffer ...

M_MIN and M_MAX should specify the range of pixel values in the buffer. Upon display, pixel values between M_MIN and M_MAX are remapped to the minimum and maximum display values possible.

Value

Specifies the maximum pixel value within the range of the buffer type. For example, for an unsigned 8-bit buffer, set this value to a value between 0.0 and 255.0, inclusive.

Open Collapse M_MIN

Sets the minimum pixel value possible in the buffer. Pixel values smaller than the minimum value will result in undetermined effects upon display. Sets the minimum pixel value possible in the buffer ...

M_MIN and M_MAX should specify the range of pixel values in the buffer. Upon display, pixel values between M_MIN and M_MAX are remapped to the minimum and maximum display values possible.

Value

Specifies the minimum pixel value within the range of the buffer type. For example, for an unsigned 8-bit buffer, set this value to a value between 0.0 and 255.0, inclusive.

Open Collapse M_MODIFICATION_HOOK

Sets whether to run the user-defined functions hooked to the buffer's modification event upon the event. These user-defined functions are initially hooked to the buffer modification event using MbufHookFunction(). Sets whether to run the user-defined functions hooked to the buffer's modification event upon the event ...

M_DISABLE

Specifies that the user-defined functions should not be called.

Note that the modification counter of the image buffer will still be incremented. To inquire the count, use MbufInquire() with M_MODIFICATION_COUNT.

M_ENABLE

Specifies that the user-defined functions should be called.

This is the default value.
Open Collapse M_MODIFIED

Signals MIL that the buffer content was modified without using MIL. This control must be used to ensure that MIL updates its internal information on the buffer. For example, if a display buffer was modified outside MIL, the display will not be updated until you use this control. Note, if only a certain region of the buffer was modified, it is more efficient to specify an appropriate child buffer as BufId. Signals MIL that the buffer content was modified without using MIL ...

Note that, if a specific region of the buffer was modified without using MIL, it is faster to use MbufControlRegion() with the M_MODIFIED control type to signal MIL to update the content of the specified region of the buffer.

M_DEFAULT

Implements the default behavior.

For buffers with an M_IMAGE + M_COMPRESS attribute, ControlType and ControlValue can also be set to one of the values below.

Note that, if the buffer contains any data, setting one of these control types automatically deletes the data. This is because, for MIL to decompress the buffer's data, it must know the control values that were used in the compression. If you change one of these controls, MIL will be unable to decompress the data and the data is therefore irrelevant. Note that the control type M_TARGET_SIZE is the only control type that can be changed without affecting the data. For more information, see Chapter 20: JPEG and JPEG2000 compression.

Open Collapse ControlType Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
ControlValue
Open Collapse M_DECOMPOSITION_LEVEL

Sets the number of iterations (decomposition levels) the discrete wavelet transform is applied to the image. This control type is only supported with JPEG2000 buffers (both lossy and losseless). Sets the number of iterations (decomposition levels) the discrete wavelet transform is applied to the image ...

The number of decomposition levels is applied to all bands by default. To specify the number of decomposition levels for a specific band, this control type must be used in combination with other values (see below).

a b c d e f g h i j k l m n o p q r
Value >= 0

Specifies the number of iterations (decomposition levels). Only integer values are accepted.

a b c d e f g h i j k l m n o p q r
Specifics

When using a Matrox Morphis with an integrated JPEG2000 accelerator, the number of iterations can be from 1 to 5.

l
Open Collapse M_HUFFMAN_AC

Associates an AC Huffman table to the buffer. This control type is only supported with JPEG lossy buffers. Associates an AC Huffman table to the buffer ...

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table. If the buffer is 3-band, the same table is applied to all bands.

a b c d e f g h i j k l m n o p q r
Open Collapse M_HUFFMAN_AC_CHROMINANCE

Associates an AC Huffman table to the U and V bands (chrominance) of the buffer. This control type is only supported with JPEG lossy buffers in YUV format. Associates an AC Huffman table to the U and V bands (chrominance) of the buffer ...

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table.

a b c d e f g h i j k l m n o p q r
Open Collapse M_HUFFMAN_AC_LUMINANCE

Associates an AC Huffman table to the Y band (luminance) of the buffer. This control type is only supported with JPEG lossy buffers in YUV format. Associates an AC Huffman table to the Y band (luminance) of the buffer ...

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table.

a b c d e f g h i j k l m n o p q r
Open Collapse M_HUFFMAN_DC

Associates a DC Huffman table to the buffer. This control type is only supported with JPEG buffers (both lossy and lossless). Associates a DC Huffman table to the buffer ...

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table. If the buffer is 3-band, the same table is applied to all bands.

a b c d e f g h i j k l m n o p q r
Open Collapse M_HUFFMAN_DC_CHROMINANCE

Associates a DC Huffman table to the U and V bands (chrominance) of the buffer. This control type is only supported with JPEG lossy buffers in YUV format. Associates a DC Huffman table to the U and V bands (chrominance) of the buffer ...

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table.

a b c d e f g h i j k l m n o p q r
Open Collapse M_HUFFMAN_DC_LUMINANCE

Associates a DC Huffman table to the Y band (luminance) of the buffer. This control type is only supported with JPEG lossy buffers in YUV format. Associates a DC Huffman table to the Y band (luminance) of the buffer ...

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table.

a b c d e f g h i j k l m n o p q r
Open Collapse M_PREDICTOR

Sets the type of predictor. This control type is only supported with JPEG lossless buffers. If the buffer is 3-band, the same predictor is applied to all bands. Sets the type of predictor ...

a b c d e f g h i j k l m n o p q r
0

Specifies predictor #0 (no prediction).

a b c d e f g h i j k l m n o p q r
1

Specifies predictor #1 (the "pixel-to-the-left" predictor).

This is the default value.

 a b c d e f g h i j k l m n o p q r
2

Specifies predictor #2 (the "pixel-above" predictor).

a b c d e f g h i j k l m n o p q r
Open Collapse M_Q_FACTOR

Sets the quantization factor. This control type is only supported with lossy buffers. Sets the quantization factor ...

For JPEG lossy buffers, the Q factor is applied to all bands.

For JPEG2000 lossy buffers, the Q factor is applied to all bands by default. To specify the Q factor for a specific band, this control type must be used in combination with other values (see below).

a b c d e f g h i j k l m n o p q r
1 to 99

Specifies the quantization factor. Only integer values are accepted. The higher the factor, the more the compression, but the lower the image quality.

The default value is 50.

a b c d e f g h i j k l m n o p q r
Open Collapse M_Q_FACTOR_CHROMINANCE

Sets the chrominance quantization factor. This control type is only supported with JPEG or JPEG2000 lossy buffers in YUV format. Sets the chrominance quantization factor ...

a b c d e f g h i j k m n o p q r
1 to 99

Specifies the factor. Only integer values are accepted. The higher the factor, the more the compression, but the lower the image quality.

The factor is applied to the U and V bands (chrominance).

The default value is 50.

a b c d e f g h i j k m n o p q r
Open Collapse M_Q_FACTOR_LUMINANCE

Sets the luminance quantization factor. This control type is only supported with JPEG or JPEG2000 lossy buffers in YUV format. Sets the luminance quantization factor ...

a b c d e f g h i j k m n o p q r
1 to 99

Specifies the factor. Only integer values are accepted. The higher the factor, the more the compression, but the lower the image quality.

The factor is applied only to the Y band (luminance).

The default value is 50.

a b c d e f g h i j k m n o p q r
Open Collapse M_QUANTIZATION

Associates a quantization table to the buffer. This control type is only supported with lossy buffers. Associates a quantization table to the buffer ...

For JPEG lossy buffers, this table is associated to all bands.

For JPEG2000 lossy buffers, this table is associated to all bands by default. To associate a quantization table to a specific band, this control type must be used in combination with other values (see below).

Note that setting this control type will reset the M_Q_... control types to their default value (50). If you set the M_Q_FACTOR control type after specifying a custom table with the M_QUANTIZATION control type, the custom table will be scaled accordingly.

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table.

a b c d e f g h i j k l m n o p q r
Open Collapse M_QUANTIZATION_CHROMINANCE

Associates a quantization table to the U and V bands (chrominance) of the buffer. This control type is only supported with JPEG or JPEG2000 lossy buffers in YUV format. Associates a quantization table to the U and V bands (chrominance) of the buffer ...

Note that setting this control type will reset the M_Q_FACTOR_CHROMINANCE control type to its default value (50). If you set a M_Q_... control type after specifying a custom table with the M_QUANTIZATION_CHROMINANCE control type, the custom table will be scaled accordingly.

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table.

a b c d e f g h i j k l m n o p q r
Open Collapse M_QUANTIZATION_LUMINANCE

Associates a quantization table to the Y band (luminance) of the buffer. This control type is only supported with JPEG or JPEG2000 lossy buffers in YUV format. Associates a quantization table to the Y band (luminance) of the buffer ...

Note that setting this control type will reset the M_Q_FACTOR_LUMINANCE control type to its default value (50). If you set a M_Q_... control type after specifying a custom table with the M_QUANTIZATION_LUMINANCE control type, the custom table will be scaled accordingly.

a b c d e f g h i j k l m n o p q r
MIL M_ARRAY buffer identifier

Specifies the table.

a b c d e f g h i j k l m n o p q r
Open Collapse M_RESTART_INTERVAL

Sets the number of rows or 8x8 blocks between restart markers in a compressed image. Sets the number of rows or 8x8 blocks between restart markers in a compressed image ...

a b c d e f g h i j k l m n o p q r
Value > 0

Specifies after how many rows (for JPEG lossless buffers) or 8x8 blocks (for JPEG lossy buffers) of data to place restart markers. Only integer values are accepted.

The default value is 8.

a b c d e f g h i j k l m n o p q r
Open Collapse M_TARGET_SIZE

Sets the size of the buffer into which the source image is compressed. This control type is only supported with JPEG2000 lossy buffers. Sets the size of the buffer into which the source image is compressed ...

To ensure that the compressed data fits into the specified buffer size, less-significant data is discarded.

a b c d e f g h i j k l m n o p q r
Value > 0

Specifies the size, in bytes. Only integer values are accepted.

a b c d e f g h i j k l m n o p q r
Open Collapse M_TILE_SIZE_X

Sets the horizontal size for the region which will be compressed/decompressed individually within the image. Sets the horizontal size for the region which will be compressed/decompressed individually within the image ...

Note that this is only supported when using a Matrox Morphis with an integrated JPEG2000 accelerator.

l
1024

Specifies the size, in pixels, for lossy buffers.

l
256, 512

Specifies the size, in pixels, for lossy or lossless buffers.

l
Open Collapse M_TILE_SIZE_Y

Sets the vertical size for the region which will be compressed/decompressed individually within the image. Sets the vertical size for the region which will be compressed/decompressed individually within the image ...

Note that this is only supported when using a Matrox Morphis with an integrated JPEG2000 accelerator.

l
1024

Specifies the size, in pixels, for lossy buffers.

l
256, 512

Specifies the size, in pixels, for lossy or lossless buffers.

l

[Combination constants]

You can add one of the following values to M_DECOMPOSITION_LEVEL (for both JPEG2000 lossy and losseless buffers), M_Q_FACTOR (for JPEG2000 lossy buffers), and M_QUANTIZATION (for JPEG2000 lossy buffers).

Open Collapse Value Description
Open Collapse M_ALL_BANDS

 Applies the specified control value to all bands of the buffer.  Applies the specified control value to all bands of the buffer ...

This is the default value.

  Open   Collapse  M_BLUE

 Applies the specified control value to the blue band only (for RGB buffers).  Applies the specified control value to the blue band only (for RGB buffers).

  Open   Collapse  M_GREEN

 Applies the specified control value to the green band only (for RGB buffers).  Applies the specified control value to the green band only (for RGB buffers).

  Open   Collapse  M_RED

 Applies the specified control value to the red band only (for RGB buffers).  Applies the specified control value to the red band only (for RGB buffers).

  Open   Collapse  M_U

 Applies the specified control value to the U band only (for YUV buffers).  Applies the specified control value to the U band only (for YUV buffers).

  Open   Collapse  M_V

 Applies the specified control value to the V band only (for YUV buffers).  Applies the specified control value to the V band only (for YUV buffers).

  Open   Collapse  M_Y

 Applies the specified control value to the Y band only (for YUV buffers).  Applies the specified control value to the Y band only (for YUV buffers).

Remark

  •  Note that MIL-Lite compression support, particularly for M_IMAGE + M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware; the compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

DC HANDLE GDI MAPPABLE MODIFICATION COUNT MODIFIED IMAGE COMPRESS TARGET SIZE Q FACTOR QUANTIZATION Q FACTOR CHROMINANCE QUANTIZATION CHROMINANCE Q FACTOR LUMINANCE QUANTIZATION LUMINANCE MIN MAX MIN MAX DECOMPOSITION LEVEL Q FACTOR QUANTIZATION IMAGE COMPRESS    ASSOCIATED LUT  DEFAULT  DC ALLOC  DEFAULT  DC FREE  DEFAULT MAP DISABLE ENABLE MAX  MIN  MODIFICATION HOOK DISABLE ENABLE MODIFIED  DEFAULT DECOMPOSITION LEVEL   HUFFMAN AC  ARRAY buffer identifier HUFFMAN AC CHROMINANCE  ARRAY buffer identifier HUFFMAN AC LUMINANCE  ARRAY buffer identifier HUFFMAN DC  ARRAY buffer identifier HUFFMAN DC CHROMINANCE ARRAY buffer identifier HUFFMAN DC LUMINANCE  ARRAY buffer identifier PREDICTOR     Q FACTOR   Q FACTOR CHROMINANCE   Q FACTOR LUMINANCE   QUANTIZATION  ARRAY buffer identifier QUANTIZATION CHROMINANCE  ARRAY buffer identifier QUANTIZATION LUMINANCE  ARRAY buffer identifier RESTART INTERVAL   TARGET SIZE   TILE SIZE X   TILE SIZE Y   ALL BANDS BLUE GREEN RED U V Y


MbufControlRegion

See Also | Example | Availability | MbufControl | MbufControlNeighborhood
Reference:
MbufControl
MbufInquire
There are no examples containing MbufControlRegion().
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus

Not supported on:
Not supported on Matrox Helios XA
Not supported on Matrox Helios XCL
Not supported on Matrox Morphis
Not supported on Matrox Solios XA
Not supported on Matrox Solios XCL
Not supported on Matrox Iris
Synopsis
Control a specified region of a buffer.
Syntax
void MbufControlRegion(
MIL_ID BufId,
long OffsetX,
long OffsetY,
long SizeX,
long SizeY,
long Band,
long ControlType,
double ControlValue
)
Description

This function allows you to control a specified region of a buffer.

Parameters
BufId

Specifies the identifier of the buffer to control.

OffsetX

Specifies the horizontal pixel offset of the region.

OffsetY

Specifies the vertical pixel offset of the region.

SizeX

Specifies the width of the region, in pixels.

SizeY

Specifies the height of the region, in pixels.

Band

Specifies the band of the region. This parameter can be set to one of the following values.

Open Collapse Value Description
Open Collapse M_DEFAULT

Same as M_ALL_BANDS.

  Open   Collapse  M_ALL_BANDS

 Specifies all color bands (for RGB, HLS, and YUV buffers).  Specifies all color bands (for RGB, HLS, and YUV buffers) ...

  Open   Collapse  M_BLUE

 Specifies the blue color band (for RGB buffers).  Specifies the blue color band (for RGB buffers).

  Open   Collapse  M_GREEN

 Specifies the green color band (for RGB buffers).  Specifies the green color band (for RGB buffers).

  Open   Collapse  M_RED

 Specifies the red color band (for RGB buffers).  Specifies the red color band (for RGB buffers).

 ControlType

 Specifies the type of buffer setting to control.

See the Parameter associations section for possible values.

 ControlValue

 Specifies the value required for the setting.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue
         parameters are described below.

  Open   Collapse  ControlType
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

ControlValue

  Open   Collapse   M_CACHE_CONTROL

 Controls the region's status in cache memory.  Controls the region's status in cache memory ...

m
n
o

 M_IN_CACHE

 Signals MIL that the content in the specified region of the buffer has been cached in cache memory without using MIL.

m
n
o

  Open   Collapse   M_MODIFIED

 Signals MIL that the content in the specified region of the buffer was modified without using MIL. This control should be used to ensure that MIL updates its internal information on this region of the buffer. For example, if a region of a buffer that is selected on a display is modified using a pointer to its memory, the display will not be updated automatically. You should use this control type to force a display update of this region.  Signals MIL that the content in the specified region of the buffer was modified without using MIL ...

 Note that this setting does the same thing as using MbufControl() with M_MODIFIED, but it is faster because it updates a specific region of the buffer, instead of updating the whole buffer.

 This setting increments the buffer's modification counter. You can inquire about the counter's current value using MbufInquire() with M_MODIFICATION_COUNT.

a
b
c

g
h
i
j
k

m
n
o
p

 M_DEFAULT

 Implements the default behavior.

a
b
c

g
h
i
j
k

m
n
o
p

MODIFIED MODIFICATION COUNT       DEFAULT ALL BANDS BLUE GREEN RED   CACHE CONTROL IN CACHE MODIFIED DEFAULT


MbufControlNeighborhood

See Also | Example | Availability | MbufControlRegion | MbufCopy
User Guide:
Custom spatial filters
Custom morphological operations
Buffer overscan region

Reference:
MbufAlloc1d
MbufAlloc2d
mimconvolve.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Genesis
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Orion
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Synopsis
Change an operation control type setting of a kernel buffer or structuring element buffer.
Syntax
void MbufControlNeighborhood(
MIL_ID BufId,
long OperationControlType,
long OperationValue
)
Description

This function changes the setting of an operation control type of the specified kernel buffer or structuring element buffer. The operation control type settings establish how to perform a neighborhood operation when using the specified kernel buffer or structuring element buffer.

Neighborhood operations that do not use a kernel buffer or structuring element buffer typically use the default values. The default normalization factor is the exception. For predefined filters, the normalization factor is automatically set to use the full data range of the destination buffer without overflows, and the result is given in the number of bits of the destination buffer. To specify a different normalization factor, define a custom filter and set the required normalization factor, using the M_NORMALIZATION_FACTOR operation control type.

Parameters
BufId

Specifies the identifier of the kernel buffer or structuring element buffer. You must have already allocated this buffer, using MbufAlloc1d() or MbufAlloc2d().

OperationControlType

Specifies the operation to perform during a neighborhood operation when using the specified buffer.

See the Parameter associations section for possible values.

OperationValue

Specifies the new value to assign to the operation setting specified by the OperationControlType parameter.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the OperationControlType and OperationValue parameters are described below.

Open Collapse OperationControlType Description
OperationValue
Open Collapse M_ABSOLUTE_VALUE

Sets whether to take the absolute value of the results. Sets whether to take the absolute value of the results ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Does not take the absolute value of the result.

M_ENABLE

Takes the absolute value of the result.

Note that for a structuring element buffer, you cannot take the absolute value of a result

Open Collapse M_DEFAULT

Sets all operation control types to their default operation value. Sets all operation control types to their default operation value ...

M_NULL

Implements the default behavior.

Open Collapse M_OFFSET_CENTER_X

Sets the X-coordinate of the center pixel of the kernel or structuring element. Sets the X-coordinate of the center pixel of the kernel or structuring element ...

M_OFFSET_CENTER_X is ignored if M_FILTER_MODE is set to M_RECURSIVE.

M_DEFAULT

Specifies the X-coordinate of the top-left pixel of the central elements.

0 to (SizeX-1)

Specifies the value of the X-coordinate.

Open Collapse M_OFFSET_CENTER_Y

Sets the Y-coordinate of the center of the kernel or structuring element. Sets the Y-coordinate of the center of the kernel or structuring element ...

M_OFFSET_CENTER_Y is ignored if M_FILTER_MODE is set to M_RECURSIVE.

M_DEFAULT

Specifies the Y-coordinate of the top-left pixel of the central elements.

0 to (SizeY-1)

Specifies the value of the Y-coordinate.

Open Collapse M_OVERSCAN

Sets the type of overscan used to handle the border pixels of a source image. Sets the type of overscan used to handle the border pixels of a source image ...

M_OVERSCAN is ignored if M_FILTER_MODE is set to M_RECURSIVE.

M_DEFAULT

Specifies that MIL automatically selects the type of overscan that optimizes speed and logic according to the specified operation and the current processing system.

M_DISABLE

Specifies that no overscan will be used. When overscan is disabled, the border pixels of the source image are not processed by the neighborhood operation if additional processing time is needed.

M_MIRROR

Processes the border pixels of a source image using overscan pixel values that mirror the source buffer pixel values. That is, the overscan pixel values will be a mirror copy of the source buffer's borders. For example:

M_REPLACE

Processes the border pixels of a source image using overscan pixel values set to the overscan replacement value (M_OVERSCAN_REPLACE_VALUE).

M_TRANSPARENT

Processes the border pixels of a source image using transparent overscan pixel values. That is, the overscan pixel values will be those of the parent buffer. If they are not available, a mirror type overscan is used instead.

Open Collapse M_OVERSCAN_REPLACE_VALUE

Sets a replacement value for the overscan pixel values. Sets a replacement value for the overscan pixel values ...

Note that to use this control type, M_OVERSCAN must be set to M_REPLACE. In addition, M_OVERSCAN_REPLACE_VALUE is ignored if M_FILTER_MODE is set to M_RECURSIVE.

M_DEFAULT

Specifies the default value. The default value is 0.

M_REPLACE_MAX

Specifies that the overscan neighborhood pixel values will be set to the maximum value of the source buffer.

M_REPLACE_MIN

Specifies that the overscan neighborhood pixel values will be set to the minimum value of the source buffer.

Value

Specifies the value of the overscan neighborhood pixels.

Open Collapse M_SATURATION

Sets whether to saturate the results. Sets whether to saturate the results ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Does not saturate the results. Results that overflow are undefined.

M_ENABLE

Saturates the results. That is, a result that overflows or underflows will be set to the maximum or minimum value (respectively) that can be represented in the destination buffer.

If the saturation, normalization, and absolute value settings are specified for a kernel buffer, the saturation is performed after the normalization factor and the absolute value operations have been applied.

For M_KERNEL data buffers only, you can set this parameter to one of the following values.

Open Collapse OperationControlType Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
OperationValue
Open Collapse M_FILTER_MODE

Sets the mode in which to apply the filter. Use M_FILTER_TYPE to set the type of the filter. Sets the mode in which to apply the filter ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default filter mode. The default is M_KERNEL.

a b c d e f g h i j k l m n o p q r
M_KERNEL

Specifies the use of a non-recursive implementation of the filter. In this mode, a kernel is used to perform the neighborhood operation. The kernel size is specified when allocating the kernel buffer using MbufAlloc1d() or MbufAlloc2d(), although the kernel size can be constrained by the available hardware resources. When using an IIR filter in this mode, the filtering is done using a kernel approximation (FIR) of the recursive filter.

a b c d e f g h i j k l m n o p q r
Specifics

When using an IIR filter, this mode is not as efficient as M_RECURSIVE for large kernels.

a b c f g h i j k l m n o p q r
M_RECURSIVE

Specifies the use of a recursive implementation of an Infinite Impulse Response (IIR) filter, when applicable. If this mode actually used a kernel, the kernel size would be theoretically infinite.

M_RECURSIVE is not supported if M_FILTER_TYPE is set to M_USER_DEFINED.

a b c d e f g h i j k l m n o p q r
Open Collapse M_FILTER_OPERATION

Sets the type of neighborhood operation to perform using the selected filter. Sets the type of neighborhood operation to perform using the selected filter ...

M_FILTER_OPERATION is ignored if M_FILTER_TYPE is set to M_USER_DEFINED.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default filter operation. The default is M_SMOOTH.

a b c d e f g h i j k l m n o p q r
M_SMOOTH

Performs a smoothing operation on the image using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_HORIZ_EDGE

Computes the absolute value of the horizontal derivative of the image using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_VERT_EDGE

Computes the absolute value of the vertical derivative of the image using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_EDGE_DETECT

Computes the gradient of the image using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_EDGE_DETECT_SQR

Computes the square of the gradient of the image using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_LAPLACIAN_EDGE

Computes the Laplacian values of the image using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_SHARPEN

Performs a sharpening operation on the image using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_FIRST_DERIVATIVE_X

Computes the first derivative of the image with respect to X using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_FIRST_DERIVATIVE_Y

Computes the first derivative of the image with respect to Y using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_SECOND_DERIVATIVE_X

Computes the second derivative of the image with respect to X using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_SECOND_DERIVATIVE_Y

Computes the second derivative of the image with respect to Y using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
M_SECOND_DERIVATIVE_XY

Computes the second derivative of the image with respect to X and Y using the Shen-Castan or Canny-Deriche filter.

a b c d e f g h i j k l m n o p q r
Open Collapse M_FILTER_SMOOTHNESS

Sets the degree of smoothness (strength of denoising) applied by the filter during the neighborhood operation. Sets the degree of smoothness (strength of denoising) applied by the filter during the neighborhood operation ...

M_FILTER_SMOOTHNESS is ignored if M_FILTER_TYPE is set to M_USER_DEFINED.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is 50.

a b c d e f g h i j k l m n o p q r
0 to 100

Specifies the smoothness value.

A value of 100 results in a strong noise reduction effect, while a value of 0 has almost no noise reduction effect.

a b c d e f g h i j k l m n o p q r
Open Collapse M_FILTER_TYPE

Sets the type of filter used to perform the neighborhood operation. The type of filter determines the distribution of the neighborhoods' influence. Sets the type of filter used to perform the neighborhood operation ...

For IIR filter types, the content of the kernel buffer is ignored even if M_FILTER_MODE is set to M_KERNEL. M_FILTER_OPERATION and M_FILTER_SMOOTHNESS determine the filter values.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default filter type. The default is M_USER_DEFINED.

a b c d e f g h i j k l m n o p q r
M_DERICHE

Specifies a Canny-Deriche Infinite Support filter. This is an exponential weighting function, of the general form:

This is an IIR filter.

For the Canny-Deriche filter, the neighborhoods' influence decreases much slower as the distance from the central pixel increases, compared to the Shen-Castan filter (see M_SHEN control value).

Use M_FILTER_MODE, M_FILTER_OPERATION, and M_FILTER_SMOOTHNESS to set the mode of the filter, the type of operation to perform using the filter, and the degree of smoothness (strength of denoising) applied to the images by the filter, respectively.

a b c d e f g h i j k l m n o p q r
M_SHEN

Specifies a Shen-Castan Infinite Support Exponential filter. This is an exponential weighting function, of the general form:

This is an IIR filter.

For the Shen-Castan filter, the neighborhoods' influence decreases much faster as the distance from the central pixel increases, compared to the Canny-Deriche filter (see M_DERICHE control value).

Use M_FILTER_MODE, M_FILTER_OPERATION, and M_FILTER_SMOOTHNESS to set the mode of the filter, the type of operation to perform using the filter, and the degree of smoothness (strength of denoising) applied to the images by the filter, respectively.

a b c d e f g h i j k l m n o p q r
M_USER_DEFINED

Specifies a user-defined filter. This is a FIR filter.

M_USER_DEFINED is not supported if M_FILTER_MODE is set to M_RECURSIVE.

a b c d e f g h i j k l m n o p q r
Open Collapse M_NORMALIZATION_FACTOR

Sets the normalization factor to apply to the result. Sets the normalization factor to apply to the result ...

Note that for a structuring element buffer, you cannot specify a normalization factor.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is 1.

a b c d e f g h i j k l m n o p q r
Value > 0

Specifies the normalization factor.

If the factor produces an overflow in the destination, saturation might occur, depending on the M_SATURATION control type.

a b c d e f g h i j k l m n o p q r

NORMALIZATION FACTOR OFFSET CENTER X FILTER MODE RECURSIVE OFFSET CENTER Y FILTER MODE RECURSIVE OVERSCAN FILTER MODE RECURSIVE OVERSCAN REPLACE VALUE OVERSCAN REPLACE OVERSCAN REPLACE VALUE FILTER MODE RECURSIVE KERNEL FILTER OPERATION FILTER TYPE USER DEFINED SMOOTH FILTER MODE KERNEL FILTER OPERATION FILTER SMOOTHNESS USER DEFINED USER DEFINED FILTER MODE RECURSIVE DERICHE SHEN FILTER TYPE KERNEL RECURSIVE FILTER TYPE USER DEFINED RECURSIVE FILTER SMOOTHNESS FILTER TYPE USER DEFINED SATURATION FILTER MODE FILTER OPERATION FILTER SMOOTHNESS DEFAULT NULL ABSOLUTE VALUE DEFAULT DISABLE ENABLE OFFSET CENTER X DEFAULT OFFSET CENTER Y DEFAULT OVERSCAN DEFAULT DISABLE MIRROR REPLACE TRANSPARENT OVERSCAN REPLACE VALUE DEFAULT REPLACE MAX REPLACE MIN SATURATION DEFAULT DISABLE ENABLE FILTER OPERATION DEFAULT SMOOTH HORIZ EDGE VERT EDGE EDGE DETECT EDGE DETECT SQR LAPLACIAN EDGE SHARPEN FIRST DERIVATIVE X FIRST DERIVATIVE Y SECOND DERIVATIVE X SECOND DERIVATIVE Y SECOND DERIVATIVE XY FILTER TYPE DEFAULT USER DEFINED SHEN DERICHE FILTER MODE DEFAULT RECURSIVE KERNEL FILTER SMOOTHNESS DEFAULT NORMALIZATION FACTOR DEFAULT


MbufCopy

See Also | Example | Availability | MbufControlNeighborhood | MbufCopyClip
User Guide:
Manipulating and controlling certain data buffer areas
Loading and generating data into LUTs
General steps
Data manipulation with multiple systems

Reference:
MimBinarize
dtkobjecttracking.c
mbufcolor.c
mdigautofocus.c
mdigdoublebuffering.c
mdiggrabsequence.c
mdighook.c
mdigmultdestination.c
mdigprocess.c
mdigprocessmultiple.c
mdigsubtract.c
mdispwindowleveling.c
mgenlc.c
mheliosconcurent.c
mimfft.c
mimmorphic.c
mimwarp.c
mmet2dig.c
mmodeltracking.c
mmorphisjpeg2000.c
mpat.c
mthread.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Copy data from one buffer to another.
Syntax
void MbufCopy(
MIL_ID SrcBufId,
MIL_ID DestBufId
)
Description

This function copies the specified source buffer data to the specified destination buffer. If the source and destination buffers are of different data types, MIL converts the data automatically.

If the source buffer depth is greater than that of the destination, the most significant bits are truncated when the data is copied into the destination. If the destination depth is greater than that of the source, the source data is zero or sign-extended (depending on the type of the source) when copied into the destination. If the destination is larger in size than the source, exceeding areas of the buffer are unaffected.

Note, when copying from a non-binary buffer to a binary buffer, all non-zero pixels in the source buffer are represented as ones (1) in the binary buffer. When copying a binary buffer to a buffer of a different depth, each bit is copied into the least-significant bit of a different destination pixel. The remaining bits of the destination pixel are set to 0; to propagate the bit value to all bits, use MimBinarize().

When copying from a floating-point buffer to an integer buffer, the values are truncated.

If the source buffer is a 3-band YUV buffer and the destination buffer is a 1-band buffer, only the Y band (luminance) is copied. If the source buffer is a 3-band RGB buffer and the destination buffer is a 1-band buffer, only the red band is copied.

Note, if the source is a 1-band image buffer associated with a LUT buffer and the destination is a 3-band image buffer, the source data copied to destination is first mapped through the LUT.

Parameters
SrcBufId

Specifies the identifier of the source data buffer.

DestBufId

Specifies the identifier of the destination data buffer.

Remark
  • This function is optimized for packed binary buffers.


MbufCopyClip

See Also | Example | Availability | MbufCopy | MbufCopyColor2d
User Guide:
Manipulating and controlling certain data buffer areas

Reference:
MimBinarize
There are no examples containing MbufCopyClip().
Available in MIL-Lite

Available in MIL
Synopsis
Copy buffer, clipping data outside the destination buffer.
Syntax
void MbufCopyClip(
MIL_ID SrcBufId,
MIL_ID DestBufId,
long DestOffX,
long DestOffY
)
Description

This function copies the source buffer data to the destination buffer, starting at the specified offset. Data outside of the destination buffer is not copied (it is clipped).

If the source buffer depth is greater than that of the destination, the most significant bits are truncated when the data is copied to the destination. If the destination depth is greater than that of the source, the source data is zero or sign-extended (depending on the type of the source) when copied to the destination.

Note, when copying from a non-binary buffer to a binary buffer, all non-zero pixels in the source buffer are represented as ones (1) in the binary buffer. When copying a binary buffer to a buffer of a different depth, each bit is copied into the least-significant bit of a different destination pixel. The remaining bits of the destination pixel are set to 0; to propagate the bit value to all bits, use MimBinarize().

When copying from a floating-point buffer to an integer buffer, the decimal point values are ignored and the most significant bits are truncated.

Parameters
SrcBufId

Specifies the identifier of the source data buffer.

DestBufId

Specifies the identifier of the destination data buffer.

DestOffX

Specifies the horizontal pixel offset of the destination buffer area at which to start copying data. The offset is relative to the top-left corner of the destination buffer (0, 0). Also, this parameter can be set to a negative value, and can be specified anywhere outside the destination buffer. Data extending beyond the limits of the destination buffer is not copied (it is clipped).

DestOffY

Specifies the vertical pixel offset of the destination buffer area at which to start copying data. The offset is relative to the top-left corner of the destination buffer (0,0). Also, this parameter can be set to a negative value and can be specified anywhere outside the destination buffer. Data extending beyond the limits of the destination buffer is not copied (it is clipped).

Remark
  • This function is optimized for packed binary buffers.


MbufCopyColor2d

See Also | Example | Availability | MbufCopyClip | MbufCopyColor
User Guide:
Manipulating and controlling certain data buffer areas

Reference:
MimBinarize
There are no examples containing MbufCopyColor2d().
Available in MIL-Lite

Available in MIL
Synopsis
Copy a two-dimensional region of one or all bands of an image buffer to another buffer.
Syntax
void MbufCopyColor2d(
MIL_ID SrcBufId,
MIL_ID DestBufId,
long SrcBand,
long SrcOffX,
long SrcOffY,
long DestBand,
long DestOffX,
long DestOffY,
long SizeX,
long SizeY
)
Description

This function copies a two-dimensional region of one or all color bands of the specified source buffer to the specified color band(s) of the destination buffer. It can also be used to insert or extract a color component from a color buffer.

If the source is a monochrome buffer and the destination is a multi-band (color) buffer, the unique source buffer band is inserted into the specified band of the destination buffer. If the source is a multi-band buffer and the destination is a monochrome buffer, the specified source buffer band is extracted from the source buffer and written to the destination buffer. If both are multi-band buffers, the specified band(s) is copied from the source to the destination.

If the source buffer depth is greater than that of the destination, the most significant bits are truncated when the data is copied to the destination. If the destination depth is greater than that of the source, the source data is zero or sign-extended (depending on the type of the source) when copied to the destination. Also, the buffers must have the same number of bands if all bands are to be copied.

Note that when copying from a non-binary buffer to a binary destination buffer, all non-zero pixels in the source buffer are represented as ones (1) in the binary destination buffer.When copying a binary buffer to a buffer of a different depth, each bit is copied into the least-significant bit of a different destination pixel. The remaining bits of the destination pixel are set to 0; to propagate the bit value to all bits, use MimBinarize().

Note, if the source is a 1-band image buffer associated with a LUT buffer and the destination is a 3-band image buffer, the source data copied to destination is first mapped through the LUT.

Note that when copying into the U or V band of a YUV destination buffer, the dimensions of the U or V band of the destination buffer must not be smaller than the dimensions of the source buffer.

Parameters
SrcBufId

Specifies the identifier of the source data buffer.

DestBufId

Specifies the identifier of the destination data buffer.

SrcBand

Specifies the source color band from which to copy. SrcBand can be set to one of the following values:

Open Collapse Value Description
Open Collapse 0 <= Value <= #bands - 1

 Specifies the index of the band to copy.  Specifies the index of the band to copy ...

 The relationship between index value and band for RGB and HLS buffers is the following:

0 | Corresponds to the red band for RGB buffers or the hue band for HLS buffers.
1 | Corresponds to the green band for RGB buffers or the saturation band for HLS buffers.
2 | Corresponds to the blue band for RGB buffers or the luminance band for HLS buffers.

  Open   Collapse  M_ALL_BANDS

 Specifies all color bands (for RGB, HLS, and YUV buffers).  Specifies all color bands (for RGB, HLS, and YUV buffers).

  Open   Collapse  M_BLUE

 Specifies the blue color band (for RGB buffers).  Specifies the blue color band (for RGB buffers).

  Open   Collapse  M_GREEN

 Specifies the green color band (for RGB buffers).  Specifies the green color band (for RGB buffers).

  Open   Collapse  M_HUE

 Specifies the hue band (for HLS buffers).  Specifies the hue band (for HLS buffers).

  Open   Collapse  M_LUMINANCE

 Specifies the luminance band (for HLS buffers).  Specifies the luminance band (for HLS buffers).

  Open   Collapse  M_RED

 Specifies the red color band (for RGB buffers).  Specifies the red color band (for RGB buffers).

  Open   Collapse  M_SATURATION

 Specifies the saturation band (for HLS buffers).  Specifies the saturation band (for HLS buffers).

  Open   Collapse  M_U

 Specifies the U band (for YUV buffers).  Specifies the U band (for YUV buffers).

  Open   Collapse  M_V

 Specifies the V band (for YUV buffers).  Specifies the V band (for YUV buffers).

  Open   Collapse  M_Y

 Specifies the Y band (for YUV buffers).  Specifies the Y band (for YUV buffers).

 SrcOffX

 Specifies the horizontal pixel offset of the region to read relative to the source buffer starting coordinate.  The offset must be within the width of the source buffer.

 SrcOffY

 Specifies the vertical pixel offset of the region to read relative to the source buffer starting coordinate.  The offset must be within the height of the source buffer.

 DestBand

 Specifies the destination color band in which to copy. DestBand can be set to the same values as SrcBand.

 DestOffX

 Specifies the horizontal pixel offset of the region to write relative to the destination buffer starting coordinate.  The offset must be within the width of the destination buffer.

 DestOffY

 Specifies the vertical pixel offset of the region to write relative to the destination buffer starting coordinate.  The offset must be within the height of the destination buffer.

 SizeX

 Specifies the width of the region to be copied, starting from the specified offset (SrcOffX, DestOffX).

 SizeY

 Specifies the height of the region to be copied, starting from the specified offset (SrcOffY, DestOffY).

Remark

  •  This function is optimized for packed binary buffers.
    •

   ALL BANDS BLUE  GREEN  HUE LUMINANCE RED SATURATION U V Y


MbufCopyColor

See Also | Example | Availability | MbufCopyColor2d | MbufCopyCond
User Guide:
Manipulating and controlling certain data buffer areas
Loading and generating data into LUTs
Processing

Reference:
MimBinarize
There are no examples containing MbufCopyColor().
Available in MIL-Lite

Available in MIL
Synopsis
Copy one or all bands of an image buffer.
Syntax
void MbufCopyColor(
MIL_ID SrcBufId,
MIL_ID DestBufId,
long Band
)
Description

This function copies one or all color bands of the specified source buffer to the specified destination buffer. It can also be used to insert or extract a color component from a color image.

If the source is a monochrome buffer and the destination is a multi-band (color) buffer, the source buffer band is copied into the specified band of the destination buffer. If the source is a multi-band buffer and the destination is a monochrome buffer, the specified source buffer band is copied from the source buffer and written to the destination buffer. If both are multi-band buffers, the specified band(s) is copied from the source to the destination.

If the source buffer depth is greater than that of the destination, the most significant bits are truncated when the data is copied to the destination. If the destination depth is greater than that of the source, the source data is zero or sign-extended (depending on the type of the source) when copied to the destination. Also, the buffers must have the same number of bands if all bands are to be copied.

Note, when copying from a non-binary buffer to a binary buffer, all non-zero pixels in the source buffer are represented as ones (1) in the binary buffer. When copying a binary buffer to a buffer of a different depth, each bit is copied into the least-significant bit of a different destination pixel. The remaining bits of the destination pixel are set to 0; to propagate the bit value to all bits, use MimBinarize().

Note, if the source is a 1-band image buffer associated with a LUT buffer and the destination is a 3-band image buffer, the source data copied to destination is first mapped through the LUT.

Parameters
SrcBufId

Specifies the identifiers of the source data buffer.

DestBufId

Specifies the identifiers of the destination data buffer.

Band

Specifies the color band to copy. Set Band to one of the following values:

Open Collapse Value Description
Open Collapse 0 <= Value <= #bands - 1

 Specifies the index of the band to copy.  Specifies the index of the band to copy ...

 The relationship between index value and band for RGB and HLS buffers is the following:

0 | Corresponds to the red band for RGB buffers or the hue band for HLS buffers.
1 | Corresponds to the green band for RGB buffers or the saturation band for HLS buffers.
2 | Corresponds to the blue band for RGB buffers or the luminance band for HLS buffers.

  Open   Collapse  M_ALL_BANDS

 Specifies all color bands (for RGB, HLS, and YUV buffers).  Specifies all color bands (for RGB, HLS, and YUV buffers).

  Open   Collapse  M_BLUE

 Specifies the blue color band (for RGB buffers).  Specifies the blue color band (for RGB buffers).

  Open   Collapse  M_GREEN

 Specifies the green color band (for RGB buffers).  Specifies the green color band (for RGB buffers).

  Open   Collapse  M_HUE

 Specifies the hue band (for HLS buffers).  Specifies the hue band (for HLS buffers).

  Open   Collapse  M_LUMINANCE

 Specifies the luminance band (for HLS buffers).  Specifies the luminance band (for HLS buffers).

  Open   Collapse  M_RED

 Specifies the red color band (for RGB buffers).  Specifies the red color band (for RGB buffers).

  Open   Collapse  M_SATURATION

 Specifies the saturation band (for HLS buffers).  Specifies the saturation band (for HLS buffers).

  Open   Collapse  M_U

 Specifies the U band (for YUV buffers).  Specifies the U band (for YUV buffers).

  Open   Collapse  M_V

 Specifies the V band (for YUV buffers).  Specifies the V band (for YUV buffers).

  Open   Collapse  M_Y

 Specifies the Y band (for YUV buffers).  Specifies the Y band (for YUV buffers).

Remark

  •  This function is optimized for packed binary buffers.
    •

   ALL BANDS BLUE  GREEN  HUE LUMINANCE RED SATURATION U V Y


MbufCopyCond

Example | Availability | MbufCopyColor | MbufCopyMask
There are no examples containing MbufCopyCond().
Available in MIL-Lite

Available in MIL
Synopsis
Copy conditionally the source buffer to the destination buffer.
Syntax
void MbufCopyCond(
MIL_ID SrcBufId,
MIL_ID DestBufId,
MIL_ID CondBufId,
long Condition,
double CondValue
)
Description

This function copies the source buffer data to the destination buffer, modifying only those pixels of the destination buffer which have a corresponding pixel in the condition buffer that satisfies the specified condition. Other pixels are unchanged. If the source and destination buffers are of different data types, MIL converts the data automatically.

If the source buffer depth is greater than that of the destination, the most-significant bits are truncated when the data is copied to the destination. If the destination depth is greater than that of the source, the source data is zero or sign-extended (depending on the type of the source) when copied to the destination. For example, the data is zero-extended when copying an 8-bit unsigned buffer to a 16-bit unsigned buffer.

Note that if a one-band condition buffer is used with a three-band destination buffer, the one band of the condition buffer will be used for each destination band.

Parameters
SrcBufId

Specifies the identifier of the source data buffer.

DestBufId

Specifies the identifier of the destination data buffer.

CondBufId

Specifies the identifier of the condition buffer.

Condition

Specifies the condition for which the condition buffer is tested. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Modify destination buffer pixels corresponding to condition buffer pixels that are non-zero.  Modify destination buffer pixels corresponding to condition buffer pixels that are non-zero.

  Open   Collapse  M_EQUAL

 Modify destination buffer pixels corresponding to condition buffer pixels that are equal to CondValue.  Modify destination buffer pixels corresponding to condition buffer pixels that are equal to CondValue.

  Open   Collapse  M_NOT_EQUAL

 Modify destination buffer pixels corresponding to condition buffer pixels that are not equal to CondValue.  Modify destination buffer pixels corresponding to condition buffer pixels that are not equal to CondValue.

 CondValue

 Specifies the pixel value for the specified condition.  Even though this value is of type double, it is treated as if it had the same type and depth as the condition buffer. If the Condition parameter is set to M_DEFAULT, CondValue is ignored. This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_RGB888(
long Red,

long Green,

long Blue

          )

 Specifies an RGB value when the source buffer, destination buffer, and condition buffer are 8-bit, and the condition buffer is a 3-band buffer.  Specifies an RGB value when the source buffer, destination buffer, and condition buffer are 8-bit, and the condition buffer is a 3-band buffer ...

 This allows you to compare each band of the condition buffer against a different value.

Parameters

Red

 Specifies the red value of an RGB value.

Green

 Specifies the green value of an RGB value.

Blue

 Specifies the blue value of an RGB value.

  Open   Collapse  Value

 Specifies a pixel value.  Specifies a pixel value ...

 If the condition buffer is binary, this value must be set to 0 or 1.

 If the condition buffer is three bands, this value will be used for each band.

Remark

  •  This function is optimized for packed binary buffers.
    •

    DEFAULT EQUAL NOT EQUAL


MbufCopyMask

Example | Availability | MbufCopyCond | MbufCreate2d
There are no examples containing MbufCopyMask().
Available in MIL-Lite

Available in MIL
Synopsis
Copy buffer with mask.
Syntax
void MbufCopyMask(
MIL_ID SrcBufId,
MIL_ID DestBufId,
long MaskValue
)
Description

This function copies the specified source buffer data to the specified destination buffer, modifying only the bits of the destination that have a non-zero corresponding bit in the mask.

Parameters
SrcBufId

Specifies the identifier of the source data buffer. Note that the source data buffer cannot be of type floating-point.

DestBufId

Specifies the identifier of the destination data buffer. Note that the destination data buffer cannot be of type floating-point.

If the source buffer depth is greater than that of the destination, the most significant bits are truncated when the data is copied to the destination. If the destination depth is greater than that of the source, the source data is zero or sign-extended (depending on the type of the source) when copied to the destination.

MaskValue

Specifies the mask value. Even though this value is of type long, it is treated as if it had the same depth as the destination buffer; the most-significant bits that are not required are ignored.


MbufCreate2d

See Also | Example | Availability | MbufCopyMask | MbufCreateColor
User Guide:
Mapping a data buffer to user-allocated memory

Reference:
MbufAlloc2d
MbufControl
MbufFree
MbufGet2d
MbufInquire
MbufPut2d
MsysAlloc
There are no examples containing MbufCreate2d().
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Partially supported on:
Partially supported on Matrox Genesis
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Create a two-dimensional data buffer.
Syntax
MIL_ID MbufCreate2d(
MIL_ID SystemId,
long SizeX,
long SizeY,
long Type,
MIL_INT64 Attribute,
long ControlFlag,
long Pitch,
void *DataPtr,
MIL_ID *BufIdPtr
)
Description

This function creates a two-dimensional data buffer that maps to a user-specified data array, or another existing buffer, and associates it with a specific MIL system.

This function should be used with caution because, when using physical addresses, it provides direct access to any of your computer's memory mapped devices; when using logical addresses, memory protection errors could result.

It is generally better to leave buffer allocation, data loading, and memory control to MIL (MbufAlloc2d(), MbufGet2d(), MbufPut2d()), since MIL might require special memory attributes (such as non-paged memory) or alignment in order to associate the buffer with a particular target system.

You must allocate the appropriate memory before calling MbufCreate2d() and you must free the created buffer when no longer required, using MbufFree() before freeing the memory. Using MbufFree() on a buffer created with MbufCreate2d() will free the internal structure required for a mapped buffer, but it will not free the memory used. MbufInquire() can be used to get the pointer to the data of a MIL allocated buffer.

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

Note that to map a buffer to on-board memory with a different system, the on-board memory must be in shared memory, unless the created buffer is created on the same system. See your Board Specific Notes for more information regarding shared memory.

Parameters
SystemId

Specifies the MIL system on which to create the buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 SizeX

 Sets the buffer width.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the buffer width is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies that the buffer width is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.

  Open   Collapse  Value

 Specifies buffer width. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, width is specified in pixels.  Specifies buffer width ...

 SizeY

 Sets the buffer height.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the buffer height is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies that the buffer height is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.

  Open   Collapse  Value

 Specifies the buffer height. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, height is specified in pixels.  Specifies the buffer height ...

 Type

 Sets a combination of two values: data type and data depth per band.  Specify the depth of the buffer per band as one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the buffer data depth and type are identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies that the buffer data depth and type are identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID ...

  Open   Collapse  1

 Specifies a 1-bit (packed binary) buffer. Note that you cannot create a 1-bit LUT buffer.  Specifies a 1-bit (packed binary) buffer ...

  Open   Collapse  8

 Specifies an 8-bit buffer.  Specifies an 8-bit buffer.

  Open   Collapse  16

 Specifies a 16-bit buffer.  Specifies a 16-bit buffer.

  Open   Collapse  32

 Specifies a 32-bit buffer.  Specifies a 32-bit buffer.

      [Combination constants]

 You can add one of the following to the Type parameter to specify the data type. Supported data types depend on the specified depth.

  Open   Collapse  Value
Description

  Open   Collapse  M_FLOAT

 Specifies that the type of data is floating point. The valid data depth is 32 bits.  Specifies that the type of data is floating point ...

  Open   Collapse  M_SIGNED

 Specifies that the type of data is signed. The valid data depths are 8, 16 or 32 bits.  Specifies that the type of data is signed ...

  Open   Collapse  M_UNSIGNED

 Specifies that the type of data is unsigned. The valid data depths are 1, 8, 16 or 32 bits.  Specifies that the type of data is unsigned ...

This is the default value.

 Attribute

 Specifies the buffer usage.  This alows you to specify the type of buffer, intended purpose, compression type, storage format, data direction, location, internal storage format, memory type, and overcan region of the created buffer; all of which provides additional information for other MIL functions.

 This function should be used with caution because, when using physical addresses, it provides direct access to any of your computer's memory mapped devices; when using logical addresses, memory protection errors could result.

 This parameter should be set to one of the values below.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_ARRAY

 Specifies a buffer to store array type data. Note that some functions take an M_ARRAY buffer rather than a user-defined array.  Specifies a buffer to store array type data ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_IMAGE

 Specifies a buffer to store image data.  Specifies a buffer to store image data.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_KERNEL

MIL-lite with restriction (see remarks).

 Specifies a kernel buffer to store a custom filter for convolution functions.  Specifies a kernel buffer to store a custom filter for convolution functions ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The depth must be 8, 16, or 32-bit integer or floating-point.

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

 Only three types of kernel buffers are supported: signed 8-bit, unsigned 8-bit, and signed 16-bit.

c

f

  Open   Collapse  M_LUT

 Specifies a buffer to store lookup table data.  Specifies a buffer to store lookup table data ...

 The valid data depths are 8, 16, or 32-bit.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_STRUCT_ELEMENT

MIL-lite with restriction (see remarks).

 Specifies a buffer to store structuring element data for morphology functions.  Specifies a buffer to store structuring element data for morphology functions ...

 The data depth must be 32-bit. If signed, the range is -32768 to +32767. If unsigned, the range is 0 to +32767.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

 When selecting an image buffer (M_IMAGE), you must also specify the intended purpose of this buffer by combining M_IMAGE with one or more of the following values:

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_COMPRESS

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can hold compressed data. Note that a buffer with this attribute cannot have the M_SIGNED data type.  Specifies an image buffer that can hold compressed data ...

 When mapping buffers for operations that require a source and destination buffer, and one of the buffers has an M_COMPRESS attribute, the data will be compressed or decompressed depending on the attributes of the destination buffer. If both the source and destination buffers have M_COMPRESS specifiers but different compression types, the data will be re-compressed according to the settings of the destination buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_DISP

 Specifies an image buffer that can be displayed.  Specifies an image buffer that can be displayed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band display buffers with a depth greater than 16 bits cannot be allocated. Three-band display buffers can only be allocated with 8 bits per band.

c

f

  Open   Collapse  M_GRAB

 Specifies an image buffer in which to grab data from input devices.  Specifies an image buffer in which to grab data from input devices ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The physical nature of the buffers (using the ControlFlag) must be set to M_PHYSICAL_ADDRESS.

a
b
c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

 Single-band buffers with a depth of 8 or 16 bits (monochrome) can have an M_GRAB attribute.

a

c
d
e

h
i

m
n
o

q
r

 Single-band buffers, with a depth of 8 bits, can have an M_GRAB attribute.

b

f
g

j
k
l

p

  Open   Collapse  M_PROC

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can be processed.  Specifies an image buffer that can be processed.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

[MIL-Lite with restriction]

 For an M_COMPRESS type of image buffer, one of the following values can be added to indicate the type of compressed data. The image buffer's data depth dictates which compression type can be selected.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description

  Open   Collapse  M_JPEG_LOSSLESS

 Specifies that the buffer will be used to hold JPEG lossless data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG lossless data ...

  Open   Collapse  M_JPEG2000_LOSSLESS

 Specifies that the buffer will be used to hold JPEG2000 lossless data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG2000 lossless data ...

  Open   Collapse  M_JPEG_LOSSLESS_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossless data in separate fields. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG lossless data in separate fields ...

  Open   Collapse  M_JPEG_LOSSY

 Specifies that the buffer will be used to hold JPEG lossy data. The supported data formats is 1-band 8-bit data.  Specifies that the buffer will be used to hold JPEG lossy data ...

This is the default value.

  Open   Collapse  M_JPEG2000_LOSSY

 Specifies that the buffer will be used to hold JPEG2000 lossy data. The supported data formats are: 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG2000 lossy data ...

  Open   Collapse  M_JPEG_LOSSY_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossy data in separate fields. The supported data formats is 1-band 8-bit data.  Specifies that the buffer will be used to hold JPEG lossy data in separate fields ...

      [Combination constants]

 MIL will interpret the created buffer in the type of specified intended usage attribute. The source buffer's actual storage format can differ. If a specific internal format is required, it should be specified.

 To specify a storage format for an image buffer, you can add one or more of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DIB

 Forces the buffer to be a DIB buffer. This ensures that your buffer is stored with a DIB header. Use MbufInquire() with M_BITMAPINFO to return a pointer (LPBITMAPINFO) to the header of the MIL buffer.  Forces the buffer to be a DIB buffer ...

  Open   Collapse  M_DIRECTX

 Forces the buffer to be a DirectX surface.  Forces the buffer to be a DirectX surface.

  Open   Collapse  M_GDI

 Forces the buffer to be compatible with GDI.  Forces the buffer to be compatible with GDI ...

 When using a device context (using MbufControl() with M_DC_ALLOC) for drawing, the buffer should be internally stored in GDI format, and cannot be a child buffer.

      [Combination constants]

 To specify a location for an image buffer, you can add one of the following values.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_HOST_MEMORY

 Specfies that the buffer is in the Host memory.  Specfies that the buffer is in the Host memory ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

a
b

d
e
f
g
h
i
j
k
l

p
q
r

  Open   Collapse  M_OFF_BOARD

 Specfies that the buffer is not in on-board memory.  Specfies that the buffer is not in on-board memory ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 To ensure that an M_OFF_BOARD buffer can be used by the bus master transfer section of the board, the buffer must be allocated in non-paged memory (M_OFF_BOARD + M_NON_PAGED or M_HOST_MEMORY + M_NON_PAGED).

d
e

l
m
n
o

q
r

  Open   Collapse  M_ON_BOARD

 Specfies that the buffer is in on-board memory.  Specfies that the buffer is in on-board memory ...

a

c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

c

m
n
o

 By default, all on-board buffers are allocated in memory that is not mapped on the PCI bus. This unshared memory cannot be accessed by the Host or any system other than the one on which it was allocated. See combination values (M_SHARED) below to change this default behavior.

d
e

m
n
o

q
r

  Open   Collapse  M_VIDEO_MEMORY

 Specfies that the buffer is in (off-screen) display memory of your graphics controller. Display memory is also referred to as video memory or frame buffer memory.  Specfies that the buffer is in (off-screen) display memory of your graphics controller ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 You can add one of the following values when creating an on-board image buffer (M_ON_BOARD).

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_FAST_MEMORY

 Specifies that the buffer is in the G4 PowerPC fast-processing memory. This memory is L3 external cache. It must be enabled using the OdcMon utility before it can be used.  Specifies that the buffer is in the G4 PowerPC fast-processing memory ...

 Use MbufInquire() with M_EXTENDED_FORMAT to establish if the buffer was allocated in fast processing memory.

 Fast processing memory is only accessible to the G4 PowerPC microprocessor and not to the Host, frame grabber module, or PA. Therefore, depending on the operation, allocating a buffer in fast processing memory might not accelerate processing.

 Note that M_GRAB and M_DISP are not supported with this attribute.

m
n
o

  Open   Collapse  M_SHARED

 Specifies that the buffer is in shared processing memory. This memory is mapped on the PCI bus.  Specifies that the buffer is in shared processing memory ...

d
e

m
n
o

q
r

      [Combination constants]

 To specify a type of memory, you can add one of the following values.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description

  Open   Collapse  M_NON_PAGED

 Specifies that the buffer is in MIL-reserved, non-pageable memory.  Specifies that the buffer is in MIL-reserved, non-pageable memory.

  Open   Collapse  M_PAGED

 Specifies that the buffer is in pageable memory.  Specifies that the buffer is in pageable memory.

      [Combination constants]

 To specify that the buffer has an overscan region, add the value below.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description

  Open   Collapse  M_FAST_OVERSCAN

 Specifies that the buffer has an overscan region.  Specifies that the buffer has an overscan region.

 ControlFlag

 Specifies the physical nature of the buffer.  This parameter can be set to one of the values below.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_HOST_ADDRESS

 Specifies that DataPtr is a logical address that points to the data.  Specifies that DataPtr is a logical address that points to the data ...

 Note that when using logical addresses, memory protection errors could result.

 Note that you can use MbufInquire() with M_HOST_ADDRESS to get the logical address of a MIL allocated buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_HOST_ADDRESS_REMOTE

 Specifies that DataPtr is the remote Host's logical address that points to the data.  Specifies that DataPtr is the remote Host's logical address that points to the data ...

 Note that when using logical addresses, memory protection errors could result.

 Note that you can use MbufInquire() with M_HOST_ADDRESS_REMOTE to get the logical address of a MIL allocated buffer.

m
n
o

  Open   Collapse  M_MIL_ID

 Specifies that the new buffer maps to an existing source buffer. DataPtr points to the MIL identifier of the source buffer.  Specifies that the new buffer maps to an existing source buffer ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_PHYSICAL_ADDRESS

 Specifies that DataPtr is a physical address that points to the data.  Specifies that DataPtr is a physical address that points to the data ...

 Note that using physical addresses provides direct access to any of your computer's memory mapped devices.

 Note that you can use MbufInquire() with M_PHYSICAL_ADDRESS to get the physical address of a MIL allocated buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This setting must be used for all buffers with the M_GRAB attribute.

a
b
c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

 You must specify how the pitch is measured by adding one of the following values below to the ControlFlag parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_PITCH

 Specifies that the pitch is in pixels.  Specifies that the pitch is in pixels ...

This is the default value.

  Open   Collapse  M_PITCH_BYTE

 Specifies that the pitch is in bytes.  Specifies that the pitch is in bytes.

 Pitch

 Sets the size of the pitch.  The pitch is the number of pixels or bytes (as specified by the ControlFlag) between the start of any two adjacent rows of the buffer. The actual length of the buffer's memory line in memory might be different from the value set by the SizeX parameter (due to use of buffer overscan, for example.)

 By default, for an M_DIB buffer, if the pitch is in pixels (M_PITCH), the pitch must equal SizeX. If the pitch is in bytes (M_PITCH_BYTE), the pitch value must be the next multiple of 4 that is larger or equal to (SizeX * bytes per pixels).

 Note that your code should not make assumptions about the actual pitch of the source memory. If the memory was allocated using an MbufAlloc...() function, use MbufInquire() with M_PITCH or M_PITCH_BYTE to establish the required pitch.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the pitch identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies the pitch identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.

  Open   Collapse  Value

 Specifies the pitch in pixels or bytes (as determined by ControlFlag).  Specifies the pitch in pixels or bytes (as determined by ControlFlag) ...

 For an M_DIB buffer, if the pitch is in pixels (M_PITCH), the pitch must equal SizeX. If the pitch is in bytes (M_PITCH_BYTE), the pitch value must be the next multiple of 4 that is larger or equal to (SizeX * bytes per pixel).

 DataPtr

 Specifies the MIL identifier of a buffer, or a pointer to the data array, to which to map the created MIL buffer.

 When the ControlFlag parameter is set to M_MIL_ID, DataPtr specifies the MIL identifier of the source buffer.

 When the ControlFlag parameter is set to M_HOST_ADDRESS, DataPtr specifies a logical address that points to the data.

 When the ControlFlag parameter is set to M_HOST_ADDRESS_REMOTE, DataPtr specifies the remote Host's logical address that points to the data.

 When the ControlFlag parameter is set to M_PHYSICAL_ADDRESS, DataPtr specifies a physical address that points to the data.

 BufIdPtr

 Specifies the address of the variable in which the buffer identifier is to be written.  Since the MbufCreate2d() function also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the buffer identifier. If allocation fails, an identifier of 0 is returned.

Remarks

  •  Note that MIL-Lite compression support, particularly for M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

  •  You can allocate an image buffer with a M_KERNEL, M_STRUCT_ELEMENT, or M_PROC attribute with MIL-Lite. However, these attributes are not required to work under MIL-Lite.
    •

MIL ID MIL ID MIL ID ARRAY IMAGE IMAGE SIGNED COMPRESS COMPRESS PHYSICAL ADDRESS GRAB GRAB COMPRESS BITMAPINFO DC ALLOC OFF BOARD OFF BOARD NON PAGED HOST MEMORY NON PAGED SHARED ON BOARD EXTENDED FORMAT GRAB DISP HOST ADDRESS HOST ADDRESS REMOTE PHYSICAL ADDRESS GRAB DIB PITCH PITCH BYTE PITCH PITCH BYTE MIL ID PITCH PITCH BYTE MIL ID HOST ADDRESS HOST ADDRESS REMOTE PHYSICAL ADDRESS COMPRESS KERNEL STRUCT ELEMENT PROC  DEFAULT HOST   DEFAULT   DEFAULT   DEFAULT     FLOAT SIGNED UNSIGNED  ARRAY  IMAGE  KERNEL LUT STRUCT ELEMENT COMPRESS  DISP GRAB  PROC JPEG LOSSLESS JPEG2000 LOSSLESS JPEG LOSSLESS INTERLACED  JPEG LOSSY JPEG2000 LOSSY JPEG LOSSY INTERLACED DIB DIRECTX GDI HOST MEMORY OFF BOARD ON BOARD VIDEO MEMORY FAST MEMORY SHARED NON PAGED PAGED FAST OVERSCAN  HOST ADDRESS HOST ADDRESS REMOTE MIL ID PHYSICAL ADDRESS  PITCH PITCH BYTE  DEFAULT


MbufCreateColor

See Also | Example | Availability | MbufCreate2d | MbufDiskInquire
User Guide:
Mapping a data buffer to user-allocated memory

Reference:
MbufAllocColor
MbufControl
MbufFree
MbufGetColor
MbufInquire
MbufPutColor
MsysAlloc
mgenlc.c
mmorphisjpeg2000.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Partially supported on:
Partially supported on Matrox Genesis
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Create a color data buffer.
Syntax
MIL_ID MbufCreateColor(
MIL_ID SystemId,
long SizeBand,
long SizeX,
long SizeY,
long Type,
MIL_INT64 Attribute,
long ControlFlag,
long Pitch,
void **ArrayOfDataPtr,
MIL_ID *BufIdPtr
)
Description

This function creates a color data buffer using memory at a specified location, and associates it with a specific MIL system.

This function should be used with caution because, when using physical addresses, it provides direct access to any of your computer's memory mapped devices; when using logical addresses, memory protection errors could result.

It is generally better to leave buffer allocation, data loading, and memory control to MIL (MbufAllocColor(), MbufGetColor(), MbufPutColor()), since MIL might require special memory attributes (such as non-paged memory) or alignment in order to associate the buffer with a particular target system.

You must allocate the appropriate memory before calling MbufCreateColor() and you must free the created buffer when no longer required, using MbufFree() before freeing the memory. Using MbufFree() on a buffer created with MbufCreateColor() will free the internal structure required for a mapped buffer, but it will not free the memory used.

If creating a 3-band buffer, be as specific as possible when setting the buffer attributes (using the Attribute parameter) and make sure to specify the color format of the buffer. The more information known about the associated buffer, the better the results.

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

Note that to map a buffer to on-board memory on a different system, the on-board memory must be shared memory, unless the created buffer is created on the same system. See your Board Specific Notes for more information regarding shared memory.

Parameters
SystemId

Specifies the MIL system on which to create the buffer. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 SizeBand

 Sets the number of (x,y) surfaces (also called color bands) that the buffer should have in order to contain each color component of the data.  When acquiring or processing monochrome images, the buffer requires only one color band. For RGB color images, it requires three color bands.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the same number color bands as the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies the same number color bands as the source buffer when the ControlFlag parameter is set to M_MIL_ID.

  Open   Collapse  1 to n

 Specifies the number of bands. The possible range is 1 to n. However, there are generally either 1 or 3 bands.  Specifies the number of bands ...

 SizeX

 Sets the buffer width.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the buffer width is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies that the buffer width is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.

  Open   Collapse  Value

 Specifies the buffer width. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, width is specified in pixels.  Specifies the buffer width ...

 SizeY

 Sets the buffer height.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the buffer height is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies that the buffer height is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.

  Open   Collapse  Value

 Specifies the buffer height. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, height is specified in pixels.  Specifies the buffer height ...

 Type

 Sets a combination of two values: data depth and data type.  Specify the depth of the buffer per band as one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the data depth and type are identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies that the data depth and type are identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID ...

  Open   Collapse  1

 Specifies a 1-bit (packed binary) buffer. Note that you cannot create a 1-bit LUT buffer.  Specifies a 1-bit (packed binary) buffer ...

  Open   Collapse  8

 Specifies an 8-bit buffer.  Specifies an 8-bit buffer.

  Open   Collapse  16

 Specifies a 16-bit buffer.  Specifies a 16-bit buffer.

  Open   Collapse  32

 Specifies a 32-bit buffer.  Specifies a 32-bit buffer.

      [Combination constants]

 You can add one of the following to the Type parameter to specify the data type. Supported data types depend on the specified depth.

  Open   Collapse  Value
Description

  Open   Collapse  M_FLOAT

 Specifies that the type of data is floating point. The valid data depth is 32 bits.  Specifies that the type of data is floating point ...

  Open   Collapse  M_SIGNED

 Specifies that the type of data is signed. The valid data depths are 8, 16 or 32 bits.  Specifies that the type of data is signed ...

  Open   Collapse  M_UNSIGNED

 Specifies that the type of data is unsigned. The valid data depths are 1, 8, 16 or 32 bits.  Specifies that the type of data is unsigned ...

This is the default value.

 Attribute

 Specifies the buffer usage.  This allows you to specify the type of buffer, intended purpose, compression type, storage format, data direction, location, internal storage format, memory type, and overscan region of the created buffer; all of which provides additional information for other MIL functions.

 Set this parameter to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_IMAGE

 Specifies a buffer to store image data.  Specifies a buffer to store image data.

  Open   Collapse  M_LUT

 Specifies a buffer to store lookup table information.  Specifies a buffer to store lookup table information ...

 The depth must be 8, 16, or 32-bit integer or floating point and the internal storage format must be planar.

      [Combination constants]

 When selecting an image buffer (M_IMAGE), you must also specify the intended purpose of this buffer by combining M_IMAGE with one or more of the following values.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_COMPRESS

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can hold compressed data. Note that a buffer with this attribute cannot have the M_SIGNED data type.  Specifies an image buffer that can hold compressed data ...

 When mapping buffers for operations that require a source and destination buffer, and one of the buffers has an M_COMPRESS attribute, the data will be compressed or decompressed depending on the attributes of the destination buffer. If both the source and destination buffers have M_COMPRESS specifiers but different compression types, the data will be re-compressed according to the settings of the destination buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_DISP

 Specifies an image buffer that can be displayed.  Specifies an image buffer that can be displayed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band display buffers with a depth greater than 16 bits cannot be allocated. Three-band display buffers can only be allocated with 8 bits per band.

c

  Open   Collapse  M_GRAB

 Specifies an image buffer in which to grab data.  Specifies an image buffer in which to grab data ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Single-band buffers with a depth of 8 or 16 bits (monochrome) and 3-band buffers with a depth of 8 bits (color) can have an M_GRAB attribute.

a

c
d
e

h
i

m
n
o

q
r

 Single-band or 3-band buffers, with a depth of 8 bits, can have an M_GRAB attribute.

b

f
g

j
k
l

p

  Open   Collapse  M_PROC

MIL-lite with restriction (see remarks).

 Specifies an image buffer that can be processed.  Specifies an image buffer that can be processed.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

[MIL-Lite with restriction]

 For an M_COMPRESS type of image buffer, one of the following values can be added to indicate the type of compressed data. The image buffer's data depth dictates which compression type can be selected.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description

  Open   Collapse  M_JPEG_LOSSLESS

 Specifies that the buffer will be used to hold JPEG lossless data. The supported data formats are: 1-band, 8- or 16-bit data, and 3-band data in M_RGB24 or M_RGB48 format.  Specifies that the buffer will be used to hold JPEG lossless data ...

  Open   Collapse  M_JPEG2000_LOSSLESS

 Specifies that the buffer will be used to hold JPEG2000 lossless data. The supported data formats are: 1-band, 8- or 16-bit data, and 3-band, 8- or 16-bit data in M_RGB24 + M_PLANAR, M_RGB48 + M_PLANAR, or M_YUV24 + M_PLANAR format.  Specifies that the buffer will be used to hold JPEG2000 lossless data ...

  Open   Collapse  M_JPEG_LOSSLESS_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossless data in separate fields. The supported data formats are 1-band, 8- or 16-bit data.  Specifies that the buffer will be used to hold JPEG lossless data in separate fields ...

  Open   Collapse  M_JPEG_LOSSY

 Specifies that the buffer will be used to hold JPEG lossy data. The supported data formats are: 1-band 8-bit data, and 3-band 8-bit data in M_RGB24, M_YUV24, M_YUV12, M_YUV9, M_YUV16 + M_PLANAR, or M_YUV16 + M_PACKED format.  Specifies that the buffer will be used to hold JPEG lossy data ...

This is the default value.

  Open   Collapse  M_JPEG2000_LOSSY

 Specifies that the buffer will be used to hold JPEG2000 lossy data. The supported data formats are: 1-band, 8- or 16-bit data, and 3-band, 8- or 16-bit data in M_RGB24, M_RGB48, M_YUV9, M_YUV12, M_YUV16 + M_PLANAR, or M_YUV24 format.  Specifies that the buffer will be used to hold JPEG2000 lossy data ...

  Open   Collapse  M_JPEG_LOSSY_INTERLACED

 Specifies that the buffer will be used to hold JPEG lossy data in separate fields. The supported data formats are: 1-band 8-bit data, and 3-band 8-bit data in M_YUV16 + M_PACKED format.  Specifies that the buffer will be used to hold JPEG lossy data in separate fields ...

      [Combination constants]

 MIL will interpret the created buffer in the type of specified intended usage attribute. The source buffer's actual storage format can differ. If a specific internal format is required, it should be specified.

 To specify a storage format for an image buffer, you can add one or more of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DIB

 Forces the buffer to be a DIB buffer. This ensures that your buffer is stored with a DIB header. Use MbufInquire() with M_BITMAPINFO to return a pointer (LPBITMAPINFO) to the header of the MIL buffer.  Forces the buffer to be a DIB buffer ...

  Open   Collapse  M_DIRECTX

 Forces the buffer to be a DirectX surface.  Forces the buffer to be a DirectX surface.

  Open   Collapse  M_GDI

 Forces the buffer to be compatible with GDI.  Forces the buffer to be compatible with GDI ...

 When using a device context (using MbufControl() with M_DC_ALLOC) for drawing, the buffer should be internally stored in GDI format, and cannot be a child buffer.

      [Combination constants]

 When dealing with color buffers, you must specify the appropriate internal storage format of the buffer by adding one of the following values. Note that MIL needs this information to manipulate the data; for example, you do not want MIL to interpret a packed data buffer as a planar.

  Open   Collapse  Value
Description

  Open   Collapse  M_PACKED

 The buffer bands are packed. Note that you cannot specify a LUT buffer to be packed.  The buffer bands are packed ...

  Open   Collapse  M_PLANAR

 The buffer bands are planar.  The buffer bands are planar.

      [Combination constants]

[All except
        Matrox Iris]

 When dealing with packed or planar color buffers, you must specify the appropriate color format. Add one of the values below to either M_PACKED or M_PLANAR, respectively. Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

 The specified format can differ from that of the specified physical memory.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_RGB24

 Specifies 24-bit color depth (RGB 8:8:8) packed or planar pixels.  Specifies 24-bit color depth (RGB 8:8:8) packed or planar pixels ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with planar (M_PLANAR) grab (M_GRAB) buffers.

a

c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

 This value can be used with packed (M_PACKED) grab (M_GRAB) buffers.

g

j
k

  Open   Collapse  M_YUV16

 Specifies YUV16 packed or planar (4:2:2) standard.  Specifies YUV16 packed or planar (4:2:2) standard ...

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with packed (M_PACKED) grab (M_GRAB) buffers.

a
b

d
e

k
l
m
n
o
p
q
r

 This value can be used with either packed (M_PACKED) or planar (M_PLANAR) grab (M_GRAB) buffers.

g

 Only available on the PC/104-Plus form factor (for M_PACKED buffers).

k

      [Combination constants]

[All except
        Matrox Iris]

 When dealing with planar color image buffers, you must specify the appropriate color format. Add one of the values below to M_PACKED. Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

 The specified format can differ from that of the specified physical memory.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_RGB3

 Specifies 3-bit color depth (RGB 1:1:1) planar pixels.  Specifies 3-bit color depth (RGB 1:1:1) planar pixels.

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_RGB48

 Specifies 48-bit color depth (RGB 16:16:16) planar pixels.  Specifies 48-bit color depth (RGB 16:16:16) planar pixels ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p

Specifics

 This value can be used with grab (M_GRAB) buffers.

c
d
e

m
n
o

  Open   Collapse  M_RGB96

 Specifies 96-bit color depth (RGB 32:32:32) planar pixels.  Specifies 96-bit color depth (RGB 32:32:32) planar pixels ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

c

  Open   Collapse  M_YUV9

 Specifies YUV9 planar standard.  Specifies YUV9 planar standard.

a
b

d
e

g
h
i
j
k
l

p
q
r

  Open   Collapse  M_YUV12

 Specifies YUV12 planar standard.  Specifies YUV12 planar standard ...

a
b

d
e

g
h
i
j
k
l

p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

  Open   Collapse  M_YUV24

 Specifies YUV24 planar standard.  Specifies YUV24 planar standard ...

a
b

d
e

g
h
i
j
k
l

p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

      [Combination constants]

[All except
        Matrox Genesis and Matrox Iris]

 When dealing with packed color image buffers, you must specify the appropriate color format. Add one of the values below to M_PACKED. Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

 The specified format can differ from that of the specified physical memory.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_BGR24

 Specifies 24-bit color depth (BGR) packed pixels.  Specifies 24-bit color depth (BGR) packed pixels ...

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

a
b

g

j
k

m
n
o

 This value can be used with grab (M_GRAB) buffers only if the DCF is color.

h
i

  Open   Collapse  M_BGR32

 Specifies 32-bit color depth (BGR) packed pixels.  Specifies 32-bit color depth (BGR) packed pixels ...

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

a
b

d
e

g

j
k

m
n
o
p
q
r

 This value can be used with grab (M_GRAB) buffers only if the DCF is color.

h
i

  Open   Collapse  M_RGB15

 Specifies 16-bit color depth packed pixels (XRGB 1:5:5:5).  Specifies 16-bit color depth packed pixels (XRGB 1:5:5:5) ...

 Note that when accessing an M_RGB15 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0.

a
b

d
e

g

j
k
l

p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

  Open   Collapse  M_RGB16

 Specifies 16-bit color depth packed pixels (RGB 5:6:5).  Specifies 16-bit color depth packed pixels (RGB 5:6:5) ...

 Note that when accessing an M_RGB16 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0.

a
b

d
e

g

j
k
l

p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

 Only available on the PC/104-Plus form factor.

j
k

  Open   Collapse  M_YUV16_UYVY

 Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the UYVY order. For more information, see the YUV buffers section in
          Chapter 14: Specifying and managing your data buffers.  Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the UYVY order ...

a

g
h
i
j
k

p

Specifics

 This value can be used with grab (M_GRAB) buffers.

g

  Open   Collapse  M_YUV16_YUYV

 Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the YUYV order. For more information, see the YUV buffers section in
          Chapter 14: Specifying and managing your data buffers.  Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the YUYV order ...

a
b

d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This value can be used with grab (M_GRAB) buffers.

a
b

d
e

g

k
l
m
n
o
p
q
r

      [Combination constants]

 To specify a location for an image buffer, you can add one of the following values.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_HOST_MEMORY

 Specifies that the buffer is in Host memory.  Specifies that the buffer is in Host memory ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

a
b

d
e
f
g
h
i
j
k
l

p
q
r

  Open   Collapse  M_OFF_BOARD

 Specifies that the buffer is not in on-board memory.  Specifies that the buffer is not in on-board memory.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_ON_BOARD

 Specifies that the buffer is in on-board memory.  Specifies that the buffer is in on-board memory ...

a

c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

Specifics

 This is the default value.

c

m
n
o

  Open   Collapse  M_VIDEO_MEMORY

 Forces the buffer in (off-screen) display memory of your graphics controller. Display memory is also referred to as video memory or frame buffer memory.  Forces the buffer in (off-screen) display memory of your graphics controller ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 You can add one of the following values when creating an on-board image buffer (M_ON_BOARD).

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_FAST_MEMORY

 Specifies that the buffer is in the G4 PowerPC fast-processing memory. This memory is L3 external cache. It must be enabled using the OdcMon utility before it can be used.  Specifies that the buffer is in the G4 PowerPC fast-processing memory ...

 Use MbufInquire() with M_EXTENDED_FORMAT to establish if the specified memory was allocated in fast processing memory.

 Fast processing memory is only accessible to the G4 PowerPC microprocessor and not to the Host, frame grabber module, or PA. Therefore, depending on the operation, allocating a buffer in fast processing memory might not accelerate processing.

 Note that M_GRAB and M_DISP are not supported with this attribute.

m
n
o

  Open   Collapse  M_SHARED

 Specifies that the buffer is in shared processing memory. This memory is mapped on the PCI bus.  Specifies that the buffer is in shared processing memory ...

d
e

m
n
o

q
r

      [Combination constants]

 To specify a type of memory, either paged or non-paged, you can add one of the following values.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description

  Open   Collapse  M_NON_PAGED

 Specifies that the buffer is in MIL-reserved, non-pageable memory.  Specifies that the buffer is in MIL-reserved, non-pageable memory.

  Open   Collapse  M_PAGED

 Specifies that the buffer is in pageable memory.  Specifies that the buffer is in pageable memory.

      [Combination constants]

 To specify that the buffer has an overscan region, add the value below.

 Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

  Open   Collapse  Value
Description

  Open   Collapse  M_FAST_OVERSCAN

 Specifies that the buffer has an overscan region.  Specifies that the buffer has an overscan region.

 ControlFlag

 Specifies the physical nature of the buffer.  This parameter can be set to one of the values below.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_HOST_ADDRESS

 Specifies that ArrayOfDataPtr is an array of logical addresses that point to the data.  Specifies that ArrayOfDataPtr is an array of logical addresses that point to the data ...

 Note that when using logical addresses, memory protection errors could result.

 Note that you can use MbufInquire() with M_HOST_ADDRESS to get the logical address of a MIL allocated buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_HOST_ADDRESS_REMOTE

 Specifies that ArrayOfDataPtr is an array of the remote Host's logical addresses that point to the data.  Specifies that ArrayOfDataPtr is an array of the remote Host's logical addresses that point to the data ...

 Note that when using logical addresses, memory protection errors could result.

 Note that you can use MbufInquire() with M_HOST_ADDRESS_REMOTE to get the logical address of a MIL allocated buffer.

m
n
o

  Open   Collapse  M_MIL_ID

 Specifies that the new buffer maps to an existing source buffer. ArrayOfDataPtr points to the MIL identifier of the source buffer.  Specifies that the new buffer maps to an existing source buffer ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_PHYSICAL_ADDRESS

 Specifies that ArrayOfDataPtr is an array of physical addresses that point to the data.  Specifies that ArrayOfDataPtr is an array of physical addresses that point to the data ...

 Note that using physical addresses provides direct access to any of your computer's memory mapped devices.

 Note that you can use MbufInquire() with M_PHYSICAL_ADDRESS to get the physical address of a MIL allocated buffer.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This setting must be used for all buffers with the M_GRAB attribute.

a
b
c

f

h
i
j
k

      [Combination constants]

 You must specify how the pitch is measured by adding one of the following values to the ControlFlag parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_PITCH

 Specifies that the pitch is in pixels.  Specifies that the pitch is in pixels ...

This is the default value.

  Open   Collapse  M_PITCH_BYTE

 Specifies that the pitch is in bytes.  Specifies that the pitch is in bytes ...

 Note that when creating an M_BGR24 + M_PACKED buffer, you should use M_PITCH_BYTE instead of M_PITCH because the latter might not be able to take into account internal padding.

 Pitch

 Sets the size of the pitch.  The pitch is the number of pixels or bytes (as specified by the ControlFlag) between the start of any two adjacent rows of the buffer. The actual length of a row in the buffer in physical memory might be different from the value set by the SizeX parameter (for example, due to use of the buffer overscan).

 Note that your code should not make assumptions about the actual pitch of the source memory. If the memory was allocated using an MbufAlloc...() function, use MbufInquire() with M_PITCH or M_PITCH_BYTE to establish the required pitch.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the pitch is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.  Specifies that the pitch is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.

  Open   Collapse  Value

 Specifies the pitch in pixels or bytes (as determined by ControlFlag).  Specifies the pitch in pixels or bytes (as determined by ControlFlag) ...

 For an M_DIB buffer, if the pitch is in pixels (M_PITCH), the pitch must equal SizeX. If the pitch is in bytes (M_PITCH_BYTE), the pitch value must be the next multiple of 4 that is larger or equal to (SizeX * bytes per pixels).

 ArrayOfDataPtr

 Specifies one or more data pointers that address the memory to which to map the created MIL buffer.

 When pointing to a planar buffer, one pointer per band must be provided. Pointers to a 3-band planar buffer must be ordered R-G-B or Y-U-V in the array. When pointing to a single-band buffer or a packed buffer, a pointer to the packed data must be provided.

 When the ControlFlag parameter is set to M_MIL_ID, ArrayOfDataPtr specifies a pointer to the MIL identifier of the source buffer.

 When the ControlFlag parameter is set to M_HOST_ADDRESS, ArrayOfDataPtr specifies an array of logical addresses that point to the data.

 When the ControlFlag parameter is set to M_HOST_ADDRESS_REMOTE, ArrayOfDataPtr specifies an array of the remote Host's logical addresses that point to the data.

 When the ControlFlag parameter is set to M_PHYSICAL_ADDRESS, ArrayOfDataPtr specifies an array of physical addresses that point to the data.

 BufIdPtr

 Specifies the address of the variable in which the buffer identifier is to be written.  Since the MbufCreateColor() function also returns the buffer identifier, you can set this parameter to M_NULL. If mapping fails, M_NULL is written as the identifier.

Return value

 The returned value is the buffer identifier. If allocation fails, M_NULL is returned.

Remarks

  •  Note that MIL-Lite compression support, particularly for the M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

  •  You can allocate an image buffer with a M_PROC attribute with MIL-Lite. However, this attribute is not required to work under MIL-Lite.
    •

MIL ID MIL ID MIL ID MIL ID IMAGE IMAGE SIGNED COMPRESS COMPRESS GRAB GRAB COMPRESS RGB24 RGB48 RGB24 YUV24 YUV12 YUV9 YUV16 PLANAR YUV16 PACKED YUV16 PACKED RGB24 PLANAR RGB48 PLANAR YUV24 PLANAR RGB24 RGB48 YUV9 YUV12 YUV16 PLANAR YUV24 BITMAPINFO DC ALLOC PACKED PLANAR GRAB PLANAR GRAB PACKED GRAB PACKED GRAB PACKED PLANAR GRAB PACKED PACKED GRAB GRAB GRAB GRAB GRAB PACKED GRAB GRAB GRAB GRAB GRAB RGB15 PACKED GRAB RGB16 PACKED GRAB GRAB GRAB ON BOARD EXTENDED FORMAT GRAB DISP HOST ADDRESS HOST ADDRESS REMOTE PHYSICAL ADDRESS GRAB BGR24  PACKED PITCH BYTE PITCH PITCH PITCH BYTE MIL ID DIB PITCH PITCH BYTE MIL ID HOST ADDRESS HOST ADDRESS REMOTE PHYSICAL ADDRESS COMPRESS PROC  DEFAULT HOST   DEFAULT   DEFAULT   DEFAULT       DEFAULT FLOAT SIGNED UNSIGNED  IMAGE LUT COMPRESS DISP  GRAB PROC  JPEG LOSSLESS JPEG LOSSLESS INTERLACED  JPEG LOSSY JPEG LOSSY INTERLACED JPEG2000 LOSSLESS JPEG2000 LOSSY DIB DIRECTX GDI PACKED  PLANAR  RGB24  YUV16 RGB3  RGB48  RGB96  YUV9  YUV12 YUV24 BGR24  BGR32  RGB15  RGB16  YUV16 UYVY YUV16 YUYV HOST MEMORY OFF BOARD ON BOARD VIDEO MEMORY FAST MEMORY SHARED NON PAGED PAGED  FAST OVERSCAN  HOST ADDRESS HOST ADDRESS REMOTE MIL ID PHYSICAL ADDRESS  PITCH  PITCH BYTE   DEFAULT


MbufDiskInquire

See Also | Example | Availability | MbufCreateColor | MbufExport
Reference:
MbufAllocColor
MbufControlNeighborhood
MbufExport
MbufExportSequence
mbufcolor.c
mdiggrabsequence.c
mfunc.c
mocr.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL
Synopsis
Inquire about the buffer data in a file.
Syntax
long MbufDiskInquire(
MIL_TEXT_PTR FileName,
long InquireType,
void *UserVarPtr
)
Description

This function inquires about the buffer data in the specified file on disk.

Parameters
FileName

Specifies the file name and path. Note, an error occurs if the file does not have a known file format or the file format is not supported.

The supported file types include all the formats supported by the MbufExport() and MbufExportSequence() functions. Since a raw data file does not have any information regarding size or type, you can only use MbufDiskInquire() to determine the file format of this type of file.

InquireType

Specifies the type of buffer setting about which to inquire. This parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_ATTRIBUTE

Returns the file attribute. Returns the file attribute ...

Note that AVI files return M_IMAGE as file attribute.

UserVarPtr info

Return values:
M_ARRAY, M_IMAGE, M_KERNEL, M_LUT, M_STRUCT_ELEMENT (details)
Open Collapse M_FILE_FORMAT

Returns the file format. See MbufExport() and MbufExportSequence() for all supported file formats. Returns the file format ...

Open Collapse M_SIGN

Returns the file data range. Returns the file data range ...

UserVarPtr info

Return values:
M_SIGNED | Data range is signed.
M_UNSIGNED | Data range is unsigned.
Open Collapse M_SIZE_BAND

Returns the number of color bands in the file. Returns the number of color bands in the file.

Open Collapse M_SIZE_BIT

Returns the file data depth, in bits. Returns the file data depth, in bits.

Open Collapse M_SIZE_X

Returns the width of the data in the file, in pixels. Returns the width of the data in the file, in pixels.

Open Collapse M_SIZE_Y

Returns the height of the data in the file, in pixels. Returns the height of the data in the file, in pixels.

Open Collapse M_TYPE

Returns the file data type and depth. The depth is returned in bits. Returns the file data type and depth ...

UserVarPtr info

Return values:
depth value + M_FLOAT | Data range is floating point.
depth value + M_SIGNED | Data range is signed.
depth value + M_UNSIGNED | Data range is unsigned.

[Combination constants]

You can add the following value to M_SIZE_X and M_SIZE_BAND. This option is available only if the file contains an image data buffer. This option is not available for AVI files.

Open Collapse Value | Description
Open Collapse M_LUT | Returns either the width of the LUT associated with the image in the file (for M_SIZE_X) or the number of bands of the LUT associated with the image in the file (for M_SIZE_BAND). When there is no LUT associated with the image, M_INVALID is returned. Returns either the width of the LUT associated with the image in the file (for M_SIZE_X) or the number of bands of the LUT associated with the image in the file (for M_SIZE_BAND) ...

You can inquire the following values for M_IMAGE files (images or AVI sequences).

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_ASPECT_RATIO

Returns the aspect ratio of the images in the file. Returns the aspect ratio of the images in the file ...

UserVarPtr info

Data type: double
Open Collapse M_COMPRESSION_TYPE

Returns the compression type of the images in the file. Returns M_NULL if the images are not compressed (for example, in a BMP file format). See MbufAllocColor() for all possible compression formats. Returns the compression type of the images in the file. Returns M_NULL if the images are not compressed (for example, in a BMP file format) ...

Open Collapse M_FRAME_RATE

Returns the frame rate (number of images/second) of an AVI file. Returns the frame rate (number of images/second) of an AVI file ...

This value is only valid for sequences.

UserVarPtr info

Data type: double
Open Collapse M_LUT_PRESENT

Returns the presence of LUT data in the file. Returns the presence of LUT data in the file ...

UserVarPtr info

Return values:
M_NO | LUT data is not available.
M_YES | LUT data is available.
Open Collapse M_NUMBER_OF_IMAGES

Returns the number of images in an AVI file. Returns the number of images in an AVI file ...

This value is only valid for sequences.

You can inquire the following values for M_KERNEL and M_STRUCT_ELEMENT files.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_OFFSET_CENTER_X | Returns the X-coordinate of the center of the kernel or structuring element. Returns the X-coordinate of the center of the kernel or structuring element.
Open Collapse M_OFFSET_CENTER_Y | Returns the Y-coordinate of the center of the kernel or structuring element. Returns the Y-coordinate of the center of the kernel or structuring element.
Open Collapse M_OVERSCAN | Returns the overscan type. Returns the overscan type ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_MIRROR, M_REPLACE, M_TRANSPARENT (details)
Open Collapse M_OVERSCAN_REPLACE_VALUE | Returns the overscan replace value. Returns the overscan replace value.

You can inquire the following values for M_KERNEL files.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_ABSOLUTE_VALUE

Returns the absolute value flag. Returns the absolute value flag ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_FILTER_MODE

Returns the mode in which the neighborhood operations are performed. Returns the mode in which the neighborhood operations are performed ...

UserVarPtr info

Return values:
M_KERNEL, M_RECURSIVE (details)
Open Collapse M_FILTER_OPERATION

Returns the type of neighborhood operation performed using the selected filter. Returns the type of neighborhood operation performed using the selected filter ...

If MbufControlNeighborhood() M_FILTER_TYPE is set to M_USER_DEFINED, then M_FILTER_OPERATION is not supported.

UserVarPtr info

Return values:
M_EDGE_DETECT, M_EDGE_DETECT_SQR, M_FIRST_DERIVATIVE_X, M_FIRST_DERIVATIVE_Y, M_HORIZ_EDGE, M_LAPLACIAN_EDGE, M_SECOND_DERIVATIVE_X, M_SECOND_DERIVATIVE_XY, M_SECOND_DERIVATIVE_Y, M_SHARPEN, M_SMOOTH, M_VERT_EDGE (details)
Open Collapse M_FILTER_SMOOTHNESS

Returns the degree of smoothness (strength of the denoising) applied by the filter during the neighborhood operation. Returns the degree of smoothness (strength of the denoising) applied by the filter during the neighborhood operation ...

If MbufControlNeighborhood() M_FILTER_TYPE is set to M_USER_DEFINED, then M_FILTER_SMOOTHNESS is not supported.

UserVarPtr info

Return values:
0 to 100 (details)
Open Collapse M_FILTER_TYPE

Returns the type of filter used to perform the neighborhood operation. Returns the type of filter used to perform the neighborhood operation ...

UserVarPtr info

Return values:
M_DERICHE, M_SHEN, M_USER_DEFINED (details)
Open Collapse M_NORMALIZATION_FACTOR

Returns the normalization factor. Returns the normalization factor ...

UserVarPtr info

Return values:
Please see MbufControlNeighborhood() with M_NORMALIZATION_FACTOR.

Open Collapse M_SATURATION

Returns the saturation flag. Returns the saturation flag ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • double
  • long

Specifies the address in which to write the requested information.

Since the MbufDiskInquire() function also returns the requested information, you can set this parameter to M_NULL.

Return value
The returned value is the requested buffer setting information of the specified file, cast to long. If the requested information is not available, M_INVALID is returned.
Remarks
  • Note that MIL-Lite does not support the inquiries available for M_KERNEL and M_STRUCT_ELEMENT data buffers.
  • Note that MIL-Lite compression support is reliant upon the presence of Matrox compression acceleration hardware; the compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
SIZE X SIZE BAND SIZE X SIZE BAND IMAGE KERNEL STRUCT ELEMENT KERNEL FILTER TYPE USER DEFINED FILTER OPERATION FILTER TYPE USER DEFINED FILTER SMOOTHNESS KERNEL STRUCT ELEMENT ATTRIBUTE FILE FORMAT SIGN SIZE BAND SIZE BIT SIZE X SIZE Y TYPE LUT ASPECT RATIO COMPRESSION TYPE FRAME RATE LUT PRESENT NUMBER OF IMAGES OFFSET CENTER X OFFSET CENTER Y OVERSCAN OVERSCAN REPLACE VALUE ABSOLUTE VALUE FILTER MODE FILTER OPERATION FILTER SMOOTHNESS FILTER TYPE NORMALIZATION FACTOR SATURATION


MbufExport

See Also | Example | Availability | MbufDiskInquire | MbufExportSequence
User Guide:
Managing data buffers
Managing color images
General steps

Reference:
MbufControl
MbufSave
There are no examples containing MbufExport().
Available in MIL-Lite with restrictions (see remarks)

Available in MIL
Synopsis
Export a data buffer to a file.
Syntax
void MbufExport(
MIL_TEXT_PTR FileName,
long FileFormat,
MIL_ID SrcBufId
)
Description

This function exports a data buffer to a file, in the specified output file format.

Note that you can also save a buffer in an M_MIL file format, using MbufSave(). The M_MIL file format is TIFF compatible.

To export an image with a LUT (color palette), associate the LUT to the image, using MbufControl(). Upon export, the image is saved with its associated color palette (MIM, TIFF, and BMP file formats).

[MIL-Lite with restriction]

When exporting uncompressed data to a file in an M_JPEG_... or M_JPEG2000_... file format, this function will automatically compress the data, according to the specified file format. The buffer does not need an M_COMPRESS attribute. If you are exporting compressed data to a file in an uncompressed file format, this function will automatically decompress the data.

Parameters
FileName

Specifies the name and path of the file in which to store the data buffer. The function handles (internally) the opening and closing of the file. If the file already exists, it will be overwritten.

FileFormat

Specifies the file format. This parameter can be set to one of the following values. Note that, except for the M_MIL and M_RAW file formats, the source buffer should have an M_IMAGE attribute; otherwise, the data is saved as if it were image data.

Open Collapse Value Description
Open Collapse M_BMP

 Saves the image buffer contents in a BMP file format. The standard Windows BMP format is used.  Saves the image buffer contents in a BMP file format. The standard Windows BMP format is used ...

 This file format supports images that are grayscale or RGB. Images in a different format are internally converted before being saved.

 This file format supports only 8-bit buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved.

  Open   Collapse  M_JPEG_LOSSLESS

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in a JPEG lossless file format. If the buffer is 3-band, the data will be stored in RGB format.  Saves the image buffer contents in a JPEG lossless file format ...

 This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image in order to keep the most significant data.

  Open   Collapse  M_JPEG2000_LOSSLESS

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in a JPEG2000 lossless file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSLESS attribute, the data will be stored in RGB format; otherwise, it will be stored in the same color format as the buffer.  Saves the image buffer contents in a JPEG2000 lossless file format ...

 This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image in order to keep the most significant data.

  Open   Collapse  M_JPEG_LOSSLESS_INTERLACED

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in an interlaced JPEG lossless file format. This file format is only applicable to 1-band image buffers.  Saves the image buffer contents in an interlaced JPEG lossless file format ...

 This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image in order to keep the most significant data.

  Open   Collapse  M_JPEG2000_LOSSLESS_JP2

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in a JPEG2000 lossless file format using the standard JP2 format. Only the color specification of the image buffer can be specified from the additional JP2 information. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSLESS attribute, the data will be stored in RGB format; otherwise, it will be stored in the same color format as the buffer.  Saves the image buffer contents in a JPEG2000 lossless file format using the standard JP2 format ...

 This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image in order to keep the most significant data.

  Open   Collapse  M_JPEG_LOSSY

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in a JPEG lossy file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG_LOSSY attribute, the data will be stored in YUV16 packed format; otherwise, it will be stored in the same color format as the buffer.  Saves the image buffer contents in a JPEG lossy file format ...

 This file format supports only 8-bit buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved.

  Open   Collapse  M_JPEG2000_LOSSY

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in a JPEG2000 lossy file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSY attribute, the data will be stored in YUV16 planar format if the buffer is 8-bit or in RGB format if the buffer is 16-bit; otherwise, it will be stored in the same color format as the buffer.  Saves the image buffer contents in a JPEG2000 lossy file format ...

 This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image in order to keep the most significant data.

  Open   Collapse  M_JPEG_LOSSY_INTERLACED

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in an interlaced JPEG lossy file format. If the buffer is 3-band, the data will be stored in YUV16 packed format.  Saves the image buffer contents in an interlaced JPEG lossy file format ...

 This file format supports only 8-bit buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved.

  Open   Collapse  M_JPEG2000_LOSSY_JP2

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in a JP2000 lossy file format using the standard JP2 file format. Only the color specification of the image buffer can be specified from the additional JP2 information. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSY attribute, the data will be stored in YUV16 planar format if the buffer is 8-bit or in RGB format if the buffer is 16-bit; otherwise, it will be stored in the same color format as the buffer.  Saves the image buffer contents in a JP2000 lossy file format using the standard JP2 file format ...

 This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image in order to keep the most significant data.

  Open   Collapse  M_JPEG_LOSSY_RGB

MIL-lite with restriction (see remarks).

 Saves the image buffer contents in a JPEG lossy file format. If the buffer is 3-band, the data will be stored in RGB format.  Saves the image buffer contents in a JPEG lossy file format ...

 This file format supports only 8-bit buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved.

  Open   Collapse  M_MIL

 Saves the buffer contents in a MIL file format. It uses a baseline TIFF 6.0 file format with extra information included in the comment field. The buffer attributes and data type are also saved in the file.  Saves the buffer contents in a MIL file format ...

 This file format supports images that are binary, grayscale, and RGB, as well as palette-color images.

 The MIL file format is a single-page, uncompressed TIFF file format.

 By default, most color image buffers are saved in a packed (chunky) format (in accordance with baseline TIFF 6.0 specifications). Color binary buffers are saved in a 1-bit per pixel format (data is stored in a 3-band, packed binary format).

  Open   Collapse  M_RAW

 Saves the buffer contents as raw data. The contents are dumped directly (byte stream) into the file and no header is added. If the buffer is multi-band, the buffer is saved in planar format (one band after another).  Saves the buffer contents as raw data ...

  Open   Collapse  M_TIFF

 Saves the image buffer contents in a TIFF file format. The TIFF file format that is used respects the baseline TIFF 6.0 specification.  Saves the image buffer contents in a TIFF file format ...

 The TIFF file format that is used supports images that are binary, grayscale, and RGB, as well as palette-color images. Also, this TIFF format supports any data type and depth that MIL supports for buffers.

 An image buffer cannot be saved using a multi-page TIFF file format; it is always saved as a single-page TIFF file. In addition, MIL only supports uncompressed TIFF files.

 By default, most color image buffers are saved in a packed (chunky) format (in accordance with baseline TIFF 6.0 specifications). Color binary buffers are saved in a 1-bit per pixel format (data is stored in a 3-band, packed binary format).

      [Combination constants]

 The following value can be added to M_MIL or M_TIFF if the buffer is a color image buffer:

  Open   Collapse  Value
Description

  Open   Collapse  M_PLANAR

 Saves the color image buffer in a planar format.  Saves the color image buffer in a planar format.

 SrcBufId

 Specifies the identifier of the data buffer to save.

Remarks

  •  This function is optimized for packed binary buffers.
    •

  •  Note that MIL-Lite compression support, particularly for M_IMAGE + M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

MIL MIL COMPRESS MIL RAW IMAGE COMPRESS JPEG2000 LOSSLESS COMPRESS JPEG2000 LOSSLESS COMPRESS JPEG LOSSY COMPRESS JPEG2000 LOSSY COMPRESS JPEG2000 LOSSY MIL TIFF IMAGE COMPRESS   BMP JPEG LOSSLESS JPEG2000 LOSSLESS JPEG LOSSLESS INTERLACED JPEG2000 LOSSLESS JP2 JPEG LOSSY JPEG2000 LOSSY JPEG LOSSY INTERLACED JPEG2000 LOSSY JP2 JPEG LOSSY RGB MIL RAW TIFF PLANAR


MbufExportSequence

Example | Availability | MbufExport | MbufFree
mdiggrabsequence.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL
Synopsis
Export a sequence of image buffers to an AVI file.
Syntax
void MbufExportSequence(
MIL_TEXT_PTR FileName,
long FileFormat,
MIL_ID *BufArrayPtr,
long NumberOfImages,
double FrameRate,
long ControlFlag
)
Description

This function exports a sequence of image buffers to an audio video interleave (AVI) file.

Parameters
FileName

Specifies the name of the file to which to export the image buffers.

FileFormat

Specifies the format of the file. This parameter can be set to one of the values below.

Open Collapse Value Description
Open Collapse M_DEFAULT

 MIL automatically decides the appropriate format.  MIL automatically decides the appropriate format.

  Open   Collapse  M_AVI_DIB

 Specifies an AVI format used to hold non-compressed DIB image buffers. If necessary, the image buffers will be converted to a non-compressed DIB format before exporting. This type of sequence is supported by Windows Media Player.  Specifies an AVI format used to hold non-compressed DIB image buffers ...

  Open   Collapse  M_AVI_MIL

 Specifies an AVI format used to hold image buffers in their MIL format. Since this function saves images in the format in which they are sent, it can be used with any format. Also, since the images are saved "as is", no additional loss is introduced in the images. To be supported by Windows Media Player, this type of sequence requires a codec.  Specifies an AVI format used to hold image buffers in their MIL format ...

  Open   Collapse  M_AVI_MJPG

MIL-lite with restriction (see remarks).

 Specifies an AVI format, known as the OpenDML format, used to hold JPEG compressed sequences. When this format is specified, the image buffers will be in YUV16 packed format. In addition, image buffers must have a width that is a multiple of 16 pixels. For image buffers that have the M_JPEG_LOSSY compression type, the height must be a multiple of 8, and less than or equal to 240 pixels. For image buffers that have the M_JPEG_LOSSY_INTERLACED compression type, the height must be a multiple of 16 pixels, greater than 240 pixels. If the image buffers are not already in these dimensions and format, MIL will automatically convert them appropriately. To be supported by Windows Media Player, this type of sequence requires a codec.  Specifies an AVI format, known as the OpenDML format, used to hold JPEG compressed sequences ...

 BufArrayPtr

 Specifies the address of the array containing the MIL identifiers of the image buffers to export.

 NumberOfImages

 Specifies the number of image buffers to export.  If the supplied array is larger than this number, the remaining buffer identifiers are ignored.

 FrameRate

 Specifies the frame rate (number of image buffers/second) of the sequence.

 ControlFlag

 Specifies whether to append the image buffers to the AVI file, if the file already exists, or overwrite the file.  This parameter can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Overwrites the file. The file will be opened, written into, and then the file will be closed.  Overwrites the file ...

  Open   Collapse  M_APPEND

 Appends the image buffers to the file. The file will be opened, the specified images will be appended, and then the file will be closed.  Appends the image buffers to the file ...

  Open   Collapse  M_CLOSE

 Closes the AVI file. BufArrayPtr, NumberOfImages, and FrameRate should be set to M_NULL.  Closes the AVI file ...

  Open   Collapse  M_OPEN

 Opens the AVI file for writing, and set the pointer to the beginning of the file.  Opens the AVI file for writing, and set the pointer to the beginning of the file ...

 Note that if M_APPEND is added to M_OPEN, the file is opened and the file pointer is set to the end of the file. BufArrayPtr, NumberOfImages, and FrameRate should be set to M_NULL.

  Open   Collapse  M_WRITE

 Writes the specified number of images in the files starting from the current file pointer position. After the write operation, the file pointer is left at the end of the file, ready for the next M_WRITE operation. BufArrayPtr, NumberOfImages, and FrameRate should be set to the appropriate values.  Writes the specified number of images in the files starting from the current file pointer position ...

Remark

  •  Note that MIL-Lite compression support, particularly for M_AVI_MJPG format, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

JPEG LOSSY JPEG LOSSY INTERLACED APPEND OPEN WRITE AVI MJPG   DEFAULT AVI DIB AVI MIL AVI MJPG     DEFAULT APPEND CLOSE OPEN WRITE


MbufFree

See Also | Example | Availability | MbufExportSequence | MbufGet1d
User Guide:
Allocating an application and its systems
Specifying the dimensions of a data buffer
Manipulating and controlling certain data buffer areas
LUTs and data buffers

Reference:
MbufCreate2d
MbufCreateColor
channel_switch.c
dtkaddconstantmain.c
dtkobjecttracking.c
dtkremap.c
dtksyncasyncfunctionsmain.c
mblob.c
mbufbayercolorfilter.c
mbufcolor.c
mcal.c
mcode.c
mdblgrab.c
mdigautofocus.c
mdigdoublebuffering.c
mdiggrabmultiple.c
mdiggrabsequence.c
mdighook.c
mdigmultformat.c
mdigprocess.c
mdigprocessmultiple.c
mdigsubtract.c
mdispoverlay.c
mdispselect.c
mdispwindow.c
mdispwindowleveling.c
medge.c
mfunc.c
mgenlc.c
mgrabbayer.c
mheliosconcurent.c
mimconvolve.c
mimfft.c
mimhistogram.c
mimmorphic.c
mimperimeter.c
mimpolar.c
mimprocessing.c
mimsegment.c
mimwarp.c
mmeas.c
mmet2dig.c
mmod.c
mmodeltracking.c
mmorphisjpeg2000.c
mnatfct.c
mocr.c
mpat.c
mstr.c
mthread.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Free a data buffer.
Syntax
void MbufFree(
MIL_ID BufId
)
Description

This function deallocates a previously allocated data buffer. The memory reserved for the specified buffer is released.

Child buffers associated to a parent buffer must be deallocated, using MbufFree(), prior to deallocating the parent buffer.

Using MbufFree() on a buffer created with either MbufCreateColor() or MbufCreate2d() will free the internal structure required to map the buffer to existing memory, but MbufFree() will not free the allocated memory used by the created buffer.

Parameter
BufId

Specifies the identifier of the data buffer to deallocate.


MbufGet1d

See Also | Example | Availability | MbufFree | MbufGet2d
User Guide:
Managing data buffers

Reference:
There are no examples containing MbufGet1d().
Available in MIL-Lite

Available in MIL
Synopsis
Get data from a 1D area of a buffer and place it in a user-supplied array.
Syntax
void MbufGet1d(
MIL_ID SrcBufId,
long OffX,
long SizeX,
void *UserArrayPtr
)
Description

This function copies data from a specified one-dimensional area of a MIL source buffer to a user-supplied array.

Note, for multi-band buffers, this function linearly copies the data from the one-dimensional region of each band (RRR...GGG...BBB...).

Parameters
SrcBufId

Specifies the identifier of the source buffer.

OffX

Specifies the horizontal offset of the required area, relative to the top-left coordinate of the source buffer.

SizeX

Specifies the width of the required area of the source buffer.

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array in which to copy the data from the source buffer. Ensure that the user array is large enough to accommodate the data to be copied from the source buffer. MbufGet1d() assumes that the array is of the same data type as the source buffer.


MbufGet2d

See Also | Example | Availability | MbufGet1d | MbufGet
User Guide:
Managing data buffers

Reference:
mimsegment.c
Available in MIL-Lite

Available in MIL
Synopsis
Get data from a 2d area of a buffer and place it in a user-supplied array.
Syntax
void MbufGet2d(
MIL_ID SrcBufId,
long OffX,
long OffY,
long SizeX,
long SizeY,
void *UserArrayPtr
)
Description

This function copies data from a specified two-dimensional region of a MIL source buffer to a user-supplied array.

Note, for multi-band buffers, this function linearly copies the data from the specified two-dimensional region of each band (RRR...GGG...BBB...).

Parameters
SrcBufId

Specifies the identifier of the source buffer.

OffX

Specifies the horizontal offset of the required area, relative to the top-left coordinate of the source buffer.

OffY

Specifies the vertical offset of the required area, relative to the top-left coordinate of the source buffer.

SizeX

Specifies the width of the required area of the source buffer.

SizeY

Specifies the height of the required area of the source buffer.

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array in which to copy the data from the source buffer. Ensure that the user array is large enough to accommodate the data to be copied. MbufGet2d() assumes that the array is of the same data type and depth as the source buffer.


MbufGet

See Also | Example | Availability | MbufGet2d | MbufGetArc
User Guide:
Managing data buffers
Accessing a MIL buffer directly
Multi-threading

Reference:
MbufGetColor
dtkobjecttracking.c
mbufbayercolorfilter.c
mgrabbayer.c
Available in MIL-Lite

Available in MIL
Synopsis
Get data from a buffer and place it in a user-supplied array.
Syntax
void MbufGet(
MIL_ID SrcBufId,
void *UserArrayPtr
)
Description

This function copies data from a specified MIL source buffer to a user-supplied array.

Note, for multi-band buffers, MbufGet() behaves like MbufGetColor() with its DataFormat parameter set to M_PLANAR, and its Band parameter set to M_ALL_BANDS. Refer to MbufGetColor() for more details.

Parameters
SrcBufId

Specifies the identifier of the source buffer.

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array in which to copy source buffer data. Ensure that the user array is large enough to accommodate the data from the source buffer. MbufGet() assumes that the array is of the same data type and depth as the source buffer's bands.

Remark
  • This function is optimized for packed binary buffers.
PLANAR ALL BANDS


MbufGetArc

See Also | Example | Availability | MbufGet | MbufGetColor2d
Reference:
There are no examples containing MbufGetArc().
Available in MIL-Lite

Available in MIL
Synopsis
Read the pixels along a specified arc and store their values in a user-defined array.
Syntax
void MbufGetArc(
MIL_ID ImageBufId,
long XCenter,
long YCenter,
long XRad,
long YRad,
long StartAngle,
long EndAngle,
long *NbPixelsPtr,
void *UserArrayPtr
)
Description

This function reads the series of pixels along an elliptic arc from an image and stores their values in a user-defined array. The ellipse is centered at (XCenter, YCenter) with radii XRad and YRad and is defined by the start angle StartAngle and the end angle EndAngle.

Note, if the source buffer is compressed, the data is decompressed before it is copied to the destination array.

Parameters
ImageBufId

Specifies the identifier of the source image buffer.

XCenter

Specifies the X-coordinate of the ellipse center, relative to the top-left coordinate of the source buffer.

YCenter

Specifies the Y-coordinate of the ellipse center, relative to the top-left coordinate of the source buffer.

XRad

Specifies the radius along the X-axis. The radius should be given in pixels and must be greater than 0.

YRad

Specifies the radius along the Y-axis. The radius should be given in pixels and must be greater than 0.

StartAngle

Specifies the angle at which to start reading the arc, moving in a counter-clockwise direction. Express the angle in degrees relative to the positive X-axis.

EndAngle

Specifies the angle at which to stop reading the arc, moving in a counter-clockwise direction. Express the angle in degrees relative to the positive X-axis.

NbPixelsPtr

Specifies the address of the variable in which to write the number of pixels found along the arc.

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array in which to store the pixels from the image buffer. Ensure that the user array is large enough to accommodate the data to be stored. MbufGetArc() assumes that the array is of the same data type and depth as the source buffer. To determine the required size of the array, you can set this parameter to M_NULL and pass a non-null address to NbPixelsPtr, which will store the value of the required size of the array. In this case, nothing is read from the image buffer.


MbufGetColor2d

Example | Availability | MbufGetArc | MbufGetColor
There are no examples containing MbufGetColor2d().
Available in MIL-Lite

Available in MIL
Synopsis
Get data from a region of one or all bands of a buffer and place it in a user-supplied array.
Syntax
void MbufGetColor2d(
MIL_ID SrcBufId,
long DataFormat,
long Band,
long OffX,
long OffY,
long SizeX,
long SizeY,
void *UserArrayPtr
)
Description

This function copies data from a specific region of one or all color bands of a specified MIL source buffer to a user-supplied array.

Parameters
SrcBufId

Specifies the identifier of the source buffer.

DataFormat

Specifies the data format to use to save the data in the user array. The internal data format of the source buffer need not match the specified data format of the user-supplied array; an internal conversion will be performed if necessary. Note, however, if the formats do match, the operation will be much faster.

This parameter must be set to one of the following values. Note that Sx and Sy denote the source width and height, respectively.

Unless otherwise specified, the following values require that you pass the UserArrayPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_PACKED | Copies the bands in an interleaved manner (for example, RGB RGB RGB ...). Copies the bands in an interleaved manner (for example, RGB RGB RGB ... M_PACKED must be used in combination with other values (see table below).
Open Collapse M_PLANAR | Copies the bands one after the other (for example, RRR...GGG...BBB...). This format is to be used when copying from all color bands of the source buffer. Copies the bands one after the other (for example, RRR...GGG...BBB...) ...
 |  | UserArrayPtr info Data type: array of the same type as the buffer Array size: Sx x Sy x number of color bands of the source buffer
Open Collapse M_SINGLE_BAND | Copies a single color band. Copies a single color band ...
 |  | UserArrayPtr info Data type: array of the same type as the buffer Array size: Sx x Sy

[Combination constants]

The values below must be added to M_PACKED. Note that the source buffer must be a three-band, 8-bit bit buffer.

Open Collapse Value | Description
Open Collapse M_BGR24 | Stores the data into a BGR24 packed format. In this format, each pixel is internally stored as three consecutive bytes in little-endian order (BGRBGR). Stores the data into a BGR24 packed format ...
 |  | UserArrayPtr info Data type: array of type char Array size: Sx x Sy x 3 bytes (char)
Open Collapse M_BGR32 | Stores the data into a BGR32 packed format. In this format, each pixel is internally stored as four consecutive bytes, in little-endian order (BGRXBGRX). The most-significant byte is a "don't care" byte. Stores the data into a BGR32 packed format ...
 |  | UserArrayPtr info Data type: array of type long Array size: Sx x Sy x 4 bytes (long)
Open Collapse M_RGB15 | Stores the data into a RGB15 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 5-bit green value, a 5-bit red value, and a "don't care" bit (most significant), in little-endian order (RGB 5:5:5). Stores the data into a RGB15 packed format ...
 |  | UserArrayPtr info Data type: array of type unsigned char Array size: Sx x Sy x 2 bytes (unsigned char)
Open Collapse M_RGB16 | Stores the data into a RGB16 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 6-bit green value, and a 5-bit red value (most significant), in little-endian order (RGB 5:6:5). Stores the data into a RGB16 packed format ...
 |  | UserArrayPtr info Data type: array of type unsigned char Array size: Sx x Sy x 2 bytes (unsigned char)
Band

Specifies the index of the color band to copy. This parameter can be set to one of the values below.

Open Collapse Value Description
Open Collapse 0 <= Value <= #bands - 1

 Specifies the index of the band to copy.  Specifies the index of the band to copy ...

 The relationship between index value and band for RGB and HLS buffers is the following:

0 | Corresponds to the red band for RGB buffers or the hue band for HLS buffers.
1 | Corresponds to the green band for RGB buffers or the saturation band for HLS buffers.
2 | Corresponds to the blue band for RGB buffers or the luminance band for HLS buffers.

  Open   Collapse  M_ALL_BANDS

 Copies from all color bands.  Copies from all color bands.

  Open   Collapse  M_BLUE

 Copies from the blue color band (for RGB buffers).  Copies from the blue color band (for RGB buffers).

  Open   Collapse  M_GREEN

 Copies from the green color band (for RGB buffers).  Copies from the green color band (for RGB buffers).

  Open   Collapse  M_HUE

 Copies from the hue color band (for HLS buffers).  Copies from the hue color band (for HLS buffers).

  Open   Collapse  M_LUMINANCE

 Copies from the luminance color band (for HLS buffers).  Copies from the luminance color band (for HLS buffers).

  Open   Collapse  M_RED

 Copies from the red color band (for RGB buffers).  Copies from the red color band (for RGB buffers).

  Open   Collapse  M_SATURATION

 Copies from the saturation color band (for HLS buffers).  Copies from the saturation color band (for HLS buffers).

 OffX

 Specifies the horizontal offset (relative to the top-left source buffer coordinate) of the source buffer region from which to get the data.

 OffY

 Specifies the vertical pixel offset (relative to the top-left source buffer coordinate) of the source buffer region in which to get the data.

 SizeX

 Specifies the width of the source buffer region from which to get the data.

 SizeY

 Specifies the height of the source buffer region from which to get the data.

 UserArrayPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type char
    •

  • array of type unsigned char
    •

  • array of type long
    •

  • array of the same type as the buffer
    •

  • long
    •

 Specifies the address of the user array from which to copy the data.  Ensure that there are enough entries in the user array to receive the data of the specified source buffer region.

PACKED PACKED   PACKED PLANAR SINGLE BAND BGR24 BGR32 RGB15 RGB16  ALL BANDS BLUE GREEN HUE LUMINANCE RED SATURATION


MbufGetColor

Example | Availability | MbufGetColor2d | MbufGetHookInfo
There are no examples containing MbufGetColor().
Available in MIL-Lite

Available in MIL
Synopsis
Get data from one or all bands of a buffer and place it in a user-supplied array.
Syntax
void MbufGetColor(
MIL_ID SrcBufId,
long DataFormat,
long Band,
void *UserArrayPtr
)
Description

This function copies data from one or all color bands of a specified MIL source buffer to a user-supplied array.

Parameters
SrcBufId

Specifies the identifier of the source buffer.

DataFormat

Specifies the data format to use to save the data in the user array. The internal data format of the source buffer need not match the specified data format; an internal conversion will be performed if necessary. Note, however, if the formats do match, the operation will be much faster.

This parameter must be set to one of the following values. Note that Sx and Sy denote the source width and height, respectively.

Unless otherwise specified, the following values require that you pass the UserArrayPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_PACKED | Copies buffer bands in an interleaved manner and stores them consecutively (for example, RGB RGB RGB ...). Copies buffer bands in an interleaved manner and stores them consecutively (for example, RGB RGB RGB ...) ... M_PACKED must be used in combination with other values (see table below).
Open Collapse M_PLANAR | Copies the bands one after the other (for example, RRR...GGG...BBB...). This format is to be used when copying all color bands of the source buffer. Copies the bands one after the other (for example, RRR...GGG...BBB...) ...
 |  | UserArrayPtr info Data type: array of the same type as the buffer Array size: Sx x Sy x number of color bands of the source buffer
Open Collapse M_SINGLE_BAND | Copies a single color band. Copies a single color band ...
 |  | UserArrayPtr info Data type: array of the same type as the buffer Array size: Sx x Sy

[Combination constants]

The values below must be added to M_PACKED. Note that the source buffer must be a three-band, 8-bit bit buffer.

Open Collapse Value | Description
Open Collapse M_BGR24 | Stores the data into a BGR24 packed format. In this format, each pixel is internally stored as three consecutive bytes in little-endian order (BGRBGR). Stores the data into a BGR24 packed format ...
 |  | UserArrayPtr info Data type: array of type char Array size: Sx x Sy x 3 bytes (char)
Open Collapse M_BGR32 | Stores the data into a BGR32 packed format. In this format, each pixel is internally stored as four consecutive bytes, in little-endian order (BGRXBGRX). The most-significant byte is a "don't care" byte. Stores the data into a BGR32 packed format ...
 |  | UserArrayPtr info Data type: array of type long Array size: Sx x Sy x 4 bytes (long)
Open Collapse M_RGB15 | Stores the data into a RGB15 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 5-bit green value, a 5-bit red value, and a "don't care" bit (most significant), in little-endian order (RGB 5:5:5). Stores the data into a RGB15 packed format ...
 |  | UserArrayPtr info Data type: array of type unsigned char Array size: Sx x Sy x 2 bytes (unsigned char)
Open Collapse M_RGB16 | Stores the data into a RGB16 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 6-bit green value, and a 5-bit red value (most significant), in little-endian order (RGB 5:6:5). Stores the data into a RGB16 packed format ...
 |  | UserArrayPtr info Data type: array of type unsigned char Array size: Sx x Sy x 2 bytes (unsigned char)
Band

Specifies the index of the color band to copy. This parameter can be set to one of the values below.

Open Collapse Value Description
Open Collapse 0 <= Value <= #bands - 1

 Specifies the index of the band to copy.  Specifies the index of the band to copy ...

 The relationship between index value and band for RGB and HLS buffers is the following:

0 | Corresponds to the red band for RGB buffers or the hue band for HLS buffers.
1 | Corresponds to the green band for RGB buffers or the saturation band for HLS buffers.
2 | Corresponds to the blue band for RGB buffers or the luminance band for HLS buffers.

  Open   Collapse  M_ALL_BANDS

 Copies from all color bands.  Copies from all color bands.

  Open   Collapse  M_BLUE

 Copies from the blue color band (for RGB buffers).  Copies from the blue color band (for RGB buffers).

  Open   Collapse  M_GREEN

 Copies from the green color band (for RGB buffers).  Copies from the green color band (for RGB buffers).

  Open   Collapse  M_HUE

 Copies from the hue color band (for HLS buffers).  Copies from the hue color band (for HLS buffers).

  Open   Collapse  M_LUMINANCE

 Copies from the luminance color band (for HLS buffers).  Copies from the luminance color band (for HLS buffers).

  Open   Collapse  M_RED

 Copies from the red color band (for RGB buffers).  Copies from the red color band (for RGB buffers).

  Open   Collapse  M_SATURATION

 Copies from the saturation color band (for HLS buffers).  Copies from the saturation color band (for HLS buffers).

 UserArrayPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type char
    •

  • array of type unsigned char
    •

  • array of type long
    •

  • array of the same type as the buffer
    •

  • long
    •

 Specifies the address of the user array in which to copy data from the source buffer.  Ensure that the user array is large enough to accommodate the data from the source buffer in the data type and depth specified.

Remark

  •  This function is optimized for packed binary buffers.
    •

PACKED PACKED   PACKED PLANAR SINGLE BAND BGR24 BGR32 RGB15 RGB16  ALL BANDS BLUE GREEN HUE LUMINANCE RED SATURATION


MbufGetHookInfo

See Also | Example | Availability | MbufGetColor | MbufGetLine
Reference:
MbufHookFunction
There are no examples containing MbufGetHookInfo().
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Synopsis
Get information about a hook event.
Syntax
long MbufGetHookInfo(
MIL_ID EventId,
long InfoType,
void *UserVarPtr
)
Description

This function allows you to get information about the event that caused the hook handler function to be called. MbufGetHookInfo() should only be called within the scope of a buffer hook-handler function (see MbufHookFunction()).

Parameters
EventId

Specifies the buffer event identifier received by the hook-handler function (see MbufHookFunction()).

InfoType

Specifies a combination of two values: the event type and the type of information about the event to return.

Set this parameter to the following event type:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_MODIFIED_BUFFER | Identifies a modified buffer type of event. This event occurs if the hook-handler function was hooked using MbufHookFunction() with M_MODIFIED_BUFFER, or you can inquire about this type of event. See combination values below to specify the type of information to be returned. Identifies a modified buffer type of event ...
 |  | UserVarPtr info Data type: MIL_ID

[Combination constants]

You must combine one of the following values with M_MODIFIED_BUFFER to specify the type of information to return.

Open Collapse Value | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_BUFFER_ID | Returns the MIL identifier of the modified buffer. Returns the MIL identifier of the modified buffer ... |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
 |  | UserVarPtr info Data type: MIL_ID
Open Collapse M_GRAB_TIME_STAMP | Returns the time the event generated service request, in secs. The time can be used to see if a frame has been missed since the last time stamp. Returns the time the event generated service request, in secs ... |  |  |  |  | d | e | f |  |  |  |  |  | l | m | n | o |  | q | r
 |  | UserVarPtr info Data type: double
Open Collapse M_REGION_OFFSET_X | Returns the X-offset of the modified region (of the buffer). Returns the X-offset of the modified region (of the buffer). |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_REGION_OFFSET_Y | Returns the Y-offset of the modified region (of the buffer). Returns the Y-offset of the modified region (of the buffer). |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_REGION_SIZE_X | Returns the width of the modified region (of the buffer). Returns the width of the modified region (of the buffer). |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
Open Collapse M_REGION_SIZE_Y | Returns the height of the modified region (of the buffer). Returns the height of the modified region (of the buffer). |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • double
  • long
  • MIL_ID

Specifies the address in which to write the requested information.

Return value
Returns null (M_NULL) on success, and returns a non-null (!M_NULL) value on failure, without logging any errors in the application.
MODIFIED BUFFER MODIFIED BUFFER MODIFIED BUFFER BUFFER ID GRAB TIME STAMP REGION OFFSET X REGION OFFSET Y REGION SIZE X REGION SIZE Y


MbufGetLine

Example | Availability | MbufGetHookInfo | MbufHookFunction
There are no examples containing MbufGetLine().
Available in MIL-Lite

Available in MIL
Synopsis
Read the pixels along a specified theoretical line, count the pixels, and store their values in a user-defined array.
Syntax
void MbufGetLine(
MIL_ID ImageBufId,
long StartX,
long StartY,
long EndX,
long EndY,
long Mode,
long *NbPixelsPtr,
void *UserArrayPtr
)
Description

This function reads the series of pixels along a theoretical line (defined by coordinates) from an image and stores their values in a user-defined array. The Bresenham algorithm is used to determine the theoretical line.

Parameters
ImageBufId

Specifies the identifier of the source image buffer. This must be a single-band (monochrome) buffer.

StartX

Specifies the horizontal pixel offset of the starting position of the line, relative to the top-left pixel of the source buffer.

StartY

Specifies the vertical pixel offset of the starting position of the line, relative to the top-left pixel of the source buffer.

EndX

Specifies the horizontal pixel offset of the finishing position of the line, relative to the top-left pixel of the source buffer.

EndY

Specifies the vertical pixel offset of the finishing position of the line, relative to the top-left pixel of the source buffer.

Mode

Specifies the operation mode. This parameter must be set to M_DEFAULT.

NbPixelsPtr

Specifies the address of the variable in which to write the number of pixels found along the theoretical line. You can set this parameter to M_NULL if you don't want this value to be evaluated.

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array in which to store the pixels from the image buffer. Ensure that the user array is large enough to accommodate the data to be stored. To determine the required size of the array, you can set this parameter to M_NULL and pass a non-null address to NbPixelsPtr. In this case, nothing is read from the image buffer.


MbufHookFunction

See Also | Example | Availability | MbufGetLine | MbufImport
Reference:
MbufGetHookInfo
dtkobjecttracking.c
Available in MIL-Lite

Available in MIL
Synopsis
Hook a function to a buffer event.
Syntax
void MbufHookFunction(
MIL_ID BufferId,
long HookType,
MBUFHOOKFCTPTR HookHandlerPtr,
void *UserDataPtr
)
Description

This function allows you to attach or detach a user-defined function to a specified buffer event (for example, a modification to the buffer's contents). Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.

You can hook more than one function to an event by making separate calls to MbufHookFunction() for each function that you want to hook. MIL automatically chains and keeps an internal list of all these hooked functions. When a function is hooked, this new function is added to the end of the list. When the event happens, all user-defined functions in the list will be executed in the same order that they were hooked to the event. You can also remove any function from the list; in this case, MIL preserves the order of the remaining functions in the list.

Parameters
BufferId

Specifies the identifier of the buffer.

HookType

Specifies the buffer event to which to hook the function. This parameter can be set to following value:

Open Collapse Value Description
Open Collapse M_MODIFIED_BUFFER

 Calls the hook-handler function each time the specified buffer is modified by a MIL function.  Calls the hook-handler function each time the specified buffer is modified by a MIL function.

      [Combination constants]

 The value below can be added to M_MODIFIED_BUFFER.

  Open   Collapse  Value
Description

  Open   Collapse  M_UNHOOK

 Unhooks the specified function if hooked to an M_MODIFIED_BUFFER event.  Unhooks the specified function if hooked to an M_MODIFIED_BUFFER event.

 HookHandlerPtr

 Specifies the address of the function that should be called when the specified event occurs.  The hook-handler function must be declared as follows:

 Upon successful completion, the hook-handler function should return M_NULL. Note MFTYPE and MBUFHOOKFCTPTR are reserved MIL predefined types for functions and data pointers.

long MFTYPE HookHandler(
long HookType,

MIL_ID EventId,

void *UserDataPtr

        )

HookType

 Type of buffer event that generated the call.

EventId

 Event identifier to pass to MbufGetHookInfo() when inquiring about the hooked event.

UserDataPtr

 User data pointer that was passed (as UserDataPtr) to MbufHookFunction().

 UserDataPtr

 Specifies the address of the user data that you want to make available to the hook-handler function.  This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.

MODIFIED BUFFER MODIFIED BUFFER   MODIFIED BUFFER UNHOOK


MbufImport

See Also | Example | Availability | MbufHookFunction | MbufImportSequence
User Guide:
Managing data buffers
Managing color images
General steps

Reference:
MappGetError
MbufDiskInquire
MbufInquire
MbufLoad
MbufRestore
MdispLut
MsysAlloc
There are no examples containing MbufImport().
Available in MIL-Lite with restrictions (see remarks)

Available in MIL
Synopsis
Import data from a file into a data buffer.
Syntax
MIL_ID MbufImport (
MIL_TEXT_PTR FileName,
long FileFormat,
long Operation,
MIL_ID SystemId,
MIL_ID *BufIdPtr
)
Description

This function imports data from a file into an existing or automatically allocated MIL data buffer. The function assumes that the data in the file is in the specified format.

Note, you can also import data using MbufLoad() or MbufRestore(); however, these functions try to determine the format from the data rather than allowing you to specify the format.

For an M_RESTORE operation, this function will allocate the destination buffer with the same attributes as the original buffer, with the exception of an M_IMAGE buffer. In the case of an M_IMAGE buffer, the MbufImport() function tries to allocate the buffer so that it can be used for acquisition (M_GRAB), display (M_DISP), and processing (M_PROC) operations. If there is insufficient appropriate memory to allocate such a buffer, it allocates one that can be used in all of the above operations except for acquisition (M_GRAB). Note that the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of MIL non-paged (DMA) memory (specified at installation time or using MilConfig). For systems with on-board processors, the total number of M_GRAB buffers and M_PROC buffers is limited by the amount of on-board memory.

[MIL-Lite with restriction]

When performing an M_RESTORE operation on a file containing compressed data, the buffer will have an M_COMPRESS attribute.

[MIL-Lite with restriction]

When importing compressed data, the following applies. When performing an M_LOAD operation and the destination buffer has an M_IMAGE attribute (but not an M_COMPRESS attribute), this function will automatically decompress it. If necessary, the data in the file will be transformed to the format of the buffer. If unsure of the compression type of the data, use M_DEFAULT as the file format rather than M_JPEG_... or M_JPEG2000_...; the data will be read correctly.

[MIL-Lite with restriction]

When importing uncompressed data into a buffer with an M_COMPRESS attribute, this function will automatically compress it, according to the compression settings found in the buffer.

When importing an image file that has been saved with an associated LUT (color palette) into a 3-band 8-bit image buffer, the LUT is automatically applied to the data to generate 3-band image data. In this case, a LUT buffer is not created and, therefore, is not associated to the 3-band 8-bit buffer. When importing an image file that has been saved with an associated LUT (color palette) into any other type of image buffer, the LUT is also imported and associated with the resulting image buffer. You can obtain the identifier of the associated LUT, using MbufInquire().

Note that the associated LUT will be automatically selected on the display (MdispLut()) if the image buffer is selected on a display and the default LUT has not been overidden by a former call to MdispLut().

Using MbufDiskInquire(), you can inquire about the dimensions of the data saved in a file (except for raw files) without importing it.

After restoring a buffer, we recommend that you check if the operation was successful, using MappGetError(), or by verifying that the returned buffer identifier is not M_NULL.

Parameters
FileName

Specifies the name and path of the file from which to get the data. The function handles the opening and closing of the file.

FileFormat

Specifies the file format. This parameter can be set to one of the following values. Note that except for the M_MIL and M_RAW file formats, data is treated as image data. When performing an M_LOAD operation, the data is internally converted appropriately.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that MIL automatically determines the file format. If the file format is not supported, its data will be treated as raw data.  Specifies that MIL automatically determines the file format ...

  Open   Collapse  M_BMP

 Imports image data that is in BMP file format. The standard Windows BMP format is used.  Imports image data that is in BMP file format ...

  Open   Collapse  M_JPEG_LOSSLESS

MIL-lite with restriction (see remarks).

 Imports a JPEG lossless image.  Imports a JPEG lossless image.

  Open   Collapse  M_JPEG2000_LOSSLESS

MIL-lite with restriction (see remarks).

 Imports a JPEG2000 lossless image.  Imports a JPEG2000 lossless image.

  Open   Collapse  M_JPEG_LOSSLESS_INTERLACED

MIL-lite with restriction (see remarks).

 Imports a JPEG lossless image stored in two separate fields.  Imports a JPEG lossless image stored in two separate fields.

  Open   Collapse  M_JPEG2000_LOSSLESS_JP2

MIL-lite with restriction (see remarks).

 Imports a JPEG2000 lossless image, as well as the additional JP2 information.  Imports a JPEG2000 lossless image, as well as the additional JP2 information.

  Open   Collapse  M_JPEG_LOSSY

MIL-lite with restriction (see remarks).

 Imports a JPEG lossy image.  Imports a JPEG lossy image.

  Open   Collapse  M_JPEG2000_LOSSY

MIL-lite with restriction (see remarks).

 Imports a JPEG2000 lossy image.  Imports a JPEG2000 lossy image.

  Open   Collapse  M_JPEG_LOSSY_INTERLACED

MIL-lite with restriction (see remarks).

 Imports a JPEG lossy image stored in two separate fields.  Imports a JPEG lossy image stored in two separate fields.

  Open   Collapse  M_JPEG2000_LOSSY_JP2

MIL-lite with restriction (see remarks).

 Imports a JPEG2000 lossy image, as well as the additional JP2 information.  Imports a JPEG2000 lossy image, as well as the additional JP2 information.

  Open   Collapse  M_JPEG_LOSSY_RGB

MIL-lite with restriction (see remarks).

 Imports a 3-band JPEG lossy image that is in an RGB format.  Imports a 3-band JPEG lossy image that is in an RGB format.

  Open   Collapse  M_MIL

 Imports data that is in a MIL file format. The baseline TIFF 6.0 specification is used.  Imports data that is in a MIL file format ...

  Open   Collapse  M_RAW

 Imports raw data.  Imports raw data.

  Open   Collapse  M_TIFF

 Imports image data that is in a TIFF file format. The baseline TIFF 6.0 specification is used.  Imports image data that is in a TIFF file format ...

 Only image formats, data types, and depths that are supported by MIL buffers will be accepted.

 Multi-page TIFF files can be imported into MIL buffers but only the first page is saved in the buffer. In addition, MIL only supports uncompressed TIFF files.

 Operation

 Specifies the import operation.  This parameter can be set to one of the following values.

  Open   Collapse  Value
Description

  Open   Collapse  M_LOAD

 Imports data from the specified file into a previously allocated MIL data buffer.  Imports data from the specified file into a previously allocated MIL data buffer.

  Open   Collapse  M_RESTORE

 Imports data from the specified file into an automatically allocated MIL data buffer. Note, you cannot restore (M_RESTORE) a RAW data file (M_RAW) because its dimensions are unknown.  Imports data from the specified file into an automatically allocated MIL data buffer ...

 SystemId

 Specifies the system on which to allocate the buffer for an M_RESTORE operation. For an M_LOAD operation, this parameter should be set to M_NULL.

 For an M_RESTORE operation, this parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 BufIdPtr

 Specifies the address of the variable containing the buffer identifier, for an M_LOAD operation, or the address of the variable in which to store the new buffer identifier, for an M_RESTORE operation.

 For an M_LOAD operation, the destination buffer must be large enough in depth and dimensions to hold the data. If the data is deeper than the buffer, the most-significant bits of the data are truncated when loaded into the buffer. If the buffer depth is greater than that of the data, the data is zero or sign-extended (depending on the data type) when loaded into the buffer. If the buffer is larger in size than the data, exceeding areas of the buffer are unaffected.

 For an M_RESTORE operation, the destination buffer will be allocated with an appropriate size and type to hold the data. Since MbufImport() also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the buffer identifier (for an M_RESTORE operation only). If allocation fails, M_NULL is returned.

Remark

  •  Note that MIL-Lite compression support, particularly for M_IMAGE + M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

RESTORE IMAGE IMAGE GRAB DISP PROC GRAB GRAB GRAB PROC RESTORE COMPRESS LOAD IMAGE COMPRESS DEFAULT COMPRESS MIL RAW LOAD RESTORE RAW RESTORE LOAD RESTORE LOAD RESTORE LOAD RESTORE RESTORE IMAGE COMPRESS   DEFAULT BMP JPEG LOSSLESS
                 JPEG2000 LOSSLESS JPEG LOSSLESS INTERLACED JPEG2000 LOSSLESS JP2 JPEG LOSSY
                 JPEG2000 LOSSY
                 JPEG LOSSY INTERLACED
                 JPEG2000 LOSSY JP2 JPEG LOSSY RGB
                 MIL RAW TIFF  LOAD  RESTORE   DEFAULT HOST


MbufImportSequence

See Also | Example | Availability | MbufImport | MbufInquire
User Guide:
Managing data buffers
Grabbing a sequence of frames in real-time
General steps

Reference:
MbufDiskInquire
MsysAlloc
mdiggrabsequence.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL
Synopsis
Import a sequence of images from an AVI file into separate image buffers.
Syntax
void MbufImportSequence(
MIL_TEXT_PTR FileName,
long FileFormat,
long Operation,
MIL_ID SystemId,
MIL_ID *BufArrayPtr,
long StartImage,
long NumberOfImages,
long ControlFlag
)
Description

This function imports a sequence of images from an AVI file into separate image buffers. MbufImportSequence() can automatically allocate the necessary buffers or you can use previously allocated buffers. In the latter case, the BufArrayPtr parameter should point to an array containing the buffer identifiers. In the former case, MbufImportSequence() will write the identifiers of the new buffers into the array pointed to by BufArrayPtr.

Rather than importing all the required images at once, you can also use this function to only open the AVI file for reading. Then, call this function as many times as required to import different sets of images from the file. Once you have finished importing images from the file, you must call this function again to close the file.

Parameters
FileName

Specifies the name and path of the AVI file. This function handles the opening and/or closing of the file, depending on the ControlFlag parameter setting.

FileFormat

Specifies the format of the file. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that MIL automatically determines the file format.  Specifies that MIL automatically determines the file format.

  Open   Collapse  M_AVI_DIB

 Specifies an AVI format containing non-compressed images.  Specifies an AVI format containing non-compressed images.

  Open   Collapse  M_AVI_MIL

 Specifies an AVI format containing images in their MIL format.  Specifies an AVI format containing images in their MIL format.

  Open   Collapse  M_AVI_MJPG

 Specifies an AVI format containing compressed images.  Specifies an AVI format containing compressed images.

 Operation

 Specifies whether to import the specified sequence of images into automatically allocated buffers or previously allocated buffers.  If not importing images, this parameter should be set to M_NULL.

 When importing images, this parameter can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_LOAD

 Imports the sequence into previously allocated buffers.  Imports the sequence into previously allocated buffers.

  Open   Collapse  M_RESTORE

 Imports the sequence into automatically allocated buffers.  Imports the sequence into automatically allocated buffers.

 SystemId

 Specifies the system on which to allocate the buffers for an M_RESTORE operation. In other cases, this parameter should be set to M_NULL.

 For an M_RESTORE operation, this parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 BufArrayPtr

 Specifies the address of the array containing the buffer identifiers for an M_LOAD operation, or the address of the array in which to store the new buffer identifiers for an M_RESTORE operation.  If not importing images, this parameter should be set to M_NULL.

 For an M_LOAD operation, the destination buffers should be large enough to hold the imported images.

 For an M_RESTORE operation, the destination buffers will be allocated with an appropriate size and type to hold the images. If an M_RESTORE operation fails, zero will be written for the buffer identifiers.

[MIL-Lite with restriction]

 When importing compressed images with the M_LOAD operation, if the destination buffers have only an M_IMAGE attribute, the images will automatically be decompressed. When importing uncompressed images with the M_LOAD operation, if the destination buffers have an M_IMAGE + M_COMPRESS attribute, the images will automatically be compressed.

 When importing compressed images with the M_RESTORE operation, the M_COMPRESS attribute will automatically be added to the destination buffer (M_IMAGE + M_COMPRESS) and the images will remain compressed in the destination buffer.

 StartImage

 Specifies the frame number of the image from which to begin importing.  If not importing images, this parameter should be set to M_NULL.

 When importing images, note that the frame number of the first image in the sequence is zero. To import the image at the current read position, set StartImage to M_DEFAULT.

 NumberOfImages

 Specifies the number of images, starting at StartImage, to import.  If not importing images, this parameter should be set to M_NULL.

 When importing images, this number cannot be larger than the size of the array pointed to by BufArrayPtr. Note that you can inquire about the number of frames (images) in the AVI file using MbufDiskInquire().

 ControlFlag

 Specifies the function's control flag.  This parameter must be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Opens the AVI file, imports the specified images, and then closes the file.  Opens the AVI file, imports the specified images, and then closes the file.

  Open   Collapse  M_CLOSE

 Closes the AVI file, and (re)sets the pointer position to the first image. No images are imported.  Closes the AVI file, and (re)sets the pointer position to the first image ...

  Open   Collapse  M_OPEN

 Opens the AVI file for reading, and sets the pointer to the first image. No images are imported.  Opens the AVI file for reading, and sets the pointer to the first image ...

  Open   Collapse  M_READ

 Imports the specified images from the AVI file, starting at the specified StartImage position. After the importing the images, the file pointer is left at the position of the next image, ready for the next M_READ operation.  Imports the specified images from the AVI file, starting at the specified StartImage position ...

Remark

  •  Note that MIL-Lite compression support, particularly for M_AVI_MJPG format and M_IMAGE + M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

RESTORE RESTORE LOAD RESTORE LOAD RESTORE RESTORE LOAD IMAGE LOAD IMAGE COMPRESS RESTORE COMPRESS IMAGE COMPRESS READ AVI MJPG IMAGE COMPRESS   DEFAULT AVI DIB AVI MIL AVI MJPG  LOAD RESTORE  DEFAULT HOST      DEFAULT CLOSE OPEN READ


MbufInquire

See Also | Example | Availability | MbufImportSequence | MbufLoad
User Guide:
Managing data buffers
Accessing a MIL buffer directly
Mapping a data buffer to user-allocated memory
Buffer overscan region
Annotating the displayed image non-destructively
JPEG2000
Working with tables

Reference:
MbufAllocColor
MbufControl
MbufControlNeighborhood
MbufCreate2d
MbufCreateColor
MbufImport
MsysInquire
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
dtkaddconstantpamaster.c
dtkremap.c
mblob.c
mdblgrab.c
mdigautofocus.c
mdispoverlay.c
mdispwindowleveling.c
mfunc.c
mgrabbayer.c
mimpolar.c
mimwarp.c
mmodeltracking.c
mmorphisjpeg2000.c
mnatfct.c
mnatgen.c
mpat.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Inquire about a MIL data buffer setting.
Syntax
long MbufInquire(
MIL_ID BufId,
long InquireType,
void *UserVarPtr
)
Description

This function inquires about a specified setting of a MIL data buffer.

Parameters
BufId

Specifies the identifier of the source data buffer. The buffer must have been previously allocated on the required system using a function of the buffer module (for example, MbufAllocColor() or MbufImport()).

InquireType

Specifies the type of buffer setting about which to inquire. This parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_ALLOCATION_OVERSCAN_SIZE

Returns the size of the overscan region of the image buffer, in pixels. Returns the size of the overscan region of the image buffer, in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_ANCESTOR_ID

Returns the MIL identifier of the ancestor buffer. Only child buffers have an ancestor buffer. The ancestor buffer is the buffer from which the specified buffer (BufId) ultimately originated. It is the root buffer; it does not have a parent buffer (it is not a child buffer of another buffer). Note that the identifier of the specified buffer is returned if it does not have an ancestor buffer. Returns the MIL identifier of the ancestor buffer ...

To establish the parent buffer of the specified buffer, use M_PARENT_ID instead.

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: MIL_ID
Open Collapse M_ANCESTOR_OFFSET_BAND

Returns the band offset relative to the ancestor buffer. Returns the band offset relative to the ancestor buffer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_ANCESTOR_OFFSET_BIT

Returns the bit offset relative to the ancestor buffer. Returns the bit offset relative to the ancestor buffer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_ANCESTOR_OFFSET_X

Returns the X-offset relative to the ancestor buffer. Returns the X-offset relative to the ancestor buffer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_ANCESTOR_OFFSET_Y

Returns the Y-offset relative to the ancestor buffer. Returns the Y-offset relative to the ancestor buffer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_ASSOCIATED_LUT

Returns the identifier of the LUT buffer associated with the image buffer (returns M_DEFAULT if no LUT). Returns the identifier of the LUT buffer associated with the image buffer (returns M_DEFAULT if no LUT) ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: MIL_ID

Return values:
M_DEFAULT, MIL LUT buffer identifier (details)
Open Collapse M_BITMAPINFO

Returns a pointer (LPBITMAPINFO) to the header of the DIB associated with the MIL buffer (if any) or M_NULL. Returns a pointer (LPBITMAPINFO) to the header of the DIB associated with the MIL buffer (if any) or M_NULL.

a b c d e f g h i j k l m n o p q r
Open Collapse M_DATA_FORMAT

Returns the color or monochrome storage format of the buffer. This includes whether it is packed or planar format. Note that to retrieve the entire list of attributes, use MbufInquire() with M_EXTENDED_ATTRIBUTE or M_EXTENDED_FORMAT. Returns the color or monochrome storage format of the buffer ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_DC_HANDLE

Returns the device context handle (HDC) of the buffer. The buffer device context must have been successfully allocated using MbufControl() with M_DC_ALLOC. Returns the device context handle (HDC) of the buffer ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_NULL | No device context is associated with the buffer.
Value | Handle of the device context associated with the buffer.
Open Collapse M_DDRAW_SURFACE

Returns a pointer (LPDIRECTDRAWSURFACE) to the DirectDraw surface associated with the MIL buffer (if any) or M_NULL. Returns a pointer (LPDIRECTDRAWSURFACE) to the DirectDraw surface associated with the MIL buffer (if any) or M_NULL.

a b c d e g h i j k l m n o p q r
Open Collapse M_DIB_HANDLE

Returns the DIB handle (HBITMAP) of the DIB associated with the MIL buffer. To ensure that the buffer has a DIB handle, the buffer must have been successfully allocated using with M_DIB + M_GDI. Returns the DIB handle (HBITMAP) of the DIB associated with the MIL buffer ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_NULL | No DIB handle is associated with the buffer.
Value | Handle of the DIB associated with the buffer.
Open Collapse M_EXTENDED_ATTRIBUTE

Returns all the buffer attributes. See the Attribute parameter of the MbufAlloc...() functions for a list of all possible return values. To retrieve only the color or monochrome storage format of the buffer, use MbufInquire() with M_DATA_FORMAT. To retrieve other formatting information, use MbufInquire() with M_EXTENDED_FORMAT. Returns all the buffer attributes ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: MIL_INT64

Return values:
M_NULL | No extended information was found.
Value | A bit-encoded value that specifies the buffer's attributes.
Open Collapse M_EXTENDED_FORMAT

Returns all the buffer's formatting attributes. See the formatting information in the Attribute parameter of the MbufAlloc...() functions for a list of all possible return values. To retrieve only the color or monochrome storage format of the buffer, use MbufInquire() with M_DATA_FORMAT. To retrieve other formatting information, use MbufInquire() with M_EXTENDED_ATTRIBUTE. Returns all the buffer's formatting attributes ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: MIL_INT64

Return values:
M_NULL | No extended information was found.
Value | A bit-encoded value that specifies the buffer's formatting attributes.
Open Collapse M_HOST_ADDRESS

Returns the Host address of the buffer, if the buffer is visible from the Host address space and is not a planar 3-band buffer. For a planar 3-band buffer, you can determine its Host address by allocating a child buffer for the required band and then using M_HOST_ADDRESS to determine its Host address. If available, this address can be used to directly access the data of a MIL buffer with the Host CPU. Returns the Host address of the buffer, if the buffer is visible from the Host address space and is not a planar 3-band buffer ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
NULL | The buffer is not visible from the Host address space or the buffer is a planar 3-band buffer.
Value | Host address of the buffer.
Open Collapse M_HOST_ADDRESS_REMOTE

Returns the on-board-Host address of the buffer, if allocated on-board and is not a planar 3-band buffer. For a planar 3-band buffer, you can determine its on-board Host address by allocating a child buffer for the required band and then using M_HOST_ADDRESS_REMOTE to determine its on-board Host address. If available, this address can be used to directly access the data of a MIL buffer with the on-board CPU of the same system. Returns the on-board-Host address of the buffer, if allocated on-board and is not a planar 3-band buffer ...

m n o

UserVarPtr info

Return values:
NULL | The buffer is not visible from the on-board address space.
Value | Address of the buffer in on-board memory.
Open Collapse M_MAP

Returns whether the buffer is mapped to the address space of the process. Returns whether the buffer is mapped to the address space of the process ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_MAX

Returns the maximum pixel value possible in the buffer. Returns the maximum pixel value possible in the buffer ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: double

Return values:
Value (details)
Open Collapse M_MIN

Returns the minimum pixel value possible in the buffer. Returns the minimum pixel value possible in the buffer ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: double

Return values:
Value (details)
Open Collapse M_MODIFICATION_COUNT

Returns the current value of the modification counter of the image buffer. The modification counter is initialized to a number that is unique to the image buffer and is given its own unique range. Returns the current value of the modification counter of the image buffer ...

This number is incremented by one each time the image buffer is modified.

If the image buffer is freed, this number will not be reassigned to a new image buffer.

If the image buffer is accessed externally, for example, when using MbufCreateColor() or MbufCreate2d(), MbufControl() with M_MODIFIED must be called to indicate that the image buffer's contents have been modified. Calling this function will increment the counter.

This feature is useful for optimization. For example, you can avoid repeating certain computations (for example, analysis computations) if you know that the image buffer has not been modified. In this case, inquire the count before the first computation in the sequence of computations, and then inquire it again before repeating the same sequence. If no modifications have been made to the image buffer, you can avoid repeating the sequence unnecessarily.

a b c d e f g h i j k l m n o p q r
Open Collapse M_NATIVE_ID

Returns the native identifier (handle) of the buffer. This identifier can be used when mixing board-specific code (from the native library function set) with MIL code. Returns the native identifier (handle) of the buffer ...

c h i m n o
Open Collapse M_OWNER_SYSTEM

Returns the identifier of the system on which the buffer has been allocated. Returns the identifier of the system on which the buffer has been allocated ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: MIL_ID

Return values:
M_DEFAULT_HOST, MIL system identifier (details)
Open Collapse M_OWNER_SYSTEM_TYPE

Returns the type of system on which the buffer was allocated. For possible return values, see the MsysInquire() M_SYSTEM_TYPE inquire type. Returns the type of system on which the buffer was allocated ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_PARENT_ID

Returns the MIL identifier of the parent buffer. Only child buffers have a parent buffer. The parent buffer is the buffer from which the specified buffer (BufId) was defined. The parent buffer can itself have a parent buffer. If the specified buffer has no parent buffer, the identifier of the specified buffer is returned. Returns the MIL identifier of the parent buffer ...

To establish the ancestor buffer (root buffer) of the specified buffer, use M_ANCESTOR_ID instead.

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: MIL_ID
Open Collapse M_PARENT_OFFSET_BAND

Returns the band offset relative to the parent buffer. Returns the band offset relative to the parent buffer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_PARENT_OFFSET_X

Returns the X-offset relative to the parent buffer. Returns the X-offset relative to the parent buffer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_PARENT_OFFSET_Y

Returns the Y-offset relative to the parent buffer. Returns the Y-offset relative to the parent buffer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_PHYSICAL_ADDRESS

Returns the physical address of the buffer if it is not a planar 3-band buffer. For a planar 3-band buffer, you can determine its physical address by allocating a child buffer for the required band and then using M_PHYSICAL_ADDRESS to determine its physical address. This type of address is available only for a non-paged buffer mapped to the Host or from a buffer allocated in a frame grabber's on-board memory. This type of address is used mostly for access by bus masters other than the Host CPU. Returns the physical address of the buffer if it is not a planar 3-band buffer ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
NULL | The buffer is not visible from the physical address space.
Value | Address of the buffer.
Open Collapse M_PHYSICAL_ADDRESS_REMOTE

Returns the physical on-board address of the buffer, if allocated on-board and is not a planar 3-band buffer. For a planar 3-band buffer, you can determine its physical on-board address by allocating a child buffer for the required band and then using M_PHYSICAL_ADDRESS_REMOTE to determine its physical on-board address. This address is only meaningful on-board the same system. Returns the physical on-board address of the buffer, if allocated on-board and is not a planar 3-band buffer ...

m n o

UserVarPtr info

Return values:
NULL | The buffer is not visible from the physical address space.
Value | Address of the buffer in on-board memory.
Open Collapse M_PITCH

Returns the number of pixels between the beginnings of any two adjacent lines of the buffer data. Returns the number of pixels between the beginnings of any two adjacent lines of the buffer data.

a b c d e f g h i j k l m n o p q r
Open Collapse M_PITCH_BYTE

Returns the number of bytes between the beginnings of any two adjacent lines of the buffer data. Returns the number of bytes between the beginnings of any two adjacent lines of the buffer data.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIGN

Returns the buffer range. Returns the buffer range ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_SIGNED | Buffer range is signed.
M_UNSIGNED | Buffer range is unsigned.
Open Collapse M_SIZE_BAND

Returns the number of buffer color bands. Returns the number of buffer color bands.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_BIT

Returns the depth per band, in bits. Returns the depth per band, in bits.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_BYTE

Returns the size of the buffer, in bytes. Returns the size of the buffer, in bytes ...

Use M_SIZE_BYTE to establish the real size of the buffer.

a b c d e f g h i j k l m n o p q r

MIL-lite with restriction

If the buffer has an M_JPEG2000_LOSSY attribute, this value might be smaller than the requested size of the compressed buffer (M_TARGET_SIZE). This is the case if the data could be compressed into a size smaller than the target buffer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_X

Returns the width of the buffer, in pixels. Returns the width of the buffer, in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_Y

Returns the height of the buffer, in pixels. Returns the height of the buffer, in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_TYPE

Returns the buffer data type and depth. Depth is returned in bits. Returns the buffer data type and depth ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
depth value + M_FLOAT | Data type is floating point
depth value + M_SIGNED | Data type is signed
depth value + M_UNSIGNED | Data type is unsigned

For M_KERNEL and M_STRUCT_ELEMENT data buffers only (see MbufControlNeighborhood() for possible values), you can set this parameter to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_OFFSET_CENTER_X | Returns the X-coordinate of the center of the kernel or structuring element. Returns the X-coordinate of the center of the kernel or structuring element ...
 |  | UserVarPtr info Return values: 0 to (SizeX-1) (details)
Open Collapse M_OFFSET_CENTER_Y | Returns the Y-coordinate of the center of the kernel or structuring element. Returns the Y-coordinate of the center of the kernel or structuring element ...
 |  | UserVarPtr info Return values: 0 to (SizeY-1) (details)
Open Collapse M_OVERSCAN | Returns the overscan type. Returns the overscan type ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_MIRROR, M_REPLACE, M_TRANSPARENT (details)
Open Collapse M_OVERSCAN_REPLACE_VALUE | Returns the overscan replace value. Returns the overscan replace value ...
 |  | UserVarPtr info Return values: M_REPLACE_MAX, M_REPLACE_MIN, Value (details)

For M_KERNEL data buffers only (see MbufControlNeighborhood() for possible values), you can set this parameter to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_ABSOLUTE_VALUE

Returns whether the absolute value should be taken. Returns whether the absolute value should be taken ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_FILTER_MODE

Returns the mode in which to apply the filter. Returns the mode in which to apply the filter ...

UserVarPtr info

Return values:
M_KERNEL, M_RECURSIVE (details)
Open Collapse M_FILTER_OPERATION

Returns the type of neighborhood operation to perform using the selected filter. Returns the type of neighborhood operation to perform using the selected filter ...

If MbufControlNeighborhood() M_FILTER_TYPE is set to M_USER_DEFINED, then M_FILTER_OPERATION is not supported.

UserVarPtr info

Return values:
M_EDGE_DETECT, M_EDGE_DETECT_SQR, M_FIRST_DERIVATIVE_X, M_FIRST_DERIVATIVE_Y, M_HORIZ_EDGE, M_LAPLACIAN_EDGE, M_SECOND_DERIVATIVE_X, M_SECOND_DERIVATIVE_XY, M_SECOND_DERIVATIVE_Y, M_SHARPEN, M_SMOOTH, M_VERT_EDGE (details)
Open Collapse M_FILTER_SMOOTHNESS

Returns the degree of smoothness (strength of the denoising) applied by the filter during the neighborhood operation. Returns the degree of smoothness (strength of the denoising) applied by the filter during the neighborhood operation ...

If MbufControlNeighborhood() M_FILTER_TYPE is set to M_USER_DEFINED, then M_FILTER_SMOOTHNESS is not supported.

UserVarPtr info

Return values:
0 to 100 (details)
Open Collapse M_FILTER_TYPE

Returns the type of filter used to perform the neighborhood operation. Returns the type of filter used to perform the neighborhood operation ...

UserVarPtr info

Return values:
M_DERICHE, M_SHEN, M_USER_DEFINED (details)
Open Collapse M_NORMALIZATION_FACTOR

Returns the normalization factor. Returns the normalization factor ...

UserVarPtr info

Return values:
Please see MbufControlNeighborhood() with M_NORMALIZATION_FACTOR. Note that M_DEFAULT is not returned.

Open Collapse M_SATURATION

Returns whether to saturate the result. Returns whether to saturate the result ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

For M_IMAGE + M_COMPRESS image buffers (see MbufAlloc...() for possible values), you can set this parameter to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_COMPRESSION_TYPE | Returns the type of compression. See MbufAlloc...() for possible values. Returns the type of compression ...
Open Collapse M_SIZE_BYTE | Returns the size of the compressed buffer, in bytes. The buffer size will be zero if the buffer has not been initialized with data. Returns the size of the compressed buffer, in bytes ...

For M_IMAGE + M_COMPRESS image buffers with a M_JPEG_LOSSY, M_JPEG_LOSSY_INTERLACED, or M_JPEG2000_LOSSY compression type, you can set this parameter to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_Q_FACTOR | Returns the quantization factor for both JPEG2000 lossy and JPEG lossy buffers. Note that for 3-band buffers, only the quantization factor associated with the first band is returned. For JPEG2000 lossy, you can combine this inquire type with another value to inquire about a specific band (see below). Returns the quantization factor for both JPEG2000 lossy and JPEG lossy buffers ...
 |  | UserVarPtr info Return values: 1 to 99 (details)
Open Collapse M_Q_FACTOR_CHROMINANCE | Returns the quantization factor of the U and V bands for both JPEG2000 lossy and JPEG lossy buffers in YUV format. Returns the quantization factor of the U and V bands for both JPEG2000 lossy and JPEG lossy buffers in YUV format ...
 |  | UserVarPtr info Return values: 1 to 99 (details)
Open Collapse M_Q_FACTOR_LUMINANCE | Returns the quantization factor of the Y band for both JPEG2000 lossy and JPEG lossy buffers in YUV format. Returns the quantization factor of the Y band for both JPEG2000 lossy and JPEG lossy buffers in YUV format ...
 |  | UserVarPtr info Return values: 1 to 99 (details)
Open Collapse M_QUANTIZATION | Returns the identifier of the array buffer containing the quantization table (for a JPEG lossy or JPEG2000 lossy buffer), which is associated with the image buffer. Note that for 3-band buffers, only the identifier of the array buffer associated with the first band is returned. For JPEG2000 lossy, you can combine this inquire type with another value to inquire about a specific band (see below). Returns the identifier of the array buffer containing the quantization table (for a JPEG lossy or JPEG2000 lossy buffer), which is associated with the image buffer ...
 |  | UserVarPtr info Return values: MIL M_ARRAY buffer identifier (details)
Open Collapse M_QUANTIZATION_CHROMINANCE | Returns the identifier of the array buffer containing the quantization table associated with the U and V bands, for both JPEG2000 lossy and JPEG lossy buffers in YUV format. Returns the identifier of the array buffer containing the quantization table associated with the U and V bands, for both JPEG2000 lossy and JPEG lossy buffers in YUV format ...
 |  | UserVarPtr info Return values: MIL M_ARRAY buffer identifier (details)
Open Collapse M_QUANTIZATION_LUMINANCE | Returns the identifier of the array buffer containing the quantization table associated with the Y band, for both JPEG2000 lossy and JPEG lossy buffers in YUV format. Returns the identifier of the array buffer containing the quantization table associated with the Y band, for both JPEG2000 lossy and JPEG lossy buffers in YUV format ...
 |  | UserVarPtr info Return values: MIL M_ARRAY buffer identifier (details)

For M_IMAGE + M_COMPRESS image buffers with a M_JPEG2000_LOSSY or M_JPEG2000_LOSSLESS compression type, you can set this parameter to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_DECOMPOSITION_LEVEL | Returns the number of iterations the discrete wavelet transform is applied to the image (for single-band images) or on the first band of the image (for 3-band images). You can combine this inquire type with another value to inquire about a specific band (see below). Returns the number of iterations the discrete wavelet transform is applied to the image (for single-band images) or on the first band of the image (for 3-band images) ...
 |  | UserVarPtr info Return values: Value >= 0 (details)
Open Collapse M_NUMBER_SUBBAND | Returns the number of sub-bands rendered from the discrete wavelet transform passed on an image (for 1-band images) or on the first band of a 3-band image. You can combine this inquire type with another value to inquire about a specific band (see below). Returns the number of sub-bands rendered from the discrete wavelet transform passed on an image (for 1-band images) or on the first band of a 3-band image ...

For M_IMAGE + M_COMPRESS image buffers with a M_JPEG2000_LOSSY compression type, you can set this parameter to the following value.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_TARGET_SIZE | Returns the requested size of the compressed buffer in bytes. Returns M_DEFAULT if no size has been requested. Returns the requested size of the compressed buffer in bytes ... Use M_SIZE_BYTE to establish the real size of the buffer.
 |  | UserVarPtr info Return values: Value > 0 (details)

For M_IMAGE + M_COMPRESS image buffers with a M_JPEG_LOSSY, M_JPEG_LOSSY_INTERLACED, M_JPEG_LOSSLESS, or M_JPEG_LOSSLESS_INTERLACED compression type, you can set this parameter to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_HUFFMAN_DC | Returns the identifier of the array buffer containing the DC Huffman table which is associated with the image buffer. For 3-band buffers, only the identifier of the array buffer associated with the first band is returned. Returns the identifier of the array buffer containing the DC Huffman table which is associated with the image buffer ...
 |  | UserVarPtr info Data type: MIL_ID Return values: MIL M_ARRAY buffer identifier (details)
Open Collapse M_HUFFMAN_DC_CHROMINANCE | Returns the identifier of the array buffer containing the DC Huffman table that is associated with the U and V bands of a JPEG lossy buffer in YUV format. Returns the identifier of the array buffer containing the DC Huffman table that is associated with the U and V bands of a JPEG lossy buffer in YUV format ...
 |  | UserVarPtr info Data type: MIL_ID Return values: MIL M_ARRAY buffer identifier (details)
Open Collapse M_HUFFMAN_DC_LUMINANCE | Returns the identifier of the array buffer containing the DC Huffman table that is associated with the Y band of a JPEG lossy buffer in YUV format. Returns the identifier of the array buffer containing the DC Huffman table that is associated with the Y band of a JPEG lossy buffer in YUV format ...
 |  | UserVarPtr info Data type: MIL_ID Return values: MIL M_ARRAY buffer identifier (details)

For M_IMAGE + M_COMPRESS image buffers with a M_JPEG_LOSSLESS or M_JPEG_LOSSLESS_INTERLACED compression type, you can set this parameter to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_PREDICTOR | Returns the type of predictor. This inquire type is supported for JPEG lossless buffers only. Returns the type of predictor ...
 |  | UserVarPtr info Return values: 0, 1, 2 (details)
Open Collapse M_RESTART_INTERVAL | Returns the number of lines between restart markers (for JPEG lossless buffers) or number of 8x8 blocks of data between restart markers (for JPEG lossy buffers). Returns the number of lines between restart markers (for JPEG lossless buffers) or number of 8x8 blocks of data between restart markers (for JPEG lossy buffers) ...
 |  | UserVarPtr info Return values: Value > 0 (details)

For M_IMAGE + M_COMPRESS image buffers with a M_JPEG_LOSSY or M_JPEG_LOSSY_INTERLACED compression type, you can set this parameter to one of the following values.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_HUFFMAN_AC | Returns the identifier of the array buffer containing the AC Huffman table that is associated with the image buffer. For 3-band buffers, only the identifier of the array buffer associated with the first band is returned. Returns the identifier of the array buffer containing the AC Huffman table that is associated with the image buffer ...
 |  | UserVarPtr info Data type: MIL_ID Return values: MIL M_ARRAY buffer identifier (details)
Open Collapse M_HUFFMAN_AC_CHROMINANCE | Returns the identifier of the array buffer containing the AC Huffman table that is associated with the U and V bands of a JPEG buffer in YUV format. Returns the identifier of the array buffer containing the AC Huffman table that is associated with the U and V bands of a JPEG buffer in YUV format ...
 |  | UserVarPtr info Data type: MIL_ID Return values: MIL M_ARRAY buffer identifier (details)
Open Collapse M_HUFFMAN_AC_LUMINANCE | Returns the identifier of the array buffer containing the AC Huffman table that is associated with the Y band of a JPEG buffer in YUV format. Returns the identifier of the array buffer containing the AC Huffman table that is associated with the Y band of a JPEG buffer in YUV format ...
 |  | UserVarPtr info Data type: MIL_ID Return values: MIL M_ARRAY buffer identifier (details)

[Combination constants]

You can add one of the following values to M_DECOMPOSITION_LEVEL, M_NUMBER_SUBBAND, M_Q_FACTOR (for JPEG2000 lossy buffers), and M_QUANTIZATION (for JPEG2000 lossy buffers), to specify the band about which to inquire.

Open Collapse Value Description
Open Collapse M_BLUE

 Returns the inquired value for the blue band (for RGB buffers).  Returns the inquired value for the blue band (for RGB buffers).

  Open   Collapse  M_GREEN

 Returns the inquired value for the green band (for RGB buffers).  Returns the inquired value for the green band (for RGB buffers).

  Open   Collapse  M_RED

 Returns the inquired value for the red band (for RGB buffers).  Returns the inquired value for the red band (for RGB buffers).

  Open   Collapse  M_U

 Returns the inquired value for the U band (for YUV buffers).  Returns the inquired value for the U band (for YUV buffers).

  Open   Collapse  M_V

 Returns the inquired value for the V band (for YUV buffers).  Returns the inquired value for the V band (for YUV buffers).

  Open   Collapse  M_Y

 Returns the inquired value for the Y band (for YUV buffers).  Returns the inquired value for the Y band (for YUV buffers).

 UserVarPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • double
    •

  • long
    •

  • MIL_ID
    •

  • MIL_INT64
    •

 Specifies the address in which the requested information is to be written.

 Since the MbufInquire() function also returns the requested information, you can set this parameter to M_NULL.

Return value

 The return value is the requested information, cast to a long; otherwise M_ERROR is returned.

Remark

  •  Note that MIL-Lite compression support, particularly for M_IMAGE + M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

PARENT ID DEFAULT  EXTENDED ATTRIBUTE EXTENDED FORMAT DIB GDI DATA FORMAT EXTENDED FORMAT DATA FORMAT EXTENDED ATTRIBUTE HOST ADDRESS HOST ADDRESS REMOTE MODIFIED SYSTEM TYPE ANCESTOR ID PHYSICAL ADDRESS PHYSICAL ADDRESS REMOTE JPEG2000 LOSSY TARGET SIZE SIZE BYTE DC ALLOC KERNEL STRUCT ELEMENT KERNEL FILTER TYPE USER DEFINED FILTER OPERATION FILTER TYPE USER DEFINED FILTER SMOOTHNESS IMAGE COMPRESS IMAGE COMPRESS JPEG LOSSY JPEG LOSSY INTERLACED JPEG2000 LOSSY IMAGE COMPRESS JPEG2000 LOSSY JPEG2000 LOSSLESS IMAGE COMPRESS JPEG2000 LOSSY SIZE BYTE IMAGE COMPRESS JPEG LOSSY JPEG LOSSY INTERLACED JPEG LOSSLESS JPEG LOSSLESS INTERLACED IMAGE COMPRESS JPEG LOSSLESS JPEG LOSSLESS INTERLACED IMAGE COMPRESS JPEG LOSSY JPEG LOSSY INTERLACED DECOMPOSITION LEVEL NUMBER SUBBAND Q FACTOR QUANTIZATION IMAGE COMPRESS   ALLOCATION OVERSCAN SIZE ANCESTOR ID  ANCESTOR OFFSET BAND  ANCESTOR OFFSET BIT ANCESTOR OFFSET X  ANCESTOR OFFSET Y  ASSOCIATED LUT BITMAPINFO  DATA FORMAT DDRAW SURFACE DIB HANDLE EXTENDED ATTRIBUTE EXTENDED FORMAT HOST ADDRESS  HOST ADDRESS REMOTE MAP MAX MIN MODIFICATION COUNT  NATIVE ID OWNER SYSTEM OWNER SYSTEM TYPE  PARENT ID  PARENT OFFSET BAND PARENT OFFSET X  PARENT OFFSET Y  PHYSICAL ADDRESS PHYSICAL ADDRESS REMOTE PITCH  PITCH BYTE SIGN SIZE BAND SIZE BIT SIZE BYTE SIZE X SIZE Y TYPE DC HANDLE OFFSET CENTER X OFFSET CENTER Y OVERSCAN OVERSCAN REPLACE VALUE ABSOLUTE VALUE FILTER MODE FILTER OPERATION FILTER SMOOTHNESS FILTER TYPE NORMALIZATION FACTOR SATURATION COMPRESSION TYPE  SIZE BYTE  Q FACTOR Q FACTOR CHROMINANCE Q FACTOR LUMINANCE QUANTIZATION  QUANTIZATION CHROMINANCE QUANTIZATION LUMINANCE  DECOMPOSITION LEVEL  NUMBER SUBBAND  TARGET SIZE HUFFMAN DC  HUFFMAN DC CHROMINANCE  HUFFMAN DC LUMINANCE  PREDICTOR  RESTART INTERVAL  HUFFMAN AC  HUFFMAN AC CHROMINANCE  HUFFMAN AC LUMINANCE  BLUE GREEN RED U V Y


MbufLoad

See Also | Example | Availability | MbufInquire | MbufPut1d
User Guide:
Processing calibrated images
Managing data buffers
Loading and generating data into LUTs
Managing color images

Reference:
MbufDiskInquire
MbufImport
MbufInquire
MdispLut
mbufcolor.c
mcal.c
mfunc.c
mimfft.c
mimmorphic.c
mimwarp.c
mmod.c
mocr.c
mpat.c
mstr.c
mthread.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL
Synopsis
Load data from a file into a data buffer.
Syntax
void MbufLoad(
MIL_TEXT_PTR FileName,
MIL_ID BufId
)
Description

This function loads data from a file into a previously allocated data buffer. The function detects the file format from the data.

Note, you can perform the same operation as MbufLoad() using MbufImport(), which uses the specified file format to open the file instead of trying to determine the format from the data.

[MIL-Lite with restriction]

When loading compressed data and the destination buffer has an M_IMAGE attribute (but not an M_COMPRESS attribute), this function will automatically decompress it. If necessary, the data in the file will be transformed to the format of the buffer. When loading uncompressed data into a buffer with an M_COMPRESS attribute, this function will automatically compress it, according to the compression settings found in the buffer.

When loading an image file that has been saved with an associated LUT (color palette) into a 3-band 8-bit image buffer, the LUT is automatically applied to the data to generate 3-band image data. In this case, a LUT buffer is not created and, therefore, is not associated with the 3-band 8-bit buffer. When loading an image file that has been saved with an associated LUT (color palette) into any other type of image buffer, the LUT is also imported and associated with the resulting image buffer. You can obtain the identifier of the associated LUT, using MbufInquire().

Note that the associated LUT will be automatically selected on the display (MdispLut()) if the image buffer is selected on a display and the default LUT has not been overidden by a former call to MdispLut().

Using MbufDiskInquire(), you can inquire about the dimensions of the data saved in a file (except for raw files) without loading it.

Parameters
FileName

Specifies the name and path of the file from which to load the data buffer. The function handles the opening and closing of the file.

BufId

Specifies the identifier of the destination buffer. This buffer must be large enough in depth and dimensions to hold the data. If the data is deeper than the buffer, the most-significant bits of the data are truncated when loaded into the buffer. If the buffer depth is greater than that of the data, the data is zero or sign-extended (depending on the data type) when loaded into the buffer. If the buffer is larger in size than the data, exceeding areas of the buffer are unaffected.

Remark
  • Note that MIL-Lite compression support, particularly for M_IMAGE + M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware. The compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
IMAGE COMPRESS COMPRESS IMAGE COMPRESS


MbufPut1d

See Also | Example | Availability | MbufLoad | MbufPut2d
User Guide:
Arithmetic with images
Managing data buffers
Using buffers with the Bayer color filter
Loading and generating data into LUTs
Working with tables

Reference:
MbufPutColor
mimwarp.c
Available in MIL-Lite

Available in MIL
Synopsis
Put data from a user-supplied array into a one-dimensional area of a buffer.
Syntax
void MbufPut1d(
MIL_ID DestBufId,
long OffX,
long SizeX,
void *UserArrayPtr
)
Description

This function copies data from a user-supplied array to a one-dimensional area of the specified MIL destination buffer.

Note, for multi-band buffers, MbufPut1d() behaves like MbufPutColor() with its DataFormat parameter set to M_PLANAR and its Band parameter set to M_ALL_BANDS. See MbufPutColor() for more details.

Parameters
DestBufId

Specifies the identifier of the destination buffer.

OffX

Specifies the horizontal offset of the destination buffer area in which to put data, relative to the destination buffer's top-left pixel.

SizeX

Specifies the width of the destination buffer area in which to copy the data (starting from the specified offset OffX).

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array from which to copy data into the destination buffer. Ensure that there are enough entries in the user array to fill the specified destination buffer area. MbufPut1d() assumes that the array is of the same data type and depth as the destination buffer.

PLANAR ALL BANDS


MbufPut2d

See Also | Example | Availability | MbufPut1d | MbufPut
User Guide:
Custom spatial filters
Custom morphological operations
Managing data buffers
Using buffers with the Bayer color filter
Working with tables

Reference:
MbufPutColor
mimfft.c
mimmorphic.c
mimwarp.c
Available in MIL-Lite

Available in MIL
Synopsis
Put data from a user-supplied array into a two-dimensional area of a buffer.
Syntax
void MbufPut2d(
MIL_ID DestBufId,
long OffX,
long OffY,
long SizeX,
long SizeY,
void *UserArrayPtr
)
Description

This function copies data from a user-supplied array to a two-dimensional area of the specified MIL destination buffer.

Note, for multi-band buffers, MbufPut2d() behaves like MbufPutColor() with its DataFormat parameter set to M_PLANAR and its Band parameter set to M_ALL_BANDS. See MbufPutColor() for more details.

Parameters
DestBufId

Specifies the identifier of the destination buffer.

OffX

Specify the horizontal offset of the destination buffer area in which to put the data, relative to the destination buffer's top-left pixel.

OffY

Specify the vertical offset of the destination buffer area in which to put the data, relative to the destination buffer's top-left pixel.

SizeX

Specify the width of the destination buffer area in which to copy the data (starting from the specified offsets OffX and OffY).

SizeY

Specify the height of the destination buffer area in which to copy the data (starting from the specified offsets OffX and OffY).

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array from which to copy data into the destination buffer. Ensure that there are enough entries in the user array to fill the specified destination buffer area. MbufPut2d() assumes that the array is of the same data type and depth as the destination buffer.

PLANAR ALL BANDS


MbufPut

See Also | Example | Availability | MbufPut2d | MbufPutColor2d
User Guide:
Custom spatial filters
Custom morphological operations
Managing data buffers
Accessing a MIL buffer directly
Loading and generating data into LUTs
Palettes and output LUTs for windowed display (256-color)

Reference:
MbufPutColor
dtkobjecttracking.c
mimconvolve.c
Available in MIL-Lite

Available in MIL
Synopsis
Put data from a user-supplied array into a data buffer.
Syntax
void MbufPut(
MIL_ID DestBufId,
void *UserArrayPtr
)
Description

This function copies data from a user-supplied array to a specified MIL destination buffer.

Note, for multi-band buffers, MbufPut() behaves like MbufPutColor() with its DataFormat parameter set to M_PLANAR and its Band parameter set to M_ALL_BANDS. See MbufPutColor() for more details.

Parameters
DestBufId

Specifies the identifier of the destination buffer.

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array from which to copy data into the destination buffer. Ensure that there are enough entries in the user array to fill the destination buffer. MbufPut() assumes that the array is of the same data type and depth as the destination buffer's bands.

PLANAR ALL BANDS


MbufPutColor2d

Example | Availability | MbufPut | MbufPutColor
There are no examples containing MbufPutColor2d().
Available in MIL-Lite

Available in MIL
Synopsis
Put data from a user-supplied array into a region of one or all bands of a data buffer.
Syntax
void MbufPutColor2d(
MIL_ID DestBufId,
long DataFormat,
long Band,
long OffX,
long OffY,
long SizeX,
long SizeY,
void *UserArrayPtr
)
Description

This function copies data from a user-supplied array to a specified region in one or all bands of a specified MIL destination buffer.

Parameters
DestBufId

Specifies the identifier of the destination buffer.

DataFormat

Specifies the data format of the user-supplied array. This information is required to properly copy the data. The internal data format of the destination buffer need not match the specified data format of the user-supplied array; an internal conversion will be performed if necessary. Note, however, if the formats do match, the operation will be much faster.

This parameter must be set to one of the following values. Note that Dx and Dy denote the destination width and height, respectively

Unless otherwise specified, the following values require that you pass the UserArrayPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_PACKED | Copies the bands in an interleaved manner (for example, RGB RGB RGB ...). M_PACKED must be used in combination with other values (see below). Copies the bands in an interleaved manner (for example, RGB RGB RGB ...) ...
Open Collapse M_PLANAR | Copies the bands one after the other (RRR...GGG...BBB...). This format is to be used when copying to all color bands (M_ALL_BANDS) of the destination buffer. Copies the bands one after the other (RRR...GGG...BBB...) ...
 |  | UserArrayPtr info Data type: array of the same type as the buffer Array size: Dx x Dy x number of color band of the destination buffer
Open Collapse M_SINGLE_BAND | Copies to a single color band. Copies to a single color band ...
 |  | UserArrayPtr info Data type: array of the same type as the buffer Array size: Dx x Dy

[Combination constants]

The values below must be added to M_PACKED. Note that the destination buffer must be a three-band, 8-bit buffer.

Open Collapse Value | Description
Open Collapse M_BGR24 | Stores the data into a BGR24 packed format. In this format, each pixel is internally stored as three consecutive bytes in little-endian order (BGRBGR). Stores the data into a BGR24 packed format ...
 |  | UserArrayPtr info Data type: array of type char Array size: Dx x Dy x 3 bytes (char)
Open Collapse M_BGR32 | Stores the data into a BGR32 packed format. In this format, each pixel is internally stored as four consecutive bytes, in little-endian order (BGRXBGRX). The most-significant byte is a "don't care" byte. Stores the data into a BGR32 packed format ...
 |  | UserArrayPtr info Data type: array of type long Array size: Dx x Dy x 4 bytes (long)
Open Collapse M_RGB15 | Stores the data into a RGB15 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 5-bit green value, a 5-bit red value, and a "don't care" bit (most significant), in little-endian order (RGB 5:5:5). Stores the data into a RGB15 packed format ...
 |  | UserArrayPtr info Data type: array of type unsigned char Array size: Dx x Dy x 2 bytes (unsigned char)
Open Collapse M_RGB16 | Stores the data into a RGB16 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 6-bit green value, and a 5-bit red value (most significant), in little-endian order (RGB 5:6:5). Stores the data into a RGB16 packed format ...
 |  | UserArrayPtr info Data type: array of type unsigned char Array size: Dx x Dy x 2 bytes (unsigned char)
Band

Specifies the index of the color band in which to copy. This parameter can be set to one of the values below.

Open Collapse Value Description
Open Collapse 0 <= Value <= #bands - 1

 Specifies the index of the band to copy.  Specifies the index of the band to copy ...

 The relationship between index value and band for RGB and HLS buffers is the following:

0 | Corresponds to the red band for RGB buffers or the hue band for HLS buffers.
1 | Corresponds to the green band for RGB buffers or the saturation band for HLS buffers.
2 | Corresponds to the blue band for RGB buffers or the luminance band for HLS buffers.

  Open   Collapse  M_ALL_BANDS

 Copies to all color bands.  Copies to all color bands.

  Open   Collapse  M_BLUE

 Copies to the blue color band (for RGB buffers).  Copies to the blue color band (for RGB buffers).

  Open   Collapse  M_GREEN

 Copies to the green color band (for RGB buffers).  Copies to the green color band (for RGB buffers).

  Open   Collapse  M_HUE

 Copies to the hue color band (for HLS buffers).  Copies to the hue color band (for HLS buffers).

  Open   Collapse  M_LUMINANCE

 Copies to the luminance color band (for HLS buffers).  Copies to the luminance color band (for HLS buffers).

  Open   Collapse  M_RED

 Copies to the red color band (for RGB buffers).  Copies to the red color band (for RGB buffers).

  Open   Collapse  M_SATURATION

 Copies to the saturation color band (for HLS buffers).  Copies to the saturation color band (for HLS buffers).

 OffX

 Specifies the horizontal offset of the destination buffer region in which to put the data, relative to the destination buffer's top-left coordinate.

 OffY

 Specifies the vertical offset of the destination buffer region in which to put the data, relative to the destination buffer's top-left coordinate.

 SizeX

 Specifies the width of the destination buffer region in which to put the data.

 SizeY

 Specifies the height of the destination buffer region in which to put the data.

 UserArrayPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type char
    •

  • array of type unsigned char
    •

  • array of type long
    •

  • array of the same type as the buffer
    •

  • long
    •

 Specifies the address of the user array from which to copy data into the destination buffer.  Ensure that there are enough entries in the user array to fill the color band of the destination buffer.

PACKED ALL BANDS PACKED   PACKED PLANAR SINGLE BAND BGR24 BGR32 RGB15 RGB16  ALL BANDS BLUE GREEN HUE LUMINANCE RED SATURATION


MbufPutColor

Example | Availability | MbufPutColor2d | MbufPutLine
There are no examples containing MbufPutColor().
Available in MIL-Lite

Available in MIL
Synopsis
Put data from a user-supplied array into one or all bands of a data buffer.
Syntax
void MbufPutColor(
MIL_ID DestBufId,
long DataFormat,
long Band,
void *UserArrayPtr
)
Description

This function copies data from a user-supplied array to one or all bands of a specified MIL destination buffer.

Parameters
DestBufId

Specifies the identifier of the destination buffer.

DataFormat

Specifies the data format of the user-supplied array. This information is required to properly copy the data. The internal data format of the destination buffer need not match the specified data format; an internal conversion will be performed if necessary. Note, however, if the formats do match, the operation will be much faster.

This parameter must be set to one of the following values. Note that Dx and Dy denote the destination width and height, respectively.

Unless otherwise specified, the following values require that you pass the UserArrayPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_PACKED | Copies the bands in an interleaved manner (for example, RGB RGB RGB ...). M_PACKED must be used in combination with other values (see below). Copies the bands in an interleaved manner (for example, RGB RGB RGB ...) ...
Open Collapse M_PLANAR | Copies the bands one after the other (RRR...GGG...BBB...). This format is to be used when copying to all color bands (M_ALL_BANDS) of the destination buffer. Copies the bands one after the other (RRR...GGG...BBB...) ...
 |  | UserArrayPtr info Data type: array of the same type as the buffer Array size: Dx x Dy x number of color band of the destination buffer
Open Collapse M_SINGLE_BAND | Copies to a single color band. Copies to a single color band ...
 |  | UserArrayPtr info Data type: array of the same type as the buffer Array size: Dx x Dy

[Combination constants]

The values below must be added to M_PACKED. Note that the destination buffer must be a three-band, 8-bit buffer.

Open Collapse Value | Description
Open Collapse M_BGR24 | Stores the data into a BGR24 packed format. In this format, each pixel is internally stored as three consecutive bytes in little-endian order (BGRBGR). Stores the data into a BGR24 packed format ...
 |  | UserArrayPtr info Data type: array of type char Array size: Dx x Dy x 3 bytes (char)
Open Collapse M_BGR32 | Stores the data into a BGR32 packed format. In this format, each pixel is internally stored as four consecutive bytes, in little-endian order (BGRXBGRX). The most-significant byte is a "don't care" byte. Stores the data into a BGR32 packed format ...
 |  | UserArrayPtr info Data type: array of type long Array size: Dx x Dy x 4 bytes (long)
Open Collapse M_RGB15 | Stores the data into a RGB15 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 5-bit green value, a 5-bit red value, and a "don't care" bit (most significant), in little-endian order (RGB 5:5:5). Stores the data into a RGB15 packed format ...
 |  | UserArrayPtr info Data type: array of type unsigned char Array size: Dx x Dy x 2 bytes (unsigned char)
Open Collapse M_RGB16 | Stores the data into a RGB16 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 6-bit green value, and a 5-bit red value (most significant), in little-endian order (RGB 5:6:5). Stores the data into a RGB16 packed format ...
 |  | UserArrayPtr info Data type: array of type unsigned char Array size: Dx x Dy x 2 bytes (unsigned char)
Band

Specifies the index of the color band in which to copy. This parameter can be set to one of the values below.

Open Collapse Value Description
Open Collapse 0 <= Value <= #bands - 1

 Specifies the index of the band to copy.  Specifies the index of the band to copy ...

 The relationship between index value and band for RGB and HLS buffers is the following:

0 | Corresponds to the red band for RGB buffers or the hue band for HLS buffers.
1 | Corresponds to the green band for RGB buffers or the saturation band for HLS buffers.
2 | Corresponds to the blue band for RGB buffers or the luminance band for HLS buffers.

  Open   Collapse  M_ALL_BANDS

 Copies to all color bands.  Copies to all color bands.

  Open   Collapse  M_BLUE

 Copies to the blue color band (for RGB buffers).  Copies to the blue color band (for RGB buffers).

  Open   Collapse  M_GREEN

 Copies to the green color band (for RGB buffers).  Copies to the green color band (for RGB buffers).

  Open   Collapse  M_HUE

 Copies to the hue color band (for HLS buffers).  Copies to the hue color band (for HLS buffers).

  Open   Collapse  M_LUMINANCE

 Copies to the luminance color band (for HLS buffers).  Copies to the luminance color band (for HLS buffers).

  Open   Collapse  M_RED

 Copies to the red color band (for RGB buffers).  Copies to the red color band (for RGB buffers).

  Open   Collapse  M_SATURATION

 Copies to the saturation color band (for HLS buffers).  Copies to the saturation color band (for HLS buffers).

 UserArrayPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type char
    •

  • array of type unsigned char
    •

  • array of type long
    •

  • array of the same type as the buffer
    •

  • long
    •

 Specifies the address of the user array from which to copy data into the destination buffer.  Ensure that there are enough entries in the user array to fill the color band of the destination buffer.

PACKED ALL BANDS PACKED   PACKED PLANAR SINGLE BAND BGR24 BGR32 RGB15 RGB16  ALL BANDS BLUE GREEN HUE LUMINANCE RED SATURATION


MbufPutLine

Example | Availability | MbufPutColor | MbufRestore
There are no examples containing MbufPutLine().
Available in MIL-Lite

Available in MIL
Synopsis
Write a specified series of pixels along a specified theoretical line.
Syntax
void MbufPutLine(
MIL_ID ImageBufId,
long StartX,
long StartY,
long EndX,
long EndY,
long Mode,
long *NbPixelsPtr,
void *UserArrayPtr
)
Description

This function reads pixel values from a user-defined array and writes them to the series of pixels, in the specified image, along the theoretical line defined by specified coordinates. The Bresenham algorithm is used to determine the theoretical line.

Parameters
ImageBufId

Specifies the identifier of the destination image buffer. This must be a single-band (monochrome) buffer.

StartX

Specifies the horizontal pixel offset of the starting position of the line, relative to the top-left pixel of the source buffer.

StartY

Specifies the vertical pixel offset of the starting position of the line, relative to the top-left pixel of the source buffer.

EndX

Specifies the horizontal pixel offset of the finishing position on the line, relative to the top-left pixel of the source buffer.

EndY

Specifies the vertical pixel offset of the finishing position on the line, relative to the top-left pixel of the source buffer.

Mode

Specifies the operation mode. This parameter must be set to M_DEFAULT.

NbPixelsPtr

Specifies the address of the variable in which to write the number of pixels found along the theoretical line. You can set this parameter to M_NULL if you don't want this value to be evaluated.

UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of the same type as the buffer

Specifies the address of the user array containing the pixels to insert in the image buffer. Ensure that the user array contains all the pixel values to be written. To determine the number of pixel values required, you can set this parameter to M_NULL and pass a non-null address to NbPixelsPtr. In this case, nothing is written to the image buffer.


MbufRestore

See Also | Example | Availability | MbufPutLine | MbufSave
User Guide:
Managing data buffers
Loading and generating data into LUTs
Managing color images

Reference:
MappGetError
MbufImport
MbufInquire
MsysAlloc
dtkaddconstantmain.c
dtkremap.c
dtksyncasyncfunctionsmain.c
mblob.c
mcal.c
mcode.c
mdigautofocus.c
mdispoverlay.c
mdispwindowleveling.c
medge.c
mimconvolve.c
mimhistogram.c
mimperimeter.c
mimpolar.c
mimprocessing.c
mimsegment.c
mimwarp.c
mmeas.c
mmod.c
mnatfct.c
mpat.c
mstr.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL
Synopsis
Restore data from a file into an automatically allocated data buffer.
Syntax
MIL_ID MbufRestore(
MIL_TEXT_PTR FileName,
MIL_ID SystemId,
MIL_ID *BufIdPtr
)
Description

This function restores the data from the specified file and loads it into an automatically allocated buffer. It tries to detect the file format from the data.

If the file is in an M_MIL file format, this function will allocate the destination buffer with the same attributes as the original buffer, with the exception of an M_IMAGE buffer. In the case of an M_IMAGE buffer, the MbufRestore() function tries to allocate the buffer so that it can be used for acquisition (M_GRAB), display (M_DISP), and processing (M_PROC) operations. If there is insufficient appropriate memory to allocate such a buffer, it allocates one that can be used in all of the above operations except for acquisition (M_GRAB). Note that the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of MIL non-paged (DMA) memory (specified at installation time or using MilConfig). For systems with on-board processors, the total number of M_GRAB buffers and M_PROC buffers is limited by the amount of on-board memory.

[MIL-Lite with restriction]

When restoring compressed data, the buffer will have an M_COMPRESS attribute.

When restoring an image file that was saved with an associated LUT (color palette), the LUT is also restored and associated with the restored image buffer. You can obtain the identifier of the associated LUT, using MbufInquire().

After restoring a buffer, we recommend that you check that the operation was successful by using MappGetError() or by checking that the buffer identifier returned is not M_NULL.

Note, you can perform the same operation as MbufRestore() by using MbufImport(), which uses the specified file format to restore the data instead of trying to determine the format from the data.

Parameters
FileName

Specifies the name and path of the file from which to restore the data buffer.

SystemId

Specifies the system on which to allocate the buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 BufIdPtr

 Specifies the address of the variable in which the buffer identifier is to be written.  Since the MbufRestore() function also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the buffer identifier. If allocation fails, M_NULL is returned.

Remarks

  •  MIL-Lite does support M_IMAGE + M_PROC image buffers. However, the M_PROC attribute is not required to work under MIL-Lite.
    •

  •  Note that MIL-Lite compression support, particularly for M_IMAGE + M_COMPRESS buffer type, is reliant upon the presence of Matrox compression acceleration hardware; the compression algorithm supported depends on the hardware. If you don't have Matrox compression acceleration hardware, you can still perform compression under MIL-Lite with the compression/decompression runtime license package installed.
    •

MIL IMAGE IMAGE GRAB DISP PROC GRAB GRAB GRAB PROC COMPRESS IMAGE PROC PROC IMAGE COMPRESS   DEFAULT HOST


MbufSave

See Also | Example | Availability | MbufRestore | MbufTransfer
User Guide:
Managing data buffers
Managing color images

Reference:
MbufExport
There are no examples containing MbufSave().
Available in MIL-Lite

Available in MIL
Synopsis
Save a data buffer in a file, using the MIL output file format.
Syntax
void MbufSave(
MIL_TEXT_PTR FileName,
MIL_ID BufId
)
Description

This function saves a previously allocated data buffer to a file, in the MIL file format. This is a baseline TIFF 6.0 file format with extra information included in the comment field. The extra information includes the buffer attributes and data type.

The MIL file format supports images that are binary, grayscale, and RGB, as well as palette-color images. Images in a different format are internally converted before being saved. In addition, by default, most color image buffers are saved in a packed (chunky) format (in accordance with baseline TIFF 6.0 specifications). Color binary buffers are saved in a 1-bit per pixel format (data is stored in a 3-band, packed binary format).

When saving an image buffer (M_IMAGE) that has an associated LUT buffer (color palette), the content of the LUT is also saved with the image.

Note, you can perform the same operation as MbufSave() by using MbufExport() with its FileFormat parameter set to M_MIL.

Parameters
FileName

Specifies the name of the file in which to save the data buffer. If this file already exists, it will be overwritten.

BufId

Specifies the identifier of the data buffer to save.

Remark
  • This function is optimized for packed binary buffers.
IMAGE MIL


MbufTransfer

See Also | Example | Availability | MbufSave
Reference:
MimBinarize
There are no examples containing MbufTransfer().
Available in MIL-Lite

Available in MIL
Synopsis
Copy a two-dimensional region of one or all bands from the source buffer into a two-dimensional region of one or all bands in the destination buffer, using a specified transfer function and transfer type.
Syntax
void MbufTransfer(
MIL_ID SrcBufId,
MIL_ID DestBufId,
long SrcOffX,
long SrcOffY,
long SrcSizeX,
long SrcSizeY,
long SrcBand,
long DestOffX,
long DestOffY,
long DestSizeX,
long DestSizeY,
long DestBand,
long TransferFunction,
long TransferType,
long OperationFlag,
void *ExtraParameter
)
Description

This function copies a two-dimensional region of one or all color bands of the source buffer to a two-dimensional region of one or all bands of the destination buffer, using a specified transfer function and transfer type.

If the size of the regions in the source and destination buffers differ, the size of the largest region is reduced so that the size of the source and destination regions become equal.

The number of bands in the source and destination regions can be different. If the source is a single-band region and the destination is a multi-band region, the source region band is copied into each of the bands of the destination region using the specified transfer function. If the source is a 3-band region of a YUV buffer and the destination is a 1-band region, only the Y band (luminance) is copied. If the source is a 3-band region of a RGB buffer and the destination is a 1-band region, only the red band is copied. If both regions are multi-band, each source band is copied to the corresponding band of the destination.

In addition, if the source is from a 1-band image buffer associated with a LUT buffer and the destination is 3-band, the source data is first mapped through the LUT before being copied to the destination using the specified transfer function.

Note that when copying from a non-binary buffer to a binary destination buffer, all non-zero pixels in the source buffer are represented as ones (1) in the binary destination buffer. When copying a binary buffer to a buffer of a different depth, each bit is copied into the least-significant bit of a different destination pixel using the specified transfer function. The remaining bits of the destination pixel are set to 0; to propagate the bit value to all bits, use MimBinarize().

Note also that when copying from a floating-point buffer to an integer buffer, the values are truncated.

Parameters
SrcBufId

Specifies the identifier of the source buffer. When the TransferFunction parameter is set to M_CLEAR, set this parameter to M_NULL.

DestBufId

Specifies the identifier of the destination buffer.

SrcOffX

Specifies the horizontal offset of the source region, relative to the top-left coordinate of the source buffer.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default horizontal offset of the source region. The default is 0.  Specifies the default horizontal offset of the source region ...

  Open   Collapse  M_NULL

 Specifies that the horizontal offset of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.  Specifies that the horizontal offset of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.

  Open   Collapse  Value

 Specifies the horizontal offset of the source region, in pixels.  Specifies the horizontal offset of the source region, in pixels.

 SrcOffY

 Specifies the vertical offset of the source region, relative to the top-left coordinate of the source buffer.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default vertical offset of the source region. The default is 0.  Specifies the default vertical offset of the source region ...

  Open   Collapse  M_NULL

 Specifies that the vertical offset of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.  Specifies that the vertical offset of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.

  Open   Collapse  Value

 Specifies the vertical offset of the source region, in pixels.  Specifies the vertical offset of the source region, in pixels.

 SrcSizeX

 Specifies the width of the source region.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default width of the source region. The default is equal to the difference between the width of the source buffer and the horizontal offset of the source region.  Specifies the default width of the source region ...

  Open   Collapse  M_NULL

 Specifies that the width of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.  Specifies that the width of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.

  Open   Collapse  Value

 Specifies the width of the source region, in pixels.  Specifies the width of the source region, in pixels.

 SrcSizeY

 Specifies the height of the source region.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default height of the source region. The default is equal to the difference between the height of the source buffer and the vertical offset of the source region.  Specifies the default height of the source region ...

  Open   Collapse  M_NULL

 Specifies that the height of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.  Specifies that the height of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.

  Open   Collapse  Value

 Specifies the height of the source region, in pixels.  Specifies the height of the source region, in pixels.

 SrcBand

 Specifies the color band of the region from which to copy. This parameter can be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_ALL_BANDS.  Same as M_ALL_BANDS ...

  Open   Collapse  0 <= Value <= #bands - 1

 Specifies the index of the band to copy.  Specifies the index of the band to copy ...

 The relationship between the index value and band for RGB and HLS buffers is the following:

0 | Corresponds to the red band for RGB buffers or the hue band for HLS buffers.
1 | Corresponds to the green band for RGB buffers or the saturation band for HLS buffers.
2 | Corresponds to the blue band for RGB buffers or the luminance band for HLS buffers.

  Open   Collapse  M_ALL_BANDS

 Specifies all color bands (for RGB, HLS, and YUV buffers).  Specifies all color bands (for RGB, HLS, and YUV buffers).

  Open   Collapse  M_BLUE

 Specifies the blue band (for RGB buffers).  Specifies the blue band (for RGB buffers).

  Open   Collapse  M_GREEN

 Specifies the green band (for RGB buffers).  Specifies the green band (for RGB buffers).

  Open   Collapse  M_HUE

 Specifies the hue band (for HLS buffers).  Specifies the hue band (for HLS buffers).

  Open   Collapse  M_LUMINANCE

 Specifies the luminance band (for HLS buffers).  Specifies the luminance band (for HLS buffers).

  Open   Collapse  M_NULL

 Specifies that the band of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.  Specifies that the band of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.

  Open   Collapse  M_RED

 Specifies the red band (for RGB buffers).  Specifies the red band (for RGB buffers).

  Open   Collapse  M_SATURATION

 Specifies the saturation band (for HLS buffers).  Specifies the saturation band (for HLS buffers).

  Open   Collapse  M_U

 Specifies the U band (for YUV buffers).  Specifies the U band (for YUV buffers).

  Open   Collapse  M_V

 Specifies the V band (for YUV buffers).  Specifies the V band (for YUV buffers).

  Open   Collapse  M_Y

 Specifies the Y band (for YUV buffers).  Specifies the Y band (for YUV buffers).

 DestOffX

 Specifies the horizontal offset of the destination region, relative to the top-left coordinate of the destination buffer.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default horizontal offset of the destination region. The default is equal to the horizontal offset of the source region.  Specifies the default horizontal offset of the destination region ...

  Open   Collapse  Value

 Specifies the horizontal offset of the destination region, in pixels.  Specifies the horizontal offset of the destination region, in pixels.

 DestOffY

 Specifies the vertical offset of the destination region, relative to the top-left coordinate of the destination buffer.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default vertical offset of the destination region. The default is equal to the vertical offset of the source region.  Specifies the default vertical offset of the destination region ...

  Open   Collapse  Value

 Specifies the value of the vertical offset of the destination region, in pixels.  Specifies the value of the vertical offset of the destination region, in pixels.

 DestSizeX

 Specifies the width of the destination region.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default width of the destination region. The default is equal to the difference between the destination buffer width and the horizontal offset of the destination region.  Specifies the default width of the destination region ...

  Open   Collapse  Value

 Specifies the width of the destination region, in pixels.  Specifies the width of the destination region, in pixels.

 DestSizeY

 Specifies the height of the destination region.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default height of the destination region. The default is equal to the difference between the destination buffer height and the vertical offset of the destination region.  Specifies the default height of the destination region ...

  Open   Collapse  Value

 Specifies the height of the destination region, in pixels.  Specifies the height of the destination region, in pixels.

 DestBand

 Specifies the color band of the destination region in which to copy.  This parameter can be set to the same values as the SrcBand parameter, except for M_NULL.

 TransferFunction

 Specifies the function to use in the transfer. This parameter can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_BYTE_SWAP

 Specifies a transfer function that swaps the bytes in each pixel of the source region and copies the new pixels in the destination region. The depth of both the source and destination buffers must be 16- or 32-bit.  Specifies a transfer function that swaps the bytes in each pixel of the source region and copies the new pixels in the destination region ...

  Open   Collapse  M_CLEAR

 Specifies a transfer function that clears the destination region. Set all source buffer parameters to M_NULL.  Specifies a transfer function that clears the destination region ...

  Open   Collapse  M_COMPOSITION

 Specifies a transfer function that copies all pixels, except for pixels in the source region that are equal to the keying color specified by the OperationFlag parameter. If the source and destination buffers are of different data types, MIL converts the data automatically.  Specifies a transfer function that copies all pixels, except for pixels in the source region that are equal to the keying color specified by the OperationFlag parameter ...

  Open   Collapse  M_COPY

 Specifies a transfer function that copies the data from the source region into the destination region. If the source and destination buffers are of different data types, MIL converts the data automatically.  Specifies a transfer function that copies the data from the source region into the destination region ...

 TransferType

 Specifies the type of transfer.  If M_DEFAULT is not selected, then any combination of the transfer modes listed below can be specified for the TransferType parameter. From this combination of transfer modes, MIL selects the most efficient method to transfer data. If the most efficient transfer mode fails, then MIL automatically selects the next most efficient transfer mode from the combination of transfer modes. If all selected transfer modes fail, an error is returned. The efficiency of the transfer mode depends on the internal format of the source and destination buffers, as well as the hardware available in your computer.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Transfers data using the most efficient transfer mode among the transfer modes listed.  Transfers data using the most efficient transfer mode among the transfer modes listed ...

  Open   Collapse  M_DIB_MODE

 Transfers data using the DIB interface. Both the source and destination buffers must have the M_DIB attribute.  Transfers data using the DIB interface ...

 This transfer mode is only possible when the TransferFunction parameter is set to M_COPY.

  Open   Collapse  M_DIRECTX_MODE

 Transfers data using the DirectX interface. Both the source and destination buffers must have the M_DIRECTX attribute.  Transfers data using the DirectX interface ...

 This transfer mode is only possible when the TransferFunction parameter is set to M_CLEAR, M_COMPOSITION, or M_COPY.

  Open   Collapse  M_MIL_MODE

 Transfers data using the standard MIL mode.  Transfers data using the standard MIL mode ...

 This transfer mode is always possible.

      [Combination constants]

 You can add one of the following values to the TransferType parameter to specify whether to transfer the data synchronously or not. By default, the MbufTransfer() function chooses the value that is the most efficient for data transfer.

  Open   Collapse  Value
Description

  Open   Collapse  M_ASYNCHRONOUS

 Specifies that the transfer of data is not synchronous. This setting is only possible when the TransferType parameter is equal to M_DIRECTX_MODE.  Specifies that the transfer of data is not synchronous ...

  Open   Collapse  M_SYNCHRONOUS

 Specifies that the transfer of data is synchronous.  Specifies that the transfer of data is synchronous.

 OperationFlag

 Specifies the flag that is passed to the transfer function. When the TransferFunction parameter is set to M_COMPOSITION, the OperationFlag sets the keying color. When the TransferFunction parameter is set to M_CLEAR, the OperationFlag sets the color with which to clear the destination region.

 ExtraParameter

 Specifies an extra parameter that is passed to the transfer function for future use.

CLEAR CLEAR CLEAR CLEAR CLEAR CLEAR DEFAULT DIRECTX CLEAR COMPOSITION COPY DIB COPY DIRECTX MODE COMPOSITION CLEAR     DEFAULT NULL   DEFAULT NULL   DEFAULT NULL   DEFAULT NULL  DEFAULT ALL BANDS BLUE  GREEN  HUE LUMINANCE RED SATURATION U V Y NULL    DEFAULT   DEFAULT   DEFAULT   DEFAULT   COPY CLEAR COMPOSITION BYTE SWAP  DEFAULT MIL MODE DIRECTX MODE DIB MODE SYNCHRONOUS ASYNCHRONOUS


cal

Mcal functions

Example | Availability
There are no examples containing cal().
Not available in MIL-Lite

Available in MIL
Synopsis
The functions prefixed with Mcal make up the Calibration module. The Calibration module allows you to create a pixel coordinate to real-world coordinate mapping for your images, despite the presence of optical (for example, pincushion and barrel), aspect ratio, rotation, and perspective distortions in the images. Other MIL modules can use this mapping to compensate for distortions in the images, and return results in real-world units. The mapping can also be used to physically correct the distortions in the images. The calibration mapping can be created using a simple physical grid image or a list of points.
Functions
  • McalAlloc
  • McalAssociate
  • McalControl
  • McalFree
  • McalGrid
  • McalInquire
  • McalList
  • McalRelativeOrigin
  • McalRestore
  • McalSave
  • McalStream
  • McalTransformCoordinate
  • McalTransformCoordinateList
  • McalTransformImage
  • McalTransformResult


McalAlloc

See Also | Example | Availability | McalAssociate
User Guide:
Steps to getting results in real-world units

Reference:
McalGrid
McalList
MsysAlloc
mcal.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a calibration object.
Syntax
MIL_ID McalAlloc(
MIL_ID SystemId,
long Mode,
long ModeFlag,
MIL_ID *CalibrationIdPtr
)
Description

This function allocates a calibration object. Use McalGrid() or McalList() to define the pixel-to-world mapping for the calibration object.

Parameters
SystemId

Specifies the system on which to allocate the calibration object. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 Mode

 Specifies the default calibration mode.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_LINEAR_INTERPOLATION.  Same as M_LINEAR_INTERPOLATION.

  Open   Collapse  M_LINEAR_INTERPOLATION

 Specifies piecewise linear interpolation.  Specifies piecewise linear interpolation.

  Open   Collapse  M_PERSPECTIVE_TRANSFORMATION

 Specifies perspective transformation.  Specifies perspective transformation.

 ModeFlag

 Specifies the function's operation flag.  This parameter must be set to the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the function's operation flag to the default.  Sets the function's operation flag to the default.

 CalibrationIdPtr

 Specifies the address in which to return the identifier of the calibration object. Since McalAlloc() also returns the identifier, you can set this parameter to M_NULL.

Return value

 Returns the identifier of the calibration object if the operation was successful; M_NULL if the operation failed.

LINEAR INTERPOLATION  DEFAULT HOST   DEFAULT LINEAR INTERPOLATION
                 PERSPECTIVE TRANSFORMATION  DEFAULT


McalAssociate

See Also | Example | Availability | McalAlloc | McalControl
User Guide:
Steps to getting results in real-world units

Reference:
McalControl
mcal.c
Not available in MIL-Lite

Available in MIL
Synopsis
Associate/disassociate a calibration object to/from an image or digitizer
Syntax
void McalAssociate(
MIL_ID CalibrationId,
MIL_ID ImageOrDigitizerId,
long ControlFlag
)
Description

This function associates a calibration object to an image or digitizer. It can also be used to disassociate a calibration object from an image or digitizer. Note that you do not have to first disassociate a calibration object from an image or digitizer in order to associate a different calibration object to it.

The calibration object gets associated to the image, not to the buffer containing the image. This implies that if you copy or process the image, the operation will copy the image's calibration settings to the destination image.

When you grab an image with a calibrated digitizer, the calibration object currently associated to the digitizer gets associated to the grabbed image.

When you associate a calibration object to an image (either with a call to McalAssociate() or a grab with a calibrated digitizer), the image receives a copy of the calibration object's current relative coordinate system and current relative camera position and a reference to the calibration object for all other settings. When you associate a calibration object to a digitizer, the digitizer only receives a reference to the calibration object.

When a calibrated image is used within a MIL module, results from this module can be returned in pixel units or in real-world units; use the calibration object's M_OUTPUT_COORDINATE_SYSTEM control to specify your preference. This control is set by McalControl(). By default, this control is set to return results in real-world units.

Note that a few results are always returned in pixel units. If a result can be returned in either real-world or pixel units, it will be stated in the function description.

Parameters
CalibrationId

Specifies the identifier of the calibration object you want to associate. To disassociate a calibration object from an image or digitizer, set this parameter to M_NULL.

ImageOrDigitizerId

Specifies the identifier of the image or digitizer.

ControlFlag

Specifies the function's control flag. This parameter must be set to the following value:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Sets the function's control to the default.  Sets the function's control to the default.

OUTPUT COORDINATE SYSTEM    DEFAULT


McalControl

See Also | Example | Availability | McalAssociate | McalFree
User Guide:
Steps to getting results in real-world units
Coordinate systems and camera position
Multiple fields of view
Calculating and retrieving results

Reference:
McalGrid
McalTransformCoordinateList
McalTransformImage
mcal.c
Not available in MIL-Lite

Available in MIL
Synopsis
Control a calibration object parameter setting.
Syntax
void McalControl(
MIL_ID CalibrationId,
long ControlType,
double ControlValue
)
Description

This function changes a setting of a calibration object.

Parameters
CalibrationId

Specifies the identifier of the calibration object.

ControlType

Specifies the setting to change. The table below lists those settings that can be changed and their allowable values.

See the Parameter associations section for possible values.

ControlValue

Specifies the setting's new value.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_CAMERA_POSITION_X |  | Sets the relative X-position of the camera. Sets the relative X-position of the camera ...
 | Value | Specifies the position in world units. The default value is the origin (0).
Open Collapse M_CAMERA_POSITION_Y |  | Sets the relative Y-position of the camera. Sets the relative Y-position of the camera ...
 | Value | Specifies the position in world units. The default value is the origin (0).
Open Collapse M_CAMERA_POSITION_Z |  | Sets the relative Z-position of the camera. Sets the relative Z-position of the camera ...
 | M_DEFAULT | Implements the default behavior.
Open Collapse M_FOREGROUND_VALUE |  | Sets whether the grid's circles, used with McalGrid(), are lighter or darker than the background. Sets whether the grid's circles, used with McalGrid(), are lighter or darker than the background ...
 | M_DEFAULT | Determines the appropriate setting automatically.
 | M_FOREGROUND_BLACK | Specifies that the grid's circles are darker than the background.
 | M_FOREGROUND_WHITE | Specifies that the grid's circles are lighter than the background.
Open Collapse M_OUTPUT_COORDINATE_SYSTEM |  | Sets the output coordinate system in which to return results from operations on calibrated images. Sets the output coordinate system in which to return results from operations on calibrated images ...
 | M_PIXEL | Returns results in pixels.
 | M_WORLD | Returns results using world coordinates. This is the default value.
Open Collapse M_TRANSFORM_CACHE |  | Sets whether a cache used to accelerate the McalTransformCoordinateList() function is enabled or disabled. Sets whether a cache used to accelerate the McalTransformCoordinateList() function is enabled or disabled ...
 | M_DISABLE | Disables the cache. Disabling the cache saves memory but slows down subsequent calls to McalTransformImage().
 | M_ENABLE | Enables the cache. This is the default value.

CAMERA POSITION X CAMERA POSITION Y CAMERA POSITION Z DEFAULT FOREGROUND VALUE DEFAULT FOREGROUND BLACK FOREGROUND WHITE OUTPUT COORDINATE SYSTEM PIXEL WORLD TRANSFORM CACHE DISABLE ENABLE


McalFree

Example | Availability | McalControl | McalGrid
mcal.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free a calibration object.
Syntax
void McalFree(
MIL_ID CalibrationId
)
Description

This function frees a calibration object.

Parameter
CalibrationId

Specifies the identifier of the calibration object.


McalGrid

Example | Availability | McalFree | McalInquire
mcal.c
Not available in MIL-Lite

Available in MIL
Synopsis
Calibrate your imaging setup using a grid.
Syntax
void McalGrid(
MIL_ID CalibrationId,
MIL_ID SrcImageBufId,
double GridOffsetX,
double GridOffsetY,
double GridOffsetZ,
long RowNumber,
long ColumnNumber,
double RowSpacing,
double ColumnSpacing,
long Mode,
long ModeFlag
)
Description

This function uses an image of a user-defined grid of circles and the world description of this grid to calibrate your imaging setup. The mapping is stored with the specified calibration object.

To create an accurate (subpixel) mapping, your physical grid should meet the following guidelines (at the working resolution):

  • The radius of the grid's circles should range between 6 and 10 pixels.
  • The center-to-center distance between the grid's circles should range from 18 to 32 pixels (22 pixels recommended).
  • The minimum distance between the edges of the circles should be 6 pixels.
  • The grid should be large enough to cover the area of the image from which you want real-world results.
  • The grid image should have high contrast.
Parameters
CalibrationId

Specifies the identifier of the calibration object.

SrcImageBufId

Specifies the identifier of the image containing the grid. This image must be 8- or 16-bit unsigned, with 1 or 3 bands.

GridOffsetX

Specifies the X-offset from the top-left circle to the origin of the real-world coordinate system.

GridOffsetY

Specifies the Y-offset from the top-left circle to the origin of the real-world coordinate system.

GridOffsetZ

Specifies the Z-offset from the top-left circle to the origin of the real-world coordinate system. Must be set to M_NULL.

RowNumber

Specifies the number of rows in the calibration grid. The minimum number of rows is 2.

ColumnNumber

Specifies the number of columns in the calibration grid. The minimum number of columns is 2.

RowSpacing

Specifies the number of world units between rows.

ColumnSpacing

Specifies the number of world units between columns.

Mode

Specifies the calibration mode. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Uses the mode selected at allocation of the calibration object.  Uses the mode selected at allocation of the calibration object.

  Open   Collapse  M_LINEAR_INTERPOLATION

 Uses piecewise linear interpolation.  Uses piecewise linear interpolation.

  Open   Collapse  M_PERSPECTIVE_TRANSFORMATION

 Uses perspective transformation.  Uses perspective transformation.

 ModeFlag

 Specifies the type of grid used.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_CIRCLE_GRID

 Specifies a grid of circles.  Specifies a grid of circles.

      [Combination constants]

 To specify the orientation of the Y-axis, you can add one of the following to the ModeFlag parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

Same as M_Y_AXIS_DOWN.

  Open   Collapse  M_Y_AXIS_DOWN

 Orients the positive Y-axis 90° clockwise with respect to the positive X-axis.  Orients the positive Y-axis 90° clockwise with respect to the positive X-axis ...

  Open   Collapse  M_Y_AXIS_UP

 Orients the positive Y-axis 90° counter-clockwise with respect to the positive X-axis.  Orients the positive Y-axis 90° counter-clockwise with respect to the positive X-axis.

          DEFAULT  LINEAR INTERPOLATION
                 PERSPECTIVE TRANSFORMATION  CIRCLE GRID  DEFAULT Y AXIS DOWN Y AXIS UP


McalInquire

See Also | Example | Availability | McalGrid | McalList
User Guide:
Calibrating your imaging setup

Reference:
McalGrid
McalList
McalTransformCoordinateList
There are no examples containing McalInquire().
Not available in MIL-Lite

Available in MIL
Synopsis
Inquire about a calibration object setting or about the calibration object associated to an image or digitizer.
Syntax
long McalInquire(
MIL_ID CalibrationOrMilId,
long InquireType,
void *UserVarPtr
)
Description

This function inquires about a setting of a calibration object. It can also be used to inquire about the calibration object associated to an image or digitizer.

Parameters
CalibrationOrMilId

Specifies the identifier of the calibration object, image, or digitizer.

InquireType

Specifies the setting about which to inquire. The setting for InquireType depends on whether you are inquiring about a calibration object, calibrated image, or calibrated digitizer.

For a calibration object, InquireType can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_ASPECT_RATIO

Returns the average aspect ratio. Returns the average aspect ratio.

Open Collapse M_CALIBRATION_IMAGE_POINTS_X

Returns the X-coordinate of the image points. Returns the X-coordinate of the image points.

Open Collapse M_CALIBRATION_IMAGE_POINTS_Y

Returns the Y-coordinate of the image points. Returns the Y-coordinate of the image points.

Open Collapse M_CALIBRATION_MODE

Returns the calibration mode. Returns the calibration mode ...

UserVarPtr info

Return values:
M_DEFAULT, M_LINEAR_INTERPOLATION, M_PERSPECTIVE_TRANSFORMATION (details)
Open Collapse M_CALIBRATION_SUCCESSFUL

Returns whether the last call to McalGrid() or McalList() was successful. Returns whether the last call to McalGrid() or McalList() was successful ...

UserVarPtr info

Return values:
M_FALSE | Calibration was not successful.
M_TRUE | Calibration was successful.
Open Collapse M_CALIBRATION_WORLD_POINTS_X

Returns the X-coordinate of the real-world points. Returns the X-coordinate of the real-world points.

Open Collapse M_CALIBRATION_WORLD_POINTS_Y

Returns the Y-coordinate of the real-world points. Returns the Y-coordinate of the real-world points.

Open Collapse M_CAMERA_POSITION_X

Returns the relative X-position of the camera. Returns the relative X-position of the camera ...

UserVarPtr info

Return values:
Please see McalControl() with M_CAMERA_POSITION_X.

Open Collapse M_CAMERA_POSITION_Y

Returns the relative Y-position of the camera. Returns the relative Y-position of the camera ...

UserVarPtr info

Return values:
Please see McalControl() with M_CAMERA_POSITION_Y.

Open Collapse M_CAMERA_POSITION_Z

Returns the relative Z-position of the camera. Returns the relative Z-position of the camera ...

UserVarPtr info

Return values:
M_DEFAULT (details)
Open Collapse M_NUMBER_OF_CALIBRATION_POINTS

Returns the number of calibration points found by McalGrid() or passed to McalList(). Returns the number of calibration points found by McalGrid() or passed to McalList().

Open Collapse M_OUTPUT_COORDINATE_SYSTEM

Returns the coordinates the system used to return results. Returns the coordinates the system used to return results ...

UserVarPtr info

Return values:
M_PIXEL, M_WORLD (details)
Open Collapse M_PIXEL_SIZE_X

Returns the average pixel size in the X-direction. Returns the average pixel size in the X-direction.

Open Collapse M_PIXEL_SIZE_Y

Returns the average pixel size in the Y-direction. Returns the average pixel size in the Y-direction.

Open Collapse M_RELATIVE_ORIGIN_ANGLE

Orients the relative coordinate system to the given Angle, in degrees. Orients the relative coordinate system to the given Angle, in degrees.

Open Collapse M_RELATIVE_ORIGIN_X

Returns the X-coordinate of the origin of the relative coordinate system. Returns the X-coordinate of the origin of the relative coordinate system.

Open Collapse M_RELATIVE_ORIGIN_Y

Returns the Y-coordinate of the origin of the relative coordinate system. Returns the Y-coordinate of the origin of the relative coordinate system.

Open Collapse M_RELATIVE_ORIGIN_Z

Returns the Z-coordinate of the origin of the relative coordinate system. Returns the Z-coordinate of the origin of the relative coordinate system.

Open Collapse M_TRANSFORM_CACHE

Returns whether the cache used to accelerate McalTransformCoordinateList() is enabled or disabled. Returns whether the cache used to accelerateMcalTransformCoordinateList() is enabled or disabled ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

The InquireType parameter can be set to one of the following values if McalGrid() was used to perform the calibration:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_COLUMN_NUMBER | Returns the number of columns in the calibration grid. Returns the number of columns in the calibration grid.
Open Collapse M_COLUMN_SPACING | Returns the number of world units between columns. Returns the number of world units between columns.
Open Collapse M_FOREGROUND_VALUE | Returns whether the grid circles are lighter or darker than the background. Returns whether the grid circles are lighter or darker than the background ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_FOREGROUND_BLACK, M_FOREGROUND_WHITE (details)
Open Collapse M_GRID_ORIGIN_X | Returns the X-coordinate of the position within the absolute coordinate system associated to the circle in the top-left corner of the grid image. Returns the X-coordinate of the position within the absolute coordinate system associated to the circle in the top-left corner of the grid image.
Open Collapse M_GRID_ORIGIN_Y | Returns the Y-coordinate of the position within the absolute coordinate system associated to the circle in the top-left corner of the grid image. Returns the Y-coordinate of the position within the absolute coordinate system associated to the circle in the top-left corner of the grid image.
Open Collapse M_GRID_ORIGIN_Z | Returns the Z-coordinate of the position within the absolute coordinate system associated to the circle in the top-left corner of the grid image. Returns the Z-coordinate of the position within the absolute coordinate system associated to the circle in the top-left corner of the grid image.
Open Collapse M_ROW_NUMBER | Returns the number of rows in the calibration grid. Returns the number of rows in the calibration grid.
Open Collapse M_ROW_SPACING | Returns the number of world units between rows. Returns the number of world units between rows.

The InquireType parameter can be set to one of the following values only for an M_PERSPECTIVE_TRANSFORMATION calibration:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_AVERAGE_PIXEL_ERROR | Returns the average calibration error, in pixels. Returns the average calibration error, in pixels.
Open Collapse M_AVERAGE_WORLD_ERROR | Returns the average calibration error, in world units. Returns the average calibration error, in world units.
Open Collapse M_MAXIMUM_PIXEL_ERROR | Returns the maximum calibration error, in pixels. Returns the maximum calibration error, in pixels.
Open Collapse M_MAXIMUM_WORLD_ERROR | Returns the maximum calibration error, in world units. Returns the maximum calibration error, in world units.

For a calibrated image or digitizer, the InquireType parameter can be set to one of the following values:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_ASSOCIATED_CALIBRATION

Returns the identifier of its associated calibration object. Returns the identifier of its associated calibration object.

Open Collapse M_CORRECTION_STATE

Returns whether the image has been physically corrected using McalTransformCoordinateList(). Returns whether the image has been physically corrected using McalTransformCoordinateList() ...

UserVarPtr info

Return values:
M_FALSE | Image has not been corrected.
M_TRUE | Image has been corrected.

[Combination constants]

To inquire the default value of an inquire type, add the value below to the specified type.

Open Collapse Value | Description
Open Collapse M_DEFAULT | Returns the default value of the specified inquire type. Returns the default value of the specified inquire type ...
 |  | UserVarPtr info Data type: double

[Combination constants]

The values below can be added to the InquireType parameter to cast the requested information to the required data type. For example, M_CALIBRATION_IMAGE_POINTS_X + M_TYPE_SHORT.

Open Collapse Value | Description
Open Collapse M_TYPE_CHAR | Casts the requested information to a char. Casts the requested information to a char ...
 |  | UserVarPtr info Data type: char
Open Collapse M_TYPE_DOUBLE | Casts the requested information to a double. This is the default. Casts the requested information to a double ...
 |  | UserVarPtr info Data type: double
Open Collapse M_TYPE_FLOAT | Casts the requested information to a float. Casts the requested information to a float ...
 |  | UserVarPtr info Data type: float
Open Collapse M_TYPE_LONG | Casts the requested information to a long. Casts the requested information to a long ...
 |  | UserVarPtr info Data type: long
Open Collapse M_TYPE_SHORT | Casts the requested information to a short. Casts the requested information to a short ...
 |  | UserVarPtr info Data type: short
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • char
  • double
  • float
  • long
  • short

Specifies the address in which to return the value of the inquired setting.

Since McalInquire() also returns the value of the inquired setting, you can set UserVarPtr to M_NULL.

Return value
The returned value is the value of the inquired setting, cast to long.
PERSPECTIVE TRANSFORMATION CALIBRATION IMAGE POINTS X TYPE SHORT ASPECT RATIO CALIBRATION IMAGE POINTS X CALIBRATION IMAGE POINTS Y CALIBRATION MODE CALIBRATION SUCCESSFUL CALIBRATION WORLD POINTS X CALIBRATION WORLD POINTS Y CAMERA POSITION X CAMERA POSITION Y CAMERA POSITION Z NUMBER OF CALIBRATION POINTS OUTPUT COORDINATE SYSTEM PIXEL SIZE X PIXEL SIZE Y RELATIVE ORIGIN ANGLE RELATIVE ORIGIN X RELATIVE ORIGIN Y RELATIVE ORIGIN Z TRANSFORM CACHE COLUMN NUMBER COLUMN SPACING FOREGROUND VALUE GRID ORIGIN X GRID ORIGIN Y GRID ORIGIN Z ROW NUMBER ROW SPACING AVERAGE PIXEL ERROR AVERAGE WORLD ERROR MAXIMUM PIXEL ERROR MAXIMUM WORLD ERROR ASSOCIATED CALIBRATION CORRECTION STATE DEFAULT TYPE CHAR TYPE DOUBLE TYPE FLOAT TYPE LONG TYPE SHORT


McalList

Example | Availability | McalInquire | McalRelativeOrigin
There are no examples containing McalList().
Not available in MIL-Lite

Available in MIL
Synopsis
Calibrate your imaging setup using a list of coordinates.
Syntax
void McalList(
MIL_ID CalibrationId,
double *XPixArray,
double *YPixArray,
double *XWorldArray,
double *YWorldArray,
double *ZWorld,
long NumPoint,
long Mode,
long ModeFlag
)
Description

This function uses a list of pixel coordinates and their associated world coordinates to calibrate your imaging setup. The mapping is stored with the specified calibration object.

Parameters
CalibrationId

Specifies the identifier of the calibration object.

XPixArray

Specifies the address of the array containing the X-pixel coordinates.

YPixArray

Specifies the address of the array containing the Y-pixel coordinates.

XWorldArray

Specifies the address of the array containing the X-world coordinates.

YWorldArray

Specifies the address of the array containing the Y-world coordinates.

ZWorld

Specifies the address of the array containing the Z-world coordinates. This parameter must be set to M_NULL.

NumPoint

Specifies the number of coordinates in the supplied arrays. For a piecewise linear interpolation calibration mode, the minimum number of coordinates is 3. For a perspective transformation calibration mode, the minimum number of coordinates is 4. Note, the specified pixel coordinates should cover the area of the image from which you want real-world coordinates (the working area).

Mode

Specifies the calibration mode. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Uses the mode selected at allocation of the calibration object.  Uses the mode selected at allocation of the calibration object.

  Open   Collapse  M_LINEAR_INTERPOLATION

 Uses piecewise linear interpolation.  Uses piecewise linear interpolation.

  Open   Collapse  M_PERSPECTIVE_TRANSFORMATION

 Uses perspective transformation.  Uses perspective transformation.

 ModeFlag

 Specifies the function's operation flag.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the operation flag.  Sets the operation flag.

        DEFAULT LINEAR INTERPOLATION
 PERSPECTIVE TRANSFORMATION
  DEFAULT


McalRelativeOrigin

Example | Availability | McalList | McalRestore
There are no examples containing McalRelativeOrigin().
Not available in MIL-Lite

Available in MIL
Synopsis
Change the origin and/or orientation of a relative coordinate system.
Syntax
void McalRelativeOrigin(
MIL_ID CalibrationId,
double XOffset,
double YOffset,
double ZOffset,
double AngularOffset,
long ControlFlag
)
Description

This function changes the origin and/or orientation of a calibration object's relative coordinate system.

Note that real-world positional results are returned in the relative coordinate system.

Parameters
CalibrationId

Specifies the identifier of the calibration object.

XOffset

Specifies the X-offset from the absolute coordinate system origin to the relative coordinate system origin.

YOffset

Specifies the Y-offset from the absolute coordinate system origin to the relative coordinate system origin.

ZOffset

Specifies the X-offset from the absolute coordinate system origin to the relative coordinate system origin. The ZOffset parameter must be set to M_NULL.

AngularOffset

Specifies the angle, in degrees, at which to orient the relative coordinate system. This angle is taken at a counter-clockwise direction relative to the X-axis of the absolute coordinate system. Note that setting the XOffset, YOffset, ZOffset, and AngularOffset parameters to 0 has the effect of resetting the relative coordinate system to that of the absolute coordinate system.

ControlFlag

Specifies the function's control flag. This parameter must be set to the following value:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Sets the function's control flag to the default.  Sets the function's control flag to the default.

      DEFAULT


McalRestore

See Also | Example | Availability | McalRelativeOrigin | McalSave
Reference:
MsysAlloc
There are no examples containing McalRestore().
Not available in MIL-Lite

Available in MIL
Synopsis
Restore a calibration object from a file.
Syntax
MIL_ID McalRestore(
MIL_TEXT_PTR FileName,
MIL_ID SystemId,
long ControlFlag,
MIL_ID *CalibrationIdPtr
)
Description

This function restores a calibration object from a file and assigns it an identifier.

Parameters
FileName

Specifies the name of the file containing the calibration object.

SystemId

Specifies the system on which to restore the calibration object. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Specifies the function's control flag.  This parameter must be set to the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the function's control flag to the default.  Sets the function's control flag to the default.

 CalibrationIdPtr

 Specifies the address in which to return the identifier of the calibration object.  Since McalRestore() also returns the identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the identifier of the calibration object if the operation was successful; M_NULL if the operation failed.

  DEFAULT HOST   DEFAULT


McalSave

Example | Availability | McalRestore | McalStream
There are no examples containing McalSave().
Not available in MIL-Lite

Available in MIL
Synopsis
Save a calibration object to a file.
Syntax
void McalSave(
MIL_TEXT_PTR FileName,
MIL_ID CalibrationId,
long ControlFlag
)
Description

This function saves a calibration object to a file.

Parameters
FileName

Specifies the name of the file in which to save the calibration object. If the file contains any data, it is overwritten.

CalibrationId

Specifies the calibration object to save.

ControlFlag

Specifies the function's control flag. This parameter must be set to the following value:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Sets the function's control flag to the default.  Sets the function's control flag to the default.

   DEFAULT


McalStream

See Also | Example | Availability | McalSave | McalTransformCoordinate
Reference:
MappInquire
McalSave
MsysAlloc
There are no examples containing McalStream().
Not available in MIL-Lite

Available in MIL
Synopsis
Load, restore, or save a calibration object from/to a file or a memory stream.
Syntax
void McalStream(
MIL_TEXT_PTR MemPtrOrFileName,
MIL_ID SystemId,
long Operation,
long StreamType,
double Version,
long ControlFlag,
MIL_ID *CalibrationIdPtr,
long *SizeByteVarPtr
)
Description

This function can load or restore a calibration object from a file or memory stream. Moreover, this function can also save a calibration object to a file or memory stream.

To inquire the number of bytes necessary to save a calibration object to memory stream, you should call this function (McalStream()) first with M_INQUIRE_SIZE_BYTE.

The content saved to memory stream is equivalent to the content saved to file. In addition, any file saved with McalSave() is equivalent to a file saved using this function.

You can use this and other MIL stream functions, for example, to save all required MIL objects, as well as any other custom data, for your application to a memory stream. Once in a memory stream, you can write the stream to a single file or transfer it over a network. You are responsible for concatenating the streams and for saving the stream to file.

Parameters
MemPtrOrFileName

Specifies the file or memory stream.

When the StreamType parameter is set to M_FILE, MemPtrOrFileName specifies the name and path of the file required for the operation. The function internally handles the opening and closing of the file. If the file already exists, it will be overwritten when M_SAVE is performed.

When the StreamType parameter is set to M_MEMORY, MemPtrOrFileName specifies the address of the block of memory required for the operation. The designated block must be large enough to stream the entire object. To know the required size, call this function (McalStream()) first with M_INQUIRE_SIZE_BYTE.

When performing an M_INQUIRE_SIZE_BYTE operation, set this parameter to M_NULL.

SystemId

Specifies the system on which to restore the calibration object. For M_INQUIRE_SIZE_BYTE, M_LOAD, and M_SAVE, SystemId is ignored and should be set to M_NULL.

For an M_RESTORE operation, this parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 Operation

 Specifies the operation to perform on the calibration object. This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_INQUIRE_SIZE_BYTE

 Inquires the number of bytes required to save a calibration object to memory stream. This operation is not supported when the StreamType parameter is set to M_FILE.  Inquires the number of bytes required to save a calibration object to memory stream ...

  Open   Collapse  M_LOAD

 Loads the content of a specified file or memory stream into a previously allocated calibration object.  Loads the content of a specified file or memory stream into a previously allocated calibration object.

  Open   Collapse  M_RESTORE

 Restores a calibration object from a file or memory stream and assigns it an identifier.  Restores a calibration object from a file or memory stream and assigns it an identifier.

  Open   Collapse  M_SAVE

 Saves a calibration object to a specified file or memory stream.  Saves a calibration object to a specified file or memory stream.

 StreamType

 Specifies the type of stream that holds the calibration object.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_FILE

 Specifies a file stream.  Specifies a file stream.

  Open   Collapse  M_MEMORY

 Specifies a memory stream. You are responsible for allocating a block of memory for the stream.  Specifies a memory stream ...

 Version

 Specifies the MIL version of the calibration object. For M_LOAD and M_RESTORE, this parameter must be set to M_DEFAULT.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the version to current version of MIL.  Sets the version to current version of MIL.

  Open   Collapse  Value

 Sets the version to a specific version of MIL. This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.  Sets the version to a specific version of MIL ...

 The version specified must be greater or equal to 7.8 for a memory stream, and greater or equal to 6.0 for a file. The version specified must never be greater than the current MIL version. To know the current MIL version, call MappInquire() with M_VERSION.

 By supplying a specific version, you can control the calibration object's accessibility. For instance, if you allocate a calibration object using MIL 8.0 and set its version to 7.8, this object can be restored on a computer where MIL 7.8 is installed. However, all settings unique to the higher version will be ignored when opened in the lower version. Note that a program using MIL of a higher version can access a calibration object stream created or designated with a lower or equal version. Settings that do not exist in the lower version will be filled with default values when the file or memory stream is restored.

 ControlFlag

 Specifies the function's control flag and should be set to M_DEFAULT.

 CalibrationIdPtr

 Specifies the address of the variable in which to write or from which to read the identifier of the calibration object.

 For M_INQUIRE_SIZE_BYTE and M_SAVE operations, CalibrationIdPtr specifies the address of the variable from which to read the calibration object identifier.

 For an M_LOAD operation, the CalibrationIdPtr specifies the address of the variable from which to read the identifier of the calibration object where the file or memory stream content will be loaded.

 For an M_RESTORE operation, the CalibrationIdPtr specifies the address in which to return the identifier of the restored calibration object. If the operation is not successful, M_NULL is returned.

 SizeByteVarPtr

 Specifies the address of the variable in which to write the size of the calibration object, in bytes.

 If the size is not required, you can set this parameter to M_NULL.

 Note that the size of a calibration object will vary depending on the MIL version specified.

INQUIRE SIZE BYTE FILE SAVE MEMORY INQUIRE SIZE BYTE INQUIRE SIZE BYTE INQUIRE SIZE BYTE LOAD SAVE RESTORE FILE LOAD  RESTORE DEFAULT INQUIRE SIZE BYTE SAVE VERSION INQUIRE SIZE BYTE SAVE LOAD RESTORE   DEFAULT HOST   INQUIRE SIZE BYTE LOAD RESTORE SAVE  FILE MEMORY  DEFAULT


McalTransformCoordinate

See Also | Example | Availability | McalStream | McalTransformCoordinateList
User Guide:
Steps to getting results in real-world units
Calibration
Drawing graphics

Reference:
McalRelativeOrigin
There are no examples containing McalTransformCoordinate().
Not available in MIL-Lite

Available in MIL
Synopsis
Convert coordinates between their world and pixel values.
Syntax
void McalTransformCoordinate(
MIL_ID CalibrationOrMilId,
long TransformType,
double X,
double Y,
double *ResXPtr,
double *ResYPtr
)
Description

This function converts a pair of coordinates from their pixel value to their world value (or vice versa). The conversion can be performed according to a calibration object, calibrated image, or corrected image.

Note that, if you changed the origin and/or orientation of the relative coordinate system (using McalRelativeOrigin()), world coordinates will be returned, or assumed to be given, in this relative coordinate system.

Parameters
CalibrationOrMilId

Specifies the identifier of the calibration object, calibrated image, or corrected image.

Note that, to convert coordinates from a child image, you must set the CalibrationOrMilId parameter to the identifier of the corresponding child buffer.

TransformType

Specifies whether to perform a pixel-to-world or world-to-pixel conversion. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_PIXEL_TO_WORLD

 Converts from pixel to world.  Converts from pixel to world.

  Open   Collapse  M_WORLD_TO_PIXEL

 Converts from world to pixel.  Converts from world to pixel.

 X

 Specifies the X-coordinate of the input.

 Y

 Specifies the Y-coordinate of the input.

 ResXPtr

 Specifies the address in which to place the X-coordinate of the output.

 ResYPtr

 Specifies the address in which to place the Y-coordinate of the output.

  PIXEL TO WORLD WORLD TO PIXEL


McalTransformCoordinateList

See Also | Example | Availability | McalTransformCoordinate | McalTransformImage
User Guide:
Steps to getting results in real-world units
Drawing graphics

Reference:
McalRelativeOrigin
There are no examples containing McalTransformCoordinateList().
Not available in MIL-Lite

Available in MIL
Synopsis
Convert a list of coordinates between their world and pixel values.
Syntax
void McalTransformCoordinateList(
MIL_ID CalibrationOrMilId,
long TransformType,
double NumPoints,
double *SrcXPtr,
double *SrcYPtr,
double *ResXPtr,
double *ResYPtr
)
Description

This function converts a list of coordinates from their pixel value to their world value (or vice versa). The conversion can be performed according to a calibration object, calibrated image, or corrected image.

Note that, if you changed the origin and/or orientation of the relative coordinate system (using McalRelativeOrigin()), world coordinates will be returned, or assumed to be given, in this relative coordinate system.

Parameters
CalibrationOrMilId

Specifies the identifier of the calibration object, calibrated image, or corrected image. When an identifier of an image buffer is specified, the transformation uses the calibration object associated with this image. Note that, to convert coordinates from a child image, you must set the CalibrationOrMilId parameter to the identifier of the corresponding child buffer.

TransformType

Specifies whether to perform a pixel-to-world or world-to-pixel conversion. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_PIXEL_TO_WORLD

 Converts from pixel to world.  Converts from pixel to world.

  Open   Collapse  M_WORLD_TO_PIXEL

 Converts from world to pixel.  Converts from world to pixel.

 NumPoints

 Specifies the number of points in the coordinate list.

 SrcXPtr

 Specifies the address of the array of X-coordinates of the input.

 SrcYPtr

 Specifies the address of the array of Y-coordinates of the input.

 ResXPtr

 Specifies the address of the array in which to place the X-coordinates of the output.

 ResYPtr

 Specifies the address of the array in which to place the Y-coordinates of the output.

  PIXEL TO WORLD
 WORLD TO PIXEL


McalTransformImage

See Also | Example | Availability | McalTransformCoordinateList | McalTransformResult
User Guide:
Steps to getting results in real-world units
Coordinate systems and camera position

Reference:
McalTransformCoordinateList
mcal.c
Not available in MIL-Lite

Available in MIL
Synopsis
Physically transform an image to remove any distortions.
Syntax
void McalTransformImage (
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
MIL_ID CalibrationId,
long InterpolationMode,
long OperationType,
long ControlFlag
)
Description

This function removes distortions in an image by physically transforming it according to a specified calibration object.

The image is transformed such that:

  • It has an aspect ratio of 1.
  • Its relative coordinate system is aligned with its image coordinate system.
  • All of its pixels fit in the destination image, in accordance with the above two points.

Note that an image can only be transformed once. If you pass a transformed image to McalTransformCoordinateList(), it will just be copied to the destination image.

Parameters
SrcImageBufId

Specifies the identifier of the source image buffer.

DestImageBufId

Specifies the identifier of the destination image buffer. This buffer should be at least as large as the source image, so that it has at least the same number of pixels to represent all the information in the source image.

CalibrationId

Specifies the identifier of the calibration object.

InterpolationMode

Specifies the type of interpolation to perform when associating destination pixels to source points. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_BICUBIC

 Specifies bicubic interpolation.  Specifies bicubic interpolation.

  Open   Collapse  M_BILINEAR

 Specifies bilinear interpolation.  Specifies bilinear interpolation.

  Open   Collapse  M_NEAREST_NEIGHBOR

 Specifies nearest-neighbor interpolation.  Specifies nearest-neighbor interpolation.

      [Combination constants]

 To specify how to determine the value of a destination pixel when its associated point falls outside the source buffer, you can add one of the following defines to the InterpolationMode parameter:

  Open   Collapse  Value
Description

  Open   Collapse  M_OVERSCAN_CLEAR

 Sets the destination pixel to 0, if the associated point falls outside the source buffer.  Sets the destination pixel to 0, if the associated point falls outside the source buffer.

  Open   Collapse  M_OVERSCAN_DISABLE

 Leaves the destination pixel as is, if the associated point falls outside the source buffer.  Leaves the destination pixel as is, if the associated point falls outside the source buffer.

  Open   Collapse  M_OVERSCAN_ENABLE

 Uses pixels from the source buffer's ancestor buffer if the associated point falls outside the source buffer. If the source buffer is not a child buffer or if the associated point falls outside the ancestor buffer, leave the destination pixel as is.  Uses pixels from the source buffer's ancestor buffer if the associated point falls outside the source buffer ...

This is the default value.

 Note that the InterpolationMode parameter can be set to M_DEFAULT which is equivalent to M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE.

 OperationType

 Specifies the function's operation type.  This parameter must be set to the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the function's operation type.  Specifies the function's operation type.

 ControlFlag

 Specifies the function's control flag.  This parameter must be set to the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the function's control flag.  Specifies the function's control flag.

NEAREST NEIGHBOR OVERSCAN ENABLE     BICUBIC  BILINEAR  NEAREST NEIGHBOR OVERSCAN CLEAR OVERSCAN DISABLE
                   OVERSCAN ENABLE
                    DEFAULT  DEFAULT


McalTransformResult

Example | Availability | McalTransformImage
There are no examples containing McalTransformResult().
Not available in MIL-Lite

Available in MIL
Synopsis
Convert a result between its world and pixel value.
Syntax
void McalTransformResult(
MIL_ID CalibrationOrMilId,
long TransformType,
long ResultType,
double Result,
double *ResResult
)
Description

This function converts a specific result (a length, area, or angle) from its pixel-to-world value or from its world-to-pixel value. The conversion can be performed according to a calibration object, calibrated image, or corrected image. However, since this function uses the average pixel size to perform the conversion, results will be more accurate if you use a corrected image.

Parameters
CalibrationOrMilId

Specifies the identifier of the calibration object, calibrated image, or corrected image.

TransformType

Specifies whether to perform a pixel-to-world or world-to-pixel conversion. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_PIXEL_TO_WORLD

 Converts from pixel to world.  Converts from pixel to world.

  Open   Collapse  M_WORLD_TO_PIXEL

 Converts from world to pixel.  Converts from world to pixel.

 ResultType

 Specifies the type of result the given input value represents.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_ANGLE

 Represents an angle.  Represents an angle.

  Open   Collapse  M_AREA

 Represents an area.  Represents an area.

  Open   Collapse  M_LENGTH

 Represents a length (for example, the perimeter of an object).  Represents a length (for example, the perimeter of an object).

  Open   Collapse  M_LENGTH_X

 Represents a length in the X direction only.  Represents a length in the X direction only.

  Open   Collapse  M_LENGTH_Y

 Represents a length in the Y direction only.  Represents a length in the Y direction only.

 Result

 Specifies the input value.

 ResResult

 Specifies the address in which to place the output value.

  PIXEL TO WORLD WORLD TO PIXEL  ANGLE AREA  LENGTH  LENGTH X LENGTH Y


code

Mcode functions

Example | Availability
dtkaddconstantpaslave.c
Not available in MIL-Lite

Available in MIL
Synopsis
The functions prefixed with Mcode make up the Code module. The Code module allows you to read and write symbols (codes) from most popular one-dimensional (1D) and two-dimensional (2D) symbologies (code types). The supported 1D code types include Code39, Code128, Codabar, BC412, UPC-A, UPC-E, EAN-13, Interleaved 2 of 5, Planet, and Postnet. The supported 2D code types are Data Matrix, Maxicode, and PDF417. The module easily handles rotated, scaled, and degraded codes, even in complex scenes.
Functions
  • McodeAlloc
  • McodeControl
  • McodeFree
  • McodeGetResult
  • McodeInquire
  • McodeRead
  • McodeRestore
  • McodeSave
  • McodeStream
  • McodeVerify
  • McodeWrite


McodeAlloc

See Also | Example | Availability | McodeControl
User Guide:
Using MIL to read and write codes
Supported code types and noteworthy characteristics
Controlling read and write operations in MIL

Reference:
McodeControl
McodeFree
MsysAlloc
mcode.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a code object.
Syntax
MIL_ID McodeAlloc(
MIL_ID SystemId,
long CodeType,
long ControlFlag,
MIL_ID *CodeIdPtr
)
Description

This function allocates a code object. A code object is used to read or write a specific type of code. The control settings of the code object can be set using McodeControl(). When the code object is no longer needed, release it, using McodeFree().

Parameters
SystemId

Specifies the system on which to allocate the object. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 CodeType

 Specifies the type of code to read or write.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_BC412

 Sets the code type to BC412.  Sets the code type to BC412.

  Open   Collapse  M_CODABAR

 Sets the code type to Codabar.  Sets the code type to Codabar.

  Open   Collapse  M_CODE39

 Sets the code type to Code 39.  Sets the code type to Code 39.

  Open   Collapse  M_CODE93

 Sets the code type to Code 93.  Sets the code type to Code 93.

  Open   Collapse  M_CODE128

 Sets the code type to Code 128.  Sets the code type to Code 128.

  Open   Collapse  M_COMPOSITECODE

 Sets the code type to Composite code. The code type is a composite of a 1D and a 2D code type. Controls that apply to both 1D and 2D codes apply to this code type.  Sets the code type to Composite code ...

  Open   Collapse  M_DATAMATRIX

 Sets the code type to DataMatrix.  Sets the code type to DataMatrix ...

 This is a 2D code type.

  Open   Collapse  M_EAN8

 Sets the code type to EAN-8.  Sets the code type to EAN-8.

  Open   Collapse  M_EAN13

 Sets the code type to EAN-13.  Sets the code type to EAN-13.

  Open   Collapse  M_INTERLEAVED25

 Sets the code type to Interleaved 25.  Sets the code type to Interleaved 25 ...

M_INTERLEAVED25 is best used in a fixed-length application, with all reading equipment programmed to accept messages only of the correct length.

  Open   Collapse  M_MAXICODE

 Sets the code type to Maxicode.  Sets the code type to Maxicode ...

 This is a 2D code type.

  Open   Collapse  M_MICROPDF417

 Sets the code type to MicroPDF417.  Sets the code type to MicroPDF417 ...

 This is a 2D code type.

  Open   Collapse  M_PDF417

 Sets the code type to PDF417.  Sets the code type to PDF417 ...

 This is a 2D code type.

  Open   Collapse  M_PHARMACODE

 Sets the code type to Pharmacode.  Sets the code type to Pharmacode.

  Open   Collapse  M_PLANET

 Sets the code type to Planet.  Sets the code type to Planet.

  Open   Collapse  M_POSTNET

 Sets the code type to Postnet.  Sets the code type to Postnet.

  Open   Collapse  M_QRCODE

 Sets the code type to QR code.  Sets the code type to QR code.

  Open   Collapse  M_RSSCODE

 Sets the code type to RSS code.  Sets the code type to RSS code.

  Open   Collapse  M_UPC_A

 Sets the code type to UPC-A.  Sets the code type to UPC-A.

  Open   Collapse  M_UPC_E

 Sets the code type to UPC-E.  Sets the code type to UPC-E.

 ControlFlag

 Specifies the function's control flag.  This parameter must be set to M_DEFAULT.

 CodeIdPtr

 Specifies the address in which to return the identifier of the code object.  Since this function also returns the identifier, this parameter can be set to M_NULL.

Return value

 The returned value is the identifier of the code object if the allocation was successful; M_NULL if allocation failed.

INTERLEAVED25  DEFAULT HOST   BC412  CODABAR CODE39  CODE93 CODE128  COMPOSITECODE DATAMATRIX EAN8 EAN13  INTERLEAVED25 MAXICODE MICROPDF417 PDF417 PHARMACODE PLANET POSTNET QRCODE RSSCODE UPC A UPC E


McodeControl

See Also | Example | Availability | McodeAlloc | McodeFree
User Guide:
Using MIL to read and write codes
Supported code types and noteworthy characteristics
Controlling read and write operations in MIL
Verifying your code

Reference:
McodeRead
McodeWrite
mcode.c
Not available in MIL-Lite

Available in MIL
Synopsis
Control a code object setting.
Syntax
void McodeControl(
MIL_ID CodeId,
long ControlType,
double ControlValue
)
Description

This function changes a setting of a specified code object.

Parameters
CodeId

Specifies the identifier of the code object.

ControlType

Specifies the setting to change.

See the Parameter associations section for possible values.

ControlValue

Specifies the new value of the setting.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

The following ControlType and ControlValue settings apply to McodeRead() and McodeWrite() operations.

Open Collapse ControlType Description
ControlValue
Open Collapse M_16BIT_CHARACTER

Sets the character format to either 8 bits or 16 bits. Sets the character format to either 8 bits or 16 bits ...

This control only applies to the M_QRCODE code type. The 16-bit format can be used to handle Kanji (Japanese) characters, for example.

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the character format will be 8 bits.

M_ENABLE

Specifies that the character format will be 16 bits.

Open Collapse M_CELL_NUMBER_X

Sets the number of cells of a 2D code in the X direction. Sets the number of cells of a 2D code in the X direction ...

This control type is only used for 2D symbology (for example, M_DATAMATRIX and M_PDF417 type codes), not for bar codes. The number of cells is not required for Maxicode because it is a fixed size.

M_DEFAULT

Same as M_ANY.

M_ANY

Searches for a code with any number of cells, when performing an McodeRead() operation.

Fits the code string into the smallest possible number of cells, when performing an McodeWrite() operation.

Value > 0

Specifies the number of cells. This can be any integer value. Note that for the PDF417 code type, the value that you pass must be equal to 17c + 35, where c is the required number of columns, and 35 represents the number of cells required for the start and stop characters.

For the MicroPDF417 code type, this setting should be set to 38 for a one-column code, 55 for a two-column code, 82 for a three-column code and 99 for a four-column code.

Open Collapse M_CELL_NUMBER_Y

Sets the number of cells of a 2D code in the Y direction. Sets the number of cells of a 2D code in the Y direction ...

This control type is only used for 2D symbology (for example, M_DATAMATRIX and M_PDF417 type codes), not for bar codes. The number of cells is not required for Maxicode because it is a fixed size.

M_DEFAULT

Same as M_ANY.

M_ANY

Searches for a code with any number of cells, when performing an McodeRead() operation.

Fits the code string into the smallest possible number of cells, when performing an McodeWrite() operation.

Value > 0

Specifies the number of cells. This can be any integer value.

Open Collapse M_CELL_SIZE_MIN

Sets the minimum cell size. Sets the minimum cell size ...

M_DEFAULT

Specifies the default cell size, in pixels. The default depends on the operation and the code type. For a read operation, M_DEFAULT is equivalent to 1.

If you are using McodeWrite() with M_NULL to inquire about the minimum buffer size required, M_DEFAULT will be equivalent to either 10 for a Maxicode code type, or 4 for other bar codes types.

If you are using McodeWrite() and specify a buffer, M_DEFAULT causes the code to be resized so as to just fit into the target image of the operation.

Value > 0

Specifies the cell size, in pixels. This value can be any integer.

Open Collapse M_DATAMATRIX_SHAPE

Sets the shape of the Datamatrix code. Sets the shape of the Datamatrix code ...

M_DEFAULT

Same as M_ANY.

M_ANY

Specifies that the Datamarix can be any shape.

M_RECTANGLE

Specifies that the Datamatrix has a rectangular shape.

M_SQUARE

Specifies that the Datamatrix has a square shape.

Open Collapse M_ENCODING

Sets the type of encoding scheme. Sets the type of encoding scheme ...

M_DEFAULT

Specifies to use the default encoding scheme for the code type. A listing of the default encoding values is given in the following table:

BC412 | M_ENC_STANDARD
Codabar | M_ENC_STANDARD
Code39 | M_ENC_STANDARD
Code93 | M_END_ASCII
Code128 | M_ENC_ASCII
Composite | M_ENC_RSS14
Datamatrix | M_ANY
Ean8 | M_ENC_NUM
Ean13 | M_ENC_NUM
Interleaved25 | M_ENC_NUM
Maxicode | M_ANY
Micro PDF417 | M_ENC_STANDARD
PDF417 | M_ENC_STANDARD
Pharmacode | M_ENC_NUM
Planet | M_ENC_NUM
Postnet | M_ENC_NUM
QR | M_ANY
RSS | M_ENC_RSS14
UPC-A | M_ENC_NUM
UPC-E | M_ENC_NUM
M_ANY

Specifies any type of encoding scheme.

For read operations, M_ANY is supported by the M_DATAMATRIX, M_MAXICODE, and M_QRCODE code types.

For write operations, M_ANY is supported by the M_DATAMATRIX code type.

M_ENC_ALPHA

Specifies an encoding scheme that uses uppercase alphabetical characters, along with the space.

M_DATAMATRIX is the code type that can use this encoding scheme.

M_ENC_ALPHANUM

Specifies an encoding scheme that uses alphanumeric characters, as well as the space.

M_DATAMATRIX is the code type that can use this encoding scheme.

M_ENC_ALPHANUM_PUNC

Specifies a similar encoding scheme to M_ENC_ALPHANUM, except it also uses the (.), (,), (-) and (/) characters.

M_DATAMATRIX is the code type that can use this encoding scheme.

M_ENC_ASCII

Specifies an encoding scheme that uses ASCII characters.

M_DATAMATRIX, M_CODE39, M_CODE93, and M_CODE128 are the code types that can use this encoding scheme.

M_ENC_EAN8

Specifies an encoding scheme for a 2D composite code whose 1D portion uses an EAN-8 format.

M_COMPOSITECODE is the code type that can use this encoding scheme.

M_ENC_EAN13

Specifies an encoding scheme for a 2D composite code whose 1D portion uses an EAN-13 format.

M_COMPOSITECODE is the code type that can use this encoding scheme.

M_ENC_ISO8

Specifies a similar encoding scheme as M_ENC_ASCII, but uses the extended ASCII character set.

M_DATAMATRIX is the code type that can use this encoding scheme.

M_ENC_MODE2

Specifies an encoding scheme that uses a Structured Carrier Message. This encoding scheme can be used for a numeric postal code.

M_MAXICODE is the code type that can use this encoding scheme.

M_ENC_MODE3

Specifies an encoding scheme that uses a Structured Carrier Message. This encoding scheme can be used for an alphanumeric postal code.

M_MAXICODE is the code type that can use this encoding scheme.

M_ENC_MODE4

Specifies an encoding scheme that uses a Free Format Message.

M_MAXICODE is the code type that can use this encoding scheme.

M_ENC_MODE5

Specifies an encoding scheme that uses a Free Format Message. This data type has a higher level of error correction than M_ENC_MODE4.

M_MAXICODE is the code type that can use this encoding scheme.

M_ENC_MODE6

Specifies an encoding scheme that uses a Free Format Message. This encoding scheme indicates that the symbol encodes a message used to program the reader system.

M_MAXICODE is the code type that can use this encoding scheme.

M_ENC_NUM

Specifies an encoding scheme that uses numbers.

M_EAN13, M_DATAMATRIX, M_POSTNET, M_PLANET, M_UPC_A, M_UPC_E, M_PHARMACODE, M_EAN8, and M_INTERLEAVED25 are the code types that can use this encoding scheme. If the code type is M_DATAMATRIX, then spaces are also allowed.

M_ENC_QRCODE_MODEL1

Specifies an encoding scheme that uses a QR code format. This specifies an older version of QR code.

M_QRCODE is the code type that can use this encoding scheme.

M_ENC_QRCODE_MODEL2

Specifies an encoding scheme that uses a QR code format. This specifies a newer version of QR code, which can handle more data and is more robust than model 1.

M_QRCODE is the code type that can use this encoding scheme.

M_ENC_RSS14

Specifies an encoding scheme that uses an RSS-14 format.

M_COMPOSITECODE and M_RSSCODE are the code types that can use this encoding scheme.

M_ENC_RSS_EXPANDED

Specifies an encoding scheme that uses an RSS-14 Expanded format.

M_COMPOSITECODE and M_RSSCODE are the code types that can use this encoding scheme.

M_ENC_RSS_EXPANDED_STACKED

Specifies an encoding scheme that uses an RSS-14 Expanded Stacked format.

M_COMPOSITECODE and M_RSSCODE are the code types that can use this encoding scheme.

M_ENC_RSS_LIMITED

Specifies an encoding scheme that uses an RSS-14 Limited format.

M_COMPOSITECODE and M_RSSCODE are the code types that can use this encoding scheme.

M_ENC_RSS14_STACKED

Specifies an encoding scheme that uses an RSS-14 Stacked format.

M_COMPOSITECODE and M_RSSCODE are the code types that can use this encoding scheme.

M_ENC_RSS14_STACKED_OMNI

Specifies an encoding scheme that uses an RSS-14 Stacked Omni format.

M_COMPOSITECODE and M_RSSCODE are the code types that can use this encoding scheme.

M_ENC_RSS14_TRUNCATED

Specifies an encoding scheme that uses an RSS-14 Truncated format.

M_COMPOSITECODE and M_RSSCODE are the code types that can use this encoding scheme.

M_ENC_STANDARD

Specifies different types of encoding schemes, depending on what code type is used.

If M_CODE39 or M_CODE93 is the code type, M_ENC_STANDARD uses the alphabet (capital letters), digits 0 - 9, and the (-), space, ($), (/), (+), (.), (%) characters.

If M_BC412 is the code type, M_ENC_STANDARD uses numbers and the alphabet (capital letters), except for the letter O.

If M_PDF417 or M_MICROPDF417 is the code type, M_ENC_STANDARD uses ASCII and extended ASCII characters.

If M_CODABAR is the code type, M_ENC_STANDARD uses digits 0 - 9, the (-), ($), (:), (/), (.), and (+) characters, and the a,b,c, and d characters. It uses the latter four characters as start and stop characters.

M_ENC_UCCEAN128_MICROPDF417

Specifies an encoding scheme that uses a MicroPDF417 format.

M_COMPOSITECODE is the code type that can use this encoding scheme.

M_ENC_UCCEAN128_PDF417

Specifies an encoding scheme that uses a PDF417 format.

M_COMPOSITECODE is the code type that can use this encoding scheme.

M_ENC_UPCA

Specifies an encoding scheme that uses a UPC-A format.

M_COMPOSITECODE is the code type that can use this encoding scheme.

M_ENC_UPCE

Specifies an encoding scheme that uses a UPC-E format.

M_COMPOSITECODE is the code type that can use this encoding scheme.

Open Collapse M_ERROR_CORRECTION

Sets the type of error correction. Sets the type of error correction ...

M_DEFAULT

Specifies to use the default error correction schemes for the code type. A listing of the default error correction values is given in the following table:

BC412 | M_ECC_NONE
Codabar | M_ECC_NONE
Code39 | M_ECC_NONE
Code93 | M_ECC_CHECK_DIGIT
Code128 | M_ECC_CHECK_DIGIT
Composite | M_ECC_COMPOSITE
Datamatrix | M_ANY
Ean8 | M_ECC_CHECK_DIGIT
Ean13 | M_ECC_CHECK_DIGIT
Interleaved25 | M_ECC_NONE
Maxicode | M_ECC_REED_SOLOMON
Micro PDF417 | M_ECC_REED_SOLOMON
PDF417 | M_ANY
Pharmacode | M_ECC_NONE
Planet | M_ECC_CHECK_DIGIT
Postnet | M_ECC_CHECK_DIGIT
QR | M_ANY
RSS | M_ECC_CHECK_DIGIT
UPC-A | M_ECC_CHECK_DIGIT
UPC-E | M_ECC_CHECK_DIGIT
M_ANY

Detects the error correction type for read operations automatically. The M_DATAMATRIX, M_PDF417 and M_QRCODE code types can use this value.

M_ECC_200

Uses a Reed Solomon-based algorithm as an error correction scheme.

M_DATAMATRIX is the code type that can use this error correction scheme.

M_ECC_CHECK_DIGIT

Uses an additional digit to check whether there is an error or not. There is error detection but not correction.

M_EAN13, M_CODE39, M_CODE93, M_POSTNET, M_PLANET, M_UPC_A, M_UPC_E, M_INTERLEAVED25, M_RSSCODE, M_EAN8 and M_CODE128 are the code types that can use this error detection scheme.

M_ECC_COMPOSITE

Uses the appropriate error correction scheme for the 1D and 2D sections of the composite code.

M_COMPOSITECODE is the code type that can use this error correction scheme.

M_ECC_H

Uses the highest-level error correction scheme.

M_QRCODE is the code type that can use this error correction scheme.

M_ECC_L

Uses the lowest-level error correction scheme.

M_QRCODE is the code type that can use this error correction scheme.

M_ECC_M

Uses a lower-level error correction scheme.

M_QRCODE is the code type that can use this error correction scheme.

M_ECC_n

Specifies an error correction algorithm that uses convolution coding. The value of n must be a multiple of 10, between 010 and 140, excluding 20 and 30; n must be represented by three digits.

M_DATAMATRIX is the code type that can use this error correction scheme.

M_ECC_NONE

Specifies no error correction.

M_DATAMATRIX, M_CODE39, M_INTERLEAVED25, M_CODABAR, M_PHARMACODE and M_BC412 are the code types that can use this control value.

M_ECC_Q

Uses a higher-level error correction scheme.

M_QRCODE is the code type that can use this error correction scheme.

M_ECC_REED_SOLOMON

Uses a Reed Solomon type of error correction.

M_MAXICODE and M_MICROPDF417 are the code types that can use this error correction scheme.

M_ECC_REED_SOLOMON_n

Uses a Reed Solomon type of error correction. n is an integer from 0 to 8. The higher the number, the higher the level of error correction.

M_PDF417 is the code type that can use this error correction scheme.

Open Collapse M_FOREGROUND_VALUE

Sets the foreground color of the code. Sets the foreground color of the code ...

M_DEFAULT

Same as M_FOREGROUND_BLACK.

M_FOREGROUND_BLACK

Specifies the color as black.

M_FOREGROUND_WHITE

Specifies the color as white.

The possible ControlType and corresponding ControlValue settings that apply only to McodeRead() operations are:

Open Collapse ControlType Description
ControlValue
Open Collapse M_CELL_NUMBER_X_MAX

Sets the maximum number of cells to search for in the X direction of a 2D code. Sets the maximum number of cells to search for in the X direction of a 2D code ...

This control type only applies to the M_DATAMATRIX code type.

M_DEFAULT

Same as M_ANY.

M_ANY

Specifies that the control can search for any number of cells in the code.

Value > 0

Specifies the maximum number of cells for which to search. If a value is specified, it must be larger than M_CELL_NUMBER_X_MIN, otherwise an error will occur.

Open Collapse M_CELL_NUMBER_X_MIN

Sets the minimum number of cells to search for in the X direction of a 2D code. Sets the minimum number of cells to search for in the X direction of a 2D code ...

This control type only applies to the M_DATAMATRIX code type.

M_DEFAULT

Same as M_ANY.

M_ANY

Specifies that the control can search for any number of cells in the code.

Value > 0

Specifies the minimum number of cells for which to search. If a value is specified, it must be smaller than M_CELL_NUMBER_X_MAX, otherwise an error will occur.

Open Collapse M_CELL_NUMBER_Y_MAX

Sets the maximum number of cells to search for in the Y direction of a 2D code. Sets the maximum number of cells to search for in the Y direction of a 2D code ...

This control type only applies to the M_DATAMATRIX code type.

M_DEFAULT

Same as M_ANY.

M_ANY

Specifies that the control can search for any number of cells in the code.

Value > 0

Specifies the maximum number of cells for which to search. If a value is specified, it must be larger than M_CELL_NUMBER_Y_MIN, otherwise an error will occur.

Open Collapse M_CELL_NUMBER_Y_MIN

Sets the minimum number of cells to search for in the Y direction of a 2D code. Sets the minimum number of cells to search for in the Y direction of a 2D code ...

This control type only applies to the M_DATAMATRIX code type.

M_DEFAULT

Same as M_ANY.

M_ANY

Specifies that the control can search for any number of cells in the code.

Value > 0

Specifies the minimum number of cells for which to search. If a value is specified, it must be smaller than M_CELL_NUMBER_Y_MAX, otherwise an error will occur.

Open Collapse M_CELL_SIZE_MAX

Sets the maximum cell size. Sets the maximum cell size ...

M_DEFAULT

Selects an appropriate size, automatically.

Value

Specifies the size, in pixels. Any integer value can be chosen.

Open Collapse M_CHECK_FINDER_PATTERN

Sets whether the check for a false Datamatrix pattern is enabled. Sets whether the check for a false Datamatrix pattern is enabled ...

This value is only used for Datamatrix code types. This value should only be enabled if it is possible parts of your image could falsely be read as a Datamatrix code.

If this value is enabled, the read will be more robust, and false Datamatrix codes will not be read.

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that checking for false Datamatrix codes is disabled.

M_ENABLE

Specifies that checking for false Datamatrix codes is enabled.

Open Collapse M_DOT_SPACING

Sets the distance between 2 dots in a matrix code composed of dots. Sets the distance between 2 dots in a matrix code composed of dots ...

M_DOT_SPACING is half the distance between the edges of the dots in the code.

M_DEFAULT

Specifies no spacing.

0 to 256

Specifies half the distance between the edges of the dots, in pixels.

Open Collapse M_SCAN_REVERSE

Sets whether the barcode reader will scan the barcode left-to-right and right-to-left. Sets whether the barcode reader will scan the barcode left-to-right and right-to-left ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the barcode reader will not scan the barcode right-to-left.

M_ENABLE

Specifies that the barcode reader will scan in both directions.

Open Collapse M_SCANLINE_HEIGHT

Sets the scanline height when reading scanline-based barcodes. The scanline is the line, taken across the image, where McodeControl() tries to read the code information. The scanline is usually first taken across the middle of the image, and then, if the code is not found, it is taken either higher or lower in the image. Sets the scanline height when reading scanline-based barcodes ...

The scanline height is the thickness of the scanline.

This control overrides the automatic selection based on the value of M_SPEED. In general, the higher the value for the control, the faster the code will be read. Using the default value is recommended.

This control only applies to 1D code types and code types with 1D components.

M_DEFAULT

Specifies that the scanline height will be based on the value of M_SPEED. The higher the search speed, the higher the value for this control.

0 < Value <= 256

Specifies the scanline height as an integer pixel value. The higher this setting, the faster the code will be read.

Open Collapse M_SCANLINE_STEP

Sets the scanline frequency when reading scanline-based barcodes. The scanline is the line, taken across the image, where McodeControl() tries to read the code information. The scanline is usually first taken across the middle of the image, and then, if the code is not found, it is taken either higher or lower in the image. Sets the scanline frequency when reading scanline-based barcodes ...

The scanline step is the gap between scanlines.

This control overrides the automatic selection based on the value of M_SPEED. In general, the higher the value for the control, the faster the code will be read. The bigger the step, the more chance of missing a readable line of code. Using the default value is recommended.

This control applies to 1D code types and to the MicroPDF417 code type.

M_DEFAULT

Specifies that the scanline frequency will be based on the value of M_SPEED. The higher the search speed, the higher the value for this control.

1 < Value

Specifies the scanline frequency as an integer value. The higher this setting, the faster the code will be read.

Open Collapse M_SEARCH_ANGLE

Sets the nominal search angle. Sets the nominal search angle ...

The search is performed between the range of angles defined by: (M_SEARCH_ANGLE- M_SEARCH_ANGLE_DELTA_NEG) to (M_SEARCH_ANGLE + M_SEARCH_ANGLE_DELTA_POS), inclusively, starting with an angle closest to that of M_SEARCH_ANGLE.

For the PDF417, Maxicode, and Data Matrix codes, the angular range does not affect the speed of the operation.

M_DEFAULT

Specifies the default value. The default value is 0.0.

0.0 to 360.0

Searches at the specified angle.

Open Collapse M_SEARCH_ANGLE_DELTA_NEG

Sets the negative angle range of the search. Sets the negative angle range of the search ...

The search is performed between the range of angles defined by: (M_SEARCH_ANGLE- M_SEARCH_ANGLE_DELTA_NEG) to (M_SEARCH_ANGLE + M_SEARCH_ANGLE_DELTA_POS), inclusively, starting with an angle closest to that of M_SEARCH_ANGLE.

For the PDF417, Maxicode, and Data Matrix codes, the angular range does not affect the speed of the operation.

M_DEFAULT

Specifies the default value. The default value is 5.0.

0.0 to 180.0

Specifies a negative angle range in degrees.

Open Collapse M_SEARCH_ANGLE_DELTA_POS

Sets the positive angle range of the search. Sets the positive angle range of the search ...

The search is performed between the range of angles defined by: (M_SEARCH_ANGLE- M_SEARCH_ANGLE_DELTA_NEG) to (M_SEARCH_ANGLE + M_SEARCH_ANGLE_DELTA_POS), inclusively, starting with an angle closest to that of M_SEARCH_ANGLE.

For the PDF417, Maxicode, and Data Matrix codes, the angular range does not affect the speed of the operation.

M_DEFAULT

Specifies the default value. The default value is 5.0.

0.0 to 180.0

Specifies a positive angle range in degrees.

Open Collapse M_SPEED

Sets the search speed. The faster the search speed, the less robust the read operation. Sets the search speed ...

M_DEFAULT

Same as M_MEDIUM.

M_HIGH

Specifies a high search speed.

M_LOW

Specifies a low search speed.

M_MEDIUM

Specifies a medium search speed.

M_VERY_HIGH

Specifies a very high search speed.

M_VERY_LOW

Specifies a very low search speed.

Open Collapse M_STRING_SIZE

Sets the size of the string, encoded in the code, for which to search. Sets the size of the string, encoded in the code, for which to search ...

M_DEFAULT

Specifies the default string size.

For all code types, except BC 412, the default is M_ANY.

For the BC 412 code type, the default is 0 characters.

M_ANY

Searches for strings of any size.

Postnet and Planet codes can use this value. If M_ANY is used with a Postnet or Planet code, MIL will choose the appropriate string size.

Value

Specifies the size.

For a Postnet code, M_STRING_SIZE must be 5, 9, or 11.

For a Planet code, M_STRING_SIZE must be 11.

Open Collapse M_SUB_TYPE

Sets the particular codes in a family of codes for which to search during a read operation. Enabling fewer sub-types will help increase the speed of the read operation. Sets the particular codes in a family of codes for which to search during a read operation ...

Some versions of RSS codes only differ by their bar height and not their structure. In these cases, the read will be successful even if only one of the sub-types is enabled. For example, RSS-14 and RSS-14 Truncated can be read if either M_RSS14 or M_RSS14_TRUNCATED is enabled.

The sub-types are additive. If you enable M_UPCA and M_RSS14, you will be able to search for UPC A and RSS 14 codes. If you enabled sub-types previously, they would no longer be enabled.

M_DEFAULT

Specifies to use the default code sub-type. For most code sub-types, this will be the same as the code type allocated.

For the Composite and RSS code sub-types, M_DEFAULT is the same as M_ANY.

M_ANY

Specifies that all of the code sub-types that can be specified for M_SUB_TYPE will be used by the read operation.

Composite and RSS code types are the only code types that support this setting.

M_EAN8

Specifies that an EAN-8 code is enabled.

Composite code is the only code type that supports this setting.

M_EAN13

Specifies that an EAN-13 code is enabled.

Composite code is the only code type that supports this setting.

M_RSS14

Specifies that an RSS-14 code is enabled.

Composite code and RSS code are the only code types that support this setting.

M_RSS_EXPANDED

Specifies that an RSS-14 Expanded code is enabled.

Composite code and RSS code are the only code types that support this setting.

M_RSS_EXPANDED_STACKED

Specifies that an RSS-14 Expanded Stacked code is enabled.

Composite code and RSS code are the only code types that support this setting.

M_RSS_LIMITED

Specifies that an RSS-14 Limited code is enabled.

Composite code and RSS code are the only code types that support this setting.

M_RSS14_STACKED

Specifies that an RSS-14 Stacked code is enabled.

Composite code and RSS code are the only code types that support this setting.

M_RSS14_STACKED_OMNI

Specifies that an RSS-14 Stacked Omni code is enabled.

Composite code and RSS code are the only code types that support this setting.

M_RSS14_TRUNCATED

Specifies that an RSS-14 Truncated code is enabled.

Composite code and RSS code are the only code types that support this setting.

M_UCCEAN128

Specifies that an UPC/EAN-128 code is enabled.

Composite code is the only code type that supports this setting.

M_UPCA

Specifies that an UPC-A code is enabled.

Composite code is the only code type that supports this setting.

M_UPCE

Specifies that an UPC-E code is enabled.

Composite code is the only code type that supports this setting.

Open Collapse M_THRESHOLD

Sets the threshold value used to internally binarize the source image of a read operation. Sets the threshold value used to internally binarize the source image of a read operation ...

Note that, if the background is both darker and lighter than the code, a simple binarization will not separate the code from the background. In this case, you should process the image before performing the read operation so that the background is either darker or lighter than the code.

M_DEFAULT

Selects the best threshold value automatically, from the source image's histogram.

0<=Value<=255

Specifies the threshold value.

M_ADAPTIVE

Specifies that a fast dynamic local threshold will be used. M_ADAPTIVE will work better than M_DEFAULT in cases where the image has non-uniform lighting.

Open Collapse M_TIMEOUT

Specifies the maximum decoding time for a read operation. Specifies the maximum decoding time for a read operation ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that there is no maximum decoding time.

Value >= 0

Specifies the maximum decoding time, in msec.

Open Collapse M_USE_PRESEARCH

Sets whether the localization operation is performed prior to the decoding step (McodeRead()). This is only supported for 2D code types. Sets whether the localization operation is performed prior to the decoding step (McodeRead()) ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the operation is not performed.

M_ENABLE

Specifies that the operation is performed.

QRCODE DISABLE ANY ANY DEFAULT NULL DEFAULT DEFAULT ANY ANY DATAMATRIX MAXICODE QRCODE ANY DATAMATRIX DATAMATRIX DATAMATRIX ENC ALPHANUM DATAMATRIX DATAMATRIX CODE39 CODE93 CODE128 COMPOSITECODE COMPOSITECODE ENC ASCII DATAMATRIX MAXICODE MAXICODE MAXICODE ENC MODE4 MAXICODE MAXICODE EAN13 DATAMATRIX POSTNET PLANET UPC A UPC E PHARMACODE EAN8 INTERLEAVED25 DATAMATRIX QRCODE QRCODE COMPOSITECODE RSSCODE COMPOSITECODE RSSCODE COMPOSITECODE RSSCODE COMPOSITECODE RSSCODE COMPOSITECODE RSSCODE COMPOSITECODE RSSCODE COMPOSITECODE RSSCODE CODE39 CODE93 ENC STANDARD BC412 ENC STANDARD PDF417 MICROPDF417 ENC STANDARD CODABAR ENC STANDARD COMPOSITECODE COMPOSITECODE COMPOSITECODE COMPOSITECODE DATAMATRIX PDF417 QRCODE DATAMATRIX EAN13 CODE39 CODE93 POSTNET PLANET UPC A UPC E INTERLEAVED25 RSSCODE EAN8 CODE128 COMPOSITECODE QRCODE QRCODE QRCODE DATAMATRIX DATAMATRIX CODE39 INTERLEAVED25 CODABAR PHARMACODE BC412 QRCODE MAXICODE MICROPDF417 PDF417 DATAMATRIX PDF417 DATAMATRIX ANY CELL NUMBER X MIN DATAMATRIX ANY CELL NUMBER X MAX DATAMATRIX ANY CELL NUMBER Y MIN DATAMATRIX ANY CELL NUMBER Y MAX DISABLE DOT SPACING SPEED SPEED SPEED SPEED ANY ANY STRING SIZE STRING SIZE RSS14 RSS14 TRUNCATED UPCA RSS14 DEFAULT ANY SUB TYPE ADAPTIVE DEFAULT DISABLE SEARCH ANGLE SEARCH ANGLE DELTA NEG SEARCH ANGLE SEARCH ANGLE DELTA POS SEARCH ANGLE 16BIT CHARACTER DEFAULT DISABLE ENABLE CELL NUMBER X DEFAULT ANY CELL NUMBER Y DEFAULT ANY CELL SIZE MIN DEFAULT DATAMATRIX SHAPE DEFAULT ANY RECTANGLE SQUARE ENCODING DEFAULT ANY ENC ALPHA ENC ALPHANUM ENC ALPHANUM PUNC ENC ASCII ENC EAN8 ENC EAN13 ENC ISO8 ENC MODE2 ENC MODE3 ENC MODE4 ENC MODE5 ENC MODE6 ENC NUM ENC QRCODE MODEL1 ENC QRCODE MODEL2 ENC RSS14 ENC RSS EXPANDED ENC RSS EXPANDED STACKED ENC RSS LIMITED ENC RSS14 STACKED ENC RSS14 STACKED OMNI ENC RSS14 TRUNCATED ENC STANDARD ENC UCCEAN128 MICROPDF417 ENC UCCEAN128 PDF417 ENC UPCA ENC UPCE ERROR CORRECTION DEFAULT ANY ECC 200 ECC CHECK DIGIT ECC COMPOSITE ECC H ECC L ECC M ECC n ECC NONE ECC Q ECC REED SOLOMON ECC REED SOLOMON n FOREGROUND VALUE DEFAULT FOREGROUND BLACK FOREGROUND WHITE CELL NUMBER X MAX DEFAULT ANY CELL NUMBER X MIN DEFAULT ANY CELL NUMBER Y MAX DEFAULT ANY CELL NUMBER Y MIN DEFAULT ANY CELL SIZE MAX DEFAULT CHECK FINDER PATTERN DEFAULT DISABLE ENABLE DOT SPACING DEFAULT SCAN REVERSE DEFAULT DISABLE ENABLE SCANLINE HEIGHT DEFAULT SCANLINE STEP DEFAULT SEARCH ANGLE DEFAULT SEARCH ANGLE DELTA NEG DEFAULT SEARCH ANGLE DELTA POS DEFAULT SPEED DEFAULT VERY LOW LOW MEDIUM HIGH VERY HIGH STRING SIZE DEFAULT ANY SUB TYPE DEFAULT ANY EAN8 EAN13 RSS14 RSS EXPANDED RSS EXPANDED STACKED RSS LIMITED RSS14 STACKED RSS14 STACKED OMNI RSS14 TRUNCATED UCCEAN128 UPCA UPCE THRESHOLD DEFAULT ADAPTIVE TIMEOUT DEFAULT DISABLE USE PRESEARCH DEFAULT DISABLE ENABLE


McodeFree

Example | Availability | McodeControl | McodeGetResult
mcode.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free a code object.
Syntax
void McodeFree(
MIL_ID CodeId
)
Description

This function frees a code object.

Parameter
CodeId

Specifies the identifier of the code object.


McodeGetResult

See Also | Example | Availability | McodeFree | McodeInquire
User Guide:
Using MIL to read and write codes
Controlling read and write operations in MIL
Retrieving results
Verifying your code

Reference:
McalControl
McodeRead
McodeVerify
McodeWrite
mcode.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified type of result, obtained from a code read, write, or verify operation.
Syntax
void McodeGetResult(
MIL_ID CodeId,
long ResultType,
void *ResultPtr
)
Description

This function retrieves the result(s) of the specified type from a code object. Results are only available after calling McodeRead(), McodeWrite(), or McodeVerify().

McodeGetResult() in combination with McodeWrite() can also be used to determine the required image buffer size to encode a given string. First, call McodeWrite() with ImageBufId set to M_NULL and then call McodeGetResult() to retrieve the minimum width (M_WRITE_SIZE_X) and height (M_WRITE_SIZE_Y) required for the code.

Note that if your target image has been associated with a calibration object, positional results are, by default, returned in real-world units. To have results returned in pixel units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to M_PIXEL. If the target image is not calibrated, positional results are returned in pixels, relative to the top-left pixel in the target image.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set ResultPtr to M_NULL. When this parameter is set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when you pass the parameter an array instead. You must ensure that the array is sufficiently large to hold the current and previously queued results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
CodeId

Specifies the identifier of the code object used in the read, write, or verify operation.

ResultType

Specifies the type of result(s) to retrieve. This parameter should be set to one of the following values.

The following values are available to retrieve results from a code read operation.

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_ANGLE

Retrieves the angle at which the code was read. Retrieves the angle at which the code was read.

Open Collapse M_CELL_NUMBER_X

Retrieves the number of cells of a 2D code in the X-direction. Retrieves the number of cells of a 2D code in the X-direction.

Open Collapse M_CELL_NUMBER_Y

Retrieves the number of cells of a 2D code in the Y-direction. Retrieves the number of cells of a 2D code in the Y-direction.

Open Collapse M_CELL_SIZE

Retrieves the cell size of the code that was read. Retrieves the cell size of the code that was read.

Open Collapse M_ENCODING

Retrieves the type of encoding. Retrieves the type of encoding ...

Note that since some versions of RSS code types only differ by the bar height (and not the structure), the same result is returned for these similar code types. RSS-14 and RSS-14 Truncated will return M_ENC_RSS14. RSS-14 Stacked and RSS-14 Stacked Omnidirectional will return M_ENC_RSS14_STACKED.

ResultPtr info

Return values:
M_ANY, M_ENC_ALPHA, M_ENC_ALPHANUM, M_ENC_ALPHANUM_PUNC, M_ENC_ASCII, M_ENC_EAN8, M_ENC_EAN13, M_ENC_ISO8, M_ENC_MODE2, M_ENC_MODE3, M_ENC_MODE4, M_ENC_MODE5, M_ENC_MODE6, M_ENC_NUM, M_ENC_QRCODE_MODEL1, M_ENC_QRCODE_MODEL2, M_ENC_RSS14, M_ENC_RSS_EXPANDED, M_ENC_RSS_EXPANDED_STACKED, M_ENC_RSS_LIMITED, M_ENC_RSS14_STACKED, M_ENC_RSS14_STACKED_OMNI, M_ENC_RSS14_TRUNCATED, M_ENC_STANDARD, M_ENC_UCCEAN128_MICROPDF417, M_ENC_UCCEAN128_PDF417, M_ENC_UPCA, M_ENC_UPCE (details)
Open Collapse M_ERROR_CORRECTION

Retrieves the type of error correction. Retrieves the type of error correction ...

ResultPtr info

Return values:
M_ANY, M_ECC_200, M_ECC_CHECK_DIGIT, M_ECC_COMPOSITE, M_ECC_H, M_ECC_L, M_ECC_M, M_ECC_n, M_ECC_NONE, M_ECC_Q, M_ECC_REED_SOLOMON, M_ECC_REED_SOLOMON_n (details)
M_ECC_UNKNOWN (unknown error correction type)

Open Collapse M_SCORE

Retrieves the confidence score of a read operation. Retrieves the confidence score of a read operation.

Open Collapse M_STRING

Retrieves the decoded string. The flag M_ESCAPE_SEQUENCE can be added to this result type to return the string in a special format that puts the ASCII codes for non-printing characters in a \xNN format where NN is the hexadecimal value of the ASCII code for the unprintable character. Retrieves the decoded string ...

If the string is decoded from a composite code, the string is returned in the following format: 1D string|2D string, where | is used as the seperator.

ResultPtr info

Data type: array of type MIL_TEXT_CHAR
Array size: large enough to contain the decoded string (M_STRING_SIZE)

Open Collapse M_STRING_SIZE

Retrieves the length of the decoded string. The value M_ESCAPE_SEQUENCE can be added to this result type to return the length of the string, including all ASCII characters used to encode the non-printing characters in the count. Retrieves the length of the decoded string ...

Open Collapse M_THRESHOLD

Retrieves the threshold value used to internally binarize the source image of a read operation. Retrieves the threshold value used to internally binarize the source image of a read operation.

[Combination constants]

The following value can be added to M_STRING and M_STRING_SIZE.

Open Collapse Value | Description
Open Collapse M_ESCAPE_SEQUENCE | Retrieves the string in a special format when combined with M_STRING. Any back slashes (\) in the string are doubled, while unprintable characters, such as carriage returns, are put in a \xNN format, where NN is the hexadecimal value of the ASCII code for the unprintable character. Retrieves the string in a special format when combined with M_STRING ... When combined with M_STRING_SIZE, it returns the size of the special format string.

The following values are available to retrieve results from a code verify operation.

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_AXIAL_NONUNIFORMITY_GRADE

Retrieves the grade for the axial nonuniformity of the code. The axial nonuniformity is a measure of how spacing between sampling points differs from one axis to another (width to height). Retrieves the grade for the axial nonuniformity of the code ...

This is available for the DataMatrix, QR code, and Maxicode code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_DECODABILITY_GRADE

Retrieves the grade for the decodability of the code. Decodability is a measure of how close the scan reflectance profile is to decode failure. Retrieves the grade for the decodability of the code ...

The scan reflectance profile is a record of values measured along a line across the width of a bar code (line profile). There are nine values that affect the grade of the scan reflectance profile: decodability, decode, defects, edge determination, minimum edge contrast, minimum reflectance, modulation, start/stop pattern, and symbol contrast.

This is available for all 1D barcodes, composite codes, RSS codes and the PDF417 code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_DECODE_GRADE

Retrieves the decode grade. MIL takes the sequence of marks and spaces in a code and decodes them into a series of digits and guard patterns. Retrieves the decode grade ...

This is available for all code types. For codes other than 1D barcodes, only M_CODE_GRADE_A, M_CODE_GRADE_F, and M_CODE_GRADE_NOT_AVAILABLE are available.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_DEFECTS_GRADE

Retrieves the grade for the defects of the code. Spots or voids in the code are considered to be defects. The more spots or voids, the lower the grade. Retrieves the grade for the defects of the code ...

This is available for all 1D barcodes, composite codes, RSS codes and the PDF417 code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_EDGE_DETERMINATION_GRADE

Retrieves the grade for whether the code has an appropriate number of bars and spaces. Retrieves the grade for whether the code has an appropriate number of bars and spaces ...

This is available for all 1D barcodes, composite codes, RSS codes and the PDF417 code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_MINIMUM_EDGE_CONTRAST_GRADE

Retrieves the grade for the minimum edge contrast of the code. Minimum edge contrast is the minimum contrast between bars and their adjacent spaces. The smallest difference allowed is 15%. Retrieves the grade for the minimum edge contrast of the code ...

This is available for all 1D barcodes, composite codes, RSS codes and the PDF417 code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_MINIMUM_REFLECTANCE_GRADE

Retrieves the grade for the minimum reflectance of the code. Reflectance is the ratio of light which is reflected back from the white spaces of a bar code during scanning to the amount of light reflected under similar illumination conditions. The darkest bar should have a reflectance less than half of the background; if not, the code will receive a failing grade. Retrieves the grade for the minimum reflectance of the code ...

This is available for all 1D barcodes, composite codes, RSS codes and the PDF417 code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_MODULATION_GRADE

Retrieves the grade for the edge contrast as a proportion of code contrast. The closer the edge contrast to the code contrast, the higher the grade. A higher grade means less chance of a poor reading result. Retrieves the grade for the edge contrast as a proportion of code contrast ...

This is available for all 1D barcodes, composite codes, RSS codes and the PDF417 code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_OVERALL_SYMBOL_GRADE

Retrieves the worst grade obtained for the results of the code. Retrieves the worst grade obtained for the results of the code ...

This is available for all code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_PRINT_GROWTH_GRADE

Retrieves the grade for the print growth of the code. The print growth is the extent in which the boundaries of the black and white markings are within their module's boundaries. Retrieves the grade for the print growth of the code ...

This is available for the DataMatrix, QR code, and Maxicode code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_RAP_GRADE

Retrieves the grade for the Row Address Patterns (RAP) of the code. This verifies how close a scanned code's RAP stands to its ideal pattern. Retrieves the grade for the Row Address Patterns (RAP) of the code ...

This is available for composite codes and the MicroPDF417 code type.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_START_STOP_PATTERN_GRADE

Retrieves the grade for the start/stop pattern of the code. The start/stop pattern is a set pattern that marks the end points of the code. Retrieves the grade for the start/stop pattern of the code ...

This is available for composite code and the PDF417 code type.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_SYMBOL_BASED_GRADE

Retrieves the grade for the code's pattern. This grade is a measure of how close a scanned code's pattern stands to its ideal pattern. Retrieves the grade for the code's pattern ...

This is available for the composite code, MicroPDF417, and PDF417 code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_SYMBOL_CONTRAST_GRADE

Retrieves the grade for the code contrast. The higher the contrast, the better it is for scanning purposes and the better the grade. Retrieves the grade for the code contrast ...

This is available for all codes except the MicroPDF417 code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.
Open Collapse M_UNUSED_ERROR_CORRECTION_GRADE

Retrieves the grade for the error correction in the code. This tests the extent to which regional or spot damage in the code has eroded the reading safety margin that error correction provides. Retrieves the grade for the error correction in the code ...

This is available for the DataMatrix, QR code, and Maxicode code types.

ResultPtr info

Return values:
M_CODE_GRADE_A | Best grade for the result.
M_CODE_GRADE_B | Good grade for the result.
M_CODE_GRADE_C | Fair grade for the result.
M_CODE_GRADE_D | Poor grade for the result.
M_CODE_GRADE_F | Worst grade for the result.
M_CODE_GRADE_NOT_AVAILABLE | The result is not available for the code.

The following values are able to retrieve results from a code write operation.

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_WRITE_SIZE_X | Retrieves the minimum width required for the destination image of a write operation. Retrieves the minimum width required for the destination image of a write operation.
Open Collapse M_WRITE_SIZE_Y | Retrieves the minimum height required for the destination image of a write operation. Retrieves the minimum height required for the destination image of a write operation.

The following value is able to retrieve results from a code read, write, or verify operation.

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_STATUS

Retrieves the status of a read, write, or verify operation. Retrieves the status of a read, write, or verify operation ...

ResultPtr info

Return values:
M_STATUS_CRC_FAILED | Code read failed (only for read operations).
M_STATUS_ECC_UNKNOWN | Code read status unknown (only for read operations).
M_STATUS_ENC_UNKNOWN | Code read status unknown (only for read operations).
M_STATUS_NO_RESULT_AVAILABLE | There are no results available (used for all three operations).
M_STATUS_NOT_FOUND | Code read status not found (only for read operations).
M_STATUS_READ_OK | Code read status is operational (only for read operations)
M_STATUS_VERIFY_FAILED | Code verify failed (only for verify operations).
M_STATUS_VERIFY_OK | Code status was verified (only for verify operations).
M_STATUS_WRITE_FAILED | Code write failed (only for write operations).
M_STATUS_WRITE_OK | Code write status is operational (only for write operations).

[Combination constants]

The following value can be added to the ResultType parameter to cast the requested result(s) to a required data type. For example, M_WRITE_SIZE_Y + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_LONG | Casts the requested results to a long. Casts the requested results to a long ...
 |  | ResultPtr info Data type: long
ResultPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type MIL_TEXT_CHAR
  • double
  • long

Specifies the address in which to place the specified result.

You can set this parameter to M_NULL to put the result request on the local queue of the result buffer.

WRITE SIZE X WRITE SIZE Y OUTPUT COORDINATE SYSTEM PIXEL ENC RSS14 ENC RSS14 STACKED STRING SIZE STRING STRING SIZE STRING STRING SIZE ANGLE CELL NUMBER X CELL NUMBER Y CELL SIZE ENCODING ERROR CORRECTION SCORE STRING STRING SIZE THRESHOLD ESCAPE SEQUENCE AXIAL NONUNIFORMITY GRADE DECODABILITY GRADE DECODE GRADE DEFECTS GRADE EDGE DETERMINATION GRADE MINIMUM EDGE CONTRAST GRADE MINIMUM REFLECTANCE GRADE MODULATION GRADE OVERALL SYMBOL GRADE PRINT GROWTH GRADE RAP GRADE START STOP PATTERN GRADE SYMBOL BASED GRADE SYMBOL CONTRAST GRADE UNUSED ERROR CORRECTION GRADE WRITE SIZE X WRITE SIZE Y STATUS TYPE LONG


McodeInquire

Example | Availability | McodeGetResult | McodeRead
There are no examples containing McodeInquire().
Not available in MIL-Lite

Available in MIL
Synopsis
Inquire about a code object setting.
Syntax
long McodeInquire(
MIL_ID CodeId,
long InquireType,
void *UserVarPtr
)
Description

This function inquires about a setting of a specified code object.

Parameters
CodeId

Specifies the identifier of the code object.

InquireType

Specifies the setting about which to inquire. This parameter can be set to one of the values listed below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_CELL_NUMBER_X | Returns the number of cells of a 2D code in the X direction. Returns the number of cells of a 2D code in the X direction ...
 |  | UserVarPtr info Return values: M_ANY, Value > 0 (details)
Open Collapse M_CELL_NUMBER_Y | Returns the number of cells of a 2D in the Y direction. Returns the number of cells of a 2D in the Y direction ...
 |  | UserVarPtr info Return values: M_ANY, Value > 0 (details)
Open Collapse M_CELL_SIZE_MAX | Returns the maximum cell size, in pixels. Returns the maximum cell size, in pixels ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_CELL_SIZE_MIN | Returns the minimum cell size, in pixels. Returns the minimum cell size, in pixels ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value > 0 (details)
Open Collapse M_CODE_TYPE | Returns type of code. Returns type of code ...
 |  | UserVarPtr info Return values: M_BC412, M_CODABAR, M_CODE39, M_CODE93, M_CODE128, M_COMPOSITECODE, M_DATAMATRIX, M_EAN8, M_EAN13, M_INTERLEAVED25, M_MAXICODE, M_MICROPDF417, M_PDF417, M_PHARMACODE, M_PLANET, M_POSTNET, M_QRCODE, M_RSSCODE, M_UPC_A, M_UPC_E (details)
Open Collapse M_DOT_SPACING | Returns the distance, in pixels, between 2 dots. M_DOT_SPACING is half the distance between the edges of the dots in the code. Returns the distance, in pixels, between 2 dots ...
 |  | UserVarPtr info Return values: 0 to 256 (details)
Open Collapse M_ENCODING | Returns the type of encoding. Returns the type of encoding ...
 |  | UserVarPtr info Return values: M_ANY, M_ENC_ALPHA, M_ENC_ALPHANUM, M_ENC_ALPHANUM_PUNC, M_ENC_ASCII, M_ENC_EAN8, M_ENC_EAN13, M_ENC_ISO8, M_ENC_MODE2, M_ENC_MODE3, M_ENC_MODE4, M_ENC_MODE5, M_ENC_MODE6, M_ENC_NUM, M_ENC_QRCODE_MODEL1, M_ENC_QRCODE_MODEL2, M_ENC_RSS14, M_ENC_RSS_EXPANDED, M_ENC_RSS_EXPANDED_STACKED, M_ENC_RSS_LIMITED, M_ENC_RSS14_STACKED, M_ENC_RSS14_STACKED_OMNI, M_ENC_RSS14_TRUNCATED, M_ENC_STANDARD, M_ENC_UCCEAN128_MICROPDF417, M_ENC_UCCEAN128_PDF417, M_ENC_UPCA, M_ENC_UPCE (details)
Open Collapse M_ERROR_CORRECTION | Returns the type of error correction. Returns the type of error correction ...
 |  | UserVarPtr info Return values: M_ANY, M_ECC_200, M_ECC_CHECK_DIGIT, M_ECC_COMPOSITE, M_ECC_H, M_ECC_L, M_ECC_M, M_ECC_n, M_ECC_NONE, M_ECC_Q, M_ECC_REED_SOLOMON, M_ECC_REED_SOLOMON_n (details)
Open Collapse M_FOREGROUND_VALUE | Returns the foreground color of the code. Returns the foreground color of the code ...
 |  | UserVarPtr info Return values: M_FOREGROUND_BLACK, M_FOREGROUND_WHITE (details)
Open Collapse M_SEARCH_ANGLE | Returns the angle at which to search. Returns the angle at which to search ...
 |  | UserVarPtr info Return values: 0.0 to 360.0 (details)
Open Collapse M_SEARCH_ANGLE_DELTA_NEG | Returns the negative angle range of the search. Returns the negative angle range of the search ...
 |  | UserVarPtr info Return values: 0.0 to 180.0 (details)
Open Collapse M_SEARCH_ANGLE_DELTA_POS | Returns the positive angle range of the search. Returns the positive angle range of the search ...
 |  | UserVarPtr info Return values: 0.0 to 180.0, M_DEFAULT (details)
Open Collapse M_SPEED | Returns the search speed. Returns the search speed ...
 |  | UserVarPtr info Return values: M_HIGH, M_LOW, M_MEDIUM, M_VERY_HIGH, M_VERY_LOW (details)
Open Collapse M_STRING_SIZE | Returns the size of string for which to search. Returns the size of string for which to search ...
 |  | UserVarPtr info Return values: M_ANY, Value (details)
Open Collapse M_THRESHOLD | Returns the threshold value used to internally binarize the source image of a read operation. Returns the threshold value used to internally binarize the source image of a read operation ...
 |  | UserVarPtr info Return values: 0<=Value<=255, M_ADAPTIVE, M_DEFAULT (details)
Open Collapse M_USE_PRESEARCH | Returns whether or not the pre-search (localization) algorithm is applied. Returns whether or not the pre-search (localization) algorithm is applied ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)

[Combination constants]

The value below can be added to the InquireType parameter to cast the requested information to the required data type. For example, M_THRESHOLD + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_LONG | Casts the requested data to a long. Casts the requested data to a long ...
 |  | UserVarPtr info Data type: long
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • double
  • long

Specifies the address in which to return the value of the inquired setting. Since this function also returns the requested information, you can set this parameter to M_NULL.

Return value
The returned value is the requested system information cast to long.
THRESHOLD TYPE LONG CELL NUMBER X CELL NUMBER Y CELL SIZE MAX CELL SIZE MIN CODE TYPE DOT SPACING ENCODING ERROR CORRECTION FOREGROUND VALUE SEARCH ANGLE SEARCH ANGLE DELTA NEG SEARCH ANGLE DELTA POS SPEED STRING SIZE THRESHOLD USE PRESEARCH TYPE LONG


McodeRead

See Also | Example | Availability | McodeInquire | McodeRestore
User Guide:
Using MIL to read and write codes
Supported code types and noteworthy characteristics

Reference:
McodeControl
McodeGetResult
mcode.c
Not available in MIL-Lite

Available in MIL
Synopsis
Read a specific type of code in an image.
Syntax
void McodeRead(
MIL_ID CodeId,
MIL_ID ImageBufId,
long ControlFlag
)
Description

This function searches for a specific type of code in an image. The control settings of the specified code object determine how to perform the operation. Retrieve results using McodeGetResult().

It is advisable to use child buffers for read operations, especially if your image contains multiple codes of the same type and you want to read more than one. MIL's code module is designed to read one code at a time, therefore if you do not use child buffers and your image contains multiple codes, results will be unpredictable.

Before performing a read operation, certain controls might have to be set in McodeControl(), specifically:

Control

Notes

M_FOREGROUND_VALUE

This control is essential for all code types, and the image will not be decoded if the foreground value is not correctly set.

M_ENCODING

For code types where M_ANY is not supported.

M_ERROR_CORRECTION

For code types where M_ANY is not supported.

M_CELL_NUMBER_X

For 2D code types only, improves the robustness of the operation.

M_CELL_NUMBER_Y

For 2D code types only, improves the robustness of the operation.

M_CELL_SIZE_MIN

To improve the robustness of read operations for some code types, especially Data Matrix and Maxicode.

Note that MIL might have difficulty reading codes if the cell size is less than 2 pixels, even if the size is specified.

M_CELL_SIZE_MAX

To improve the robustness of read operations for some code types, especially Data Matrix and Maxicode.

Note that MIL might have difficulty reading codes if the cell size is less than 2 pixels, even if the size is specified.

M_STRING_SIZE

For M_BC412, the string size must be specified.

M_SEARCH_ANGLE, M_SEARCH_ANGLE_DELTA_NEG, M_SEARCH_ANGLE_DELTA_POS

If the code to read is not within 5° of the horizontal axis, and/or if it has bearer bars.

Parameters
CodeId

Specifies the identifier of the code object.

ImageBufId

Specifies the image buffer in which to search. This buffer must be 8-bit unsigned.

ControlFlag

Specifies the function's control flag. This parameter must be set to M_DEFAULT.

FOREGROUND VALUE ENCODING ANY ERROR CORRECTION ANY CELL NUMBER X CELL NUMBER Y CELL SIZE MIN CELL SIZE MAX STRING SIZE BC412 SEARCH ANGLE SEARCH ANGLE DELTA NEG SEARCH ANGLE DELTA POS


McodeRestore

See Also | Example | Availability | McodeRead | McodeSave
Reference:
McodeSave
MsysAlloc
There are no examples containing McodeRestore().
Not available in MIL-Lite

Available in MIL
Synopsis
Restore a code object previously saved to a file.
Syntax
void McodeRestore(
MIL_TEXT_PTR FileName,
MIL_ID SystemId,
long ControlFlag,
MIL_ID *CodeIdPtr
)
Description

This function restores a code object that has been saved to a filename with McodeSave(). All of the code object's controls are restored and the identifier to the newly allocated code object is returned.

Parameters
FileName

Specifies the name of the file in which the code object was saved.

SystemId

Specifies the system on which to allocate the object. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Specifies the function's control flag. This parameter must be set to M_DEFAULT.

 CodeIdPtr

 Specifies the address in which to return the identifier of the code object.  Since the function also returns the identifier, this parameter can be set to M_NULL.

  DEFAULT HOST


McodeSave

See Also | Example | Availability | McodeRestore | McodeStream
Reference:
McodeRestore
There are no examples containing McodeSave().
Not available in MIL-Lite

Available in MIL
Synopsis
Save the specified code object in a file.
Syntax
void McodeSave(
MIL_TEXT_PTR FileName,
MIL_ID CodeId,
long ControlFlag
)
Description

This function saves a code object in a file so that it can be reloaded with McodeRestore().

Parameters
FileName

Specifies the name of the file in which to save the code object. If this file already exists, it will be overwritten.

CodeId

Specifies the identifier of the data buffer to save.

ControlFlag

Specifies the function's control flag This parameter must be set to M_DEFAULT.


McodeStream

See Also | Example | Availability | McodeSave | McodeVerify
Reference:
MappInquire
McodeSave
MsysAlloc
There are no examples containing McodeStream().
Not available in MIL-Lite

Available in MIL
Synopsis
Load, restore, or save a code object from/to a file or a memory stream.
Syntax
void McodeStream(
MIL_TEXT_PTR MemPtrOrFileName,
MIL_ID SystemId,
long Operation,
long StreamType,
double Version,
long ControlFlag,
MIL_ID *CodeIdPtr,
long *SizeByteVarPtr
)
Description

This function can load or restore a code object from a file or memory stream. Moreover, this function can also save a code object to a file or memory stream.

To inquire the number of bytes necessary to save a code object to memory stream, you should call this function (McodeStream()) first with M_INQUIRE_SIZE_BYTE.

The content saved to memory stream is equivalent to the content saved to file. In addition, any file saved with McodeSave() is equivalent to a file saved using this function.

You can use this and other MIL stream functions, for example, to save all required MIL objects, as well as any other custom data, for your application to a memory stream. Once in a memory stream, you can write the stream to a single file or transfer it over a network. You are responsible for concatenating the streams and for saving the stream to file.

Parameters
MemPtrOrFileName

Specifies the file or memory stream.

When the StreamType parameter is set to M_FILE, MemPtrOrFileName specifies the name and path of the file required for the operation. The function internally handles the opening and closing of the file. If the file already exists, it will be overwritten when M_SAVE is performed.

When the StreamType parameter is set to M_MEMORY, MemPtrOrFileName specifies the address of the block of memory required for the operation. The designated block must be large enough to stream the entire object. To know the required size, call this function (McodeStream()) first with M_INQUIRE_SIZE_BYTE.

When performing an M_INQUIRE_SIZE_BYTE operation, set this parameter to M_NULL.

SystemId

Specifies the system on which to restore the code object. For M_INQUIRE_SIZE_BYTE, M_LOAD, and M_SAVE, SystemId is ignored and should be set to M_NULL.

For an M_RESTORE operation, this parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 Operation

 Specifies the operation to perform on the code object.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_INQUIRE_SIZE_BYTE

 Inquires the number of bytes required to save a code object to memory stream. This operation is not supported when the StreamType parameter is set to M_FILE.  Inquires the number of bytes required to save a code object to memory stream ...

  Open   Collapse  M_LOAD

 Loads the content of a specified file or memory stream into a previously allocated code object.  Loads the content of a specified file or memory stream into a previously allocated code object.

  Open   Collapse  M_RESTORE

 Restores a code object from a file or memory stream and assigns it an identifier.  Restores a code object from a file or memory stream and assigns it an identifier.

  Open   Collapse  M_SAVE

 Saves a code object to a specified file or memory stream.  Saves a code object to a specified file or memory stream.

 StreamType

 Specifies the type of stream that holds the code object.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_FILE

 Specifies a file stream.  Specifies a file stream.

  Open   Collapse  M_MEMORY

 Specifies a memory stream. You are responsible for allocating a block of memory for the stream.  Specifies a memory stream ...

 Version

 Specifies the MIL version of the code object. For M_LOAD and M_RESTORE, this parameter must be set to M_DEFAULT.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the version to current version of MIL.  Sets the version to current version of MIL.

  Open   Collapse  Value

 Sets the version to a specific version of MIL. This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.  Sets the version to a specific version of MIL ...

 The version specified must never be greater than the current MIL version, but must be greater or equal to 7.0. To know the current MIL version, call MappInquire() with M_VERSION.

 By supplying a specific version, you can control the code object's accessibility. For instance, if you allocate a code object using MIL 8.0 and set its version to 7.0, this object can be restored on a computer where MIL 7.0 is installed. However, all settings unique to the higher version will be ignored when opened in the lower version. Note that a program using MIL of a higher version can access a code object stream created or designated with a lower or equal version. Settings that do not exist in the lower version will be filled with default values when the file or memory stream is restored.

 ControlFlag

 Specifies the function's control flag and should be set to M_DEFAULT.

 CodeIdPtr

 Specifies the address of the variable in which to write or from which to read the identifier of the code object.

 For M_INQUIRE_SIZE_BYTE and M_SAVE operations, CodeIdPtr specifies the address of the variable from which to read the code object idenfier.

 For an M_LOAD operation, the CodeIdPtr specifies the address of the variable from which to read the identifier of the code object where the file or memory stream content will be loaded.

 For an M_RESTORE operation, the CodeIdPtr specifies the address in which to return the identifier of the restored code object. If the operation is not successful, M_NULL is returned.

 SizeByteVarPtr

 Specifies the address of the variable in which to write the size of the code object, in bytes.

 If the size is not required, you can set this parameter to M_NULL.

 Note that the size of a code object will vary depending on the MIL version specified.

INQUIRE SIZE BYTE FILE SAVE MEMORY INQUIRE SIZE BYTE INQUIRE SIZE BYTE INQUIRE SIZE BYTE LOAD SAVE RESTORE FILE LOAD  RESTORE DEFAULT INQUIRE SIZE BYTE SAVE VERSION INQUIRE SIZE BYTE SAVE LOAD RESTORE   DEFAULT HOST   INQUIRE SIZE BYTE LOAD RESTORE SAVE  FILE MEMORY  DEFAULT


McodeVerify

See Also | Example | Availability | McodeStream | McodeWrite
User Guide:
Verifying your code

Reference:
McodeGetResult
MimResize
There are no examples containing McodeVerify().
Not available in MIL-Lite

Available in MIL
Synopsis
Compute the different quality-grades of the code in the specified source image.
Syntax
void McodeVerify (
MIL_ID CodeId,
MIL_ID ImageBufId,
MIL_TEXT_PTR String,
long ControlFlag
)
Description

This function computes the different quality-grades of the code in the specified source image.

You can read the results of the verify operation with McodeGetResult().

Before performing a verify operation, you might have to set some controls.

Control | Notes
M_FOREGROUND_VALUE | Specifies the foreground value of the image. This control is essential and the code will not be graded if the foreground value is not correctly set.
M_ENCODING | Specifies the type of encoding scheme for the code. This control has to be set for the code types where M_ANY is not supported.
M_ERROR_CORRECTION | Specifies the type of error correction for the code. This control has to be set for the code types where M_ANY is not supported.
M_STRING_SIZE | Specifies the size of the string for which to search. This control has to be specified for the BC412 code type.
M_SEARCH_ANGLE | Specifies the nominal search angle. This control has to be specified if the code to read is not within the angular range of -5 to 5 degrees.
M_SEARCH_ANGLE_DELTA_NEG | Specifies the negative angle range of the search. This control has to be specified if the code to read is not within the angular range of -5 to 5 degrees.
M_SEARCH_ANGLE_DELTA_POS | Specifies the positive angle range of the search. This control has to be specified if the code to read is not within the angular range of -5 to 5 degrees.

This function is not supported for Pharmacode, Postnet and Planet code types.

You should note that if the code cannot be decoded by MIL, all verify grades will be returned as F.

If you cannot read a barcode with cell sizes that are size 2 or smaller, you can enlarge the image using MimResize() and try again.

Parameters
CodeId

Specifies the identifier of the code object.

ImageBufId

Specifies the identifier of the image buffer containing the string to be verified.

String

Specifies the string of the code to be graded. Set this parameter to M_NULL if the string is unknown. If the string is a composite code, the string must be passed with the following format: 1D string|2D string, where | is used as the separator.

ControlFlag

Specifies the function's control flag. This parameter must be set to M_DEFAULT.


McodeWrite

See Also | Example | Availability | McodeVerify
User Guide:
Using MIL to read and write codes
Controlling read and write operations in MIL

Reference:
McodeControl
McodeGetResult
There are no examples containing McodeWrite().
Not available in MIL-Lite

Available in MIL
Synopsis
Encode an ASCII string into a symbol.
Syntax
void McodeWrite(
MIL_ID CodeId,
MIL_ID ImageBufId,
MIL_TEXT_PTR String,
long ControlFlag
)
Description

This function encodes a null-terminated ASCII string into a symbol (code) using the code type and encoding scheme, specified by the code object, and saves the symbol into an image. For a given code object and string, you can also use this function to inquire about the minimum buffer size required to encode the string. Retrieve results using McodeGetResult().

The control type settings of the specified code object determine how to perform the operation. Before performing a write operation, you have to set certain controls, using McodeControl(), specifically:

Control | Notes
M_CELL_NUMBER_X | Specifies the number of cells in the X direction. Improves the robustness of the operation, for 2D code types only.
M_CELL_NUMBER_Y | Specifies the number of cells in the Y direction. Improves the robustness of the operation, for 2D code types only.
M_CELL_SIZE_MIN | Specifies the cell size, in pixels, of a unit of the code. If this setting is set to M_DEFAULT, the code will be written so as to just fit into the destination image.
M_ENCODING | Specifies the encoding scheme. This control type must be set for code types where an M_ANY encoding is not supported.
M_ERROR_CORRECTION | Specifies the type of error correction. This control type must be set for code types where an M_ANY error correction is not supported.
M_FOREGROUND_VALUE | Specifies the foreground color of the code. This control type is essential for all code types.
Parameters
CodeId

Specifies the identifier of the code object.

ImageBufId

Specifies the image buffer in which to write the symbol. Set this parameter to one of the following.

Open Collapse Value Description
Open Collapse M_NULL

 Allows you to inquire about the minimum buffer size required. Using this value means that McodeWrite() will not write into an image buffer.  Allows you to inquire about the minimum buffer size required ...

 After calling McodeWrite() with M_NULL, call McodeGetResult() to retrieve the minimum width (M_WRITE_SIZE_X) and height (M_WRITE_SIZE_Y) required for the image buffer.

  Open   Collapse  MIL image buffer identifier

 Specifies that McodeWrite() will write into the image buffer, and in which image buffer to write. This buffer must be 8-bit unsigned. In addition, it should be large enough to hold the symbol.  Specifies that McodeWrite() will write into the image buffer, and in which image buffer to write ...

 String

 Specifies the address of the string.

 You need to know the string specifications of the code to write.

 Note the following restrictions for certain code types:

  •  If the code type is a Codabar code, the string must be numeric, but can contain the following ASCII characters: -, $, :, /, ., and +. In addition, the string must start and end with any of the following characters: a, b, c, or d.
    •

  •  If the code type is an Interleaved 2 of 5 code, the string must have an even number of characters.
    •

  •  If the code type is a Maxicode code, with M_ENCODING set to M_ENC_MODE2 or M_ENC_MODE3, the string must respect the structured carrier message format (the portion of the string that contains postal code, country code, and class of service information).
    •

  •  If the code type is a composite code, the string must be passed in the following format: 1D string|2D string, where | is used as the separator.
    •

  •  If the code type is a composite code, the FNC1 separator is represented by the unprintable character with ASCII value 29.
    •

 In addition, add parentheses around the application identifiers in your string. Note that this is required by the write operation; the parentheses are not actually coded.

 ControlFlag

 Specifies the function's control flag.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the string to encode does not use ASCII codes for non-printable characters. Non-printable characters are not encoded.  Specifies that the string to encode does not use ASCII codes for non-printable characters ...

  Open   Collapse  M_ESCAPE_SEQUENCE

 Specifies that the string to encode uses ASCII codes for non-printable characters.  Specifies that the string to encode uses ASCII codes for non-printable characters ...

 You must use a code type that supports non-printable characters that are specified using ASCII codes. When typing the string to encode, the non-printable character's ASCII code must be in hexadecimal format, preceded by \x, for example, \x0D for ASCII 13, which is the carriage return.

 Note that if you want to encode the "\" character in escape sequence mode, type "\\".

CELL NUMBER X CELL NUMBER Y
                 CELL SIZE MIN
                 DEFAULT ENCODING ANY ERROR CORRECTION
                 ANY FOREGROUND VALUE
                 NULL WRITE SIZE X WRITE SIZE Y ENCODING ENC MODE2 ENC MODE3   NULL    DEFAULT ESCAPE SEQUENCE


dig

Mdig functions

Example | Availability
There are no examples containing dig().
Available in MIL-Lite

Available in MIL
Synopsis
The digitizer control module allows you to manipulate and control the digitizer section of an imaging board. It also allows you to set the state required for either simple or complex acquisition and allows acquisition functions to be sent to the imaging board
Functions
  • MdigAlloc
  • MdigChannel
  • MdigControl
  • MdigFocus
  • MdigFree
  • MdigGetHookInfo
  • MdigGrab
  • MdigGrabContinuous
  • MdigGrabWait
  • MdigHalt
  • MdigHookFunction
  • MdigInquire
  • MdigLut
  • MdigProcess
  • MdigReference


MdigAlloc

See Also | Example | Availability | MdigChannel
User Guide:
Allocating an application and its systems
Grabbing images
Cameras and video sources
Data format
Device number
Multiple cameras
Grabbing

Reference:
MdigChannel
MdigFree
MdigGrab
MdigGrabContinuous
MdigProcess
MsysInquire
channel_switch.c
dtkobjecttracking.c
mdblgrab.c
mdiggrabmultiple.c
mdigmultdestination.c
mdigmultformat.c
mdigprocessmultiple.c
mdispoverlay.c
mdispwindow.c
met2_1394serialbus.c
mgenlc.c
mmet2dig.c
muart.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Allocate a digitizer.
Syntax
MIL_ID MdigAlloc(
MIL_ID SystemId,
long DigNum,
MIL_TEXT_PTR DataFormat,
long InitFlag,
MIL_ID *DigIdPtr
)
Description

This function allocates a digitizer on the specified system so that it can be used by subsequent MIL digitizer functions. A digitizer on the target system must be allocated to acquire data from a camera. Its device number specifies the first acquisition path of the digitizer. Its digitizer configuration format (DCF) establishes the number of acquisition paths used. One digitizer might use several acquisition paths depending on the input format of the camera. Use MdigGrab(), MdigGrabContinuous(), or MdigProcess() to grab.

Multiple digitizers can be allocated on the same system. If the system supports the possibility of independent acquisition paths, the digitizers' device number together with their DCF establishes if they represent dependent or independent acquisition path(s) on the system. If independent, grabs from these digitizers occur simultaneously. If dependent, grabs from these digitizers occur consecutively.

If multiple cameras of the same type are connected to the same acquisition path(s), instead of allocating multiple digitizers, you can allocate a single digitizer in the required format and then use MdigChannel() to switch between the cameras. MdigChannel() selects the active input channel of the digitizer. The switch occurs upon the next call to MdigGrab(), MdigGrabContinuous(), or MdigProcess() with the digitizer. The default input channel is determined by the selected DCF (generally, M_CH0).

It is faster to allocate all the required digitizers first, perform the required grabs, and then free all the digitizers rather than allocate, grab, and then free each digitizer in succession.

Upon execution of this function, MIL ensures that the digitizer is present before allocating it and generates an error if it is not. Note that the corresponding hardware won't necessarily be programmed at the time of allocation.

When you have completely finished using a digitizer, you should free it, using MdigFree().

[Matrox Orion]

To perform a real-time transfer of grabbed images to the display and Host memory simultaneously, two digitizers must be allocated. Both digitizers must have the same the device number (M_DEV0) and the same DCF because physically, the same acquisition paths are used to digitize the input signal. Refer to the Simultaneous real-time grab transfer to the display and Host section in Chapter 9: Matrox Orion in the MIL Board specific notes for more information.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

You can allocate a digitizer even if the frame grabber is physically connected to another system, as long as the systems are both part of the same cluster.

Parameters
SystemId

Specifies the identifier of the system on which to allocate the digitizer. This parameter must be given a valid system identifier.

DigNum

Specifies the device number of the digitizer that is required. The device number identifies the first acquisition path with which to associate a timing control unit (for example, a programmable synchronization generator (PSG) or a video capture controller) on your frame grabber.

This parameter can be set to one of the following:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_DEFAULT

 Specifies the default device number. This value is set during MIL installation and using MilConfig. Note that the end-user can always change this value.  Specifies the default device number ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_DEVn

 Specifies the first acquisition path of the digitizer with which to associate to a timing control unit of your frame grabber.  Specifies the first acquisition path of the digitizer with which to associate to a timing control unit of your frame grabber ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The value of n must be 0 since you can only grab from one digitizer at a time.

a
b
c

f

h
i
j
k

 The value of n must be either 0 to 3. The number of digitizers that can be allocated depends on the amount of bandwidth available using M_1394_BANDWIDTH().

g

 The value of n must be from 0 to 3. For details regarding allocation of specific independent digitizers, see the the Allocating independent MIL digitizers on Matrox Helios section in
          Chapter 4: Matrox Helios section of the appropriate chapter of the Board Specific Notes.

d

 The value of n must be either 0 or 1 for Matrox Morphis Dual. The value of n must be from 0 to 3 for Matrox Morphis Quad.

l

 When dealing with a cluster of boards featuring Matrox Odyssey Xpro, n can be a value from 0 to 31. Use MsysInquire() with M_DIGITIZER_NUM to return the total number of possible independent acquisition paths available on the system. Use MsysInquire() with M_DIGITIZER_TYPE + M_DEVn to return the type of frame grabber on which the specified acquisition path is present.

m
n
o

 When not dealing with a cluster, the value of n must be from 0 to 3. For details regarding allocation of specific independent digitizers, see the Allocating independent MIL digitizers on Matrox Odyssey section in
          Chapter 8: Matrox Odyssey.

m
n
o

 The value of n must be from 0 to 3, except when using Matrox Solios XA single analog. In this case, the value of n must be 0. For details regarding allocation of specific independent digitizers, see the Allocating independent MIL digitizers on Matrox Solios section in
          Chapter 10: Matrox Solios.

q

 The value of n must be either 0 or 1. 1 is available to allocate a digitizer only in dual-Base mode.

e

n

r

 The value of n must be either 0 or 1. 1 is only available for Matrox Orion /Dual for 4Sight-II.

p

 DataFormat

 Specifies the name of the digitizer configuration format (DCF) appropriate for your camera.  Depending on the target system, different DCFs are supported.

 One of the following values can be specified when allocating a digitizer for either a monochrome or a color camera:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  "DCF Filename"

 Specifies the file name and path of the DCF.  Specifies the file name and path of the DCF ...

 See the \Matrox Imaging\Drivers directory for the current list of supported formats.

 Use the Matrox Intellicam program to create your own DCF file.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  "M_DEFAULT"

 Specifies the default digitizer. This value is set during MIL installation and using MilConfig. Note that the end-user can always change this value.  Specifies the default digitizer ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 This corresponds to the largest image dimensions possible with the highest frame rate. For color cameras, this also corresponds to the color data format.

g

  Open   Collapse  "M_xXy_data[@z[FPS]]"

 Specifies the string format, where X is SizeX in pixels, Y is SizeY in pixels, data is the image data format (for example, YUV, RGB...), and Z is the frame rate; the information in brackets is optional (for example, "M_640X480_YUV411@30FPS", "M_320x240_YUV422@7.5" and "M_1024X768_YUV" are accepted strings from one type of camera).  Specifies the string format, where X is SizeX in pixels, Y is SizeY in pixels, data is the image data format (for example, YUV, RGB ...

g

  Open   Collapse  "M_xXy_data_format_7_z"

 Specifies the string format, where X is SizeX in pixels, Y is SizeY in pixels, data_format_7 is the image data format (for example, YUV, RGB...), and Z is the format 7 mode (for example, "M_640X480_UYUV411_FORMAT_&_1", "M_320X240_YUV422_FORMAT_7_2", and "M_780X580_YUV422_FORMAT_7_0" are accepted strings from one type of camera).  Specifies the string format, where X is SizeX in pixels, Y is SizeY in pixels, data_format_7 is the image data format (for example, YUV, RGB ...

 To use this string format, the total available bandwith for a camera to communicate with Matrox Meteor-II 1394 should be divided amonst multiple cameras.

 The InitFlag must be set to M_1394_BANDWIDTH(), where n is the amount of bandwidth for the camera of the specified digitizer.

g

[All except
        Matrox Helios XCL, Matrox Iris, Matrox Meteor-II /Camera Link, Matrox Meteor-II /Digital, Matrox Odyssey XCL, Matrox Odyssey XD, and Matrox Solios XCL]

 One of the following values can be specified when allocating a digitizer for a monochrome cameras:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  "M_CCIR"

 Specifies a DCF for a CCIR, 768x576, 14.75 MHz, analog camera.  Specifies a DCF for a CCIR, 768x576, 14.75 MHz, analog camera ...

a
b
c
d

j
k
l
m

p
q

  Open   Collapse  "M_CCIR_VIA_RGB"

 Specifies a DCF for an CCIR, 768x576, 14.75 MHz, analog camera. If your frame grabber has both a decoder and an RGB path, the red acquisition path of the RGB path will be used.  Specifies a DCF for an CCIR, 768x576, 14.75 MHz, analog camera ...

a

d

j

m

p
q

  Open   Collapse  "M_RS170"

 Specifies a DCF for an RS-170, 640x480, 12.27 MHz, analog camera.  Specifies a DCF for an RS-170, 640x480, 12.27 MHz, analog camera ...

a
b
c
d

g

j
k
l
m

p
q

Specifics

 If "M_RS170" is not supported by the camera, the mode will be emulated.

g

  Open   Collapse  "M_RS170_VIA_RGB"

 Specifies a DCF for an RS170, 640x480, 12.27 MHz, analog camera. If your frame grabber has both a decoder and an RGB path, the red acquisition path of the RGB path will be used.  Specifies a DCF for an RS170, 640x480, 12.27 MHz, analog camera ...

a

d

j

m

p
q

[All except
        Matrox Helios XCL, Matrox Iris, Matrox Meteor-II /Camera Link, Matrox Meteor-II /Digital, Matrox Odyssey XCL, Matrox Odyssey XD, and Matrox Solios XCL]

 One of the following values can be specified when allocating a digitizer for a color camera:

[Matrox Solios XA]

 The following values are not supported on Matrox Solios XA single analog.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  "M_NTSC"

 Specifies a DCF for a composite NTSC 640x480, 12.27 MHz camera.  Specifies a DCF for a composite NTSC 640x480, 12.27 MHz camera ...

b

g

k
l

p

Specifics

 If "M_NTSC" is not supported by the camera, the mode will be emulated.

g

  Open   Collapse  "M_NTSC_RGB"

 Specifies a DCF for a component RGB, 640x480, 12.27 MHz camera. If your frame grabber has both a decoder and an RGB path, the RGB path will be used.  Specifies a DCF for a component RGB, 640x480, 12.27 MHz camera ...

a

c
d

j

m

p
q

Specifics

 Specifies a DCF for RGB format with an external synchronization signal.

a

d

j

m

q

 Specifies a DCF for RGB format with a composite synchronization signal on green.

c

p

  Open   Collapse  "M_NTSC_YC"

 Specifies a DCF for a component NTSC Y/C (SVHS), 640x480, 12.27 MHz camera.  Specifies a DCF for a component NTSC Y/C (SVHS), 640x480, 12 ...

b

k
l

p

  Open   Collapse  "M_PAL"

 Specifies a DCF for a composite PAL 768x576, 14.75 MHz camera.  Specifies a DCF for a composite PAL 768x576, 14 ...

b

k
l

p

  Open   Collapse  "M_PAL_RGB"

 Specifies a DCF for a component RGB, 768x576, 14.75 MHz camera. If your frame grabber has both a decoder and an RGB path, the RGB path will be used.  Specifies a DCF for a component RGB, 768x576, 14.75 MHz camera ...

a

c
d

j

m

p
q

Specifics

 Specifies a DCF for RGB format with an external synchronization signal.

a

d

j

m

q

 Specifies a DCF for RGB format with a composite synchronization signal on green.

c

p

  Open   Collapse  "M_PAL_YC"

 Specifies a DCF for a PAL Y/C, 768x576, 14.75 MHz camera.  Specifies a DCF for a PAL Y/C, 768x576, 14 ...

b

k
l

p

 InitFlag

 Specifies the type of initialization to perform on the digitizer.  This parameter should be set to M_DEFAULT.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_DEFAULT

 Specifies the default value.  Specifies the default value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_1394_BANDWIDTH(
long divisor

          )

 Specifies that the total available bandwith for a camera to communicate with Matrox Meteor-II 1394 should be divided among multiple cameras.  Specifies that the total available bandwith for a camera to communicate with Matrox Meteor-II 1394 should be divided among multiple cameras ...

g

Parameters

divisor

 Specifies the total amount of bandwidth, as a percentage.

 DigIdPtr

 Specifies the address of the variable in which to write the digitizer identifier.  Since the MdigAlloc() function also returns the digitizer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the digitizer identifier. If allocation fails, M_NULL is returned.

CH0 1394 BANDWIDTH() DIGITIZER NUM DIGITIZER TYPE DEVn 1394 BANDWIDTH() RS170" NTSC" DEFAULT   DEFAULT DEVn   DEFAULT" xXy data[@z[FPS]]" xXy data format 7 z" CCIR" CCIR VIA RGB" RS170" RS170 VIA RGB" NTSC" NTSC RGB" NTSC YC" PAL" PAL RGB" PAL YC"  DEFAULT


MdigChannel

See Also | Example | Availability | MdigAlloc | MdigControl
User Guide:
Multiple cameras

Reference:
MdigControl
channel_switch.c
mdigmultformat.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL

Not supported on:
Not supported on Matrox Iris
Synopsis
Select the active input data or synchronization channel of a digitizer.
Syntax
void MdigChannel(
MIL_ID DigId,
long Channel
)
Description

This function selects the active input data or synchronization channel for the specified digitizer. If the digitizer does not have the specified channel, an error is generated and the last selected channel remains effective. The default channel corresponds to the default channel for the specified digitizer's DCF.

When choosing the data channel, the default synchronization channel will be used. This value is specified in the DCF. For more channel information when grabbing, see the Board Specific notes of the appropriate board.

[Matrox Corona-II, Matrox Genesis, Matrox Helios XA, Matrox Meteor-II /Multi-Channel, Matrox Odyssey XA, Matrox Orion, and Matrox Solios XA]

To override the default synchronization and data channels, make two calls to MdigChannel(). The first should specify the data input channel using M_CHn + M_SIGNAL and the second should specify the synchronization channel using M_CHn+M_SYNC.

[Matrox Corona-II, Matrox CronosPlus, Matrox Helios XA, Matrox Meteor-II /Multi-Channel, Matrox Meteor-II /Standard, Matrox Morphis, Matrox Odyssey XA, Matrox Orion, and Matrox Solios XA]

If you intend to switch channels, enable camera locking before the switch (use MdigControl() with M_CAMERA_LOCK). This avoids corrupt images or synchronization-lost errors when channel-switching.

[Matrox Morphis and Matrox Orion]

If you intend to switch channels after grabbing a single field or frame, enable the fast-channel switching mode to minimize loss of time between grabs; set MdigControl() M_CAMERA_LOCK control type to M_ENABLE + M_FAST.

Parameters
DigId

Specifies the identifier of the digitizer.

Channel

Specifies the channel on which the digitizer is to acquire data. This parameter can be set to one of the following values, depending on the number of channels available for the specified digitizer's data format.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_DEFAULT

 Corresponds to the default channel for the specified digitizer's data format or M_CH0.  Corresponds to the default channel for the specified digitizer's data format or M_CH0 ...

 If your digitizer has only one channel that supports the selected data format, this parameter can only be set to M_DEFAULT or M_CH0.

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_CH0

 Specifies channel 0 as the channel on which the digitizer is to receive input data. In cases where you can connect and switch between more than one camera, the signal names are mentioned in the specifics.  Specifies channel 0 as the channel on which the digitizer is to receive input data ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 For RGB input, this corresponds to VID1_IN1, VID1_IN2, and VID1_IN3.

a

j

 For RGB input, this corresponds to DATA, Input 0-24.

i

 For RGB input, this corresponds to VID_IN1, VID_IN2, and VID_IN3. Note that RGB input is not supported on Matrox Orion /Standard and /Dual for 4Sight-II.

p

 For monochrome input, this corresponds to VID1_IN1.

a

j

 For monochrome dual-tap input, this corresponds to VID1_IN1 and VID1_IN2.

a

j

 For monochrome or composite input, this corresponds to VID_IN0.

b

l

 For monochrome input, this corresponds to Analog video input 1.

c

 For 8-bit monochrome digital input, this corresponds to DATA, INPUT 0-7. For 16-bit monochrome or 8-bit dual-tap monochrome, this corresponds to DATA, INPUT 0-15.

c

i

 This corresponds to a signal whose name ends with A.

d

m

q

 For the base-mode configuration, this corresponds to connector 1. For information on the camera description, see the section the Cameras that can be connected to Matrox Meteor-II section in
          Chapter 6: Matrox Meteor-II in the Board Specific notes.

h

 For composite color/monochrome input, this corresponds to VID_IN1.

k

p

 For Y/C input, this corresponds to VID_IN1 (Y of camera 1) and VID_IN2 (C of camera 1).

k

p

 For all other types of input not mentioned above, this is the only channel supported. No channel switching is supported.

e

n
o

r

  Open   Collapse  M_CH1

 Specifies channel 1 as the channel on which the digitizer is to receive input data.  Specifies channel 1 as the channel on which the digitizer is to receive input data ...

a
b
c
d

h
i
j
k
l
m

p
q

Specifics

 For RGB input, this corresponds to VID2_IN1, VID2_IN2, and VID2_IN3.

a

j

 For RGB input, this corresponds to VID_IN5, VID_IN6, and VID_IN7. Note that RGB input is not supported on Matrox Orion /Standard and /Dual for 4Sight-II.

p

 For monochrome dual-tap input, this corresponds to VID2_IN1 and VID2_IN2.

a

j

 For monochrome input, this corresponds to VID1_IN2.

a

j

 For a monochrome or composite input, this corresponds to VID_IN1.

b

l

 For 8-bit monochrome digital input, this corresponds to DATA, INPUT 8-15. For 16-bit monochrome or 8-bit dual-tap monochrome, this corresponds to DATA, INPUT 16-31.

c

i

 For monochrome input, this corresponds to Analog video input 2.

c

 This corresponds to a signal whose name ends with B.

d

m

q

 For the base-mode configuration, this corresponds to connector 2. For information on the camera description, see the section the Cameras that can be connected to Matrox Meteor-II section in
          Chapter 6: Matrox Meteor-II in the Board Specific notes.

h

 For composite color/monochrome input, this corresponds to VID_IN2.

k

p

 For Y/C input, this corresponds to VID_IN3 (Y of camera 2) and VID_IN4 (C of camera 2).

k

p

 For Y/C input, this corresponds to VID_IN2 (Y of camera 2) and VID_IN3 (C of camera 2).

l

  Open   Collapse  M_CH2

 Specifies channel 2 as the channel on which the digitizer is to receive input data.  Specifies channel 2 as the channel on which the digitizer is to receive input data ...

a
b
c

i
j
k
l

p

Specifics

 For monochrome input, this corresponds to VID1_IN3.

a

j

 For monochrome digital input, this corresponds to DATA, INPUT 16-23.

c

i

 For monochrome input, this corresponds to Analog video input 3.

c

 For composite color/monochrome input, this corresponds to VID_IN2.

b

l

 For composite color/monochrome input, this corresponds to VID_IN3.

k

p

 For Y/C input, this corresponds to VID_IN6 (Y of camera 3) and VID_IN7 (C of camera 3).

k

 For Y/C input, this corresponds to VID_IN4 (Y of camera 3) and VID_IN5 (C of camera 3).

l

 For Y/C input, this corresponds to VID_IN5 (Y of camera 3) and VID_IN6 (C of camera 3).

p

  Open   Collapse  M_CH3

 Specifies channel 3 as the channel on which the digitizer is to receive input data.  Specifies channel 3 as the channel on which the digitizer is to receive input data ...

b
c

i

k
l

p

Specifics

 For monochrome digital input, this corresponds to DATA, INPUT 24-31.

c

i

 For monochrome input, this corresponds to Analog video input 4.

c

 For composite color/monochrome input, this corresponds to VID_IN3.

l

 For composite color/monochrome input, this corresponds to VID_IN4.

k

p

 For Y/C input, this corresponds to VID_IN8 (Y of camera 4) and VID_IN5 (C of camera 4).

k

 For Y/C input, this corresponds to VID_IN6 (Y of camera 4) and VID_IN7 (C of camera 4).

l

 For Y/C input, this corresponds to VID_IN7 (Y of camera 4) and VID_IN8 (C of camera 4).

p

  Open   Collapse  M_CH4

 Specifies channel 4 as the channel on which the digitizer is to receive input data.  Specifies channel 4 as the channel on which the digitizer is to receive input data ...

a

j
k
l

p

Specifics

 For monochrome input, this corresponds to VID2_IN1.

a

j

 For composite color/monochrome input, this corresponds to VID_IN4.

l

 For composite color/monochrome input, this corresponds to VID_IN5.

k

p

 For Y/C input, this corresponds to VID_IN8 (Y of camera 5) and VID_IN9 (C of camera 5).

l

 For Y/C input, this corresponds to VID_IN9 (Y of camera 5) and VID_IN10 (C of camera 5).

k

p

  Open   Collapse  M_CH5

 Specifies channel 5 as the channel on which the digitizer is to receive input data.  Specifies channel 5 as the channel on which the digitizer is to receive input data ...

a

j
k
l

p

Specifics

 For monochrome input, this corresponds to VID2_IN2.

a

j

 For composite color/monochrome input, this corresponds to VID_IN5.

l

 For composite color/monochrome input, this corresponds to VID_IN6.

k

p

 For Y/C input, this corresponds to VID_IN10 (Y of camera 6) and VID_IN11 (C of camera 6).

l

 For Y/C input, this corresponds to VID_IN11 (Y of camera 6) and VID_IN12 (C of camera 6).

k

p

  Open   Collapse  M_CH6

 Specifies channel 6 as the channel on which the digitizer is to receive input data.  Specifies channel 6 as the channel on which the digitizer is to receive input data ...

a

j
k
l

p

Specifics

 For monochrome input, this corresponds to VID2_IN3.

a

j

 For composite color/monochrome input, this corresponds to VID_IN6.

l

 For composite color/monochrome input, this corresponds to VID_IN7.

k

p

 For Y/C input, this corresponds to VID_IN12 (Y of camera 7) and VID_IN13 (C of camera 7).

l

  Open   Collapse  M_CH7

 Specifies channel 7 as the channel on which the digitizer is to receive input data.  Specifies channel 7 as the channel on which the digitizer is to receive input data ...

k
l

p

Specifics

 For composite color/monochrome input, this corresponds to VID_IN7.

l

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN8.

k

p

 For Y/C input, this corresponds to VID_IN14 (Y of camera 8) and VID_IN15 (C of camera 8).

l

  Open   Collapse  M_CH8

 Specifies channel 8 as the channel on which the digitizer is to receive input data.  Specifies channel 8 as the channel on which the digitizer is to receive input data ...

k
l

p

Specifics

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN9.

 This channel is only available on the Matrox Orion /Standard and /Dual for 4Sight-II.

p

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN9.

 This channel is only available to the Matrox Meteor-II /Standard for PCI and PC/104-Plus.

k

 For composite color/monochrome input, this corresponds to VID_IN8.

l

  Open   Collapse  M_CH9

 Specifies channel 9 as the channel on which the digitizer is to receive input data.  Specifies channel 9 as the channel on which the digitizer is to receive input data ...

k
l

p

Specifics

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN9.

 This channel is only available on the Matrox Orion /Standard and /Dual for 4Sight-II.

p

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN9.

 This channel is only available to the Matrox Meteor-II /Standard for PCI and PC/104-Plus.

k

 For composite color/monochrome input, this corresponds to VID_IN9.

l

  Open   Collapse  M_CH10

 Specifies channel 10 as the channel on which the digitizer is to receive input data.  Specifies channel 10 as the channel on which the digitizer is to receive input data ...

k
l

p

Specifics

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN9.

 This channel is only available on the Matrox Orion /Standard and /Dual for 4Sight-II.

p

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN9.

 This channel is only available to the Matrox Meteor-II /Standard for PCI and PC/104-Plus.

k

 For composite color/monochrome input, this corresponds to VID_IN10.

l

  Open   Collapse  M_CH11

 Specifies channel 11 as the channel on which the digitizer is to receive input data.  Specifies channel 11 as the channel on which the digitizer is to receive input data ...

k
l

p

Specifics

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN9.

 This channel is only available on the Matrox Orion /Standard and /Dual for 4Sight-II.

p

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN9.

k

 For composite color/monochrome input, this corresponds to VID_IN11.

l

  Open   Collapse  M_CH12

 Specifies channel 12 as the channel on which the digitizer is to receive input data.  Specifies channel 12 as the channel on which the digitizer is to receive input data ...

l

p

Specifics

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN13. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

 For composite color/monochrome input, this corresponds to VID_IN12.

l

  Open   Collapse  M_CH13

 Specifies channel 13 as the channel on which the digitizer is to receive input data.  Specifies channel 13 as the channel on which the digitizer is to receive input data ...

l

p

Specifics

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN14. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

 For composite color/monochrome input, this corresponds to VID_IN13.

l

  Open   Collapse  M_CH14

 Specifies channel 14 as the channel on which the digitizer is to receive input data.  Specifies channel 14 as the channel on which the digitizer is to receive input data ...

l

p

Specifics

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN15. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

 For composite color/monochrome input, this corresponds to VID_IN14.

l

  Open   Collapse  M_CH15

 Specifies channel 15 as the channel on which the digitizer is to receive input data.  Specifies channel 15 as the channel on which the digitizer is to receive input data ...

l

p

Specifics

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN16. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

 For composite color/monochrome input, this corresponds to VID_IN15.

l

  Open   Collapse  M_CH16

 Specifies channel 16 as the channel on which the digitizer is to receive input data.  Specifies channel 16 as the channel on which the digitizer is to receive input data ...

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN17. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

  Open   Collapse  M_CH17

 Specifies channel 17 as the channel on which the digitizer is to receive input data.  Specifies channel 17 as the channel on which the digitizer is to receive input data ...

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN18. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

  Open   Collapse  M_CH18

 Specifies channel 18 as the channel on which the digitizer is to receive input data.  Specifies channel 18 as the channel on which the digitizer is to receive input data ...

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN19. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

  Open   Collapse  M_CH19

 Specifies channel 19 as the channel on which the digitizer is to receive input data.  Specifies channel 19 as the channel on which the digitizer is to receive input data ...

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN20. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

  Open   Collapse  M_CH20

 Specifies channel 20 as the channel on which the digitizer is to receive input data.  Specifies channel 20 as the channel on which the digitizer is to receive input data ...

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN21. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

  Open   Collapse  M_CH21

 Specifies channel 21 as the channel on which the digitizer is to receive input data.  Specifies channel 21 as the channel on which the digitizer is to receive input data ...

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN22. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

  Open   Collapse  M_CH22

 Specifies channel 22 as the channel on which the digitizer is to receive input data.  Specifies channel 22 as the channel on which the digitizer is to receive input data ...

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN23. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

  Open   Collapse  M_CH23

 Specifies channel 23 as the channel on which the digitizer is to receive input data.  Specifies channel 23 as the channel on which the digitizer is to receive input data ...

 For composite color/monochrome (decoder path) input, this corresponds to VID_IN24. Note that this is only available for composite cameras connected to the Matrox Orion /Dual for 4Sight-II.

p

  Open   Collapse  M_RGB

 Specifies the RGB input source (if present) on which the digitizer is to receive input data. This is the same as M_CH0, except that the synchronization is set on channel 3. This selection can be used only for RGB input.  Specifies the RGB input source (if present) on which the digitizer is to receive input data ...

a

c

j

p

Specifics

 This corresponds to VID1_IN1, VID1_IN2, VID1_IN3, and SYNC_IN (synchronization signal).

a

j

 This corresponds to VID_IN1, VID_IN2, VID_IN3 and VID_IN4 (synchronization signal). Note that this is not available on Matrox Orion /Standard and /Dual for 4Sight-II.

p

      [Combination constants]

[Matrox Corona-II, Matrox Genesis, Matrox Helios XA, Matrox Meteor-II /Multi-Channel, Matrox Odyssey XA, Matrox Orion, and Matrox Solios XA]

 The following value can be added to any supported channel:

  Open   Collapse  Value
Description

  Open   Collapse  M_SIGNAL

 Specifies that the selected channel will be used for data input.  Specifies that the selected channel will be used for data input.

      [Combination constants]

[Matrox Corona-II, Matrox Genesis, Matrox Helios XA, Matrox Meteor-II /Multi-Channel, Matrox Odyssey XA, Matrox Orion, and Matrox Solios XA]

 The following values can be used to select a synchronization channel instead of a data channel.

[Matrox Helios XA, Matrox Odyssey XA, and Matrox Solios XA]

 Note that using a digitizer as an external synchronization signal renders the digitizer of that signal "occupied" and not available for allocating as a digitizer.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_CH0 + M_SYNC

 Specifies channel 0 as the channel on which the digitizer is to receive synchronization data.  Specifies channel 0 as the channel on which the digitizer is to receive synchronization data ...

a

c
d

j

m

p
q

Specifics

 This corresponds to VID1_IN1.

a

j

 This corresponds to Analog video input 1.

c

 This corresponds to VID_IN1. This setting is available when, for monochrome, the data channel is M_CH0, M_CH1, or M_CH2, and for RGB input, when the data channel is M_CH0.

 Note that this settings is only supported when using the RGB path of Matrox Orion and Matrox Orion /RGB for 4Sight-II.

p

 This corresponds to P0_VID_IN_ n, where n is either A or B. The synchronization signal must be received on a signal whose name ends with the same letter as the data signal or the specified digitizer must not be able to receive data on this signal.

d

m

q

  Open   Collapse  M_CH1 + M_SYNC

 Specifies channel 1 as the channel on which the digitizer is to receive synchronization data.  Specifies channel 1 as the channel on which the digitizer is to receive synchronization data ...

a

c
d

j

m

p
q

Specifics

 This corresponds to VID_IN2. This setting is available when, for monochrome, the data channel is M_CH0, M_CH1, or M_CH2, and for RGB input, when the data channel is M_CH0.

 Note that this settings is only supported when using the RGB path of Matrox Orion and Matrox Orion /RGB for 4Sight-II.

p

 This corresponds to VID1_IN2.

a

j

 This corresponds to Analog video input 2.

c

 This corresponds to P1_VID_IN_ n, where n is either A or B. The synchronization signal must be received on a signal whose name ends with the same letter as the data signal or the specified digitizer must not be able to receive data on this signal.

d

m

q

  Open   Collapse  M_CH2 + M_SYNC

 Specifies channel 2 as the channel on which the digitizer is to receive synchronization data.  Specifies channel 2 as the channel on which the digitizer is to receive synchronization data ...

a

c
d

j

m

p
q

Specifics

 This corresponds to Analog video input 3.

c

 This corresponds to VID1_IN3.

a

j

 This corresponds to VID_IN3. This setting is available when, for monochrome, when the data channel is M_CH0, M_CH1, or M_CH2, and for RGB input, when the data channel is M_CH0.

 Note that this settings is only supported when using the RGB path of Matrox Orion and Matrox Orion /RGB for 4Sight-II.

p

 This corresponds to P2_VID_IN_ n, where n is either A or B. The synchronization signal must be received on a signal whose name ends with the same letter as the data signal or the specified digitizer must not be able to receive data on this signal.

d

m

q

  Open   Collapse  M_CH3 + M_SYNC

 Specifies channel 3 as the channel on which the digitizer is to receive synchronization data.  Specifies channel 3 as the channel on which the digitizer is to receive synchronization data ...

a

c
d

j

m

p
q

Specifics

 This corresponds to Analog video input 4.

c

 This corresponds to SYNCH_IN.

a

j

 This corresponds to VID_IN4. This setting is available when, for monochrome, the data channel is M_CH0, M_CH1, or M_CH2, and for RGB input, when the data channel is M_CH0.

 Note that this settings is only supported when using the RGB path of Matrox Orion and Matrox Orion /RGB for 4Sight-II.

p

 This corresponds to P3_VID_IN_ n, where n is either A or B. The synchronization signal must be received on a signal whose name ends with the same letter as the data signal or the specified digitizer must not be able to receive data on this signal.

d

m

q

  Open   Collapse  M_CH4 + M_SYNC

 Specifies channel 4 as the channel on which the digitizer is to receive synchronization data.  Specifies channel 4 as the channel on which the digitizer is to receive synchronization data ...

a

j

p

Specifics

 This corresponds to VID2_IN1.

a

j

 This corresponds to VID_IN5. This setting is available when, for monochrome, when the data channel is M_CH4, M_CH5, or M_CH6, and for RGB input, when the data channel is M_CH1.

 Note that this settings is only supported when using the RGB path of Matrox Orion and Matrox Orion /RGB for 4Sight-II.

p

  Open   Collapse  M_CH5 + M_SYNC

 Specifies channel 5 as the channel on which the digitizer is to receive synchronization data.  Specifies channel 5 as the channel on which the digitizer is to receive synchronization data ...

a

j

p

Specifics

 This corresponds to VID2_IN2.

a

j

 This corresponds to VID_IN6. This setting is available when, for monochrome, when the data channel is M_CH4, M_CH5, or M_CH6, and for RGB input, when the data channel is M_CH1.

 Note that this settings is only supported when using the RGB path of Matrox Orion and Matrox Orion /RGB for 4Sight-II.

p

  Open   Collapse  M_CH6 + M_SYNC

 Specifies channel 6 as the channel on which the digitizer is to receive synchronization data.  Specifies channel 6 as the channel on which the digitizer is to receive synchronization data ...

a

j

p

Specifics

 This corresponds to VID2_IN3.

a

j

 This corresponds to VID_IN7. This setting is available when, for monochrome, when the data channel is M_CH4, M_CH5, or M_CH6, and for RGB input, when the data channel is M_CH1.

 Note that this settings is only supported when using the RGB path of Matrox Orion and Matrox Orion /RGB for 4Sight-II.

p

  Open   Collapse  M_CH7 + M_SYNC

 Specifies channel 7 as the channel on which the digitizer is to receive synchronization data.  Specifies channel 7 as the channel on which the digitizer is to receive synchronization data ...

a

j

p

Specifics

 This corresponds to SYNC_IN.

a

j

 This corresponds to VID_IN8. This setting is available when, for monochrome, when the data channel is M_CH4, M_CH5, or M_CH6, and for RGB input, when the data channel is M_CH1.

 Note that this settings is only supported when using the RGB path of Matrox Orion and Matrox Orion /RGB for 4Sight-II.

p

SIGNAL CAMERA LOCK CAMERA LOCK ENABLE FAST CH0 DEFAULT CH0 CH0 CH0 CH1 CH2 CH0 CH0 CH1 CH2 CH0 CH0 CH1 CH2 CH0 CH0 CH1 CH2 CH0 CH4 CH5 CH6 CH1 CH4 CH5 CH6 CH1 CH4 CH5 CH6 CH1 CH4 CH5 CH6 CH1   DEFAULT CH0 CH1 CH2 CH3 CH4 CH5 CH6 CH7 CH8 CH9 CH10 CH11 CH12 CH13 CH14 CH15 CH16 CH17 CH18 CH19 CH20 CH21 CH22 CH23 RGB  SIGNAL CH0  M SYNC CH1  M SYNC CH2  M SYNC CH3  M SYNC CH4  M SYNC CH5  M SYNC CH6  M SYNC CH7  M SYNC


MdigControl

See Also | Example | Availability | MdigChannel | MdigFocus
User Guide:
Using this help
Grabbing images
Using buffers with the Bayer color filter
Data format
Multiple cameras
Grabbing a single field
Reference levels, lookup tables, and scaling
Optimizing application performance when grabbing
Grabbing with triggers and exposures
Multi-threading

Reference:
MbufBayer
MdigGetHookInfo
MdigGrab
MdigGrabContinuous
MdigHalt
MdigInquire
MdigReference
MsysControl
MsysInquire
channel_switch.c
dtkobjecttracking.c
mdigdoublebuffering.c
mdiggrabmultiple.c
mdiggrabsequence.c
mdighook.c
mdigmultdestination.c
mdigmultformat.c
mgbfocus.c
mgrabbayer.c
mheliosconcurent.c
mmodeltracking.c
muart.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Control a digitizer setting.
Syntax
void MdigControl(
MIL_ID DigId,
long ControlType,
double ControlValue
)
Description

This function allows you to control various digitizer settings.

If changing a control type of a digitizer currently being used in a grab, the change does not affect the current grab. It does, however, affect the very next grab.

Note that you can use MdigInquire() to inquire about specific digitizer settings.

Parameters
DigId

Specifies the identifier of the digitizer.

ControlType

Specifies the digitizer setting to control.

See the Parameter associations section for possible values.

ControlValue

Specifies the value to assign to the digitizer setting.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

Open Collapse ControlType Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
ControlValue
Open Collapse M_BASE_PIXEL_OFFSET

Sets the offset to add to each grabbed pixel value. Adding an offset has a similar effect as applying an automatic linear LUT (for contrast). Sets the offset to add to each grabbed pixel value ...

f
0 to 255

Specifies the value to add to each grabbed pixel value.

f
Open Collapse M_BAYER_COEFFICIENTS_ID

Loads the internal white balance coefficients buffer with the specified values. To have MIL automatically calculate these coefficients and load them into the internal buffer, use the M_WHITE_BALANCE control type with M_CALCULATE. Note that the internal buffer only has an effect if the M_BAYER_CONVERSION and M_WHITE_BALANCE control types are enabled. Loads the internal white balance coefficients buffer with the specified values ...

e n o
MIL array buffer identifier

Specifies the identifier of an M_ARRAY buffer containing the white balance coefficients. The buffer must be allocated as a single-band 32-bit floating point buffer with a 3X1 dimension. For more information, see the Correcting the white balance of your Bayer images subsection in the Using buffers with the Bayer color filter section in Chapter 14: Specifying and managing your data buffers.

If you change the coefficient values in your buffer, you must call MdigControl() again with the updated buffer.

e n o
Open Collapse M_BAYER_CONVERSION

Sets whether to perform a Bayer color conversion. This control type can only be used when grabbing from a camera that has a Bayer color filter (as specified by the DCF), otherwise an error will be generated. For a more conventional technique of controlling Bayer conversion, use MbufBayer() and see the Correcting the white balance of your Bayer images subsection in the Using buffers with the Bayer color filter section in Chapter 14: Specifying and managing your data buffers. Sets whether to perform a Bayer color conversion ...

e n o
M_DEFAULT

Same as M_ENABLE.

e n o
M_DISABLE

Disables a Bayer conversion on the grabbed image.

e n o
M_ENABLE

Enables a Bayer conversion on the grabbed image. The DCF specifies the conversion's Bayer pattern. Note that to white balance an image, M_WHITE_BALANCE must also be set to M_ENABLE.

e n o
Open Collapse M_BRIGHTNESS

Sets the black level of the picture. For a more conventional technique of setting camera brightness, use MdigReference() with M_BRIGHTNESS_REF. Sets the black level of the picture ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_CAMERA_COLOR_LOCK

Sets whether a color-lock check is done before starting each grab if M_CAMERA_LOCK is enabled, or when using MdigInquire() with M_CAMERA_LOCKED. Note that this only applies when the digitizer uses a composite or Y/C color DCF. Sets whether a color-lock check is done before starting each grab if M_CAMERA_LOCK is enabled, or when using MdigInquire() with M_CAMERA_LOCKED ...

b k l p
M_DEFAULT

Same as M_ENABLE.

b k l p
M_DISABLE

Specifies that a color-lock check will not be done.

b k l p
M_ENABLE

Specifies that a color-lock check will be done.

b k l p
Open Collapse M_CAMERA_LOCK

Sets whether the camera is locked during channel-switching. Locking the camera during channel-switching is useful when the digitizer might not be synchronized with the source. When performing a channel-switch, the hardware needs to be unlocked from the current camera and locked to the new camera. If the hardware is not locked properly, it can affect the speed and reliability of the next unlock. Sets whether the camera is locked during channel-switching ...

a b d j k l m p q
M_DEFAULT

Implements the default behavior.

a b d j k l m p q
Specifics

Same as M_DISABLE.

a j k

Same as M_ENABLE.

b d l m p q
M_DISABLE

Causes MdigGrab() to grab without verifying whether the digitizer is locked with the camera. Corrupt images or a synchronization-lost error can occur if the digitizer is not locked.

a b d j k l m p q
M_ENABLE

Causes MdigGrab() to wait until the digitizer is locked with the camera before starting the grab.

Note that M_ENABLE can be used in combination with another value; see below.

a b d j k l m p q
Open Collapse M_CAMERA_LOCK_SENSITIVITY

Sets how sensitive the frame grabber is to locking with the next camera, during a channel switch. This control type only has an effect if M_CAMERA_LOCK is enabled. The lock sensitivity determines how quickly a lock can occur and how reliable the lock is. Sets how sensitive the frame grabber is to locking with the next camera, during a channel switch ...

a j k l p
Specifics

Note that M_CAMERA_LOCK_SENSITIVITY is not available if M_CAMERA_LOCK is set to M_ENABLE + M_FAST.

p
M_DEFAULT

Specifies the optimal compromise between speed and reliability, and varies depending on the board.

a j k l p
0 to 255

Specifies the camera line-lock sensitivity level. 0 is the least reliable but fastest lock speed.

a j k l p
256 to 511

Specifies the additional camera line-lock sensitivity levels available.

l
Open Collapse M_CAMERA_PRESENT_SENSITIVITY

Sets the number of vertical synchronization pulses that will occur after a channel switch. If no signal is present, a "Signal not present" error is generated. This control type is only available when the control type M_CAMERA_LOCK is set to M_ENABLE + M_FAST. Sets the number of vertical synchronization pulses that will occur after a channel switch ...

This is supported only on the Matrox Orion /Standard and /Dual for 4Sight-II.

p
M_DEFAULT

Specifies the optimal compromise between speed and reliability, and varies depending on the board.

p
0 to 255

Specifies the number of vertical synchronization pulses for which the digitizer will wait. 0 means the digitizer will not check for a camera before grabbing.

p
Open Collapse M_CAMERA_UNLOCK_SENSITIVITY

Sets how sensitive the frame grabber is to unlocking from the camera, during a channel switch. This control type only has an effect if M_CAMERA_LOCK is enabled. The unlock sensitivity determines how quickly an unlock can occur and how reliable the unlock is. Sets how sensitive the frame grabber is to unlocking from the camera, during a channel switch ...

a l p
Specifics

This is supported only on the Matrox Orion /Standard and /Dual for 4Sight-II.

p

Note that M_CAMERA_UNLOCK_SENSITIVITY is available only if M_CAMERA_LOCK is not set to M_ENABLE + M_FAST.

l p
M_DEFAULT

Specifies the optimal compromise between speed and reliability, and varies depending on the board.

a l p
0 to 255

Specifies the camera line-unlock sensitivity level. 0 is the least reliable but fastest lock speed.

a l p
Open Collapse M_CAMERALINK_CCn_SOURCE

Routes a specific signal to camera control output n, where n is the number of the camera control output (1, 2, 3, or 4). Routes a specific signal to camera control output n, where n is the number of the camera control output (1, 2, 3, or 4) ...

e h n r
M_DEFAULT

Same as the one specified by the DCF.

e h n r
M_GRAB_EXPOSURE

Specifies that the camera control output comes from an exposure timer.

Note that this value can be used in combination; see below.

e h n r
M_HSYNC

Uses the horizontal synchronization frequency of the camera.

e n r
M_PIXCLK

Uses the pixel clock frequency of the camera.

e n r
M_USER_BIT_CC_A

Adds the specified camera link signal to group A, so that setting one of the user-defined signal in this group will set all user-defined signals in this group.

e h n r
Specifics

Use M_USER_BIT_VALUE + M_CCn to access this group of user-defined signals. Note that you can only output a total of 2 different signals on the 4 signals available.

e n r

For Meteor-II /Camera Link, user-defined signal 0 can only be assigned to group A. In addition, use M_USER_BIT_VALUE + 0 to access this group of user-defined signals.

h
M_USER_BIT_CC_B

Adds the specified camera link signal to group B, so that setting one of the user-defined signal in this group will set all user-defined signals in this group.

e h n r
Specifics

Use M_USER_BIT_VALUE + M_CCn to access this group of user-defined signals. Note that you can only output a total of 2 different signals on the 4 signals available.

e n r

For Meteor-II /Camera Link, user-defined signal 1 can only be assigned to group B. In addition, use M_USER_BIT_VALUE + 1 to access this group of user-defined signals.

e n r
M_VSYNC

Uses the vertical synchronization frequency of the camera.

e n r
Open Collapse M_CAPTURE_QUALITY

Sets the capture quality of the image. Sets the capture quality of the image ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_CAPTURE_SIZE

Sets the capture size of the image. Sets the capture size of the image ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_COUPLING_MODE

Sets the signal coupling of the available data channels. Sets the signal coupling of the available data channels ...

d m q
M_AC

Specifies that the input signal of the data channel(s) is capacitor coupled (AC coupled).

This is the default value.

 d m q
M_DC

Specifies that the input signal of the data channel(s) is directly coupled (DC coupled).

d m q
Open Collapse M_FOCUS

Sets the lens focus capabilities. Sets the lens focus capabilities ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_GAIN

Sets the camera circuit gain. For a more conventional technique of setting the gain, use MdigControl() with M_GRAB_INPUT_GAIN. Sets the camera circuit gain ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_GAMMA

Specifies the difference between the incoming light level and output picture level for a grab. Specifies the difference between the incoming light level and output picture level for a grab ...

f g
Specifics

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g

Note that the gamma level is used to control a physical LUT which is applied automatically to the grab buffer.

f
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

f g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

f g
Open Collapse M_GRAB_ABORT

Immediately stops a grabs in progress and aborts queued grabs. This is useful for cancelling a triggered grab that is waiting for the trigger. Immediately stops a grabs in progress and aborts queued grabs ...

a b c d e h i j k l m n o p q r
M_DEFAULT

Implements the default behavior.

a b c d e h i j k l m n o p q r
Open Collapse M_GRAB_AUTOMATIC_INPUT_GAIN

Specifies whether the on-board decoder should automatically set the input gain. Specifies whether the on-board decoder should automatically set the input gain ...

b k l p
Specifics

By default, this setting is applied to both Y (luminance) and C (chrominance) components (for composite, after separation). To apply this setting to a specific component, see combination values below.

l
M_DEFAULT

Same as M_ENABLE.

b k l p
M_DISABLE

Disables automatic input gain.

b k l p
M_ENABLE

Enables automatic input gain.

b k l p
Open Collapse M_GRAB_CONTINUOUS_END_TRIGGER

Sets whether to automatically generate a trigger after MdigHalt() is issued when performing a triggered continuous grab. Sets whether to automatically generate a trigger after MdigHalt() is issued when performing a triggered continuous grab ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value.

M_ENABLE is the default for a software trigger grab.

M_DISABLE is the default for a hardware trigger grab.

a b c d e f g h i j k l m n o p q r
M_DISABLE

Does not generate the trigger automatically.

With a software triggered continuous grab operation, MdigHalt() will wait indefinitely until a software trigger is issued on a separate thread.

With a hardware triggered continuous grab operation, MdigHalt() will wait indefinitely until a hardware trigger is generated before invoking the last grab.

a b c d e f g h i j k l m n o p q r
M_ENABLE

Generates the trigger automatically.

With a software triggered continuous grab operation, MdigHalt() will generate a software trigger that invokes the last grab.

With a hardware triggered continuous grab operation, MdigHalt() will invoke a last grab and not wait indefinitely for a hardware trigger.

a b c d e f g h i j k l m n o p q r
Open Collapse M_GRAB_DIRECTION_X

Sets the horizontal grab direction. Sets the horizontal grab direction ...

a b c d e h i j k l m n o p q r
M_DEFAULT

Same as M_FORWARD.

a b c d e h i j k l m n o p q r
M_FORWARD

Grabs from left to right, in the horizontal direction.

a b c d e h i j k l m n o p q r
M_REVERSE

Flips the grabbed image horizontally.

a b c d e h i j k l m n o p q r
Open Collapse M_GRAB_DIRECTION_Y

Sets the vertical grab direction. Sets the vertical grab direction ...

a b c d e h i j k l m n o p q r
Specifics

This control type only has an effect if the grab buffer has an M_ON_BOARD attribute; there is no effect when grabbing to Host memory.

In addition, grab buffers with the M_DISP attribute are not supported.

h i
M_DEFAULT

Same as M_FORWARD.

a b c d e h i j k l m n o p q r
M_FORWARD

Grabs from top to bottom, in the vertical direction.

a b c d e h i j k l m n o p q r
M_REVERSE

Flips the grabbed image vertically.

a b c d e h i j k l m n o p q r
Open Collapse M_GRAB_FAIL_CHECK

Sets whether and when to log a grab-fail error. Sets whether and when to log a grab-fail error ...

b
M_DEFAULT

Same as M_FINAL_GRAB.

b
M_DISABLE

Does not log grab failures.

b
M_ENABLE

Logs all grab failures.

b
M_FINAL_GRAB

Logs monoshot grab failures or that of the last frame of a continuous grab.

b
Open Collapse M_GRAB_FAIL_RETRY_NUMBER

Sets the number of retries when a field or frame grab fails. Sets the number of retries when a field or frame grab fails ...

b
M_DEFAULT

Specifies the default value. The default value is 1.

b
0 to 255

Specifies the required number.

b
Open Collapse M_GRAB_FIELD_NUM

Sets the number of fields to grab when grabbing data with MdigGrab(). Sets the number of fields to grab when grabbing data with MdigGrab() ...

This control type should only be used for interlaced video. When using progressive cameras, set this control type to 1.

a b c d e g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. For interlaced cameras, the default is 2. For progressive cameras, the default is 1.

a b c d e g h i j k l m n o p q r
1

Specifies to grab one field. The grabbed field is written to sequential rows of the grab buffer. When set to 1, each field is treated like a frame and the following digitizer hook events are aligned with the field: M_GRAB_FRAME_START, M_GRAB_END, and M_GRAB_FRAME_END. To achieve 60 fps in NTSC or 50 fps in PAL, the control type M_GRAB_START_MODE must be set to M_FIELD_START.

a b c d e g h i j k l m n o p q r
2

Specifies to grab two fields.

a b c d e g h i j k l m n o p q r
Open Collapse M_GRAB_INPUT_GAIN

Sets the input gain with which to amplify the input signal. This allows you to optimize the amplitude of the video input signal so that the full dynamic range of the component digitizing the video is used. Sets the input gain with which to amplify the input signal ...

a b c d f g j k l m p q
Specifics

By default, this setting is applied to all acquisition paths used by the digitizer or to both Y (luminance) and C (chrominance) components (for composite, after separation). To apply this setting to a specific acquisition path or component see combination values below.

c d l m q

M_GRAB_INPUT_GAIN affects the black and white references, set using MdigReference().

d m q

Note that the M_GRAB_INPUT_GAIN cannot be changed if M_GRAB_TRIGGER is set to M_ENABLE.

f
M_DEFAULT

Specifies the default input gain.

a b c d f j l m p q
Specifics

Same as M_GAIN2.

a j p

Same as M_GAIN3.

c

The exact gain level varies depending on the board.

b l

Same as the one specified by the DCF.

d f m q
0 to 255

Specifies a specific integer value which is used to determine the input gain.

b d f g k l m p q
Specifics

The control type M_GRAB_AUTOMATIC_INPUT_GAIN must be disabled.

b k l p

0 is mapped to the minimum value supported by the camera; 255 is mapped to the maximum value supported by the camera.

f g
M_GAIN0

Specifies the first input gain supported for the given valid input voltage.

a c d j m p q
Specifics

Sets a gain of 1.3. This should be used when the input voltage is 1.4 - 2.0 Vpp.

a p

Sets a gain of 1.3. This should be used when the input voltage is 1.4 - 2.1 Vpp.

j

Sets a gain of 2. This should be used when the input voltage is 1.0 - 1.4 Vpp.

c

Sets a gain of 1. This should be used when the input voltage is 0.0 - 1.0 Vpp. Note that this control value can be modified by modifying the DCF or by using the native library function set.

d m q

Only available on Matrox Orion /RGB for 4Sight-II.

p
M_GAIN1

Specifies the second input gain supported for the given valid input voltage.

a c d j m p q
Specifics

Sets a gain of 2. This should be used when the input voltage is 1.0 - 1.4 Vpp.

a j p

Sets a gain of 2.7. This should be used when the input voltage is 0.8 - 1.0 Vpp.

c

Sets a gain of 2. This should be used when the input voltage is 0.0 - 0.5 Vpp. Note that this control value can be modified by modifying the DCF or by using the native library function set.

d m q

Only available on Matrox Orion /RGB for 4Sight-II.

p
M_GAIN2

Specifies the third input gain supported for the given valid input voltage.

a c d j m p q
Specifics

Sets a gain of 2.8. This should be used when the input voltage is 0.7 - 1.0 Vpp.

a j p

Sets a gain of 3.3. This should be used when the input voltage is 0.7 - 0.8 Vpp.

c

Sets a gain of 3. This should be used when the input voltage is 0.0 - 0.333 Vpp. Note that this control value can be modified by modifying the DCF or by using the native library function set.

d m q

Only available on Matrox Orion /RGB for 4Sight-II.

p
M_GAIN3

Specifies the fourth input gain supported for the given valid input voltage.

a c d j m p q
Specifics

Sets a gain of 4. This should be used when the input voltage is 0.0 - 0.7 Vpp.

a j p

Sets a gain of 4.1. This should be used when the input voltage is 0.0 - 0.7 Vpp.

c

Sets a gain of 3.99. This should be used when the input voltage is 0.0 - 0.25 Vpp. Note that this control value can be modified by modifying the DCF or by using the native library function set.

d m q

Only available on Matrox Orion /RGB for 4Sight-II.

p
M_GAIN4

Specifies the fifth input gain supported for the given valid input voltage.

Sets a gain of 1. This should be used when the input voltage is 2.1 - 2.9 Vpp.

a j
Open Collapse M_GRAB_MODE

Sets how the grab should be synchronized with the Host when grabbing data with MdigGrab(). Note that this does not affect MdigGrabContinuous(), which always runs asynchronously, otherwise MdigHalt() could not stop the grab. Sets how the grab should be synchronized with the Host when grabbing data with MdigGrab() ...

a b c d e f g h i j k l m n o p q r
M_ASYNCHRONOUS

Allows your application to continue after initiating the start of a grab, rather than waiting for the grab to finish. This option allows other functions to execute instead of waiting for MdigGrab() to execute.

Note, a call to another MdigGrab() before the current grab has finished will cause your application to wait until the current grab has finished.

a b c d e f g h i j k l m n o p q r
M_ASYNCHRONOUS_QUEUED

Queues the grab on-board if another grab is issued before the first one has finished. This option allows other functions to execute instead of waiting for MdigGrab() to execute. More than one MdigGrab() function can be queued.

a b c d e f g h i j k l m n o p q r
M_SYNCHRONOUS

Synchronizes your application with the end of a grab operation (that is, waits until the grab has finished before returning from the grab function).

This is the default value.

 a b c d e f g h i j k l m n o p q r
Open Collapse M_GRAB_SAMPLING_POSITION

Sets the delay along the analog signal at which the pixel clock will sample. Sets the delay along the analog signal at which the pixel clock will sample ...

Only available on the PC/104-Plus form factor.

j
0 to 255

Specifies the delay along the analog signal.

j
Open Collapse M_GRAB_SCALE

Controls the vertical and horizontal scaling factor when grabbing data with MdigGrab() or MdigGrabContinuous(). Controls the vertical and horizontal scaling factor when grabbing data with MdigGrab() or MdigGrabContinuous() ...

a b c d e f g h i j k l m n o p q r
1

Applies no scaling.

a b c d e f g h i j k l m n o p q r
Specifics

A nearest-neighbor interpolation is applied by default. Use M_INTERPOLATION_MODE to specify different interpolation mode.

p
M_FILL_DESTINATION

Calculates and sets the scaling factor to fill the destination buffer. The best scaling factor supported will be used.

a b c d e f g h i j k l m n o p q r
Value = 1/n

Reduces the image size. Remember that to reduce the image size, the specified value must always be less than 1.

a b c d e f g h i j k l m n o p q r
Specifics

The value of n can be any integer between 2 and 16.

a c d e f h i j k l m n o q r

Note that data grabbed into a YUV buffer can only have a ½ scaling factor.

a

Supports arbitrary scaling. A bilinear interpolation filter is always applied when the scaling value is not 1 or 0.5. When the scaling value is 1 or 0.5, a nearest-neighbor interpolation filter is applied by default. Use M_INPUT_FILTER to specify a different filter.

p

The value of n can be any value between 1 and 64. Supports arbitrary scaling.

b
Value > 1

Increases the image size.

c p
Specifics

Only supports scaling factors of 2 and 4.

c

Supports scaling factors between 1 and 255, including non-integer values.

p
Open Collapse M_GRAB_SCALE_QUALITY

Sets the quality of the scaling. Sets the quality of the scaling ...

p
M_DEFAULT

Same as M_LOW.

p
M_HIGH

Specifies that an entire frame is grabbed in on-board memory before scaling. This setting yields a high quality scaling, but grab latency is doubled.

p
M_LOW

Specifies that each field is scaled separately before being composed into one scaled frame. This setting can cause some vertical scaling artifacts, but grab latency is minimal.

p
Open Collapse M_GRAB_SCALE_X

Controls the horizontal scaling factor when grabbing data with MdigGrab() or MdigGrabContinuous(). Controls the horizontal scaling factor when grabbing data with MdigGrab() or MdigGrabContinuous() ...

a b c d e f g h i j k l m n o p q r
1

See the description of this setting in M_GRAB_SCALE.

a b c d e f g h i j k l m n o p q r
M_FILL_DESTINATION

See the description of this setting in M_GRAB_SCALE.

a b c d e f g h i j k l m n o p q r
Value = 1/n

See the description of this setting in M_GRAB_SCALE.

a b c d e f g h i j k l m n o p q r
Specifics

Note that data grabbed into a YUV buffer can only have a ½ horizontal scaling factor.

a
Value > 1

See the description of this setting in M_GRAB_SCALE.

c p
Open Collapse M_GRAB_SCALE_Y

Controls the vertical scaling factor when grabbing data with MdigGrab() or MdigGrabContinuous(). Controls the vertical scaling factor when grabbing data with MdigGrab() or MdigGrabContinuous() ...

a b c d e f g h i j k l m n o p q r
1

See the description of this setting in M_GRAB_SCALE.

a b c d e f g h i j k l m n o p q r
M_FILL_DESTINATION

See the description of this setting in M_GRAB_SCALE.

a b c d e f g h i j k l m n o p q r
Value = 1/n

See the description of this setting in M_GRAB_SCALE.

a b c d e f g h i j k l m n o p q r
Specifics

Note that the restriction of using a ½ scaling factor when grabbing into a YUV buffer does not apply.

a
Value > 1

See the description of this setting in M_GRAB_SCALE.

c p
Open Collapse M_GRAB_START_MODE

Sets the grab start mode. Sets the grab start mode ...

a b c d e g h i j k l m n o p q r
M_DEFAULT

Specifies the default mode.

a b c d e g h i j k l m n o p q r
Specifics

Specifies M_FIELD_START_EVEN as the default.

c g h i k

Specifies M_FIELD_START_ODD as the default.

a b d e j l m n o p q r
M_FIELD_START

Specifies that the grab start mode starts on any field.

a b c d e g h i j k l m n o p q r
M_FIELD_START_EVEN

Specifies that the grab start mode starts on even.

a b c d e g h i j k l m n o p q r
M_FIELD_START_ODD

Specifies that the grab start mode starts on odd.

a b c d e g h i j k l m n o p q r
Open Collapse M_GRAB_TIMEOUT

Sets the maximum time to wait for a frame before generating an error. Sets the maximum time to wait for a frame before generating an error ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Waits for the frame period to expire. Note that this is the same as M_INFINITE when using a triggered DCF.

a b c d e f g h i j k l m n o p q r
M_INFINITE

Waits indefinitely. This is recommended only for triggered cameras.

a b c d e f g h i j k l m n o p q r
Value > 0

Specifies the time for the wait, in msec.

a b c d e f g h i j k l m n o p q r
Open Collapse M_GRAB_WAIT

Forces the grab of a digitizer to wait and start upon a grab of a second digitizer. This forces MIL to wait for the start of a grab performed by a second digitizer. Note that these grabs can be synchronized so that they are performed in sequence, using MdigControl() with M_SYNCHRONIZE_ON_STARTED instead. Forces the grab of a digitizer to wait and start upon a grab of a second digitizer ...

Note that this is only valid when the destination buffers are on different systems of the same cluster. See the example at the end of this function for more information.

c m n o
M_NULL

Specifies not to wait for a second digitizer.

c m n o
MIL digitizer identifier

Specifies the MIL identifier of the second digitizer.

c m n o
Open Collapse M_GRAB_WINDOW_RANGE

Limits the range of the grabbed pixel values. Limits the range of the grabbed pixel values ...

a b c d e f g h i j k l m n o p q r
Specifics

The range of the limit when grabbing into a 1-band buffer is between 10 and 245.

a c d e g h i j m n o q r

The range of the limit when grabbing into a 1-band buffer is between 16 and 235.

b f k l p

Limits the range of the pixels, grabbed with the RGB path into a 1-band buffer, to between 10 and 245.

p
M_DEFAULT

Same as M_DISABLE.

a b c d e f g h i j k l m n o p q r
M_DISABLE

Disables limiting the range.

a b c d e f g h i j k l m n o p q r
M_ENABLE

Enables limiting the range.

a b c d e f g h i j k l m n o p q r
Open Collapse M_HUE

Sets the color phase of the picture. For a more conventional technique of setting camera hue, use MdigReference() with M_HUE_REF. Sets the color phase of the picture ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_INPUT_FILTER

Sets the low-pass filter applied to incoming data for all available acquisition paths used by the specified digitizer. Note that, to apply the setting to a specific acquisition path, see combination values below. Sets the low-pass filter applied to incoming data for all available acquisition paths used by the specified digitizer ...

a d m p q
Specifics

For Matrox Orion for 4Sight-II, a filter setting cannot be applied to only one specific acquisition path used by the specified digitizer; it is applied to all the available acquisition paths used by the specified digitizer.

p

Refer to the Installation and hardware reference manual for more information regarding the frequencies of low-pass filters.

d m q
M_DEFAULT

Specifies the default value.

a d m p q
Specifics

Same as M_LOW_PASS_1.

d m p q

Same as M_LOW_PASS_2.

a
M_BYPASS

Uses no input filter.

a p
Specifics

Note that this setting is available only for the RGB path.

p
M_LOW_PASS_0

Uses the first low-pass filter.

a d m q
Specifics

Uses a filter of 8 MHz.

a

Uses a filter of 7.5 MHz.

d m q
M_LOW_PASS_1

Uses the second low-pass filter.

a d m p q
Specifics

Uses a filter of 10 MHz.

a

Uses a filter of 40 MHz.

d m q

Uses a filter of 8 MHz.

p
M_LOW_PASS_2

Uses the third low-pass filter.

Uses a filter of 12.5 MHz.

a
Open Collapse M_INTERPOLATION_MODE

Sets the type of interpolation used when scaling the input image. When not scaling, you can use this control type to smooth the grabbed image. Interpolation can be performed on each field separately if M_GRAB_SCALE_QUALITY is set to M_LOW, or on a frame if M_GRAB_SCALE_QUALITY is set to M_HIGH. Sets the type of interpolation used when scaling the input image ...

p
M_DEFAULT

Same as M_NEAREST_NEIGHBOR when the scaling factor is 1 or 0.5, otherwise M_BILINEAR.

p
M_AVERAGE

Specifies averaging interpolation.

Note this is not supported when grabbing into a YUV buffer and the grab is scaled by ½.

p
M_BILINEAR

Specifies bilinear interpolation.

Note this is not supported when grabbing into a YUV buffer and the grab is scaled by ½.

p
M_NEAREST_NEIGHBOR

Specifies the nearest neighbor interpolation.

p
Open Collapse M_IRIS

Sets the aperture for the mechanical lens iris. Sets the aperture for the mechanical lens iris ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_LAST_GRAB_IN_TRUE_BUFFER

Sets whether a monoshot grab is performed when MdigHalt() is called after performing a continuous grab operation. This control type only has an effect if the target buffer of the continuous grab is selected on a display. When the target buffer is selected on the display, the continuous grab will typically grab into the display and only update the target image when MdigHalt() is called. This control type establishes how the update to the target image is made. Sets whether a monoshot grab is performed when MdigHalt() is called after performing a continuous grab operation. This control type only has an effect if the target buffer of the continuous grab is selected on a display ...

a b c d e f g h i j k l m n o p q r
M_DISABLE

Specifies that the last frame grabbed during the continuous grab operation is copied to the target image. This setting might reduce the time it takes for the continuous grab to terminate once MdigHalt() is called (since copying a frame tends to take less time than grabbing a frame).

a b c d e f g h i j k l m n o p q r
M_ENABLE

Specifies that a monoshot grab is performed. Note that after performing a monoshot grab in the buffer selected to the display, the display is updated.

This is the default value.

 a b c d e f g h i j k l m n o p q r
Open Collapse M_OPTICAL_FILTER

Sets the optical filter of the camera lens function. Sets the optical filter of the camera lens function ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_PAN

Sets the panning capabilities for your camera. Sets the panning capabilities for your camera ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_ROTARY_ENCODER

Sets whether the rotary counter is enabled. If enabled, the value of the rotary counter can be retrieved at the end of a grab using MdigGetHookInfo() with M_ROTARY_ENCODER_FRAME_END_POSITION. Note that the current value of the rotary counter can be inquired using MdigInquire() with M_ROTARY_ENCODER_POSITION. Sets whether the rotary counter is enabled ...

e r
M_DEFAULT

Same as M_DISABLE.

e r
M_DISABLE

Disables the rotary counter.

e r
M_ENABLE

Enables rotary counter.

e r
Open Collapse M_ROTARY_ENCODER_DIRECTION

Specifies whether the rotary counter is incrementing or decrementing for the forward direction of the rotary encoder. Specifies whether the rotary counter is incrementing or decrementing for the forward direction of the rotary encoder ...

e r
M_DEFAULT

Same as M_FORWARD.

e r
M_BACKWARD

Decrements the rotary counter. Note that the counter does not decrement to negative numbers. For example, if the rotary counter is zero, the next decremented value is 65535.

e r
M_FORWARD

Increments the rotary counter. Note that the counter cannot increment beyond the value of 65535. In this case, the next incremented value is 0.

e r
Open Collapse M_ROTARY_ENCODER_POSITION

Resets the rotary counter. Resets the rotary counter ...

e r
Value = 0

The rotary counter can only reset to zero. If a non-zero value is specified, an error is generated.

e r
Open Collapse M_ROTARY_ENCODER_POSITION_TRIGGER

Specifies the rotary counter value upon which a trigger is generated. Specifies the rotary counter value upon which a trigger is generated ...

e r
0 <= Value < 65535

Specifies the value of the rotary counter upon which a trigger is generated. If a value beyond this range is specified, an error is generated.

You do not specify a negative number when the rotary direction is set to M_BACKWARD. You must instead specify a positive trigger value calculated by substracting the required number of increments from 65536, the total number of positions in the counter. For example, to trigger after 8 decrements, specify the trigger value as 65528.

e r
Open Collapse M_SATURATION

Sets the color saturation of the picture. For a more conventional technique of setting camera brightness, use MdigReference() with M_SATURATION_REF. Sets the color saturation of the picture ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_SHARPNESS

Sets the sharpness of the picture. Sets the sharpness of the picture ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_SHUTTER

Sets the integration time of the incoming light. Sets the integration time of the incoming light ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_SOURCE_COMPENSATION

Sets whether software compensation is possible when cropping the input signal capture window. Sets whether software compensation is possible when cropping the input signal capture window ...

On Matrox Meteor-II /1394, it is possible to optimize grabs by taking advantage of hardware cropping with a format-7 capable camera. To do so, allocate the camera in format 7. When using the M_SOURCE_SIZE... and M_SOURCE_OFFSET... control types, the cropping will be done by the camera's hardware if it is supported, that is, if the specified offsets and sizes match the boundaries of one of the supported subregions.

Under any other circumstance, cropping will be done by software.

This control type can be used to disable the software compensation to make sure that hardware cropping is used.

g
M_DEFAULT

Same as M_ENABLE.

g
M_DISABLE

Uses hardware settings to crop the capture window, provided that you are using a format 7-capable camera. In this case, if the capture window specified does not match a subregion, an error will be generated.

g
M_ENABLE

Uses software settings to crop the capture window, if not supported by hardware.

g
Open Collapse M_SOURCE_OFFSET_X

Sets the X-offset of the input signal capture window. Sets the X-offset of the input signal capture window ...

Note that certain source sizes, offsets, and destination buffer sizes can affect a grab. Refer to MdigGrab() and MdigGrabContinuous() for more information.

a b c d e f g h i j k l m n o p q r
Value

Specifies the X-offset, in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SOURCE_OFFSET_Y

Sets the Y-offset of the input signal capture window. Sets the Y-offset of the input signal capture window ...

a b c d e f g h i j k l m n o p q r
Value

Specifies the Y-offset, in pixels.

Note that certain source sizes, offsets, and destination buffer sizes can affect a grab. Refer to MdigGrab() and MdigGrabContinuous() for more information.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SOURCE_SIZE_X

Sets the width of the input signal capture window. Sets the width of the input signal capture window ...

Note that certain source sizes, offsets, and destination buffer sizes can affect a grab. Refer to MdigGrab() and MdigGrabContinuous() for more information.

a b c d e f g h i j k l m n o p q r
Value

Specifies the width, in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SOURCE_SIZE_Y

Sets the height of the input signal capture window. Sets the height of the input signal capture window ...

Note that certain source sizes, offsets, and destination buffer sizes can affect a grab. Refer to MdigGrab() and MdigGrabContinuous() for more information.

a b c d e f g h i j k l m n o p q r
Value

Specifies the height, in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SYNCHRONIZE_ON_STARTED

Synchronizes the grab of a digitizer with the end of a grab from a second digitizer, so that the grabs are consecutive. This allows you to grab sequential frames from two or more MIL digitizers. Note that to force MIL to wait for the start of a grab performed by a second digitizer instead, use MdigControl() with M_GRAB_WAIT. Synchronizes the grab of a digitizer with the end of a grab from a second digitizer, so that the grabs are consecutive ...

See the M_SYNCHRONIZE_ON_STARTED example below.

c m n o
M_NULL

Specifies not to synchronize with a second digitizer.

This is the default value.

 c m n o
MIL digitizer identifier

Specifies the MIL identifier of the second digitizer.

c m n o
Open Collapse M_TARGET_TEMPERATURE

Sets the target temperature for the camera. Sets the target temperature for the camera ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_TILT

Sets the camera's tilt capabilities. Sets the camera's tilt capabilities ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_VCR_INPUT_TYPE

Sets the digitizer input type to VCR and improves the image's stability when grabbing from a VCR. Sets the digitizer input type to VCR and improves the image's stability when grabbing from a VCR ...

k p
Specifics

This is only valid when using the decoder path.

p
M_DEFAULT

Same as M_DISABLE.

k p
M_DISABLE

Does not adjust the stability of the image.

k p
M_ENABLE

Improves the image stability when grabbing with a VCR.

k p
Open Collapse M_WHITE_BALANCE

Sets whether to perform white balancing. Sets whether to perform white balancing ...

The white balance coefficients used for white balance correction are taken from an internal buffer, which is created and updated when you specify coefficients (using MdigControl() with M_BAYER_COEFFICIENTS_ID) or when you let the driver calculate them (using this control type with M_CALCULATE).

Note that to use this control type, M_BAYER_CONVERSION must be enabled.

e n o
M_CALCULATE

Calculates new white balance coefficients, overwriting old coefficients.

To calculate the coefficients, it automatically grabs an image that it assumes is a uniform shade of gray that is not saturated. If you are using a triggered camera, you must send a trigger for the internal grab to complete; otherwise, this function will wait indefinitely. For more information, see the Correcting the white balance of your Bayer images subsection in the Using buffers with the Bayer color filter section in Chapter 14: Specifying and managing your data buffers.

You can use MdigInquire() with M_BAYER_COEFFICIENTS_ID to determine the calculated values.

e n o
M_DISABLE

Disables white balancing.

e n o
M_ENABLE

Enables white balancing.

If you have not called MdigControl() with M_BAYER_COEFFICIENTS_ID or with M_WHITE_BALANCE set to M_CALCULATE before enabling white balancing, it will automatically calculate the white balance coefficients and then use those coefficients for subsequent images. Note that if M_WHITE_BALANCE is disabled and then re-enabled, the previously calculated coefficients are used.

e n o
Open Collapse M_WHITE_BALANCE_U

Sets the U chrominance (color) component of the data. Sets the U chrominance (color) component of the data ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_WHITE_BALANCE_V

Sets the V chrominance (color) component of the data. Sets the V chrominance (color) component of the data ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g
Open Collapse M_ZOOM

Sets the camera lens's zoom capabilities. Sets the camera lens's zoom capabilities ...

Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II.

g
M_DEFAULT

Specifies either the camera's default value or the camera's control setting to automatic mode (if supported).

g
Value

Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g

[Combination constants]
[Matrox Morphis and Matrox Orion]

The value below can be added to M_CAMERA_LOCK, enabling it to use ultra-fast camera locking.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_FAST

 Enables ultra-fast camera locking. This uses numerous optimizations to increase the speed of the lock. Use ultra-fast camera locking when high reliability is not an issue; increasing the speed of the camera lock affects the robustness of the subsequent unlock.  Enables ultra-fast camera locking ...

l

p

Specifics

 This is only supported on Matrox Orion /Standard and /Dual for the 4Sight-II.

 Note that M_CAMERA_LOCK_SENSITIVITY and M_CAMERA_UNLOCK_SENSITIVITY have no effect when in this mode.

p

      [Combination constants]

[Matrox Meteor-II /Camera Link]

 One of the following can be added to M_USER_OUT_FORMAT when enabling the LVDS drivers for use with the Camera Link connectors.

  Open   Collapse  Value
Description

  Open   Collapse  M_CH0

 Specifies that the format should be applied to the first acquisition path used by the specified digitizer.  Specifies that the format should be applied to the first acquisition path used by the specified digitizer.

  Open   Collapse  M_CH1

 Specifies that the format should be applied to the second acquisition path used by the specified digitizer.  Specifies that the format should be applied to the second acquisition path used by the specified digitizer.

  Open   Collapse  M_CH0 + M_CH1

 Specifies that the format should be applied to both the first and the second acquisition paths used by the specified digitizer.  Specifies that the format should be applied to both the first and the second acquisition paths used by the specified digitizer ...

This is the default value.

      [Combination constants]

[Matrox Corona-II, Matrox Helios XA, Matrox Odyssey XA, Matrox Orion, and Matrox Solios XA]

 One of the following values can be added to any of the M_INPUT_FILTER settings, to apply the filter to a specific acquisition path used by the digitizer. Each channel represents the available acquisition path used by the digitizer.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_ALL_CHANNELS

 Applies the filter to all acquisition paths used by the specified digitizer.  Applies the filter to all acquisition paths used by the specified digitizer ...

This is the default value.

a

d

m

q

  Open   Collapse  M_CH0

 Applies the filter to the first acquisition path used by the specified digitizer.  Applies the filter to the first acquisition path used by the specified digitizer ...

a

d

m

p
q

Specifics

 For Matrox Orion for 4Sight-II, a filter cannot be applied to only one specific acquisition path used by the specified digitizer; it is applied to all the available acquisition paths used by the specified digitizer.

p

  Open   Collapse  M_CH1

 Applies the filter to the second acquisition path used by the specified digitizer.  Applies the filter to the second acquisition path used by the specified digitizer ...

a

d

m

p
q

Specifics

 For Matrox Orion for 4Sight-II, a filter cannot be applied to only one specific acquisition path used by the specified digitizer; it is applied to all the available acquisition paths used by the specified digitizer.

p

  Open   Collapse  M_CH2

 Applies the filter to the third acquisition path used by the specified digitizer.  Applies the filter to the third acquisition path used by the specified digitizer ...

a

d

m

p
q

Specifics

 For Matrox Orion for 4Sight-II, a filter cannot be applied to only one specific acquisition path used by the specified digitizer; it is applied to all the available acquisition paths used by the specified digitizer.

p

  Open   Collapse  M_CH3

 Applies the filter to the fourth acquisition path used by the specified digitizer.  Applies the filter to the fourth acquisition path used by the specified digitizer.

d

m

q

      [Combination constants]

[Matrox Genesis, Matrox Helios XA, Matrox Morphis, Matrox Odyssey XA, and Matrox Solios XA]

 One of the following values can be added to M_GRAB_INPUT_GAIN and M_GRAB_AUTOMATIC_INPUT_GAIN to apply the input gain setting to a specific acquisition path or component of the input signal.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_CHn

 Applies the input-gain setting to the nth acquisition path used by the digitizer.  Applies the input-gain setting to the nth acquisition path used by the digitizer ...

 More than one acquisition path can be specified by adding them sequentially (for example, M_CH0 + M_CH1).

 M_CHn can only be combined with M_GRAB_INPUT_GAIN.

c
d

m

q

  Open   Collapse  M_CHROMINANCE

 Applies the input-gain setting to the chrominance component of the input signal.  Applies the input-gain setting to the chrominance component of the input signal ...

 Note that the gain setting is applied only after the composite signal is separated into its components.

l

  Open   Collapse  M_LUMINANCE

 Applies the input-gain setting to the luminance component of the input signal.  Applies the input-gain setting to the luminance component of the input signal ...

 Note that the gain setting is applied only after the composite signal is separated into its components.

l

[All except
        Matrox CronosPlus, Matrox Iris, Matrox Meteor-II /1394, and Matrox Morphis]

 The following control types and control values specify the settings for user-defined signals. The user bits are the bits on user-defined input, output, and/or I/O (bidirectional) signals. Refer to the board-specific notes for the correspondence between user-defined signal numbers and the user-defined signal names.

 Note that for other Matrox imaging boards that have user-defined signals, but are not supported with the constants below, see MsysControl().

  Open   Collapse  ControlType
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

ControlValue

  Open   Collapse   M_USER_BIT_FORMAT

 Sets whether to enable the TTL or LVDS transmitter/receiver for a user-defined signal, on systems whose transmitters/receivers are enabled through software and where the option of both TTL and LVDS are possible. Note that some user-defined signals cannot be affected individually. In this case, if you affect any one of the user-defined signals in the group, they will all be affected. Refer to the Technical information appendix in the Installation and Hardware Reference manual for your Matrox imaging board.  Sets whether to enable the TTL or LVDS transmitter/receiver for a user-defined signal, on systems whose transmitters/receivers are enabled through software and where the option of both TTL and LVDS are possible ...

 You must specify the user-defined signal to affect. See combination values below.

 Refer to M_USER_IN_FORMAT and M_USER_OUT_FORMAT to change formats on other Matrox imaging boards.

d
e

m
n
o

q
r

 M_DEFAULT

 Same as the one specified by the DCF.

d
e

m
n
o

q
r

 M_DISABLE

 Disables the transmitters/receivers for the specified user-defined signal.

d
e

m
n
o

q
r

 M_ENABLE

 Enables the transmitters/receivers for the specified user-defined signal.

d
e

m
n
o

q
r

 M_LVDS

 Enables the LVDS transmitters/receivers for the specified user-defined signal.

d
e

m
n
o

q
r

Specifics

 Uses the LVDS user-defined signal on external auxiliary I/O connector 0 (HB-44), instead of the TTL signal. See the User-defined signals section of the board-specific notes for your Matrox imaging board.

d

m

q

 Uses the LVDS user-defined signal on either external auxiliary I/O connectors or digital video input connector 0, instead of the TTL signal. See the Digital subsection in the User-defined signals for Matrox Odyssey section in
          Chapter 8: Matrox Odyssey in the
          Chapter 8: Matrox Odyssey.

o

 M_TTL

 Enables the TTL transmitters/receivers for the specified user-defined I/O signals.

d
e

m
n
o

q
r

Specifics

 Uses the LVDS user-defined signal on external auxiliary I/O connector 0 (HB-44), instead of the TTL signal. See the User defined signals section of the board-specific notes for your Matrox imaging board.

d

m

q

 Uses the LVDS user-defined signals on either external auxiliary I/O connectors or digital video input connector 0, instead of the TTL signal. See the Digital subsection in the User-defined signals for Matrox Odyssey section in
          Chapter 8: Matrox Odyssey.

o

  Open   Collapse   M_USER_BIT_INTERRUPT_MODE

 Sets the type of functional-state change upon which to generate an interrupt. Note that this only applies to user-defined input signals.  Sets the type of functional-state change upon which to generate an interrupt ...

 Note that this control type only has an effect when M_USER_BIT_INTERRUPT_STATE is enabled.

 You must specify the user-defined signal to affect. See below for combination values.

d
e

m
n
o

q
r

 M_DEFAULT

 Same as M_EDGE_RISING.

d
e

m
n
o

q
r

 M_EDGE_RISING

 Specifies to generate an interrupt upon a low-to-high signal variation.

d
e

m
n
o

q
r

  Open   Collapse   M_USER_BIT_INTERRUPT_STATE

 Sets whether to generate an interrupt when the functional state of the user-defined signal changes. Note that this only applies to user-defined input signals.  Sets whether to generate an interrupt when the functional state of the user-defined signal changes ...

 You must specify the user-defined signal to affect. See below for combination values.

d
e

m
n
o

q
r

 M_DISABLE

 Disables the interrupt.

This is the default value.

d
e

m
n
o

q
r

 M_ENABLE

 Enables the interrupt.

d
e

m
n
o

q
r

  Open   Collapse   M_USER_BIT_MODE

 Sets the mode of the specified user-defined I/O signal(s).  Sets the mode of the specified user-defined I/O signal(s) ...

 Note that you can only change the mode of an user-defined I/O (bidirectional) signal.

 You must specify the user-defined signal(s) to affect. See combination values below.

d
e

m
n
o

q
r

 Bit-encoded value

 Specifies the mode of the specified user-defined signals. Bits set to 1 in the bit-encoded value set their corresponding user-defined signals to input. Bits set to 0 in the bit-encoded value set their corresponding user-defined signals to output.

d
e

m
n
o

q
r

 M_INPUT

 Specifies that the user-defined signal is for input.

d
e

m
n
o

q
r

 M_OUTPUT

 Specifies that the user-defined signal is for output.

d
e

m
n
o

q
r

  Open   Collapse   M_USER_BIT_VALUE

 Sets the state of the current bit on the specified user-defined output signal(s) or I/O signals set to output.  Sets the state of the current bit on the specified user-defined output signal(s) or I/O signals set to output ...

 You must specify the user-defined signal(s) to affect. See combination values below.

a

c
d
e

h
i
j
k

m
n
o
p
q
r

 Bit-encoded-value

 Specifies the state of the current bit on the specified user-defined signals. Bits set to 1 in the bit-encoded value set their corresponding user-defined signals to on. Bits set to 0 in the bit-encoded value set their corresponding user-defined signals to off.

d
e

m
n
o

q
r

 M_OFF

 Specifies that the current bit is set to off.

a

c
d
e

h
i
j
k

m
n
o
p
q
r

 M_ON

 Specifies that the current bit is set to on.

a

c
d
e

h
i
j
k

m
n
o
p
q
r

  Open   Collapse   M_USER_IN_FORMAT

 Sets whether to enable the TTL or RS-422/LVDS receivers for trigger and user-defined input signals, on systems whose receivers are enabled through software and where the option of both TTL and RS-422/LVDS are possible. For more information, refer to the Technical information appendix in the Installation and Hardware Reference manual for your Matrox imaging board.  Sets whether to enable the TTL or RS-422/LVDS receivers for trigger and user-defined input signals, on systems whose receivers are enabled through software and where the option of both TTL and RS-422/LVDS are possible ...

 Refer to M_USER_BIT_FORMAT and M_GRAB_TRIGGER_FORMAT to change formats on other Matrox imaging boards.

c

h
i

 M_DEFAULT

 Same as the one specified by the DCF.

c

h
i

 M_DISABLE

 Disables trigger and user-defined input signals. For a more conventional technique of disabling a trigger, use MdigControl() with M_GRAB_TRIGGER set to M_DISABLE.

c

h
i

 M_LVDS

 Enables the LVDS receivers for trigger and user-defined input signals.

c

h
i

Specifics

 Uses the LVDS trigger on either the companion digital input board or the digital cable adaptor board, instead of the TTL trigger.

 Uses the LVDS USER0 and USER1 user-defined signals instead of the TTL user-defined signals.

c

 Uses the LVDS trigger signal on the digital interface connector instead of the TTL trigger signal on the trigger input connector.

h
i

 M_RS422

 Enables the RS-422 receivers for trigger signals and user-defined input signals.

c

h
i

Specifics

 Uses the RS-422 trigger signal on either the companion digital input board or the digital cable adaptor board, instead of the TTL trigger signal.

 Uses the RS-422 USER0 and USER1 INPUT user-defined signals instead of the TTL user-defined signals.

c

 Uses the RS-422 trigger signals on the digital interface connector instead of the TTL trigger signals on the trigger input connector.

h
i

 M_TTL

 Enables the TTL receivers for trigger signals.

c

h
i

Specifics

 Uses the TTL trigger signals instead of the RS-422/LVDS trigger on either the companion digital input board or the digital cable adaptor board.

 Uses the TTL USER0 and USER1 INPUT user-defined signals instead of the RS-422/LVDS user-defined signals.

c

 Uses the TTL trigger signals on the trigger input connector instead of the RS-422/LVDS trigger signals on the digital interface connector.

h
i

  Open   Collapse   M_USER_OUT_FORMAT

 Sets whether to enable the TTL or RS-422/LVDS drivers for exposure and user-defined output signals, on systems whose I/O drivers are enabled through software and where the option of both TTL and RS-422/LVDS are possible. For more information, refer to the Technical information appendix in the Installation and Hardware Reference manual for your Matrox imaging board.  Sets whether to enable the TTL or RS-422/LVDS drivers for exposure and user-defined output signals, on systems whose I/O drivers are enabled through software and where the option of both TTL and RS-422/LVDS are possible ...

 Refer to M_USER_BIT_FORMAT and M_GRAB_EXPOSURE_FORMAT to change formats on other Matrox imaging boards.

c

h
i

 M_DEFAULT

 Same as the one specified by the DCF.

c

h
i

 M_DISABLE

 Disables exposure signals and user-defined output signals. For a more conventional technique of disabling an exposure signal, use MdigControl() with M_GRAB_EXPOSURE set to M_DISABLE.

c

h
i

 M_LVDS

 Enables the LVDS drivers for exposure signals and user-defined output signals.

c

h
i

Specifics

 To enable the LVDS drivers on the Camera Link connectors, you can either apply this control type to one or all acquisition paths available to the digitizer. See combination values below.

h

 Uses the LVDS USER0 and USER1 OUTPUT user-defined signals instead of the TTL user-defined signals.

c

 Uses the LVDS exposure signals (1 and 2) instead of the TTL exposure signals.

i

 M_RS422

 Enables the RS-422 drivers for exposure signals and user-defined output signals.

c

h
i

Specifics

 Uses the RS-422 USER0 and USER1 OUTPUT user-defined signals instead of the TTL user-defined signals.

 Uses the RS-422 exposure signals (1 and 2) instead of the TTL exposure signals.

c

 Uses the RS-422 exposure signals (1 and 2) instead of the TTL exposure signals.

i

 M_TTL

 Enables the TTL drivers for exposure and user-defined output signals.

c

h
i

Specifics

 Uses the TTL USER0 and USER1 OUTPUT user-defined signals instead of the RS-422/LVDS user-defined signals.

c

 Uses the TTL exposure signals (1 and 2) instead of the RS-422/LVDS exposure signals.

h
i

 By default, the TTL drivers are used with the Camera Link connectors.

h

      [Combination constants]

[All except
        Matrox CronosPlus, Matrox Iris, Matrox Meteor-II /1394, and Matrox Morphis]

 One of the following must be added to M_USER_BIT_VALUE or M_USER_BIT_MODE.

 See the Board Specific Notes for a listing of available user-defined signals and their corresponding numbers in MIL.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_BIT_MASK(
long Bit_encoded_value

          )

 Specifies a bit-encoded mask value that identifies the group of user-defined signals to affect. Enabled bits in the mask value identify which user-defined signals to affect.  Specifies a bit-encoded mask value that identifies the group of user-defined signals to affect ...

 Note that in this case, the control value can only be set to a bit-encoded value.

d
e

m
n
o

q
r

Parameters

Bit_encoded_value

 The bit-encoded mask value.

  Open   Collapse  0 <= Value

 Specifies the number of a specific user-defined signal.  Specifies the number of a specific user-defined signal ...

 Note that in this case, the control value cannot be set to a bit-encoded value.

a

c
d
e

h
i
j
k

m
n
o
p
q
r

Specifics

 For Meteor-II /Camera Link, user-defined signals 0 and 1 correspond to the camera control signals. To use these signals, you must set M_CAMERALINK_CCn_SOURCE to M_USER_BIT_CC_A or M_USER_BIT_CC_B.

h

  Open   Collapse  M_CCn

 Specifies the number of a specific camera control signal, where n can be from 1 to 4. To use the CC signals as user-defined signals, you must specify them as such, using M_CAMERALINK_CCn_SOURCE.  Specifies the number of a specific camera control signal, where n can be from 1 to 4 ...

 Note that in this case, the returned value is not a bit-encoded value and it can only be added to M_USER_BIT_VALUE.

e

n

r

      [Combination constants]

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 The following must be added to M_USER_BIT_FORMAT, M_USER_BIT_INTERRUPT_MODE, or M_USER_BIT_INTERRUPT_STATE.

 See the Board Specific Notes for a listing of available user-defined signals and their corresponding numbers in MIL.

  Open   Collapse  Value
Description

  Open   Collapse  0 <= Value

 Specifies the number of a specific user-defined signal.  Specifies the number of a specific user-defined signal ...

 Note that in this case, the control value cannot be set to a bit-encoded value.

[Matrox Corona-II, Matrox Meteor-II /Camera Link, Matrox Meteor-II /Digital, Matrox Meteor-II /Multi-Channel, Matrox Meteor-II /Standard, Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

 The following control types and control values specify the settings for UARTS.

 Note that for other Matrox imaging boards that have a UART, but are not supported with the constants below, see MsysControl().

[Matrox Meteor-II /Camera Link]

 To specify which UART to affect, see combination values below.

Open Collapse ControlType |  | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
 | ControlValue
Open Collapse M_UART_DATA_LENGTH |  | Sets the number of data bits per character that is sent or received by the UART. Sets the number of data bits per character that is sent or received by the UART ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DEFAULT | Same as 8. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | 7 | Specifies data length to 7 bits. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | 8 | Specifies data length to 8 bits. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
Open Collapse M_UART_PARITY |  | Sets whether character data is sent or received with a parity bit and how the parity bit set. The parity bit is an extra data bit (0 or 1) that is added to each character for error checking purposes. Sets whether character data is sent or received with a parity bit and how the parity bit set ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DEFAULT | Same as M_DISABLE. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DISABLE | Species that no extra bit is added (no parity). |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_EVEN | Specifies that the number of 1's will be even. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_ODD | Specifies that the number of 1's will be odd. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
Open Collapse M_UART_READ_CHAR |  | Reads one character from the UART input buffer. If the input buffer is empty, the function will wait for the amount of time specified by M_UART_TIMEOUT. If a time-out occurs, the '?' character will be returned. Reads one character from the UART input buffer ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_PTR_TO_DOUBLE( void MPTYPE *PTR ) | Specifies the address of the variable in which to save the character read from the UART. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 |  |  | Parameters
 |  |  | PTR The address of the variable in which to save the character.
Open Collapse M_UART_READ_STRING |  | Reads a string of incoming data from the UART. The number of characters to read can be specified with M_UART_READ_STRING_LENGTH or M_UART_STRING_DELIMITER. M_UART_TIMEOUT specifies the maximum time to wait between each byte when reading incoming data. Reads a string of incoming data from the UART ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_PTR_TO_DOUBLE( void MPTYPE *PTR ) | Specifies the address of the character array in which to save the string read from the UART. The size of this array must be set to the same value as the M_UART_READ_STRING_MAXIMUM_LENGTH control type. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 |  |  | Parameters
 |  |  | PTR The address of the character array in which to save the string.
Open Collapse M_UART_READ_STRING_LENGTH |  | Sets the length of the string to be read using M_UART_READ_STRING. Sets the length of the string to be read using M_UART_READ_STRING ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DEFAULT | Specifies the use of M_UART_STRING_DELIMITER to delineate the end of the string to be read. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | Value | Specifies the string length, in bytes. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
Open Collapse M_UART_READ_STRING_MAXIMUM_LENGTH |  | Sets the maximum length to be read. This prevents global protection faults from happening when using the M_UART_READ_STRING control type. Sets the maximum length to be read ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | Value | Specifies the maximum length of the string, in bytes. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
Open Collapse M_UART_SPEED |  | Sets the baud rate of the UART. Sets the baud rate of the UART ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DEFAULT | Specifies the default value. The default value is 14400. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | 600; 1200; 1800; 2400; 3600; 4800; 7200; 9600; 14400; 19200; 28800; 38400; 57600; 76800; 115200; 230400 | Specifies the baud rate of the UART. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
Open Collapse M_UART_STOP_BITS |  | Sets the number of extra data bit(s) (1 or 2) that are added to each character to indicate the end of the character. Sets the number of extra data bit(s) (1 or 2) that are added to each character to indicate the end of the character ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DEFAULT | Same as 1. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | 1 | Specifies that there is 1 stop bit. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | 2 | Specifies that there are 2 stop bits. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
Open Collapse M_UART_STRING_DELIMITER |  | Sets the character used to terminate strings of incoming or outgoing data. The delimiter is used but not sent when writing data with M_UART_WRITE_STRING; it is read for incoming data with M_UART_READ_STRING. Sets the character used to terminate strings of incoming or outgoing data ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DEFAULT | Specifies the default value. The default value is '\0'. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | Value | Specifies the character used to terminate strings. Note that the character value must be cast to a double. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
Open Collapse M_UART_TIMEOUT |  | Sets the maximum time to wait between each byte when reading incoming data. Sets the maximum time to wait between each byte when reading incoming data ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DEFAULT | Same as M_INFINITE. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_INFINITE | Waits indefinitely. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | Value | Specifies the time to wait, in msec. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
Open Collapse M_UART_WRITE_CHAR |  | Sends one character to the UART for transmission. Sends one character to the UART for transmission ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_PTR_TO_DOUBLE( void MPTYPE *PTR ) | Specifies a pointer to the one character to send. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 |  |  | Parameters
 |  |  | PTR The pointer to the character.
Open Collapse M_UART_WRITE_STRING |  | Sends a string of data through the UART for transmission. The number of characters to send can be specified with M_UART_WRITE_STRING_LENGTH or M_UART_STRING_DELIMITER. Sends a string of data through the UART for transmission ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_PTR_TO_DOUBLE( void MPTYPE *PTR ) | Specifies a pointer to the string to send. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 |  |  | Parameters
 |  |  | PTR The pointer to the string.
Open Collapse M_UART_WRITE_STRING_LENGTH |  | Sets the length of the string to be sent to the UART for transmission. Sets the length of the string to be sent to the UART for transmission ... |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | M_DEFAULT | Specifies the use of M_UART_STRING_DELIMITER to end the string. The delimiter will not be sent through the UART. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |
 | Value | Specifies the string length, in bytes. |  | a |  |  |  |  |  |  | h | i | j | k |  | m | n | o |  |  |

      [Combination constants]

[Matrox Meteor-II /Camera Link]

 The value below can be added to M_UART... to specify which UART is being used. In this case, channel refers to the number assigned to each virtual UART available to be programmed on Matrox Meteor-II /Camera-Link. Only one virtual UART can be in use at any one time. This setting allows for two UART configurations to be stored and called for use, one at a time, as needed.

  Open   Collapse  Value
Description

  Open   Collapse  M_CH0

 Specifies that the first UART should be used.  Specifies that the first UART should be used ...

This is the default value.

  Open   Collapse  M_CH1

 Specifies that the second UART should be used.  Specifies that the second UART should be used.

 The following control types and control values specify the settings to grab using a trigger. For more information, see the Grabbing with triggers and exposures section in
          Chapter 18: Grabbing with your digitizer.

  Open   Collapse  ControlType
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

ControlValue

  Open   Collapse   M_GRAB_TRIGGER

 Sets the grab trigger detection state.  Sets the grab trigger detection state ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Same as the one specified by the DCF or, if none specified, M_DISABLE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ACTIVATE

 Starts the grab immediately (that is, issues a software trigger). To use this setting, the trigger source must be set to software (use MdigControl() with M_GRAB_TRIGGER_SOURCE set to M_SOFTWARE).

 An asynchronous or continuous grab must be in progress.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables trigger detection.

 With a hardware trigger, setting M_GRAB_TRIGGER to M_DISABLE temporarily stops a continuous grab.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Enables trigger detection.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_GRAB_TRIGGER_FORMAT

 Sets whether to enable the TTL, OPTO, or LVDS receivers for triggers, on systems whose receivers are enabled through software and where the option of TTL, OPTO, and LVDS are possible. Refer to the Technical information appendix in the Installation and Hardware Reference manual for your Matrox imaging board.  Sets whether to enable the TTL, OPTO, or LVDS receivers for triggers, on systems whose receivers are enabled through software and where the option of TTL, OPTO, and LVDS are possible ...

 Refer to M_USER_IN_FORMAT to change formats on other Matrox imaging boards.

 Note that this value can be used in combination; see below.

d
e

m
n
o

q
r

 M_DEFAULT

 Same as the one specified by the DCF.

d
e

m
n
o

q
r

 M_DISABLE

 Disables the receivers for the specified triggers. For a more conventional technique of disabling a trigger, use MdigControl() with M_GRAB_TRIGGER set to M_DISABLE.

d
e

m
n
o

q
r

 M_ENABLE

 Enables the receivers for the specified triggers. For a more conventional technique of enabling a trigger, use MdigControl() with M_GRAB_TRIGGER set to M_ENABLE.

d
e

m
n
o

q
r

 M_LVDS

 Enables the LVDS receivers for the specified for triggers.

d
e

m
n
o

q
r

Specifics

 Uses the LVDS trigger instead of the TTL trigger. See M_HARDWARE_PORT4 through M_HARDWARE_PORT9 for a detailed description of the location of these trigger signals.

d

m

o

q

 Uses the LVDS trigger instead of the TTL trigger. See M_HARDWARE_PORT5 for a detailed description of the location of these trigger signals.

e

n

r

 M_OPTO

 Enables the OPTO transmitters/receivers for the specified for triggers.

d
e

m
n
o

q
r

 M_TTL

 Enables the TTL transmitters/receivers for the specified for triggers.

d
e

m
n
o

q
r

Specifics

 Uses the TTL trigger instead of the LVDS trigger. See M_HARDWARE_PORT4 through M_HARDWARE_PORT9 for a detailed description of the location of these trigger signals.

d

m

o

q

 Uses the TTL trigger instead of the LVDS trigger. See M_HARDWARE_PORT5 for a detailed description of the location of these trigger signals.

e

n

r

  Open   Collapse   M_GRAB_TRIGGER_MODE

 Sets the hardware trigger activation mode.  Sets the hardware trigger activation mode ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Same as the one specified by the DCF.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 If no trigger mode is specified in the DCF, M_EDGE_RISING is the default.

a
b
c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

 M_EDGE_FALLING

 Specifies to trigger upon a high to low signal variation.

a
b
c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

 M_EDGE_RISING

 Specifies to trigger upon a low to high signal variation.

a
b
c
d
e
f

h
i
j
k
l
m
n
o
p
q
r

 M_LEVEL_HIGH

 Specifies to trigger while a maximum signal level occurs.

a
b
c
d
e

h
i
j
k
l
m
n
o
p
q
r

 M_LEVEL_LOW

 Specifies to trigger while a minimum signal level occurs.

a
b
c
d
e

h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_GRAB_TRIGGER_SOURCE

 Sets the source of the grab trigger.  Sets the source of the grab trigger ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Note that most of the possible signals are actually multi-purpose auxiliary signals and can only be used as trigger signals if they are not defined/used for another purpose. For more information, refer to the Synchronization and control signals section in the Frame Grabber chapter of the Installation and Hardware Reference manual. In addition, some of these signals, when used for trigger input, affect the same trigger input controller. See the board specific section for more information.

d
e

m
n
o

q
r

 When dealing with a cluster of boards featuring Matrox Odyssey Xpro, the total number of independent acquisition paths available includes those of the frame grabber modules attached to any Matrox Odyssey Xpro board (or PMC board) in the cluster. The total number can be from 0 to 31. When all the digitizers of the first board are used, the next digitizer uses the same signal names as the first digitizer as the same board (for example, after using M_DEV0 through M_DEV3 for a Matrox Odyssey XA, the next Matrox imaging board has the same signals as M_DEV0 for that board type.) Use MsysInquire() with M_DIGITIZER_TYPE + M_DEVn to return the type of frame grabber module to which an independent acquisition path belongs.

m
n
o

 M_DEFAULT

 Same as the one specified by the DCF or M_NULL.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_HARDWARE_PORT0

 Uses the hardware trigger input signal connected to port 0.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Uses the OPTOTRIG signal, available from the video input connector.

a

j
k

p

 Uses user bit 0.

b

 Description is camera-dependent.

g

 Uses the opto-isolated trigger input signal, available from the video input connector.

c

 Uses the OPTOTRIG signal, available from the trigger input connector.

h
i

 Uses the IND_USER/TRIG_IN0 signal, available from the input/output connector.

f

 Uses the OPTO_AUX_IN0 signal, available from external auxiliary I/O connector 0 (HD-44) .

e

n

r

 Port 0 is assigned to external auxiliary I/O connector 1 (DB-9). The exact signal used is dependent upon the device number of the digitizer.

 For an M_DEV0 digitizer, it uses the P0_OPTO_AUX(TRIG)_IN signal.

 For an M_DEV1 digitizer, it uses the P1_OPTO_AUX(TRIG)_IN signal.

 For an M_DEV2 digitizer, it uses the P2_OPTO_AUX(TRIG)_IN signal.

 For an M_DEV3 digitizer, it uses the P3_OPTO_AUX(TRIG)_IN signal.

d

m

q

 Port 0 is assigned to digital video input connector 0 or 1. The exact signal used is dependent upon the device number of the digitizer.

 For an M_DEV0 digitizer, it uses the P0_TTL_AUX(TRIG)_IO (connector 0) signal.

 For an M_DEV1 digitizer, it uses the P1_TTL_AUX(TRIG)_IO (connector 0) signal.

 For an M_DEV2 digitizer, it uses the P2_TTL_AUX(TRIG)_IO (connector 1) signal.

 For an M_DEV3 digitizer, it uses the P3_TTL_AUX(TRIG)_IO (connector 1) signal.

o

 Uses the P0_TTL_TRIG_IN signal, available from the BNC 2 connector.

l

 M_HARDWARE_PORT1

 Uses the hardware trigger input signal connected to port 1.

a

c
d
e
f

h
i
j

l
m
n
o
p
q
r

Specifics

 Uses the TRIGGER signal, either available from the video input/output connector or from the digital interface connector.

a

p

 Depending on the receiver format (specified with M_GRAB_TRIGGER_FORMAT), uses either the TRIGGER, INPUT, 422 signal for RS-422 or the TRIGGER, INPUT, TTL signal for TTL. Both signals are available from the digital cable adaptor board.

 User-defined signals can be configured as RS-422 (specified with M_USER_IN_FORMAT set to M_RS422). RS-422 user-defined signals are available from the companion digital input board.

c

 Uses the IND_USER/TRIG_IN1 signal, available from the input/output connector.

f

 Port 1 is assigned to the analog video input connector (DVI). The exact signal used is dependent upon the device number of the digitizer.

 For an M_DEV0 digitizer, it uses the P0_TTL_AUX(TRIG)_IN (DVI 0) signal.

 For an M_DEV1 digitizer, it uses the P1_TTL_AUX(TRIG)_IN (DVI 0) signal.

 For an M_DEV2 digitizer, it uses the P2_TTL_AUX(TRIG)_IN (DVI 1) signal.

 For an M_DEV3 digitizer, it uses the P3_TTL_AUX(TRIG)_IN (DVI 1) signal.

d

m

q

 Port 1 is assigned to digital video input connector (DVI) 0 or 1. The exact signal used is dependent upon the device number of the digitizer.

 For an M_DEV0 digitizer, it uses the P0_LVDS_AUX_(VSYNC)_IN (connector 0) signal.

 For an M_DEV1 digitizer, it uses the P1_LVDS_AUX_(VSYNC)_IN (connector 0) signal.

 For an M_DEV2 digitizer, it uses the P2_LVDS_AUX_(VSYNC)_IN (connector 1) signal.

 For an M_DEV3 digitizer, it uses the P3_LVDS_AUX_(VSYNC)_IN (connector 1) signal.

o

 Uses the OPTO_AUX_IN1 signal, available from external auxiliary I/O connector 0 (HD-44).

e

n

r

 Depending on the receiver format (specified with M_USER_IN_FORMAT), uses either the TTL TRIG signal for TTL, available from the trigger input connector, or the LVDS TRIG signal for LVDS signal, available from the digital interface connector).

h

 Depending on the receiver format (specified with M_USER_IN_FORMAT), uses either the TTL TRIG signal for TTL, available from the trigger input connector, or the TRIGGER, INPUT signal for LVDS, available from the digital interface connector.

i

 Uses the TRIGGER signal, available from the video input connector. Note that to select this receiver, use M_USER_IN_FORMAT with M_TTL.

j

 Uses the P1_TTL_TRIG_IN signal, available from the BNC 3 connector.

l

 M_HARDWARE_PORT2

 Connects the hardware trigger to port 2.

a

d
e

m
n
o

q
r

Specifics

 Uses the TRIG signal, available from the video input connector of the companion digital-input board.

a

 Uses the TTL_AUX_IO_0 signal, available from external auxiliary I/O connector 0 (DB-44).

e

n

r

 Uses the LVDS/TTL_AUX_IN0 signal, available from external auxiliary I/O connector 0 (DB-44).

d

m

q

 Port 2 is assigned to external auxiliary I/O connector 0 (DB-44). The exact signal used is dependent upon the device number of the digitizer.

 For an M_DEV0 digitizer, it uses the P0_OPTO_AUX(TRIG)_IN0 signal.

 For an M_DEV1 digitizer, it uses the P1_OPTO_AUX(TRIG)_IN0 signal.

 For an M_DEV2 digitizer, it uses the P2_OPTO_AUX(TRIG)_IN0 signal.

 For an M_DEV3 digitizer, it uses the P3_OPTO_AUX(TRIG)_IN0 signal.

o

 M_HARDWARE_PORT3

 Uses the hardware trigger input signal connected to port 3.

d
e

m
n
o

q
r

Specifics

 Uses the TTL_AUX_IO_1 signal, available from external auxiliary I/O connector 0 (DB-44).

e

n

r

 Uses the LVDS/TTL_AUX_IN1 signal, available from external auxiliary I/O connector 0 (HD-44).

d

m

q

 Port 3 is assigned to external auxiliary I/O connector 1 (DB-9). The exact signal used is dependent upon the device number of the digitizer.

 For an M_DEV0 digitizer, it uses the P0_OPTO_AUX(TRIG)_IN1 signal.

 For an M_DEV1 digitizer, it uses the P1_OPTO_AUX(TRIG)_IN1 signal.

 For an M_DEV2 digitizer, it uses the P2_OPTO_AUX(TRIG)_IN1 signal.

 For an M_DEV3 digitizer, it uses the P3_OPTO_AUX(TRIG)_IN1 signal.

o

 M_HARDWARE_PORT4

 Uses the hardware trigger input signal connected to port 4.

d
e

m
n
o

q
r

Specifics

 Uses the LVDS_AUX_IN0 signal, available from external auxiliary I/O connector 0 (DB-44).

e

n

r

 Uses the LVDS/TTL_AUX_IN2 signal. available from external auxiliary I/O connector 0 (DB-44).

d

m

q

 For an M_DEV0 digitizer, it uses the LVDS/TTL_AUX(TRIG)_IN0 signal, available from external auxiliary I/O connector 0 (DB-44).

 Note that this hardware port is not available for a M_DEV1, M_DEV2, or a M_DEV3 digitizer.

o

 M_HARDWARE_PORT5

 Uses the hardware trigger input signal connected to port 5.

d
e

m
n
o

q
r

Specifics

 Uses the LVDS/TTL_AUX_IN3 signal, available from external auxiliary I/O connector 0 (DB-44).

d

m

q

 Uses the LVDS_AUX_IN1 signal, available from external auxiliary I/O connector 0 (DB-44).

e

n

r

 For an M_DEV0 digitizer, it uses the LVDS/TTL_AUX(TRIG)_IN1 signal, available from external auxiliary I/O connector 0 (DB-44).

 Note that this hardware port is not available for a M_DEV1, M_DEV2, or a M_DEV3 digitizer.

o

 M_HARDWARE_PORT6

 Uses the hardware trigger input signal connected to port 6.

d
e

m
n
o

q
r

Specifics

 For an M_DEV0 digitizer, it uses the P0_OPTO_AUX_IN0 signal, available from external auxiliary I/O connector 1 (DB-9). Note that this hardware port is not available for an M_DEV1 digitizer.

e

n

r

 Uses the LVDS/TTL_AUX_IN4 signal, available from external auxiliary I/O connector 0 (DB-44).

d

m

q

 For an M_DEV1 digitizer, it uses the LVDS/TTL_AUX(TRIG)_IN2 signal, available from external auxiliary I/O connector 0 (DB-44).

 Note that this hardware port is not available for M_DEV0, M_DEV2, or a M_DEV3 digitizer.

o

 M_HARDWARE_PORT7

 Uses the hardware trigger input signal connected to port 7.

d
e

m
n
o

q
r

Specifics

 For an M_DEV0 digitizer, it uses the P0_OPTO_AUX_IN1 signal, available from external auxiliary I/O connector 1 (DB-9). Note that this hardware port is not available for an M_DEV1 digitizer.

e

n

r

 Uses the LVDS/TTL_AUX_IN5 signal, available from external auxiliary I/O connector 0 (HD-44).

d

m

q

 For an M_DEV1 digitizer, it uses the LVDS/TTL_AUX(TRIG)_IN3 signal, available from external auxiliary I/O connector 0 (DB-44).

 Note that this hardware port is not available for M_DEV0, M_DEV2, or a M_DEV3 digitizer.

o

 M_HARDWARE_PORT8

 Uses the hardware trigger input signal connected to port 8.

d
e

m
n
o

q
r

Specifics

 For an M_DEV0 digitizer, it uses the P0_TTL_AUX_IO_0 signal, available from external auxiliary I/O connector 1 (DB-9).

 For an M_DEV1 digitizer, it uses the P1_TTL_AUX_IO_0 signal, available from external auxiliary I/O connector 0 (DB-44).

e

n

r

 Uses the LVDS/TTL_AUX_IN6 signal, available from external auxiliary I/O connector 0 (HD-44).

d

m

q

 For an M_DEV2 digitizer, it uses the LVDS/TTL_AUX(TRIG)_IN4 signal, available from external auxiliary I/O connector 0 (DB-44).

 Note that this hardware port is not available for M_DEV0, M_DEV1, or a M_DEV3 digitizer.

o

 M_HARDWARE_PORT9

 Uses the hardware trigger input signal connected to port 9.

d
e

m
n
o

q
r

Specifics

 Port 8 is assigned to external auxiliary I/O connector 0 (DB-44). The exact signal used is dependent upon the device number of the digitizer.

 For an M_DEV0 digitizer, it uses the P0_TTL_AUX_IO_1 signal.

 For an M_DEV1 digitizer, it uses the P1_TTL_AUX_IO_1 signal.

e

n

r

 Uses the LVDS/TTL_AUX_IN7 signal, available from external auxiliary I/O connector 0 (DB-44).

d

m

q

 For an M_DEV2 digitizer, it uses the LVDS/TTL_AUX(TRIG)_IN5 signal, available from external auxiliary I/O connector 0 (DB-44).

 Note that this hardware port is not available for M_DEV0, M_DEV1, or a M_DEV3 digitizer.

o

 M_HARDWARE_PORT10

 Uses the hardware trigger input signal connected to port 10.

e

n
o

r

Specifics

 For an M_DEV0 digitizer, it uses the P0_LVDS_AUX_IN0 signal, available from external auxiliary I/O connector 1 (DB-9). Note that this Hardware port is not available for an M_DEV1 digitizer.

e

n

r

 For an M_DEV3 digitizer, it uses the LVDS/TTL_AUX(TRIG)_IN6 signal, available from external auxiliary I/O connector 0 (DB-44).

 Note that this hardware port is not available for M_DEV0, M_DEV1, or a M_DEV2 digitizer.

o

 M_HARDWARE_PORT11

 Uses the hardware trigger input signal connected to port 11.

e

n
o

r

Specifics

 For an M_DEV0 digitizer, it uses the P0_LVDS_AUX_IN1 signal, available from external auxiliary I/O connector 0 (HD-44). Note that this Hardware port is not available for an M_DEV1 digitizer.

e

n

r

 For an M_DEV3 digitizer, it uses the LVDS/TTL_AUX(TRIG)_IN7 signal available from external auxiliary I/O connector 0 (DB-44).

 Note that this hardware port is not available for M_DEV0, M_DEV1, or a M_DEV2 digitizer.

o

 M_HARDWARE_PORT_CAMERA

 Uses a hardware trigger connected to the same port as the selected camera, as specified in the DCF.

a
b
c
d
e

h
i
j
k
l
m
n
o
p
q
r

Specifics

 Uses the same specifications as M_HARDWARE_PORT0.

b

d
e

l
m
n
o

q
r

 M_NULL

 Disables the specified trigger. For a more conventional technique of disabling the specified trigger, use MdigControl() with M_GRAB_TRIGGER set to M_DISABLE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ROTARY_ENCODER

 Uses the rotary encoder as the trigger source. Use MdigControl() with M_ROTARY_ENCODER_POSITION_TRIGGER to set the trigger value of the rotary encounter.

e

r

 M_SOFTWARE

 Uses a software trigger. Use MdigControl() with M_GRAB_TRIGGER set to M_ACTIVATE to issue the trigger.

a
b
c
d
e

h
i
j
k
l
m
n
o
p
q
r

 M_TIMER1

 Specifies to trigger on the exposure timer 1 signal.

a

c
d
e

h
i
j

m
n
o

q
r

 M_TIMER2

 Specifies to trigger on the exposure timer 2 signal.

a

c
d
e

h
i
j

m
n
o

q
r

      [Combination constants]

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 The following can be added to M_GRAB_TRIGGER_FORMAT.

  Open   Collapse  Value
Description

  Open   Collapse  M_HARDWARE_PORTn

 Specifies that hardware port n will change its trigger format, where n is a number from 0 to 11.  Specifies that hardware port n will change its trigger format, where n is a number from 0 to 11 ...

 To view the trigger formats available for each hardware port of each Matrox imaging board, see M_GRAB_TRIGGER_SOURCE.

[All except
        Matrox CronosPlus, Matrox Meteor-II /Standard, Matrox Morphis, and Matrox Orion]

 The following control types and control values specify the settings for controlling exposure signals. For more information, see the Grabbing with triggers and exposures section in
          Chapter 18: Grabbing with your digitizer.

 To specify which exposure timer to affect, See combination values below.

  Open   Collapse  ControlType
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

ControlValue

  Open   Collapse   M_AUTO_EXPOSURE

 Sets whether the exposure should be set manually to the specified value or if the camera controls the exposure level automatically and continuously.  Sets whether the exposure should be set manually to the specified value or if the camera controls the exposure level automatically and continuously ...

 Note that this is DCAM-specific. For more information, refer to your camera's Hardware Reference manual and the Setting 1394 DCS-compliant camera features section in
          Chapter 6: Matrox Meteor-II.

g

 M_DEFAULT

 Specifies the default value or the camera's control setting to automatic mode (if supported).

g

 Value

 Specifies a value between the minimum and maximum values supported by the camera. Use MdigInquire() to determine these values.

g

  Open   Collapse   M_GRAB_EXPOSURE

 Sets the state of the specified exposure timer.  Sets the state of the specified exposure timer ...

a

c
d
e

h
i
j

m
n
o

q
r

 M_DEFAULT

 Same as the one specified by the DCF.

a

c
d
e

h
i
j

m
n
o

q
r

 M_ACTIVATE

 Activates a software trigger for the specified exposure timer. To use this setting, set the trigger source for the exposure timer (using MdigControl() with M_GRAB_EXPOSURE_SOURCE) to M_SOFTWARE.

a

c
d
e

h
i
j

m
n
o

q
r

 M_DISABLE

 Disables the exposure timer.

a

c
d
e

h
i
j

m
n
o

q
r

 M_ENABLE

 Enables the exposure timer.

a

c
d
e

h
i
j

m
n
o

q
r

  Open   Collapse   M_GRAB_EXPOSURE_CLOCK_SOURCE

 Specifies the clock source that drives the exposure counter for the specified timer. See below for an example on how to clock a timer.  Specifies the clock source that drives the exposure counter for the specified timer ...

 A clock source must have a frequency greater than or equal to 1 Hz.

a

d
e

j

m
n
o

q
r

 M_DEFAULT

 Uses the most appropriate clock source (as determined by the driver).

a

d
e

j

m
n
o

q
r

 M_HSYNC

 Uses the horizontal synchronization frequency of your camera.

a

d
e

j

m
n
o

q
r

 M_PIXCLK

 Uses the pixel clock frequency of your camera.

a

d
e

j

m
n
o

q
r

 M_SYSCLK

 Uses the Matrox imaging board's clock source frequency.

a

d
e

j

m
n
o

q
r

Specifics

 Uses a 25 MHz clock source frequency.

a

j

 Uses a 16.666 MHz clock source frequency.

d
e

m
n
o

q
r

 M_TIMER1

 Uses the frequency of timer 1, if continuous.

 Only a continuous timer can clock another timer. References where timer 1 points to timer 2, and timer 2 points back to timer 1, are not supported and will generate an error.

a

d
e

j

m
n
o

q
r

 M_TIMER2

 Uses the frequency of timer 2, if continuous.

 Only a continuous timer can clock another timer. References where timer 1 points to timer 2, and timer 2 points back to timer 1, are not supported and will generate an error.

a

d
e

j

m
n
o

q
r

 M_VSYNC

 Uses the vertical synchronization frequency of your camera.

d
e

m
n
o

q
r

  Open   Collapse   M_GRAB_EXPOSURE_FORMAT

 Sets whether to enable the TTL or RS-422/LVDS transmitters for exposures and user-defined output signals, on systems whose transmitters are enabled through software and where the option of both TTL and RS-422/LVDS are possible. Refer to the Technical information appendix in the Installation and Hardware Reference manual for your Matrox imaging board.  Sets whether to enable the TTL or RS-422/LVDS transmitters for exposures and user-defined output signals, on systems whose transmitters are enabled through software and where the option of both TTL and RS-422/LVDS are possible ...

 Refer to M_USER_OUT_FORMAT to change formats on other Matrox imaging boards.

d
e

m
n
o

q
r

 M_DEFAULT

 Same as the one specified by the DCF.

d
e

m
n
o

q
r

 M_DISABLE

 Disables the transmitters/receivers for the specified exposures. For a more conventional technique of disabling an exposure timer, use MdigControl() with M_GRAB_EXPOSURE set to M_DISABLE.

d
e

m
n
o

q
r

 M_ENABLE

 Enables the transmitters/receivers for the specified exposures. For a more conventional technique of enabling an exposure timer, use MdigControl() with M_GRAB_EXPOSURE set to M_ENABLE.

d
e

m
n
o

q
r

 M_LVDS

 Enables the LVDS transmitters/receivers for the specified exposures.

d
e

m
n
o

q
r

Specifics

 Uses the LVDS trigger on either the companion digital input board or the digital cable adaptor board, instead of the TTL trigger. See M_HARDWARE_PORT4 through M_HARDWARE_PORT9 for a detailed description of the location of these trigger signals.

d

m

o

q

 Uses the LVDS trigger on either the companion digital input board or the digital cable adaptor board, instead of the TTL trigger. See M_HARDWARE_PORT5 for a detailed description of the location of these trigger signals.

e

n

r

 M_TTL

 Enables the TTL drivers for exposures.

d
e

m
n
o

q
r

Specifics

 Uses the TTL trigger on either the companion digital input board or the digital cable adaptor board, instead of the LVDS trigger. See M_HARDWARE_PORT4 through M_HARDWARE_PORT9 for a detailed description of the location of these trigger signals.

d

m

o

q

 Uses the TTL trigger on either the companion digital input board or the digital cable adaptor board, instead of the LVDS trigger. See M_HARDWARE_PORT5 for a detailed description of the location of these trigger signals.

e

n

r

  Open   Collapse   M_GRAB_EXPOSURE_MODE

 Sets the polarity of the active portion of the exposure signal.  Sets the polarity of the active portion of the exposure signal ...

a

c
d
e

h
i
j

m
n
o

q
r

 M_DEFAULT

 Same as the one specified by the DCF.

a

c
d
e

h
i
j

m
n
o

q
r

 M_LEVEL_HIGH

 Specifies a high signal polarity.

a

c
d
e

h
i
j

m
n
o

q
r

 M_LEVEL_LOW

 Specifies a low signal polarity.

a

c
d
e

h
i
j

m
n
o

q
r

  Open   Collapse   M_GRAB_EXPOSURE_SOURCE

 Selects the trigger source for the specified exposure timer.  Selects the trigger source for the specified exposure timer ...

a

c
d
e

h
i
j

m
n
o

q
r

Specifics

 Note that most of the possible signals are actually multi-purpose auxiliary signals and can only be used as trigger signals if they are not defined/used for another purpose. For more information, refer to the Synchronization and control signals section in the Frame Grabber chapter of the Installation and Hardware Reference manual. In addition, some of these signals, when used for trigger input, affect the same trigger input controller. See the board specific section for more information.

d
e

m
n
o

q
r

 When dealing with a cluster of boards featuring Matrox Odyssey Xpro, the total number of independent acquisition paths available includes those of the frame grabber modules attached to any Matrox Odyssey Xpro board (or PMC board) in the cluster. The total number can be from 0 to 31. When all the digitizers of the first board are used, the next digitizer uses the same signal names as the first digitizer as the same board (for example, after using M_DEV0 through M_DEV3 for a Matrox Odyssey XA, the next Matrox imaging board has the same signals as M_DEV0 for that board type.) Use MsysInquire() with M_DIGITIZER_TYPE + M_DEVn to return the type of frame grabber module to which an independent acquisition path belongs.

m
n
o

 M_DEFAULT

 Same as the one specified by the DCF.

a

c
d
e

h
i
j

m
n
o

q
r

 M_CONTINUOUS

 Runs the specified exposure timer in periodic mode; no actual trigger signal is used. Automatically resets the timer after each exposure signal is output. Exposure signal loops between delay and active mode.

a

c
d
e

h
i
j

m
n
o

q
r

 M_HARDWARE_PORT0

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

a

c
d
e

h
i
j

m
n
o

q
r

 M_HARDWARE_PORT1

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

a

c
d
e

h
i
j

m
n
o

q
r

 M_HARDWARE_PORT2

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

a

d
e

m
n
o

q
r

 M_HARDWARE_PORT3

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

d
e

m
n
o

q
r

 M_HARDWARE_PORT4

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

d
e

m
n
o

q
r

 M_HARDWARE_PORT5

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

d
e

m
n
o

q
r

 M_HARDWARE_PORT6

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

d
e

m
n
o

q
r

 M_HARDWARE_PORT7

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

d
e

m
n
o

q
r

 M_HARDWARE_PORT8

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

d
e

m
n
o

q
r

 M_HARDWARE_PORT9

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

d
e

m
n
o

q
r

 M_HARDWARE_PORT10

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

e

n
o

r

 M_HARDWARE_PORT11

 See the description of this setting in M_GRAB_TRIGGER_SOURCE.

e

n
o

r

 M_HSYNC

 Uses the horizontal synchronization signal.

a

c
d
e

h
i
j

m
n
o

q
r

 M_NULL

 Disables the specified exposure timer. For a more conventional technique of disabling the specified exposure timer, use MdigControl() with M_GRAB_EXPOSURE set to M_DISABLE.

a

c
d
e

h
i
j

m
n
o

q
r

 M_ROTARY_ENCODER

 Uses the rotary encoder as the trigger source. Use MdigControl() with M_ROTARY_ENCODER_POSITION_TRIGGER to set the trigger value of the rotary encounter.

e

r

 M_SOFTWARE

 Uses a software trigger. Use MdigControl() with M_GRAB_EXPOSURE + M_TIMERn set to M_ACTIVATE to issue the trigger.

a

c
d
e

h
i
j

m
n
o

q
r

 M_TIMER1

 Specifies to use timer 1 signal as a trigger. In this case, M_GRAB_EXPOSURE cannot be added to M_TIMER1.

a

c
d
e

h
i
j

m
n
o

q
r

 M_TIMER2

 Specifies to use timer 2 signal as a trigger. In this case, M_GRAB_EXPOSURE cannot be added to M_TIMER2.

a

c
d
e

h
i
j

m
n
o

q
r

 M_VSYNC

 Uses the vertical synchronization signal.

a

c
d
e

h
i
j

m
n
o

q
r

  Open   Collapse   M_GRAB_EXPOSURE_TIME

 Sets the time for the active portion of the exposure signal (that is, the exposure time).  Sets the time for the active portion of the exposure signal (that is, the exposure time) ...

 Note, an error is returned if the specified exposure time cannot be generated.

a

c
d
e
f

h
i
j

m
n
o

q
r

 M_DEFAULT

 Same as the one specified by the DCF.

a

c
d
e
f

h
i
j

m
n
o

q
r

 Value

 Specifies the time, in nsec. Set this value to 0 to disable the exposure and perform the grab immediately.

a

c
d
e
f

h
i
j

m
n
o

q
r

  Open   Collapse   M_GRAB_EXPOSURE_TIME_DELAY

 Sets the delay between the trigger and the start of exposure.  Sets the delay between the trigger and the start of exposure ...

 Note, an error is returned if the specified delay cannot be generated.

a

c
d
e
f

h
i
j

m
n
o

q
r

 M_DEFAULT

 Same as the one specified by the DCF.

a

c
d
e
f

h
i
j

m
n
o

q
r

 Value

 Specifies the delay, in nsec.

a

c
d
e
f

h
i
j

m
n
o

q
r

  Open   Collapse   M_GRAB_EXPOSURE_TRIGGER_MODE

 Sets the trigger activation mode for specified timer.  Sets the trigger activation mode for specified timer ...

a

c
d
e

h
i
j

m
n
o

q
r

 M_DEFAULT

 Same as the one specified by the DCF.

a

c
d
e

h
i
j

m
n
o

q
r

 M_EDGE_FALLING

 Specifies to trigger upon a high-to-low signal variation.

a

c
d
e

h
i
j

m
n
o

q
r

 M_EDGE_RISING

 Specifies to trigger upon a low-to-high signal variation.

a

c
d
e

h
i
j

m
n
o

q
r

      [Combination constants]

[All except
        Matrox CronosPlus, Matrox Meteor-II /Standard, Matrox Morphis, and Matrox Orion]

 The following can be added to M_GRAB_EXPOSURE... control types and M_GRAB_EXPOSURE_FORMAT.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_TIMER1

 Controls the first on-board exposure timer.  Controls the first on-board exposure timer ...

This is the default value.

a

c
d
e
f
g
h
i
j

m
n
o

q
r

Specifics

 The DCF establishes on which signals the exposure timer routes its exposure signal.

d
e

m
n
o

q
r

 The first on-board exposure timer is dedicated to the CCD.

f

  Open   Collapse  M_TIMER2

 Controls the second on-board exposure timer.  Controls the second on-board exposure timer ...

a

c
d
e
f
g
h
i
j

m
n
o

q
r

Specifics

 The DCF establishes on which signals the exposure timer routes its exposure signal.

d
e

m
n
o

q
r

 The second on-board exposure timer is dedicated to the control of the IND_USER/STB_OUT0 (strobe) signal, available on external auxiliary I/O connector 0 (HD-44).

f

Examples

[Matrox Genesis, Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

 The following example uses M_GRAB_WAIT to grab the same frame from multiple digitizers allocated on different Matrox Genesis or Matrox Odyssey systems in the same cluster. Note that if the specified digitizer is already grabbing when this sample is invoked, the frame that is grabbed will be the one currently in on-board memory and not necessarily the one intended.

/* Synopsis: This program grabs the same frame to three buffers on different
 * systems.To do so, it uses 3 digitizers, each of which is allocated on
 * a different system within a cluster. Note that Dig1, Dig2, and Dig3 are different
 * digitizers and their grab mode is already set to M_ASYNCHRONOUS.
 */

/* Enable Dig2 and Dig3 to wait for the grab of Dig1.
 * Note that this needs to be done only once.
 */
 MdigControl(Dig2, M_GRAB_WAIT, Dig1);
 MdigControl(Dig3, M_GRAB_WAIT, Dig1);

/* Queue the grabs. */
 MdigGrab(Dig2, Buf2);
 MdigGrab(Dig3, Buf3);

/* Now queue the controlling grab. */
 MdigGrab(Dig1, Buf1);

 The following example uses M_SYNCHRONIZE_ON_STARTED to grab frames sequentially from multiple digitizers allocated on different Matrox Genesis or Matrox Odyssey systems in the same cluster.

/* Synopsis: This program grabs sequential frames to three buffers on different
 * systems. To do so, it uses 3 digitizers, each of which is allocated on a
 * different system within a cluster. Note that Dig1, Dig2, and Dig3 are different
 * digitizers (on separate independent acquisition paths) and their grab
 * mode is already set to M_ASYNCHRONOUS.
*/

/* Queue the first grab. */
 MdigGrab(Dig1, Buf1);

/* Queue the synchronization.
 * The grab of Dig2 will not be queued until Dig1 has started grabbing.
 */
 MdigControl(Dig2, M_SYNCHRONIZE_ON_STARTED, Dig1);
 MdigGrab(Dig2, Buf2);

/* Now synchronize Dig3 with Dig2. */
 MdigControl(Dig3, M_SYNCHRONIZE_ON_STARTED, Dig2);
 MdigGrab(Dig3, Buf3);

[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 The following example uses M_USER_BIT_VALUE + M_BIT_MASK(Bit-encoded value). It sets user bit 0 to 1 (on), 1 to 1 (on), and 5 to 0 (off):

MdigControl(MilDigitizer, M_USER_BIT_VALUE+M_BIT_MASK(0x23), 0x03);

 The following example uses M_USER_BIT_MODE + M_BIT_MASK(Bit-encoded value). It sets user bit 6 and 7 to input (0), and 8 as output (1):

MdigControl(MilDigitizer, M_USER_BIT_MODE+M_BIT_MASK(0x1C0), 0x100);

WHITE BALANCE CALCULATE BAYER CONVERSION WHITE BALANCE ARRAY WHITE BALANCE ENABLE BRIGHTNESS REF CAMERA LOCK CAMERA LOCKED DISABLE ENABLE ENABLE CAMERA LOCK CAMERA LOCK SENSITIVITY CAMERA LOCK ENABLE FAST CAMERA LOCK ENABLE FAST CAMERA LOCK CAMERA UNLOCK SENSITIVITY CAMERA LOCK ENABLE FAST USER BIT VALUE CCn USER BIT VALUE USER BIT VALUE CCn USER BIT VALUE GRAB INPUT GAIN ON BOARD DISP GRAB FRAME START GRAB END GRAB FRAME END GRAB START MODE FIELD START GRAB INPUT GAIN GRAB INPUT GAIN GRAB TRIGGER ENABLE GAIN2 GAIN3 GRAB AUTOMATIC INPUT GAIN INTERPOLATION MODE INPUT FILTER GRAB SCALE GRAB SCALE GRAB SCALE GRAB SCALE GRAB SCALE GRAB SCALE GRAB SCALE GRAB SCALE FIELD START EVEN FIELD START ODD INFINITE SYNCHRONIZE ON STARTED HUE REF LOW PASS 1 LOW PASS 2 GRAB SCALE QUALITY LOW GRAB SCALE QUALITY HIGH NEAREST NEIGHBOR BILINEAR ENABLE DISABLE BACKWARD FORWARD ROTARY ENCODER FRAME END POSITION ROTARY ENCODER POSITION DISABLE SATURATION REF GRAB WAIT SYNCHRONIZE ON STARTED BAYER COEFFICIENTS ID BAYER CONVERSION BAYER COEFFICIENTS ID BAYER COEFFICIENTS ID WHITE BALANCE CALCULATE WHITE BALANCE CAMERA LOCK CAMERA LOCK SENSITIVITY CAMERA UNLOCK SENSITIVITY USER OUT FORMAT INPUT FILTER GRAB INPUT GAIN GRAB AUTOMATIC INPUT GAIN GRAB INPUT GAIN USER IN FORMAT USER OUT FORMAT USER BIT INTERRUPT STATE EDGE RISING USER BIT FORMAT GRAB TRIGGER FORMAT GRAB TRIGGER DISABLE USER BIT FORMAT GRAB EXPOSURE FORMAT GRAB EXPOSURE DISABLE USER BIT VALUE USER BIT MODE CAMERALINK CCn SOURCE USER BIT CC A USER BIT CC B CAMERALINK CCn SOURCE USER BIT VALUE USER BIT FORMAT USER BIT INTERRUPT MODE USER BIT INTERRUPT STATE UART TIMEOUT UART READ STRING UART STRING DELIMITER UART READ STRING UART READ STRING LENGTH UART STRING DELIMITER UART TIMEOUT UART READ STRING MAXIMUM LENGTH UART WRITE STRING UART READ STRING UART WRITE STRING LENGTH UART STRING DELIMITER UART STRING DELIMITER DISABLE GRAB TRIGGER SOURCE SOFTWARE GRAB TRIGGER DISABLE USER IN FORMAT GRAB TRIGGER DISABLE GRAB TRIGGER ENABLE HARDWARE PORT4 HARDWARE PORT9 HARDWARE PORT5 HARDWARE PORT4 HARDWARE PORT9 HARDWARE PORT5 EDGE RISING NULL GRAB TRIGGER FORMAT USER IN FORMAT  RS422 USER IN FORMAT USER IN FORMAT USER IN FORMAT TTL HARDWARE PORT0 GRAB TRIGGER DISABLE ROTARY ENCODER POSITION TRIGGER GRAB TRIGGER ACTIVATE DIGITIZER TYPE GRAB TRIGGER FORMAT GRAB TRIGGER SOURCE GRAB EXPOSURE SOURCE SOFTWARE USER OUT FORMAT GRAB EXPOSURE DISABLE GRAB EXPOSURE ENABLE HARDWARE PORT4 HARDWARE PORT9 HARDWARE PORT5 HARDWARE PORT4 HARDWARE PORT9 HARDWARE PORT5 GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE GRAB TRIGGER SOURCE ROTARY ENCODER POSITION TRIGGER GRAB EXPOSURE DISABLE GRAB EXPOSURE ACTIVATE GRAB EXPOSURE TIMER1 GRAB EXPOSURE TIMER2 GRAB EXPOSURE FORMAT GRAB WAIT SYNCHRONIZE ON STARTED USER BIT VALUE USER BIT MODE    BASE PIXEL OFFSET  BAYER COEFFICIENTS ID  BAYER CONVERSION DEFAULT DISABLE ENABLE BRIGHTNESS  DEFAULT CAMERA COLOR LOCK DEFAULT  DISABLE  ENABLE  CAMERA LOCK  DEFAULT  DISABLE  ENABLE  CAMERA LOCK SENSITIVITY  DEFAULT   CAMERA PRESENT SENSITIVITY  DEFAULT  CAMERA UNLOCK SENSITIVITY  DEFAULT  CAMERALINK CCn SOURCE DEFAULT  GRAB EXPOSURE HSYNC  PIXCLK  USER BIT CC A USER BIT CC B VSYNC CAPTURE QUALITY  DEFAULT CAPTURE SIZE  DEFAULT COUPLING MODE AC DC FOCUS  DEFAULT GAIN  DEFAULT GAMMA  DEFAULT GRAB ABORT  DEFAULT  GRAB AUTOMATIC INPUT GAIN  DEFAULT  DISABLE  ENABLE  GRAB DIRECTION X  DEFAULT  FORWARD  REVERSE  GRAB DIRECTION Y  DEFAULT  FORWARD  REVERSE  GRAB FAIL CHECK DEFAULT  DISABLE  ENABLE  FINAL GRAB  GRAB FAIL RETRY NUMBER DEFAULT  GRAB FIELD NUM  DEFAULT   GRAB INPUT GAIN  DEFAULT   GAIN0  GAIN1  GAIN2  GAIN3 GAIN4 GRAB MODE  ASYNCHRONOUS  ASYNCHRONOUS QUEUED SYNCHRONOUS GRAB SAMPLING POSITION   GRAB SCALE   FILL DESTINATION    GRAB SCALE QUALITY  DEFAULT  HIGH  LOW  GRAB SCALE X   FILL DESTINATION    GRAB SCALE Y   FILL DESTINATION    GRAB START MODE  DEFAULT FIELD START FIELD START EVEN  FIELD START ODD GRAB TIMEOUT  DEFAULT  INFINITE   GRAB WAIT  NULL  GRAB WINDOW RANGE  DEFAULT DISABLE ENABLE  HUE  DEFAULT INPUT FILTER DEFAULT  BYPASS  LOW PASS 0 LOW PASS 1 LOW PASS 2 INTERPOLATION MODE  DEFAULT  AVERAGE  BILINEAR  NEAREST NEIGHBOR  IRIS  DEFAULT LAST GRAB IN TRUE BUFFER DISABLE  ENABLE GRAB CONTINUOUS END TRIGGER  DEFAULT DISABLE ENABLE  OPTICAL FILTER  DEFAULT PAN  DEFAULT ROTARY ENCODER POSITION  ROTARY ENCODER POSITION TRIGGER  ROTARY ENCODER DIRECTION DEFAULT FORWARD BACKWARD ROTARY ENCODER DEFAULT ENABLE DISABLE SATURATION  DEFAULT SHARPNESS  DEFAULT SHUTTER  DEFAULT SOURCE COMPENSATION DEFAULT  DISABLE  ENABLE  SOURCE OFFSET X   SOURCE OFFSET Y   SOURCE SIZE X   SOURCE SIZE Y   SYNCHRONIZE ON STARTED  NULL  TARGET TEMPERATURE  DEFAULT TILT  DEFAULT VCR INPUT TYPE  DEFAULT  DISABLE  ENABLE  WHITE BALANCE CALCULATE DISABLE ENABLE WHITE BALANCE U  DEFAULT WHITE BALANCE V  DEFAULT ZOOM  DEFAULT FAST CH0 CH1 CH0  M CH1 ALL CHANNELS  CH0 CH1 CH2 CH3 CHn LUMINANCE CHROMINANCE USER BIT FORMAT DEFAULT DISABLE ENABLE LVDS  TTL USER BIT INTERRUPT MODE DEFAULT EDGE RISING USER BIT INTERRUPT STATE DISABLE ENABLE USER BIT MODE  INPUT OUTPUT  USER BIT VALUE  OFF  ON  USER IN FORMAT  DEFAULT  DISABLE  LVDS  RS422  TTL  USER OUT FORMAT  DEFAULT  DISABLE  LVDS  RS422  TTL   CCn   UART DATA LENGTH  DEFAULT    UART PARITY  DEFAULT  DISABLE  EVEN  ODD  UART READ CHAR   UART READ STRING LENGTH  DEFAULT   UART READ STRING MAXIMUM LENGTH   UART READ STRING   UART SPEED  DEFAULT   UART STOP BITS  DEFAULT    UART STRING DELIMITER  DEFAULT   UART TIMEOUT  DEFAULT  INFINITE   UART WRITE CHAR   UART WRITE STRING   UART WRITE STRING LENGTH  DEFAULT   CH0 CH1 GRAB TRIGGER  DEFAULT  ACTIVATE DISABLE  ENABLE  GRAB TRIGGER FORMAT DEFAULT  DISABLE  ENABLE LVDS  OPTO TTL  GRAB TRIGGER MODE  DEFAULT  EDGE FALLING EDGE RISING LEVEL HIGH  LEVEL LOW  GRAB TRIGGER SOURCE  DEFAULT  HARDWARE PORT0  HARDWARE PORT1 HARDWARE PORT2  HARDWARE PORT3 HARDWARE PORT4 HARDWARE PORT5 HARDWARE PORT6 HARDWARE PORT7 HARDWARE PORT8 HARDWARE PORT9 HARDWARE PORT10 HARDWARE PORT11 HARDWARE PORT CAMERA NULL  ROTARY ENCODER SOFTWARE TIMER1  TIMER2  HARDWARE PORTn AUTO EXPOSURE  DEFAULT GRAB EXPOSURE  DEFAULT  ACTIVATE  DISABLE  ENABLE  GRAB EXPOSURE CLOCK SOURCE  DEFAULT  HSYNC  PIXCLK  SYSCLK  TIMER1  TIMER2 VSYNC GRAB EXPOSURE FORMAT DEFAULT  DISABLE  ENABLE LVDS  TTL  GRAB EXPOSURE MODE  DEFAULT  LEVEL HIGH  LEVEL LOW  GRAB EXPOSURE SOURCE  DEFAULT  CONTINUOUS  HARDWARE PORT0  HARDWARE PORT1  HARDWARE PORT2 HARDWARE PORT3 HARDWARE PORT4 HARDWARE PORT5 HARDWARE PORT6 HARDWARE PORT7 HARDWARE PORT8 HARDWARE PORT9 HARDWARE PORT10 HARDWARE PORT11 HSYNC  ROTARY ENCODER NULL  SOFTWARE  TIMER1  TIMER2  VSYNC  GRAB EXPOSURE TIME  DEFAULT  GRAB EXPOSURE TIME DELAY  DEFAULT  GRAB EXPOSURE TRIGGER MODE  DEFAULT  EDGE FALLING  EDGE RISING  TIMER1 TIMER2


MdigFocus

See Also | Example | Availability | MdigControl | MdigFree
User Guide:
Grabbing images
Auto-focusing

Reference:
mdigautofocus.c
mgbfocus.c
Not available in MIL-Lite

Available in MIL
Synopsis
Adjust a camera's lens motor to a position which provides optimum focus.
Syntax
void MdigFocus(
MIL_ID DigId,
MIL_ID DestImageBufId,
MIL_ID FocusImageRegionBufId,
MFOCUSHOOKFCTPTR FocusHookPtr,
void *UserDataPtr,
long MinPosition,
long StartPosition,
long MaxPosition,
long MaxPositionVariation,
long ProcMode,
long *ResultPtr
)
Description

This function adjusts the lens motor of the camera, attached to the specified digitizer, to a position which produces optimum focus. MdigFocus() determines the optimum focus position by grabbing an image at an initial lens position, analyzing the focus quality of the grabbed image, calling a user-defined function that changes the position of the lens motor, and then grabbing and analyzing another image. The process repeats until the optimum focus position is found.

A specified search strategy determines how the position of the lens motor is updated (in which direction and by how much) between grabs. For more information, see the Auto-focusing section in Chapter 18: Grabbing with your digitizer.

By default, before an image is analyzed, it is subsampled and filtered.

Parameters
DigId

Specifies the identifier of the digitizer. If you want the user-defined function to perform the grab, as well as move the lens motor, set this parameter to M_NULL.

DestImageBufId

Specifies the identifier of the buffer in which to place the grabbed images. This buffer should be of an appropriate type to hold the grabbed images. This buffer cannot be a signed 3-band buffer, a 32-bit buffer, or a 1-bit packed buffer.

FocusImageRegionBufId

Specifies the identifier of a child buffer of the destination buffer. Analysis of each grabbed image is limited to the region specified by this buffer. If you want the entire image analyzed, set this parameter to M_DEFAULT.

FocusHookPtr

Specifies the address of the user-defined hook function to call before each grab. This function must be declared as follows:

long MFTYPE FocusHook(
long HookType,

long Position,

void *UserDataPtr
)
HookType

Indicates whether the optimum focus position was found or whether a new position needs to be analyzed. Use M_CHANGE (change the focus position to the value specified by the Position parameter) or M_ON_FOCUS (the optimum focus position was found and is specified by the Position parameter).

Position

Focus position.

UserDataPtr

Pointer to data.

UserDataPtr

Sets the address of the data that you want to make available to the user-defined function.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that the function does not require data.  Specifies that the function does not require data ...

  Open   Collapse  Value

 Specifies the address of the data.  Specifies the address of the data.

 MinPosition

 Sets the minimum focus position of the search.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

Specifies the default value. The default value is 0.

  Open   Collapse  Value

 Specifies the position in lens motor steps.  Specifies the position in lens motor steps.

 StartPosition

 Sets the starting focus position of the search.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default value. The default value is equal to the value specified by MinPosition.  Specifies the default value ...

  Open   Collapse  Value

 Specifies the position in lens motor steps.  Specifies the position in lens motor steps.

 MaxPosition

 Specifies the maximum focus position of the search.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

Specifies the default value. The default value is 255.

  Open   Collapse  Value

 Specifies the position in lens motor steps.  Specifies the position in lens motor steps.

 MaxPositionVariation

 Specifies the positional increment to use in a smart scan strategy.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default value. The default value is equal to 1/6 of the value specified by MaxPosition.  Specifies the default value ...

  Open   Collapse  Value

 Specifies the position in lens motor steps.  Specifies the position in lens motor steps.

 ProcMode

 Specifies the mode of operation.  It can be set to:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

Same as M_SMART_SCAN.

  Open   Collapse  M_BISECTION

 Specifies that the bisection search strategy will be used.  Specifies that the bisection search strategy will be used.

  Open   Collapse  M_EVALUATE

 Returns the focus indicator value for the image passed instead of finding the optimum focus position. To grab an image at the current lens position into DestImageBufId and evaluate this image, pass a valid digitizer identifier to DigId.  Returns the focus indicator value for the image passed instead of finding the optimum focus position ...

 Note that in this processing mode, the user-defined function, specified by the FocusHookPtr parameter, is not called.

  Open   Collapse  M_REFOCUS

 Specifies that the refocus search strategy will be used. Note that this value can be used in combination; see below.  Specifies that the refocus search strategy will be used ...

 The default value is 2.

  Open   Collapse  M_SCAN_ALL

 Specifies that the scan_all search strategy will be used.  Specifies that the scan_all search strategy will be used.

  Open   Collapse  M_SMART_SCAN

 Specifies that the smart scan search strategy will be used. Note that this value can be used in combination; see below.  Specifies that the smart scan search strategy will be used ...

 The default value is 2.

      [Combination constants]

 To change the default number of positions, add the value below to either M_REFOCUS or M_SMART_SCAN.

  Open   Collapse  Value
Description

  Open   Collapse  Value

 Specifies the required number of positions to verify a peak.  Specifies the required number of positions to verify a peak.

      [Combination constants]

 One or both of the following values can be added to the ProcMode parameter:

  Open   Collapse  Value
Description

  Open   Collapse  M_NO_FILTER

 Skips the filtering of each image grabbed by MdigFocus().  Skips the filtering of each image grabbed by MdigFocus().

  Open   Collapse  M_NO_SUBSAMPLING

 Skips the subsampling of each image grabbed by MdigFocus().  Skips the subsampling of each image grabbed by MdigFocus().

 ResultPtr

 Specifies the address in which to return the optimum focus position or the focus indicator value, depending on the mode of operation.

REFOCUS SMART SCAN         DEFAULT   DEFAULT   DEFAULT   DEFAULT   DEFAULT   DEFAULT BISECTION EVALUATE REFOCUS SCAN ALL SMART SCAN  NO FILTER NO SUBSAMPLING


MdigFree

See Also | Example | Availability | MdigFocus | MdigGetHookInfo
User Guide:
Allocating an application and its systems
Cameras and video sources
Multiple cameras
Grabbing

Reference:
MdigAlloc
channel_switch.c
dtkobjecttracking.c
mdblgrab.c
mdiggrabmultiple.c
mdigmultformat.c
mdigprocessmultiple.c
mdispoverlay.c
mdispwindow.c
met2_1394serialbus.c
mgenlc.c
mmet2dig.c
muart.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Free a digitizer.
Syntax
void MdigFree(
MIL_ID DigId
)
Description

This function deallocates a digitizer previously allocated with MdigAlloc().

Parameter
DigId

Specifies the identifier of the digitizer.


MdigGetHookInfo

See Also | Example | Availability | MdigFree | MdigGrab
Reference:
MdigControl
MdigHookFunction
MdigInquire
MdigProcess
mdiggrabsequence.c
mdigprocess.c
mdigprocessmultiple.c
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Helios XCL
Fully supported on Matrox Solios XCL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Iris
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Synopsis
Get information about a digitizer hook event.
Syntax
long MdigGetHookInfo(
MIL_ID EventId,
long InfoType,
void *UserVarPtr
)
Description

This function allows you to get information about the event that caused the hook-handler function to be called. MdigGetHookInfo() should only be called within the scope of a digitizer hook-handler function.

Parameters
EventId

Specifies the digitizer event identifier received by the hook-handler function (see MdigProcess(), MdigHookFunction() and MdigControl()).

InfoType

Specifies a combination of two values: the event type and the type of information about the event to return. Set this parameter to the one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_MODIFIED_BUFFER | Identifies a modified-buffer type of event. This event only occurs if the hook-handler function was hooked using MdigProcess(). You must specify the type of information to return regarding this event; see combination values below. Identifies a modified-buffer type of event ... |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
 |  | UserVarPtr info Data type: MIL_ID
Open Collapse M_ROTARY_ENCODER_FRAME_END_POSITION | Identifies a grab end or grab frame end type of event, and returns the value of the rotary counter at the end of the last frame grabbed. This event only occurs if the hook-handler function was enabled using MdigControl() with M_ROTARY_ENCODER. Note that the current value of the rotary counter can be inquired using MdigInquire() with M_ROTARY_ENCODER_POSITION. Identifies a grab end or grab frame end type of event, and returns the value of the rotary counter at the end of the last frame grabbed ... |  |  |  |  |  | e |  |  |  |  |  |  |  |  |  |  |  |  | r
Open Collapse M_USER_BIT | Identifies a user-defined input signal type of event, and returns the number of the user-defined input signal that triggered the event. This event only occurs if the hook-handler function was hooked using MdigHookFunction() with M_USER_BIT_CHANGE. If more than one user-defined input signal triggers an interrupt at the same time, the hook-handler function (or chain of hook-handler functions) is called for each user-defined input signal that generated an interrupt. As a result, any and all user-specified function(s) hooked using MdigHookFunction() with M_USER_BIT_CHANGE will be executed for each interrupt. Identifies a user-defined input signal type of event, and returns the number of the user-defined input signal that triggered the event ... |  |  |  |  | d | e |  |  |  |  |  |  |  | m | n | o |  | q | r

[Combination constants]

You must combine one of the following values with M_MODIFIED_BUFFER to specify the type of information to return.

Open Collapse Value | Description
Open Collapse M_BUFFER_ID | Returns the MIL identifier of the buffer modified by MdigProcess(). Returns the MIL identifier of the buffer modified by MdigProcess() ...
 |  | UserVarPtr info Data type: MIL_ID
Open Collapse M_BUFFER_INDEX | Returns the index of the modified buffer. This index always starts at 0. Returns the index of the modified buffer ...
Open Collapse M_GRAB_TIME_STAMP | Returns the time stamp of the event that generates a service request, in secs. The time stamp can be used to see if a frame has been missed since the last time stamp. Returns the time stamp of the event that generates a service request, in secs ...
 |  | UserVarPtr info Data type: double
Open Collapse M_REGION_OFFSET_X | Returns the X-offset of the modified region (of the buffer). Returns the X-offset of the modified region (of the buffer).
Open Collapse M_REGION_OFFSET_Y | Returns the Y-offset of the modified region (of the buffer). Returns the Y-offset of the modified region (of the buffer).
Open Collapse M_REGION_SIZE_X | Returns the width of the modified region (of the buffer). Returns the width of the modified region (of the buffer).
Open Collapse M_REGION_SIZE_Y | Returns the height of the modified region (of the buffer). Returns the height of the modified region (of the buffer).
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • double
  • long
  • MIL_ID

Specifies the address in which to write the requested information.

Return value
Returns null (M_NULL) on success, and returns a non-null (!M_NULL) value on failure, without logging any errors in the application.
USER BIT CHANGE USER BIT CHANGE ROTARY ENCODER ROTARY ENCODER POSITION MODIFIED BUFFER MODIFIED BUFFER USER BIT ROTARY ENCODER FRAME END POSITION BUFFER ID BUFFER INDEX GRAB TIME STAMP REGION OFFSET X REGION OFFSET Y REGION SIZE X REGION SIZE Y


MdigGrab

See Also | Example | Availability | MdigGetHookInfo | MdigGrabContinuous
User Guide:
Grabbing images
Cameras and video sources
Multiple cameras
Grabbing a single field
Grabbing to the display
Optimizing application performance when grabbing
Grabbing a sequence of frames in real-time
Grabbing with triggers and exposures
Grabbing
General steps
Multi-threading
Executing the slave function on a system with an on-board processor

Reference:
MdigControl
MdigGrabContinuous
MdigProcess
channel_switch.c
dtkobjecttracking.c
mbufbayercolorfilter.c
mdigdoublebuffering.c
mdiggrab.c
mdighook.c
mdigmultdestination.c
mdigmultformat.c
mdigsubtract.c
mgenlc.c
mgrabbayer.c
mheliosconcurent.c
mmet2dig.c
mmodeltracking.c
mmorphisjpeg2000.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Grab data from a camera into a buffer.
Syntax
void MdigGrab(
MIL_ID DigId,
MIL_ID DestImageBufId
)
Description

This function uses the specified digitizer to acquire a frame of data and stores this data in the destination image buffer.

When acquiring data from a line-scan type of camera, the exact number of rows grabbed is determined by the DCF.

In all cases, if the grab destination buffer is smaller than the digitizer's frame size, the buffer will be filled and all other data will be lost. If the grab destination buffer is larger than the digitizer's frame size, the buffer will be filled up to the digitizer's frame size. The rest of the buffer will remain untouched.

When acquiring data from an interlaced camera, both the odd and even fields are grabbed unless otherwise set with MdigControl() using M_GRAB_FIELD_NUM.

You can use MdigGrabContinuous() to continuously acquire frames of data, or MdigProcess() for its multiple buffering capabilities. Refer to MbufAlloc...() for potential restrictions relating to your destination buffer.

Parameters
DigId

Specifies the identifier of the digitizer.

DestImageBufId

Specifies the identifier of the destination image buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse MIL color image buffer identifier

 Specifies the identifier of a color destination image buffer.  Specifies the identifier of a color destination image buffer ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The width and the horizontal position of the grab destination buffer and the grab region (set with MdigControl() using M_SOURCE_SIZE_X and M_SOURCE_SIZE_Y, or M_SOURCE_OFFSET_X and M_SOURCE_OFFSET_Y) must be a multiple of 4 bytes. If not, the grab will be clipped accordingly.

a

h
i
j
k

p

 The width of the grab destination buffer must be at least 32 bytes. If not, an error will occur.

c

 The grab buffer's depth can only be 8 bits.

f

l

p
q
r

 The grab buffer's depth can be 8 or 16 bits.

d
e

g
h
i

 The width of the grab destination buffer must be at least 16 bytes. The height must be at least 4 lines. If not, an error will occur.

b

 The width of the grab destination buffer must be at least 16 bytes. If not, an error will occur.

a

j
k

 The grab buffer's depth can be 8, 16 or 32 bits.

c

m
n
o

  Open   Collapse  MIL monochrome image buffer identifier

 Specifies the identifier of a monochrome destination image buffer.  Specifies the identifier of a monochrome destination image buffer ...

 It is not possible to grab into a color-band child buffer when the buffer is packed.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The width and the horizontal position of the grab destination buffer and the grab region (set with MdigControl() using M_SOURCE_SIZE_X and M_SOURCE_SIZE_Y, or M_SOURCE_OFFSET_X and M_SOURCE_OFFSET_Y) must be a multiple of 4 bytes. If not, the grab will be clipped accordingly.

a

h
i
j
k

p

 When using a color camera, the color data is first converted into YUV, and then the Y (luminance) component is stored in the buffer. The color space conversion is done in the hardware.

a
b

d
e
f
g

k
l
m
n
o
p
q
r

 The width of the grab destination buffer must be at least 32 bytes.

c

 When using a color camera, the red (alpha) band is grabbed.

c

h
i

 When using a color camera, the green band is grabbed.

j

 The grab buffer's depth can only be 8 bits.

f

l

p

 The grab buffer's depth can be 8 or 16 bits.

a

d
e

g
h
i

q
r

 The grab buffer's depth can be 8, 16 or 32 bits.

c

m
n
o

 The width of the grab destination buffer must be at least 16 bytes. The height must be at least 4 lines. If not, an error will occur.

b

 The width of the grab destination buffer must be at least 16 bytes. If not, an error will occur.

a

j
k

GRAB FIELD NUM SOURCE SIZE X SOURCE SIZE Y SOURCE OFFSET X SOURCE OFFSET Y SOURCE SIZE X SOURCE SIZE Y SOURCE OFFSET X SOURCE OFFSET Y


MdigGrabContinuous

See Also | Example | Availability | MdigGrab | MdigGrabWait
User Guide:
Grabbing images
Cameras and video sources
Multiple cameras
Optimizing application performance when grabbing
Grabbing with triggers and exposures
Grabbing

Reference:
MdigControl
MdigGrab
MdigHalt
MdigProcess
mdblgrab.c
mdigdoublebuffering.c
mdiggrab.c
mdiggrabmultiple.c
mdiggrabsequence.c
mdighook.c
mdigmultdestination.c
mdigprocess.c
mdigprocessmultiple.c
mdigsubtract.c
mdispoverlay.c
mdispwindow.c
mgrabbayer.c
mmodeltracking.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Grab data continuously from a camera.
Syntax
void MdigGrabContinuous(
MIL_ID DigId,
MIL_ID DestImageBufId
)
Description

This function uses the specified digitizer to continuously acquire frames of data and store this data in the destination image buffer, until MdigHalt() is called. If the destination buffer is selected to the display, the display is continuously updated, however only the last frame grabbed is written to the specified buffer.

When acquiring data from a line-scan type of camera, the exact number of rows grabbed is determined by the DCF.

In all cases, if the grab destination buffer is smaller than the digitizer's frame size, the buffer will be filled and all other data will be lost. If the grab destination buffer is larger than the digitizer's frame size, the buffer will be filled up to the digitizer's frame size. The rest of the buffer will remain untouched.

If you need to save/process each grabbed frame, you should perform the grab using MdigGrab(); alternatively, you can use MdigProcess() for its multiple buffering capabilities. Refer to MbufAlloc...() for potential restrictions relating to your destination buffer.

Parameters
DigId

Specifies the identifier of the digitizer.

DestImageBufId

Specifies the identifier of the destination image buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse MIL color image buffer identifier

 Specifies the identifier of a color destination image buffer.  Specifies the identifier of a color destination image buffer ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The width and the horizontal position of the grab destination buffer and the grab region (set with MdigControl() using M_SOURCE_SIZE_X and M_SOURCE_SIZE_Y, or M_SOURCE_OFFSET_X and M_SOURCE_OFFSET_Y) must be a multiple of 4 bytes. If not, the grab will be clipped accordingly.

a

h
i
j
k

p

 The width of the grab destination buffer must be at least 32 bytes.

c

 The grab buffer's depth can only be 8 bits.

f

l

p
q
r

 The grab buffer's depth can be 8 or 16 bits.

d
e

g
h
i

 The grab buffer's depth can be 8, 16 or 32 bits.

c

m
n
o

 The width of the grab destination buffer must be at least 16 bytes. The height must be at least 4 lines. If not, an error will occur.

b

 The width of the grab destination buffer must be at least 16 bytes. If not, an error will occur.

a

j
k

  Open   Collapse  MIL monochrome image buffer identifier

 Specifies the identifier of a monochrome destination image buffer.  Specifies the identifier of a monochrome destination image buffer ...

 It is not possible to grab into a color-band child buffer when the buffer is packed.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The width and the horizontal position of the grab destination buffer and the grab region (set with MdigControl() using M_SOURCE_SIZE_X and M_SOURCE_SIZE_Y, or M_SOURCE_OFFSET_X and M_SOURCE_OFFSET_Y) must be a multiple of 4 bytes. If not, the grab will be clipped accordingly.

a

h
i
j
k

p

 When using a color camera, the color data is first converted into YUV, and then the Y (luminance) component is stored in the buffer. The color space conversion is done in the hardware.

a
b

d
e
f
g

k
l
m
n
o
p
q
r

 The width of the grab destination buffer must be at least 32 bytes.

c

 When using a color camera, the red (alpha) band is grabbed.

c

h
i

 When using a color camera, the green band is grabbed.

j

 The grab buffer's depth can only be 8 bits.

f

l

p

 The grab buffer's depth can be 8 or 16 bits.

d
e

g
h
i

q
r

 The grab buffer's depth can be 8, 16 or 32 bits.

c

m
n
o

 The width of the grab destination buffer must be at least 16 bytes. The height must be at least 4 lines. If not, an error will occur.

b

 The width of the grab destination buffer must be at least 16 bytes. If not, an error will occur.

a

j
k

SOURCE SIZE X SOURCE SIZE Y SOURCE OFFSET X SOURCE OFFSET Y SOURCE SIZE X SOURCE SIZE Y SOURCE OFFSET X SOURCE OFFSET Y


MdigGrabWait

See Also | Example | Availability | MdigGrabContinuous | MdigHalt
User Guide:
Optimizing application performance when grabbing

Reference:
MdigControl
MdigGrabContinuous
dtkobjecttracking.c
mdigdoublebuffering.c
mdighook.c
mdigmultdestination.c
mmodeltracking.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Wait for the end of the grab in progress.
Syntax
void MdigGrabWait (
MIL_ID DigId,
long Flag
)
Description

This function allows you to temporarily override a grab mode of M_ASYNCHRONOUS or M_ASYNCHRONOUS_QUEUED on the specified digitizer (see MdigControl()). Using this function allows your application to wait for the grab in progress to end, before continuing.

Parameters
DigId

The DigId parameter specifies the identifier of the digitizer.

Flag

The Flag parameter specifies the digitizer flag to set. This parameter must be set to one of the following:

Open Collapse Value Description
Open Collapse M_GRAB_END

 Wait for the end of the queued grabs.  Wait for the end of the queued grabs.

  Open   Collapse  M_GRAB_FRAME_END

 Waits for the end of the current grab.  Waits for the end of the current grab.

 The M_GRAB_END flag should not be used when grabbing data with MdigGrabContinuous().

ASYNCHRONOUS ASYNCHRONOUS QUEUED GRAB END   GRAB END GRAB FRAME END


MdigHalt

See Also | Example | Availability | MdigGrabWait | MdigHookFunction
User Guide:
Grabbing images
Screen tearing
Optimizing application performance when grabbing
Grabbing with triggers and exposures

Reference:
MdigGrabContinuous
mdblgrab.c
mdigdoublebuffering.c
mdiggrab.c
mdiggrabmultiple.c
mdiggrabsequence.c
mdighook.c
mdigmultdestination.c
mdigprocess.c
mdigprocessmultiple.c
mdigsubtract.c
mdispoverlay.c
mdispwindow.c
mgrabbayer.c
mmodeltracking.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Halt a continuous grab from an input device.
Syntax
void MdigHalt(
MIL_ID DigId
)
Description

This function stops the specified digitizer from grabbing data. It should be used when performing a continuous grab with MdigGrabContinuous().

This function will wait for the end of the current frame before returning, to ensure the last frame is always valid.

Parameter
DigId

Specifies the identifier of the digitizer.


MdigHookFunction

See Also | Example | Availability | MdigHalt | MdigInquire
User Guide:
Multiple cameras
Multi-threading

Reference:
MdigControl
MdigGetHookInfo
MdigInquire
mdighook.c
muart.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Hook a function to a digitizer event.
Syntax
void MdigHookFunction(
MIL_ID DigId,
long HookType,
MDIGHOOKFCTPTR HookHandlerPtr,
void *UserDataPtr
)
Description

This function allows you to attach or detach a user-defined function to a specified digitizer event. Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.

You can hook more than one function to an event by making separate calls to MdigHookFunction() for each function that you want to hook. MIL automatically chains and keeps an internal list of all these hooked functions. When a function is hooked, this new function is added to the end of the list. When the event happens, all user-defined functions in the list will be executed in the same order that they were hooked to the event. You can also remove any function from the list; in this case, MIL preserves the order of the remaining functions in the list.

For some events, you can obtain more information about the event from within the hook handler function using MdigGetHookInfo().

Note that functions hooked to an event execute on a distinct thread. This permits the functions to run asynchronously from the operation that fired the event and from functions hooked to other events. Although there is a small queue to permit a certain amount of overlap, hooked functions should not take longer to execute than the period in which two of their associated events can occur. Typically, a hooked function performs the minimum number of operations required and, if necessary, performs longer processes by launching other threads.

Parameters
DigId

Specifies the identifier of the digitizer.

HookType

Specifies the digitizer event to which to hook the function. This parameter can be set to one of the following values:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_CAMERA_PRESENT

 Hooks the function to the presence of the camera. Use MdigInquire() with M_CAMERA_PRESENT to inquire if the camera is currently present.  Hooks the function to the presence of the camera ...

a

d

l
m

q

  Open   Collapse  M_FIELD_START

 Hooks the function to the event that occurs at the start of each field of the incoming signal.  Hooks the function to the event that occurs at the start of each field of the incoming signal ...

 Note that MIL need not be grabbing the incoming signal for this event to occur. The event is only dependent on the presence of a camera.

a
b

d
e

l
m
n
o
p
q
r

  Open   Collapse  M_FIELD_START_EVEN

 Hooks the function to the event that occurs at the start of the incoming signal's even fields.  Hooks the function to the event that occurs at the start of the incoming signal's even fields ...

 Note that MIL need not be grabbing the incoming signal for this event to occur. The event is only dependent on the presence of a camera.

a
b

d
e

l
m
n
o
p
q
r

  Open   Collapse  M_FIELD_START_ODD

 Hooks the function to the event that occurs at the start of the incoming signal's odd fields.  Hooks the function to the event that occurs at the start of the incoming signal's odd fields ...

 Note that MIL need not be grabbing the incoming signal for this event to occur. The event is only dependent on the presence of a camera.

a
b

d
e

l
m
n
o
p
q
r

  Open   Collapse  M_FRAME_START

 Hooks the function to the event that occurs at the start of each frame of the incoming signal.  Hooks the function to the event that occurs at the start of each frame of the incoming signal ...

 Note that MIL need not be grabbing the incoming signal for this event to occur. The event is only dependent on the presence of a camera.

a
b

d
e

l
m
n
o
p
q
r

  Open   Collapse  M_GRAB_END

 Hooks the function to the event that occurs at the end of each grab.  Hooks the function to the event that occurs at the end of each grab ...

 When grabbing continuously, the M_GRAB_END event is fired only when the last frame is grabbed. To be notified at the end of each frame, use the M_GRAB_FRAME_END event.

 A function hooked to an M_GRAB_END event is called when all the data of the grab is transferred to the Host. This means that this hooked function can be called after the M_GRAB_START or M_GRAB_FRAME_START event of the next frame.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_GRAB_FIELD_END

 Hooks the function to event that occurs at the end of grabbed fields.  Hooks the function to event that occurs at the end of grabbed fields.

a
b
c
d
e

h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_GRAB_FIELD_END_EVEN

 Hooks the function to the event that occurs at the end of grabbed even fields.  Hooks the function to the event that occurs at the end of grabbed even fields.

a
b
c
d
e

h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_GRAB_FIELD_END_ODD

 Hooks the function to the event that occurs at the end of grabbed odd fields.  Hooks the function to the event that occurs at the end of grabbed odd fields.

a
b
c
d
e

h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_GRAB_FRAME_END

 Hooks the function to the event that occurs at the end of grabbed frames. Note that, in this case, the grabbed data might not be completely transferred to the Host.  Hooks the function to the event that occurs at the end of grabbed frames ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_GRAB_FRAME_START

 Hooks the function to the event that occurs at the start of grabbed frames.  Hooks the function to the event that occurs at the start of grabbed frames ...

a
b
c
d
e
f
g

j
k
l
m
n
o
p
q
r

Specifics

M_GRAB_FRAME_START is not supported on Matrox Genesis-LC.

c

o

  Open   Collapse  M_GRAB_LINE + n

 Hooks the function to the event that occurs when the specified line (row) is reached, where n is the specified line. (For example, M_GRAB_LINE+200 would call the hook-handler function when line number 200 is reached). Note that the data of the specified line number might not be in the buffer.  Hooks the function to the event that occurs when the specified line (row) is reached, where n is the specified line ...

c
d
e

h
i

m
n
o

q
r

  Open   Collapse  M_GRAB_LINE_END + n

 Hooks the function to the event that occurs when the data of the specified line (row) is in the buffer and ready to be processed, where n is the specified line. (For example, M_GRAB_LINE+200 would call the hook-handler function when the data of line number 200 is in the buffer).  Hooks the function to the event that occurs when the data of the specified line (row) is in the buffer and ready to be processed, where n is the specified line ...

d
e

q
r

  Open   Collapse  M_GRAB_START

 Hooks the function to the event that occurs at the start of each grab.  Hooks the function to the event that occurs at the start of each grab ...

 When grabbing continuously, the M_GRAB_START event is fired only when the first frame is grabbed. To be notified at the start of each frame, use the M_GRAB_FRAME_START event.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_ROTARY_ENCODER

 Hooks the function to the event that occurs when the rotary counter reaches its trigger position (specified using MdigControl() with M_ROTARY_ENCODER_POSITION_TRIGGER.  Hooks the function to the event that occurs when the rotary counter reaches its trigger position (specified using MdigControl() with M_ROTARY_ENCODER_POSITION_TRIGGER.

e

r

  Open   Collapse  M_UART_DATA_RECEIVED

 Hooks the function to the event that occurs when data is received by the UART.  Hooks the function to the event that occurs when data is received by the UART.

a

h
i
j
k

m
n
o

  Open   Collapse  M_USER_BIT_CHANGE

 Hooks the function to the event that occurs when a user-defined input signal changes in accordance with its specified interrupt mode (see M_USER_BIT_INTERRUPT_MODE in MdigControl()). It is prudent to verify that the appropriate user-defined signal triggered the hook-handler function. To determine which bit caused the event, call MdigGetHookInfo() from within your hook-handler function.  Hooks the function to the event that occurs when a user-defined input signal changes in accordance with its specified interrupt mode (see M_USER_BIT_INTERRUPT_MODE in MdigControl()) ...

d
e

m
n
o

q
r

      [Combination constants]

 The HookType parameter can be combined with the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_UNHOOK

 Unhooks a hooked function.  Unhooks a hooked function.

 HookHandlerPtr

 Specifies the address of the function that should be called when the specified event occurs.

 The hook-handler function, pointed to by HookHandlerPtr, must be declared as follows:

long MFTYPE HookHandler(
long HookType,

MIL_ID EventId,

void *UserDataPtr

        )

HookType

 Type of event hooked.

EventId

 Event identifier. Not that currently events are not assigned an event identifier. The information passed to this parameter is null.

UserDataPtr

 User data pointer.

 Upon successful completion, the hook-handler function should return M_NULL. Note, MFTYPE and MDIGHOOKFCTPTR are reserved MIL predefined types for functions and data pointers.

 UserDataPtr

 Specifies the address of the user data that you want to make available to the hook-handler function.  This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.

CAMERA PRESENT GRAB END GRAB FRAME END GRAB END GRAB START GRAB FRAME START GRAB FRAME START GRAB START GRAB FRAME START ROTARY ENCODER POSITION TRIGGER USER BIT INTERRUPT MODE   CAMERA PRESENT FIELD START FIELD START EVEN FIELD START ODD FRAME START GRAB END GRAB FIELD END GRAB FIELD END EVEN GRAB FIELD END ODD GRAB FRAME END GRAB FRAME START GRAB LINE  n GRAB LINE END  n GRAB START ROTARY ENCODER UART DATA RECEIVED USER BIT CHANGE UNHOOK


MdigInquire

See Also | Example | Availability | MdigHookFunction | MdigLut
User Guide:
Using this help
Data format
Multiple cameras

Reference:
MdigAlloc
MdigControl
MdigGrab
MdigHalt
MdigHookFunction
MdigProcess
MsysControl
channel_switch.c
dtkobjecttracking.c
mbufbayercolorfilter.c
mdigdoublebuffering.c
mdiggrabmultiple.c
mdiggrabsequence.c
mdighook.c
mdigmultdestination.c
mdigmultformat.c
mdigprocess.c
mdigprocessmultiple.c
mdigsubtract.c
mdispoverlay.c
mdispwindow.c
met2_1394serialbus.c
mgbfocus.c
mgenlc.c
mgrabbayer.c
mmet2dig.c
mmorphisjpeg2000.c
mnatgen.c
muart.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Inquire about a digitizer setting.
Syntax
long MdigInquire(
MIL_ID DigId,
long InquireType,
void *UserVarPtr
)
Description

This function allows you to inquire about various digitizer settings.

Note that you can use MdigControl() to control specific digitizer settings.

Parameters
DigId

Specifies the identifier of the digitizer.

InquireType

Specifies the digitizer setting to inquire. This parameter can be set to one of the following values:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_BAYER_COEFFICIENTS_ID

Returns a MIL identifier of the internal buffer containing the white balance coefficients used when grabbing from a camera with a Bayer color filter. This buffer should not be freed. Returns a MIL identifier of the internal buffer containing the white balance coefficients used when grabbing from a camera with a Bayer color filter ...

e n o

UserVarPtr info

Data type: MIL_ID

Return values:
MIL array buffer identifier (details)
Open Collapse M_BAYER_CONVERSION

Returns whether automatic Bayer color conversion is enabled or disabled. Returns whether automatic Bayer color conversion is enabled or disabled ...

e n o

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_BLACK_REF

Returns the digitization black reference level. See below for combination value. Returns the digitization black reference level ...

a c d f j m p q

UserVarPtr info

Return values:
M_MAX_LEVEL, M_MIN_LEVEL, M_MIN_LEVEL <= Value <= M_MAX_LEVEL, Minimum voltage <= Value <= Maximum voltage (details)
Specifics

Note that this inquire type is only supported when grabbing from the RGB section.

p
Open Collapse M_BRIGHTNESS

Returns the black level of the picture. Returns the black level of the picture ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_BRIGHTNESS. Note that M_DEFAULT is not returned.

Open Collapse M_BRIGHTNESS_REF

Returns the digitization brightness reference level. Returns the digitization brightness reference level ...

b k l p

UserVarPtr info

Return values:
M_MAX_LEVEL, M_MIN_LEVEL, M_MIN_LEVEL <= Value <= M_MAX_LEVEL (details)
Specifics

Note that this inquire type is only supported on composite and Y/C cameras (decoder path).

p
Open Collapse M_CAMERA_COLOR_LOCK

Returns whether a color-lock check is done before starting each grab and M_CAMERA_LOCK is enabled, or when using MdigInquire() with M_CAMERA_LOCKED. Note that this only applies when the digitizer uses a composite or Y/C color DCF. Returns whether a color-lock check is done before starting each grab and M_CAMERA_LOCK is enabled, or when using MdigInquire() with M_CAMERA_LOCKED ...

b k l p

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_CAMERA_LOCK

Returns the state of the camera lock mechanism. See below for combination value. Returns the state of the camera lock mechanism ...

a b d j k l m p q

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_CAMERA_LOCK_SENSITIVITY

Returns the line-lock sensitivity when M_CAMERA_LOCK is enabled. Returns the line-lock sensitivity when M_CAMERA_LOCK is enabled ...

a j k l p

UserVarPtr info

Return values:
0 to 255, 256 to 511 (details)
Open Collapse M_CAMERA_LOCKED

Returns whether a camera lock was successful. Returns whether a camera lock was successful ...

a b d k l m p q

UserVarPtr info

Return values:
M_NO | A camera lock failed.
M_YES | A camera lock succeeded.
Open Collapse M_CAMERA_PRESENT

Returns whether a camera is present. Note that this does not indicate that a camera is locked. Returns whether a camera is present ...

a b d k l m p q

UserVarPtr info

Return values:
M_NO | A camera is not present.
M_YES | A camera is present.
Open Collapse M_CAMERA_UNLOCK_SENSITIVITY

Returns the sensitivity of the frame grabber to unlocking from the camera, during a channel switch. Note that M_CAMERA_LOCK must be enabled for this to have an effect. The unlock sensitivity determines how quickly an unlock can occur and how reliable the unlock is. Returns the sensitivity of the frame grabber to unlocking from the camera, during a channel switch ...

a l p

UserVarPtr info

Return values:
0 to 255 (details)
Open Collapse M_CAMERALINK_CCn_SOURCE

Returns the type of signal routed to camera control output n, where n is the number of the camera control output (1,2,3, or 4). Returns the type of signal routed to camera control output n, where n is the number of the camera control output (1,2,3, or 4) ...

e h n r

UserVarPtr info

Return values:
M_GRAB_EXPOSURE, M_HSYNC, M_PIXCLK, M_USER_BIT_CC_A, M_USER_BIT_CC_B, M_VSYNC (details)
Open Collapse M_CAPTURE_QUALITY

Returns the capture quality of the image. Returns the capture quality of the image ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_CAPTURE_QUALITY. Note that M_DEFAULT is not returned.

Open Collapse M_CAPTURE_SIZE

Returns the capture size of the image. Returns the capture size of the image ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_CAPTURE_SIZE. Note that M_DEFAULT is not returned.

Open Collapse M_CHANNEL

Returns the current data channel of the digitizer. Returns the current data channel of the digitizer ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_CH0, M_CH1, M_CH2, M_CH3, M_CH4, M_CH5, M_CH6, M_CH7, M_CH8, M_CH9, M_CH10, M_CH11, M_CH12, M_CH13, M_CH14, M_CH15, M_CH16, M_CH17, M_CH18, M_CH19, M_CH20, M_CH21, M_CH22, M_CH23 (details)
Open Collapse M_CHANNEL + M_SIGNAL

Returns the current data channel of the digitizer. Returns the current data channel of the digitizer ...

a c d j k l m p q

UserVarPtr info

Return values:
M_CH0, M_CH1, M_CH2, M_CH3, M_CH4, M_CH5, M_CH6, M_CH7, M_CH8, M_CH9, M_CH10, M_CH11, M_CH12, M_CH13, M_CH14, M_CH15, M_CH16, M_CH17, M_CH18, M_CH19, M_CH20, M_CH21, M_CH22, M_CH23 (details)
Open Collapse M_CHANNEL + M_SYNC

Returns the current synchronization channel of the digitizer. Returns the current synchronization channel of the digitizer ...

a b c d j m p q

UserVarPtr info

Return values:
M_CH0, M_CH1, M_CH2, M_CH3, M_CH4, M_CH5, M_CH6, M_CH7, M_CH8, M_CH9, M_CH10, M_CH11, M_CH12, M_CH13, M_CH14, M_CH15, M_CH16, M_CH17, M_CH18, M_CH19, M_CH20, M_CH21, M_CH22, M_CH23 (details)
Open Collapse M_CHANNEL_NUM

Returns the number of available channels of the digitizer. Returns the number of available channels of the digitizer ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
1 to 23 The number of channels available varies depending on the board.

Open Collapse M_COLOR_MODE

Returns the type of input (specifically monochrome or color) set in the DCF. Returns the type of input (specifically monochrome or color) set in the DCF ...

See the MIL Board-Specific Notes to determine which mode applies to your particular board.

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_COMPOSITE | Composite input.
M_EXTERNAL_CHROMINANCE | External chrominance input.
M_MONO8_VIA_RGB | Monochrome 8-bit through RGB input.
M_MONOCHROME | Monochrome input.
M_RGB | RGB component input.
Open Collapse M_CONTRAST_REF

Returns the digitizer contrast reference level. Returns the digitizer contrast reference level ...

b g k l p

UserVarPtr info

Return values:
M_MAX_LEVEL, M_MIN_LEVEL, M_MIN_LEVEL <= Value <= M_MAX_LEVEL (details)
Open Collapse M_COUPLING_MODE

Returns the signal coupling of the available data channels. Returns the signal coupling of the available data channels ...

d m q

UserVarPtr info

Return values:
M_AC, M_DC (details)
Open Collapse M_FIELD_START_EVEN_HANDLER_PTR

Returns the handler pointer, hooked to the start of the incoming signal's even fields using MdigHookFunction(). Returns the handler pointer, hooked to the start of the incoming signal's even fields using MdigHookFunction().

a b d e l m n o p q r
Open Collapse M_FIELD_START_EVEN_HANDLER_USER_PTR

Returns the user pointer, hooked to the start of the incoming signal's even fields using MdigHookFunction(). Returns the user pointer, hooked to the start of the incoming signal's even fields using MdigHookFunction().

a b d e l m n o p q r
Open Collapse M_FIELD_START_HANDLER_PTR

Returns the handler pointer, hooked to the start of the incoming signal's fields using MdigHookFunction(). Returns the handler pointer, hooked to the start of the incoming signal's fields using MdigHookFunction().

a b d e l m n o p q r
Open Collapse M_FIELD_START_HANDLER_USER_PTR

Returns the user pointer, hooked to the start of the incoming signal's fields using MdigHookFunction(). Returns the user pointer, hooked to the start of the incoming signal's fields using MdigHookFunction().

a b d e l m n o p q r
Open Collapse M_FIELD_START_ODD_HANDLER_PTR

Returns the handler pointer, hooked to the start of the incoming signal's odd fields using MdigHookFunction(). Returns the handler pointer, hooked to the start of the incoming signal's odd fields using MdigHookFunction().

a b d e l m n o p q r
Open Collapse M_FIELD_START_ODD_HANDLER_USER_PTR

Returns the user pointer, hooked to the start of the incoming signal's odd fields using MdigHookFunction(). Returns the user pointer, hooked to the start of the incoming signal's odd fields using MdigHookFunction().

a b d e l m n o p q r
Open Collapse M_FOCUS

Returns the lens focus capabilities. Returns the lens focus capabilities ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_FOCUS. Note that M_DEFAULT is not returned.

Open Collapse M_FORMAT

Returns the digitizer data format. Returns the digitizer data format ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: array of type MIL_TEXT_CHAR
Array size: Call MdigInquire() with the InquireType parameter set to M_FORMAT_SIZE.

Return values:
"DCF Filename", "M_CCIR", "M_CCIR_VIA_RGB", "M_DEFAULT", "M_NTSC", "M_NTSC_RGB", "M_NTSC_YC", "M_PAL", "M_PAL_RGB", "M_PAL_YC", "M_RS170", "M_RS170_VIA_RGB", "M_xXy_data[@z[FPS]]", "M_xXy_data_format_7_z" (details)
Open Collapse M_FORMAT_SIZE

Returns the number of characters in the digitizer data format string. Returns the number of characters in the digitizer data format string.

a b c d e f g h i j k l m n o p q r
Open Collapse M_FORMAT_SUPPORTED

Returns the names of all supported formats that can be accepted by MdigAlloc() for your 1394 DCS-compliant digital camera. Returns the names of all supported formats that can be accepted by MdigAlloc() for your 1394 DCS-compliant digital camera ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g
Open Collapse M_FORMAT_SUPPORTED_LENGTH

Returns the maximum number of characters of the names of the supported formats. Returns the maximum number of characters of the names of the supported formats ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g
Open Collapse M_FORMAT_SUPPORTED_NUM

Returns the number of supported strings. Returns the number of supported strings ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g
Open Collapse M_FRAME_START_HANDLER_PTR

Returns the handler pointer, hooked to the start of the incoming signal's frames using MdigHookFunction(). Returns the handler pointer, hooked to the start of the incoming signal's frames using MdigHookFunction().

a b d e l m n o p q r
Open Collapse M_FRAME_START_HANDLER_USER_PTR

Returns the user pointer, hooked to the start of the incoming signal's frames using MdigHookFunction(). Returns the user pointer, hooked to the start of the incoming signal's frames using MdigHookFunction().

a b d e l m n o p q r
Open Collapse M_GAIN

Returns the camera circuit gain. Returns the camera circuit gain ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_GAIN. Note that M_DEFAULT is not returned.

Open Collapse M_GAMMA

Returns the function between the incoming light level and output picture level. Returns the function between the incoming light level and output picture level ...

f g

UserVarPtr info

Return values:
Please see MdigControl() with M_GAMMA. Note that M_DEFAULT is not returned.

Specifics

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

Note that the gamma level is used to control a physical LUT which is applied automatically to the grab buffer.

f
Open Collapse M_GRAB_AUTOMATIC_INPUT_GAIN

Returns the state of the automatic input gain. Returns the state of the automatic input gain ...

b k l p

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Specifics

If the components of the input signal have different automatic input gain states, this inquire type returns the automatic input gain state of the luminance component. To inquire about the state of the automatic input-gain setting for a specific component of the input signal, see combination values below.

l
Open Collapse M_GRAB_CONTINUOUS_END_TRIGGER

Returns whether an automatic trigger is generated after MdigHalt() is issued when performing a triggered continuous grab. Returns whether an automatic trigger is generated after MdigHalt() is issued when performing a triggered continuous grab ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_GRAB_DIRECTION_X

Returns the horizontal grab direction. Returns the horizontal grab direction ...

a b c d e f h i j k l m n o p q r

UserVarPtr info

Return values:
M_FORWARD, M_REVERSE (details)
Open Collapse M_GRAB_DIRECTION_Y

Returns the vertical grab direction. Returns the vertical grab direction ...

a b c d e f h i j k l m n o p q r

UserVarPtr info

Return values:
M_FORWARD, M_REVERSE (details)
Open Collapse M_GRAB_END_HANDLER_PTR

Returns the handler pointer, hooked to the end of a grab using MdigHookFunction(). Returns the handler pointer, hooked to the end of a grab using MdigHookFunction().

a b c d e f g h i j k l m n o p q r
Open Collapse M_GRAB_END_HANDLER_USER_PTR

Returns the user pointer, hooked to the end of grab using MdigHookFunction(). Returns the user pointer, hooked to the end of grab using MdigHookFunction().

a b c d e f g h i j k l m n o p q r
Open Collapse M_GRAB_FAIL_CHECK

Returns the state of the grab-fail check control. Returns the state of the grab-fail check control ...

b

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE, M_FINAL_GRAB (details)
Open Collapse M_GRAB_FAIL_RETRY_NUMBER

Returns the number of retries to attempt upon a grab failure. Returns the number of retries to attempt upon a grab failure ...

b

UserVarPtr info

Return values:
0 to 255 (details)
Open Collapse M_GRAB_FAIL_STATUS

Returns the status of the fail check on the last grab. Returns the status of the fail check on the last grab ...

b

UserVarPtr info

Return values:
M_NO | The last grab did not fail.
M_YES | The last grab failed.
Open Collapse M_GRAB_FIELD_END_EVEN_HANDLER_PTR

Returns the handler pointer, hooked to the end of grabbed even fields using MdigHookFunction(). Returns the handler pointer, hooked to the end of grabbed even fields using MdigHookFunction().

a b c d e g h i j k l m n o p q r
Open Collapse M_GRAB_FIELD_END_EVEN_HANDLER_USER_PTR

Returns the user pointer, hooked to the end of grabbed even fields using MdigHookFunction(). Returns the user pointer, hooked to the end of grabbed even fields using MdigHookFunction().

a b c d e g h i j k l m n o p q r
Open Collapse M_GRAB_FIELD_END_HANDLER_PTR

Returns the handler pointer, hooked to the end of grabbed fields using MdigHookFunction(). Returns the handler pointer, hooked to the end of grabbed fields using MdigHookFunction().

a b c d e g h i j k l m n o p q r
Open Collapse M_GRAB_FIELD_END_HANDLER_USER_PTR

Returns the user pointer, hooked to the end of grabbed fields using MdigHookFunction(). Returns the user pointer, hooked to the end of grabbed fields using MdigHookFunction().

a b c d e g h i j k l m n o p q r
Open Collapse M_GRAB_FIELD_END_ODD_HANDLER_PTR

Returns the handler pointer, hooked to the end of grabbed odd fields using MdigHookFunction(). Returns the handler pointer, hooked to the end of grabbed odd fields using MdigHookFunction().

a b c d e g h i j k l m n o p q r
Open Collapse M_GRAB_FIELD_END_ODD_HANDLER_USER_PTR

Returns the user pointer, hooked to the end of grabbed odd fields using MdigHookFunction(). Returns the user pointer, hooked to the end of grabbed odd fields using MdigHookFunction().

a b c d e g h i j k l m n o p q r
Open Collapse M_GRAB_FIELD_NUM

Returns the number of fields grabbed when MdigGrab() is called. Returns the number of fields grabbed when MdigGrab() is called ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
1, 2 (details)
Open Collapse M_GRAB_IN_PROGRESS

Returns the current grab state. Returns the current grab state ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_NO | There is no grab in progress.
M_YES | There is a grab in progress.
Open Collapse M_GRAB_INPUT_GAIN

Returns the input gain last applied to the input signal. Returns the input gain last applied to the input signal ...

a b c d f g j k l m p q

UserVarPtr info

Return values:
0 to 255, M_GAIN0, M_GAIN1, M_GAIN2, M_GAIN3, M_GAIN4 (details)
Specifics

If the acquisition paths or components of the input signal have different input gain, this inquire type returns the input gain of the first acquisition path or the luminance component, respectively. To inquire about the input gain last applied to a specific acquisition path or component of the input signal, see combination values below.

c d l m q
Open Collapse M_GRAB_MODE

Returns the grab synchronization with the Host. Returns the grab synchronization with the Host ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_ASYNCHRONOUS, M_ASYNCHRONOUS_QUEUED, M_SYNCHRONOUS (details)
Open Collapse M_GRAB_PERIOD

Returns the duration of a frame (as specified in the DCF), in msec. Returns the duration of a frame (as specified in the DCF), in msec.

a b d e f h i j k l m n o p q r
Open Collapse M_GRAB_SAMPLING_POSITION

Returns the delay along the analog signal at which the pixel clock will sample. Note that this is only available on the PC/104-plus form factor. Returns the delay along the analog signal at which the pixel clock will sample ...

j

UserVarPtr info

Return values:
0 to 255 (details)
Open Collapse M_GRAB_SCALE_QUALITY

Returns the scaling quality. Returns the scaling quality ...

p

UserVarPtr info

Return values:
M_HIGH, M_LOW (details)
Open Collapse M_GRAB_SCALE_X

Returns the horizontal scaling factor. Returns the horizontal scaling factor ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: double

Return values:
1, M_FILL_DESTINATION, Value = 1/n, Value > 1 (details)
Open Collapse M_GRAB_SCALE_Y

Returns the vertical scaling factor. Returns the vertical scaling factor ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: double

Return values:
1, M_FILL_DESTINATION, Value = 1/n, Value > 1 (details)
Open Collapse M_GRAB_START_HANDLER_PTR

Returns the handler pointer, hooked to the start of each grab using MdigHookFunction(). Returns the handler pointer, hooked to the start of each grab using MdigHookFunction().

a b c d e f g h i j k l m n o p q r
Open Collapse M_GRAB_START_HANDLER_USER_PTR

Returns the user pointer, hooked to the start of each grab using MdigHookFunction(). Returns the user pointer, hooked to the start of each grab using MdigHookFunction().

a b c d e f g h i j k l m n o p q r
Open Collapse M_GRAB_START_MODE

Returns the type of field on which to grab. Returns the type of field on which to grab ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_FIELD_START, M_FIELD_START_EVEN, M_FIELD_START_ODD (details)
Open Collapse M_GRAB_TIMEOUT

Returns the maximum time to wait (in msec) for a frame before generating an error. Returns the maximum time to wait (in msec) for a frame before generating an error ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_INFINITE, Value > 0 (details)
Open Collapse M_GRAB_WAIT

Returns whether the grab of a digitizer is to wait and start upon a grab of a second digitizer (MIL digitizer identifier), or not (M_NULL). Returns whether the grab of a digitizer is to wait and start upon a grab of a second digitizer (MIL digitizer identifier), or not (M_NULL) ...

c m n o

UserVarPtr info

Return values:
M_NULL, MIL digitizer identifier (details)
Open Collapse M_GRAB_WINDOW_RANGE

Returns the state of limiting the range of the grabbed pixel values. Returns the state of limiting the range of the grabbed pixel values ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_HOOK_MASTER_THREAD_HANDLE

Returns the handle of the main interrupt thread that dispatches the user-defined functions attached to a specified digitizer event to their respective threads. Returns the handle of the main interrupt thread that dispatches the user-defined functions attached to a specified digitizer event to their respective threads.

a b j k p
Open Collapse M_HOOK_MASTER_THREAD_ID

Returns the identifier of the main interrupt thread that dispatches the handling of the user-defined functions attached to a specified digitizer event to their respective threads. Returns the identifier of the main interrupt thread that dispatches the handling of the user-defined functions attached to a specified digitizer event to their respective threads.

a b j k p
Open Collapse M_HUE

Returns the color phase of the picture. Returns the color phase of the picture ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_HUE. Note that M_DEFAULT is not returned.

Open Collapse M_HUE_REF

Returns the digitizer hue reference level. Note that this inquire type is not supported for monochrome cameras. Returns the digitizer hue reference level ...

b g k l p

UserVarPtr info

Return values:
M_MAX_LEVEL, M_MIN_LEVEL, M_MIN_LEVEL <= Value <= M_MAX_LEVEL (details)
Open Collapse M_INIT_FLAG

Returns the digitizer initialization flag. Returns the digitizer initialization flag ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DEFAULT (details)
Open Collapse M_INPUT_FILTER

Returns the low-pass filter applied to incoming data for all acquisition paths used by the digitizer. Note that, to return the filter for a specific acquisition path, see combination values below. Returns the low-pass filter applied to incoming data for all acquisition paths used by the digitizer ...

a d m p q

UserVarPtr info

Return values:
M_BYPASS, M_LOW_PASS_0, M_LOW_PASS_1, M_LOW_PASS_2 (details)
Specifics

For Matrox Orion for 4Sight-II, the filter cannot be returned for a specific acquisition path.

p

Refer to the Installation and hardware reference manual for more information regarding the frequencies of low-pass filters.

d m q
Open Collapse M_INPUT_MODE

Returns analog or digital input mode (as specified in the DCF). Returns analog or digital input mode (as specified in the DCF) ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_ANALOG | Analog input mode.
M_DIGITAL | Digital input mode.
Open Collapse M_INTERPOLATION_MODE

Returns the type of interpolation used when scaling the input image or to smooth the grabbed image. Returns the type of interpolation used when scaling the input image or to smooth the grabbed image ...

p

UserVarPtr info

Return values:
M_AVERAGE, M_BILINEAR, M_NEAREST_NEIGHBOR (details)
Open Collapse M_IRIS

Returns the aperture for the mechanical lens iris. Returns the aperture for the mechanical lens iris ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_IRIS. Note that M_DEFAULT is not returned.

Open Collapse M_LAST_GRAB_IN_TRUE_BUFFER

Returns whether a monoshot grab is performed when MdigHalt() is called after performing a continuous grab operation. Returns whether a monoshot grab is performed when MdigHalt() is called after performing a continuous grab operation ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_LUT_ID

Returns the MIL identifier of the LUT associated with the digitizer. Returns the MIL identifier of the LUT associated with the digitizer ...

a c d e f g h i j m n o p q r

UserVarPtr info

Data type: MIL_ID

Return values:
MIL LUT buffer identifier (details)
Open Collapse M_MODEL

Returns the name of the camera model. Returns the name of the camera model.

g
Open Collapse M_MODEL_LENGTH

Returns the length of the string returned by M_MODEL. Returns the length of the string returned by M_MODEL.

g
Open Collapse M_NATIVE_CAMERA_ID

Returns the native identifier of the camera associated with the specified MIL digitizer. Returns the native identifier of the camera associated with the specified MIL digitizer.

c h i m n o
Open Collapse M_NATIVE_CONTROL_ID

Returns the native identifier of the control buffer associated with the specified MIL digitizer. Returns the native identifier of the control buffer associated with the specified MIL digitizer.

c h i m n o
Open Collapse M_NATIVE_ID

Returns the identifier of the Native Library device that corresponds to the given MIL digitizer. Returns the identifier of the Native Library device that corresponds to the given MIL digitizer.

c h i m n o
Open Collapse M_NATIVE_LAST_GRAB_OSB_ID

Returns the identifier of the Native Library operations status block (OSB) used in the last grab. Returns the identifier of the Native Library operations status block (OSB) used in the last grab.

c h i m n o
Open Collapse M_NUMBER

Returns the device number of the digitizer. Returns the device number of the digitizer ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DEFAULT, M_DEVn (details)
Open Collapse M_OPTICAL_FILTER

Returns the optical filter of the camera lens function. Returns the optical filter of the camera lens function ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_OPTICAL_FILTER. Note that M_DEFAULT is not returned.

Open Collapse M_OWNER_SYSTEM

Returns the MIL identifier of the system on which the digitizer has been allocated. Returns the MIL identifier of the system on which the digitizer has been allocated ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: MIL_ID

Return values:
Please see the DigIdPtr parameter of MdigAlloc().

Open Collapse M_PAN

Returns the camera panning capabilities for your camera. Returns the camera panning capabilities for your camera ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_PAN. Note that M_DEFAULT is not returned.

Open Collapse M_PROCESS_FRAME_COUNT

Returns the number of frames grabbed in the sequence with MdigProcess(). Returns the number of frames grabbed in the sequence with MdigProcess().

a b c d e f g h i j k l m n o p q r
Open Collapse M_PROCESS_FRAME_MISSED

Returns the number of frames believed to be missed when grabbing with MdigProcess(). This value is based on a comparison between the frame rate (M_PROCESS_FRAME_RATE) and the frame count (M_PROCESS_FRAME_COUNT). If a grab is triggered from a variable trigger or if the hooked function is slow, this value will be affected. This value is most trustworthy with a camera in continuous mode. Returns the number of frames believed to be missed when grabbing with MdigProcess() ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_PROCESS_FRAME_RATE

Returns the rate at which the frames are grabbed using MdigProcess(). Note that this value is determined based on the average of the camera's frame rate, and the total amount of time to process the user-defined hooked function(s). Returns the rate at which the frames are grabbed using MdigProcess() ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: double
Open Collapse M_ROTARY_ENCODER_DIRECTION

Returns whether the rotary counter is incremented or decremented when the rotary encoder is turning in the forward direction. Returns whether the rotary counter is incremented or decremented when the rotary encoder is turning in the forward direction ...

e r

UserVarPtr info

Return values:
M_BACKWARD, M_DEFAULT, M_FORWARD (details)
Open Collapse M_ROTARY_ENCODER_FRAME_END_POSITION

Returns the value of the rotary counter at the end of the last grab. Returns the value of the rotary counter at the end of the last grab.

e r
Open Collapse M_ROTARY_ENCODER_POSITION

Returns the current value of the rotary counter. Returns the current value of the rotary counter.

e r
Open Collapse M_ROTARY_ENCODER_POSITION_TRIGGER

Returns the value of the rotary counter upon which a trigger is generated. Returns the value of the rotary counter upon which a trigger is generated.

e r
Open Collapse M_SATURATION

Returns the color saturation of the picture. Returns the color saturation of the picture ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_SATURATION. Note that M_DEFAULT is not returned.

Open Collapse M_SATURATION_REF

Returns the digitizer saturation reference level. Note that this inquire type is not supported for monochrome cameras. Returns the digitizer saturation reference level ...

b g k l p

UserVarPtr info

Return values:
M_MAX_LEVEL, M_MIN_LEVEL, M_MIN_LEVEL <= Value <= M_MAX_LEVEL (details)
Open Collapse M_SCAN_MODE

Returns the scan mode. Returns the scan mode ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_INTERLACE | Interlace mode
M_LINESCAN | Line-scan mode
M_PROGRESSIVE | Progressive mode
Open Collapse M_SERIAL_NUMBER_0

Returns the most-significant 32 bits of the serial number of the camera. Returns the most-significant 32 bits of the serial number of the camera ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g
Open Collapse M_SERIAL_NUMBER_1

Returns the least-significant 32 bits of the serial number of the camera. Returns the least-significant 32 bits of the serial number of the camera ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g
Open Collapse M_SHARPNESS

Returns the sharpness of the picture. Returns the sharpness of the picture ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_SHARPNESS. Note that M_DEFAULT is not returned.

Open Collapse M_SHUTTER

Returns the integration time of the incoming light. Returns the integration time of the incoming light ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_SHUTTER. Note that M_DEFAULT is not returned.

Open Collapse M_SIGN

Returns whether the data is signed or unsigned. Returns whether the data is signed or unsigned ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_SIGNED | Data range is signed.
M_UNSIGNED | Data range is unsigned.
Open Collapse M_SIZE_BAND

Returns the number of input color bands of the digitizer. Returns the number of input color bands of the digitizer.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_BAND_LUT

Returns the number of input color bands of the LUT buffer (if any) associated with the digitizer. Returns the number of input color bands of the LUT buffer (if any) associated with the digitizer.

a c d e f g h i j m n o p q r
Open Collapse M_SIZE_BIT

Returns the depth per band, in bits. Returns the depth per band, in bits.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_X

Returns the width of the image, in pixels. Returns the width of the image, in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_Y

Returns the height of the image, in pixels. Returns the height of the image, in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SOURCE_COMPENSATION

Returns whether source compensation for cropping an input signal capture window is enabled or disabled. Returns whether source compensation for cropping an input signal capture window is enabled or disabled ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_SOURCE_OFFSET_X

Returns the X-offset of the input-signal capture window. Returns the X-offset of the input-signal capture window ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see MdigControl() with M_SOURCE_OFFSET_X.

Open Collapse M_SOURCE_OFFSET_Y

Returns the Y-offset of the input-signal capture window. Returns the Y-offset of the input-signal capture window ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see MdigControl() with M_SOURCE_OFFSET_Y.

Open Collapse M_SOURCE_SIZE_X

Returns the width of the input-signal capture window. Returns the width of the input-signal capture window ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see MdigControl() with M_SOURCE_SIZE_X.

Open Collapse M_SOURCE_SIZE_Y

Returns the height of the input-signal capture window. Returns the height of the input-signal capture window ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see MdigControl() with M_SOURCE_SIZE_Y.

Open Collapse M_SYNCHRONIZE_ON_STARTED

Returns the MIL identifier of the second digitizer, or M_NULL if this is not enabled. Returns the MIL identifier of the second digitizer, or M_NULL if this is not enabled ...

c m n o

UserVarPtr info

Data type: MIL_ID

Return values:
M_NULL, MIL digitizer identifier (details)
Open Collapse M_TARGET_TEMPERATURE

Returns the target temperature for the camera. Returns the target temperature for the camera ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_TARGET_TEMPERATURE. Note that M_DEFAULT is not returned.

Open Collapse M_TILT

Returns the camera tilt capabilities. Returns the camera tilt capabilities ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_TILT. Note that M_DEFAULT is not returned.

Open Collapse M_TYPE

Returns the data type and depth of the digitizer's input. Depth is returned in bits. Returns the data type and depth of the digitizer's input ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
depth value + M_SIGNED | Signed data type
depth value + M_UNSIGNED | Unsigned data type
Open Collapse M_VCR_INPUT_TYPE

Returns whether the digitizer input type was set to VCR or not. Returns whether the digitizer input type was set to VCR or not ...

k p

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_VENDOR

Returns the name of the camera vendor. Returns the name of the camera vendor.

g
Open Collapse M_VENDOR_LENGTH

Returns the length of the string returned by M_VENDOR. Returns the length of the string returned by M_VENDOR.

g
Open Collapse M_WHITE_BALANCE

Returns whether white balancing is enabled or disabled. Returns whether white balancing is enabled or disabled ...

e n o

UserVarPtr info

Return values:
M_DISABLE | White balancing is disabled.
M_ENABLE | White balancing is enabled.
Open Collapse M_WHITE_BALANCE_U

Returns the U chrominance (color) component of the data. Returns the U chrominance (color) component of the data ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_WHITE_BALANCE_U. Note that M_DEFAULT is not returned.

Open Collapse M_WHITE_BALANCE_V

Returns the V chrominance (color) component of the data. Returns the V chrominance (color) component of the data ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_WHITE_BALANCE_V. Note that M_DEFAULT is not returned.

Open Collapse M_WHITE_REF

Returns the digitizer white reference level. See below for combination value. Returns the digitizer white reference level ...

a c d g j m p q

UserVarPtr info

Return values:
M_MAX_LEVEL, M_MIN_LEVEL, M_MIN_LEVEL <= Value <= M_MAX_LEVEL, Minimum voltage <= Value <= Maximum voltage (details)
Specifics

Note that this inquire type is only supported when grabbing from the RGB section.

p
Open Collapse M_ZOOM

Returns the camera lens zoom capabilities. Returns the camera lens zoom capabilities ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_ZOOM. Note that M_DEFAULT is not returned.

[Combination constants]
[Matrox Corona-II, Matrox Genesis, Matrox Helios XA, Matrox Meteor-II /1394, Matrox Meteor-II /Multi-Channel, Matrox Odyssey XA, Matrox Orion, and Matrox Solios XA]

The following values can be added to M_BLACK_REF and M_WHITE_REF to inquire about a specific acquisition path used by the digitizer.

Open Collapse Value | Description
Open Collapse M_CH0_REF | Returns the reference level for the first acquisiton path used by the specified digitizer. Returns the reference level for the first acquisiton path used by the specified digitizer.
Open Collapse M_CH1_REF | Returns the reference level for the second acquisiton path used by the specified digitizer. Returns the reference level for the second acquisiton path used by the specified digitizer.
Open Collapse M_CH2_REF | Returns the reference level for the third acquisiton path used by the specified digitizer. Returns the reference level for the third acquisiton path used by the specified digitizer.
Open Collapse M_CH3_REF | Returns the reference level for the fourth acquisiton path used by the specified digitizer. Returns the reference level for the fourth acquisiton path used by the specified digitizer.

[Combination constants]
[Matrox Morphis and Matrox Orion]

The value below can be added to M_CAMERA_LOCK when it is enabled, to inquire about ultra-fast camera locking.

Open Collapse Value | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_FAST | Returns whether ultra-fast camera locking is enabled. Returns whether ultra-fast camera locking is enabled ... |  |  |  |  |  |  |  |  |  |  |  |  | l |  |  |  | p |  |
 |  | Specifics |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  | Note that this is only supported on Matrox Orion /Standard and /Dual for the 4Sight-II. |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |

[Combination constants]
[Matrox Corona-II, Matrox Helios XA, Matrox Odyssey XA, Matrox Orion, and Matrox Solios XA]

One of the following values can be added to M_INPUT_FILTER to inquire about the filter applied to a specific acquisition path used by the digitizer.

Open Collapse Value | Description | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_CH0 | Returns the filter for the first acquisition path used by the specified digitizer. Returns the filter for the first acquisition path used by the specified digitizer. | a |  |  | d |  |  |  |  |  |  |  |  | m |  |  | p | q |
Open Collapse M_CH1 | Returns the filter for the second acquisition path used by the specified digitizer. Returns the filter for the second acquisition path used by the specified digitizer. | a |  |  | d |  |  |  |  |  |  |  |  | m |  |  | p | q |
Open Collapse M_CH2 | Returns the filter for the third acquisition path used by the specified digitizer. Returns the filter for the third acquisition path used by the specified digitizer. | a |  |  | d |  |  |  |  |  |  |  |  | m |  |  | p | q |
Open Collapse M_CH3 | Returns the filter for the fourth acquisition path used by the specified digitizer. Returns the filter for the fourth acquisition path used by the specified digitizer. |  |  |  | d |  |  |  |  |  |  |  |  | m |  |  |  | q |

[Combination constants]
[Matrox Helios XA, Matrox Morphis, Matrox Odyssey XA, and Matrox Solios XA]

One of the following values can be added to M_GRAB_INPUT_GAIN or M_GRAB_AUTOMATIC_INPUT_GAIN to inquire about the input gain setting applied to a specific acquisition path or component of the input signal used by the digitizer.

Open Collapse Value | Description | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_CHn | Specifies the acquisition path for which to inquire the input gain, where n is the number of the acquisiton path used by the specified digitizer (for example, 0 is the first acqusition path used by the specified digitizer. 1 is the second, and so on). Specifies the acquisition path for which to inquire the input gain, where n is the number of the acquisiton path used by the specified digitizer (for example, 0 is the first acqusition path used by the specified digitizer ... M_CHn can only be added to M_GRAB_INPUT_GAIN. |  |  | c | d |  |  |  |  |  |  |  |  | m |  |  |  | q |
Open Collapse M_CHROMINANCE | Returns the input-gain setting applied to the chrominance component of the input signal. Returns the input-gain setting applied to the chrominance component of the input signal. |  |  |  |  |  |  |  |  |  |  |  | l |  |  |  |  |  |
Open Collapse M_LUMINANCE | Returns the input-gain setting applied to the luminance component of the input signal. Returns the input-gain setting applied to the luminance component of the input signal. |  |  |  |  |  |  |  |  |  |  |  | l |  |  |  |  |  |

[Combination constants]
[Matrox Meteor-II /Camera Link]

One of the following can be added to M_USER_OUT_FORMAT to inquire about the status of the LVDS drivers on the Camera Link connectors.

Open Collapse Value | Description
Open Collapse M_CH0 | Returns the format that should be applied to the first acquisition path used by the specified digitizer. Returns the format that should be applied to the first acquisition path used by the specified digitizer.
Open Collapse M_CH1 | Returns the format that should be applied to the second acquisition path used by the specified digitizer. Returns the format that should be applied to the second acquisition path used by the specified digitizer.

[Combination constants]
[Matrox Helios XA, Matrox Odyssey XA, and Matrox Solios XA]

The following value can added to M_BLACK_REF and M_WHITE_REF to inquire the reference in Volts.

Open Collapse Value | Description
Open Collapse M_VOLTAGE | Specifies the reference level in Volts. Specifies the reference level in Volts ...
 |  | UserVarPtr info Data type: double

[Combination constants]
[Matrox Meteor-II /1394]

One of the following values can be added to any of 1394, DCAM-specific InquireType settings.

Open Collapse Value | Description
Open Collapse M_MAX_VALUE | Returns the largest value supported. Returns the largest value supported.
Open Collapse M_MIN_VALUE | Returns the smallest value supported. Returns the smallest value supported.

[All except Matrox CronosPlus, Matrox Iris, Matrox Meteor-II /1394, and Matrox Morphis]

The following inquire types specify the settings that can be inquired for user-defined signals. The user bits are the bits on user-defined input, output, and/or I/O (bidirectional) signals. Refer to the board-specific notes for the correspondence between user-defined signal numbers and the user-defined signal names.

Note that for other Matrox imaging boards that have user-defined signals, but are not supported with the constants below, see MsysControl().

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_USER_BIT_COUNT

Returns the total number of user-defined signals. Returns the total number of user-defined signals ...

This count includes the number of input, output, and I/O user-defined signals.

a c d e h i j k m n o p q r

UserVarPtr info

Return values:
Value Total number of user-defined signals.

Open Collapse M_USER_BIT_COUNT_IN

Returns the number of user-defined signals that can be used for input. Returns the number of user-defined signals that can be used for input ...

This count includes the number of input and I/O user-defined signals.

c d e h i m n o q r

UserVarPtr info

Return values:
Value Number of user-defined signals that can be used for input.

Open Collapse M_USER_BIT_COUNT_OUT

Returns the number of user-defined signals that can be used for output. Returns the number of user-defined signals that can be used for output ...

This count includes the number of output and I/O user-defined signals.

c d e h i m n o q r

UserVarPtr info

Return values:
Value Number of user-defined signals that can be used for output.

Open Collapse M_USER_BIT_FORMAT

Returns the type of receivers enabled for the specified user-defined input signal, on systems whose receivers are enabled through software and where the option of both TTL and/or LVDS are possible. Returns the type of receivers enabled for the specified user-defined input signal, on systems whose receivers are enabled through software and where the option of both TTL and/or LVDS are possible ...

Refer to M_USER_IN_FORMAT and M_USER_OUT_FORMAT to change formats on other Matrox Imaging boards.

You must specify the user-defined signal to inquire. See combination values below.

d e m n o q r

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE, M_LVDS, M_TTL (details)
Open Collapse M_USER_BIT_INTERRUPT_MODE

Returns the type of functional-state change upon which to generate an interrupt. Note that this only applies to user-defined input signals. Returns the type of functional-state change upon which to generate an interrupt ...

You must specify the user-defined signal to inquire. See below for combination values.

d e m n o q r

UserVarPtr info

Return values:
M_DEFAULT, M_EDGE_RISING (details)
Open Collapse M_USER_BIT_INTERRUPT_STATE

Returns whether to generate an interrupt when the functional state for the user-defined signal changes. Note that this only applies to user-defined input signals. Returns whether to generate an interrupt when the functional state for the user-defined signal changes ...

You must specify the user-defined signal to inquire. See below for combination values.

d e m n o q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_USER_BIT_MODE

Returns the current mode of the specified I/O user-defined signal(s). Returns the current mode of the specified I/O user-defined signal(s) ...

You must specify the user-defined signal to inquire. See combination values below.

d e m n o q r

UserVarPtr info

Return values:
Bit-encoded value, M_INPUT, M_OUTPUT (details)
Open Collapse M_USER_BIT_VALUE

Returns the current state of the specified user-defined signal(s). Returns the current state of the specified user-defined signal(s) ...

You must specify the user-defined signal to inquire. See combination values below.

Note that if there is no device connected to the pin associated with the specified user-defined signal, indeterminate results will result when that user-defined signal is inquired.

a c d e h i j k m n o p q r

UserVarPtr info

Return values:
Bit-encoded-value, M_OFF, M_ON (details)
Open Collapse M_USER_IN_FORMAT

Returns the type of the receivers for triggers and user-defined input signals, on systems whose receivers are enabled through software and where the option of both TTL and RS-422/LVDS are possible. Returns the type of the receivers for triggers and user-defined input signals, on systems whose receivers are enabled through software and where the option of both TTL and RS-422/LVDS are possible ...

Refer to M_USER_BIT_FORMAT and M_GRAB_TRIGGER_FORMAT to inquire formats on other Matrox Imaging boards.

c h i

UserVarPtr info

Return values:
M_DISABLE, M_LVDS, M_RS422, M_TTL (details)
Open Collapse M_USER_OUT_FORMAT

Returns the type of the exposure or user-defined output signal(s), on systems whose I/O drivers are enabled through software and where the option of both TTL and RS-422/LVDS are possible. Returns the type of the exposure or user-defined output signal(s), on systems whose I/O drivers are enabled through software and where the option of both TTL and RS-422/LVDS are possible ...

Refer to M_USER_BIT_FORMAT and M_GRAB_EXPOSURE_FORMAT to inquire formats on other Matrox Imaging boards.

c h i

UserVarPtr info

Return values:
M_DISABLE, M_LVDS, M_RS422, M_TTL (details)

[Combination constants]
[All except Matrox CronosPlus, Matrox Iris, Matrox Meteor-II /1394, and Matrox Morphis]

One of the following values can be added to M_USER_BIT_FORMAT, M_USER_BIT_MODE, M_USER_BIT_VALUE, M_USER_BIT_INTERRUPT_MODE or M_USER_BIT_INTERRUPT_STATE. Refer to the board-specific notes for the correspondence between user-defined signal numbers and the user-defined signal names.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_BIT_MASK(
long Bit_encoded_value
)

Specifies a bit-encoded mask value that identifies the group of user-defined signals about which to inquire. Enabled bits in the mask value identify the user-defined signals about which to inquire. See the example below for details. Specifies a bit-encoded mask value that identifies the group of user-defined signals about which to inquire ...

Note that in this case, the inquire value can only be set to a bit-encoded value and it can only be added to M_USER_BIT_MODE and M_USER_BIT_VALUE.

d e m n o q r

Parameters
Bit_encoded_value

The bit-encoded mask value.

Open Collapse 0 <= Value

Specifies the number of a specific user-defined signal to inquire. Specifies the number of a specific user-defined signal to inquire ...

Note that in this case, the returned value is not a bit-encoded value.

a c d e h i j k m n o p q r
Open Collapse M_CCn

Specifies the number of a specific camera control user-defined signal to be inquired, n can be from 1 to 4. Specifies the number of a specific camera control user-defined signal to be inquired, n can be from 1 to 4 ...

Note that in this case, the returned value is not a bit-encoded value and it can only be added to M_USER_BIT_VALUE.

e n r

[Matrox Corona-II, Matrox Meteor-II /Camera Link, Matrox Meteor-II /Digital, Matrox Meteor-II /Multi-Channel, Matrox Meteor-II /Standard, Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The following inquire types specify the settings that can be inquired for UARTS.

Note that for other Matrox imaging boards that have user-defined signals, but are not supported with the constants below, see MsysControl().

[Matrox Meteor-II /Camera Link]

To specify which UART to inquire, see combination values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_UART_DATA_LENGTH

Returns the number of data bits per character that are sent or received by the UART. Returns the number of data bits per character that are sent or received by the UART ...

UserVarPtr info

Return values:
7, 8 (details)
Open Collapse M_UART_DATA_PENDING

Returns whether the UART input buffer has pending data or not. Returns whether the UART input buffer has pending data or not ...

UserVarPtr info

Return values:
M_FALSE | The UART input buffer does not have pending data.
M_TRUE | The UART input buffer has pending data.
Open Collapse M_UART_PARITY

Returns the UART parity setting. Returns the UART parity setting ...

UserVarPtr info

Return values:
M_DISABLE, M_EVEN, M_ODD (details)
Open Collapse M_UART_READ_STRING_LENGTH

Returns the number of bytes to be read when using MdigControl() with M_UART_READ_STRING. If this length is specified by M_UART_STRING_DELIMITER, the returned result will be M_DEFAULT. Returns the number of bytes to be read when using MdigControl() with M_UART_READ_STRING ...

UserVarPtr info

Return values:
M_DEFAULT | Returns that the length is limited by M_UART_STRING_DELIMITER.
Value | Returns the length of the string, in bytes.
Open Collapse M_UART_READ_STRING_MAXIMUM_LENGTH

Returns the maximum length of the string to be read using M_UART_READ_STRING. Returns the maximum length of the string to be read using M_UART_READ_STRING ...

UserVarPtr info

Return values:
Please see MdigControl() with M_UART_READ_STRING_MAXIMUM_LENGTH.
M_DEFAULT | Returns the maximum length of the string, in bytes.
Value | Returns the maximum length of the string, in bytes.
Open Collapse M_UART_SPEED

Returns the baud rate of the UART. Returns the baud rate of the UART ...

UserVarPtr info

Return values:
600; 1200; 1800; 2400; 3600; 4800; 7200; 9600; 14400; 19200; 28800; 38400; 57600; 76800; 115200; 230400 (details)
Open Collapse M_UART_STOP_BITS

Returns the number of extra data bit(s) that are added to each character to indicate the end of a character. Returns the number of extra data bit(s) that are added to each character to indicate the end of a character ...

UserVarPtr info

Return values:
1, 2 (details)
Open Collapse M_UART_STRING_DELIMITER

Returns the character used to terminate strings of incoming or outgoing data. The delimiter is used but not sent when writing data with M_UART_WRITE_STRING; it is read for incoming data with M_UART_READ_STRING. Returns the character used to terminate strings of incoming or outgoing data ...

UserVarPtr info

Return values:
Please see MdigControl() with M_UART_STRING_DELIMITER.

Open Collapse M_UART_TIMEOUT

Returns the maximum time (in msec) to wait between each byte when reading incoming data. Returns the maximum time (in msec) to wait between each byte when reading incoming data ...

UserVarPtr info

Return values:
M_INFINITE, Value (details)
Open Collapse M_UART_WRITE_STRING_LENGTH

Returns the length of the string to be sent to the UART for transmission. Returns the length of the string to be sent to the UART for transmission ...

UserVarPtr info

Return values:
Please see MdigControl() with M_UART_WRITE_STRING_LENGTH.

[Combination constants]
[Matrox Meteor-II /Camera Link]

The value below can be added to M_UART... to specify which UART to inquire. In this case channel refers to the number assigned to each virtual UART available to be programmed on Matrox Meteor-II /Camera-Link. Only one virtual UART can be in use at any one time. This setting allows for two UART configurations to be stored and called for use, one at a time, as needed.

Open Collapse Value | Description
Open Collapse M_CH0 | Specifies that the first UART should be inquired. Specifies that the first UART should be inquired.
Open Collapse M_CH1 | Specifies that the second UART should be inquired. Specifies that the second UART should be inquired.

The following inquire types specify the settings for inquiring triggers. For more information, see the Grabbing with triggers and exposures section in Chapter 18: Grabbing with your digitizer.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_GRAB_TRIGGER | Returns the grab trigger detection state. Returns the grab trigger detection state ... |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_GRAB_TRIGGER_FORMAT | Returns the type of receivers enabled for the specified trigger signals, on systems whose I/O drivers are enabled through software and where the option of TTL, LVDS and/or OPTO are possible. Returns the type of receivers enabled for the specified trigger signals, on systems whose I/O drivers are enabled through software and where the option of TTL, LVDS and/or OPTO are possible ... |  |  |  |  | d | e |  |  |  |  |  |  |  | m | n | o |  | q | r
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE, M_LVDS, M_OPTO, M_TTL (details)
Open Collapse M_GRAB_TRIGGER_MODE | Returns the hardware trigger activation mode. Returns the hardware trigger activation mode ... |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
 |  | UserVarPtr info Return values: M_EDGE_FALLING, M_EDGE_RISING, M_LEVEL_HIGH, M_LEVEL_LOW (details)
Open Collapse M_GRAB_TRIGGER_SOURCE | Returns the source for the trigger signal. Returns the source for the trigger signal ... |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
 |  | UserVarPtr info Return values: M_HARDWARE_PORT0, M_HARDWARE_PORT1, M_HARDWARE_PORT2, M_HARDWARE_PORT3, M_HARDWARE_PORT4, M_HARDWARE_PORT5, M_HARDWARE_PORT6, M_HARDWARE_PORT7, M_HARDWARE_PORT8, M_HARDWARE_PORT9, M_HARDWARE_PORT10, M_HARDWARE_PORT11, M_HARDWARE_PORT_CAMERA, M_NULL, M_ROTARY_ENCODER, M_SOFTWARE, M_TIMER1, M_TIMER2 (details)
[Combination constants]
[Matrox Helios XA, Matrox Helios XCL, Matrox Iris, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

The value below can be added to M_GRAB_TRIGGER_FORMAT to specify which hardware port to inquire.

Open Collapse Value | Description
Open Collapse M_HARDWARE_PORTn | Specifies the hardware port to inquire, where n is a number between 0 and 11. Specifies the hardware port to inquire, where n is a number between 0 and 11.

[All except Matrox CronosPlus, Matrox Iris, Matrox Meteor-II /Standard, Matrox Morphis, and Matrox Orion]

The following inquire types specify the settings for inquiring exposure signals. For more information, see the Grabbing with triggers and exposures section in Chapter 18: Grabbing with your digitizer.

To specify which exposure timer to inquire, see combination values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_AUTO_EXPOSURE

Returns whether the exposure should be set manually to the specified value or if the camera controls the exposure level automatically and continuously. Returns whether the exposure should be set manually to the specified value or if the camera controls the exposure level automatically and continuously ...

Note that this is DCAM-specific. For more information, refer to your camera's hardware manual and the Setting 1394 DCS-compliant camera features section in Chapter 6: Matrox Meteor-II. See below for combination values.

g

UserVarPtr info

Return values:
Please see MdigControl() with M_AUTO_EXPOSURE. Note that M_DEFAULT is not returned.

Open Collapse M_GRAB_EXPOSURE

Returns the state for a hardware trigger source. Returns the state for a hardware trigger source ...

a c d e f h i j m n o q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_GRAB_EXPOSURE_CLOCK_FREQUENCY

Returns the frequency (in hertz) of the clock driving the exposure counter. Returns the frequency (in hertz) of the clock driving the exposure counter ...

a d e m n o q r

UserVarPtr info

Data type: double

Return values:
Value | The frequency (in hertz) of the exposure counter clock.
0 | Unable to inquire the value.
Open Collapse M_GRAB_EXPOSURE_CLOCK_SOURCE

Returns the clock source that drives the exposure clock counter. Returns the clock source that drives the exposure clock counter ...

a d e j m n o q r

UserVarPtr info

Return values:
M_HSYNC, M_PIXCLK, M_SYSCLK, M_TIMER1, M_TIMER2, M_VSYNC (details)
Open Collapse M_GRAB_EXPOSURE_FORMAT

Returns the type of receivers enabled for the specified exposure signals, on systems whose I/O drivers are enabled through software and where the option of TTL and/or LVDS are possible. Returns the type of receivers enabled for the specified exposure signals, on systems whose I/O drivers are enabled through software and where the option of TTL and/or LVDS are possible ...

d e m n o q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE, M_LVDS, M_TTL (details)
Open Collapse M_GRAB_EXPOSURE_MODE

Returns the polarity of the active portion of the exposure signal. Returns the polarity of the active portion of the exposure signal ...

a c d e h i j m n o q r

UserVarPtr info

Return values:
M_LEVEL_HIGH, M_LEVEL_LOW (details)
Open Collapse M_GRAB_EXPOSURE_SOURCE

Returns the trigger source for the exposure signal. Returns the trigger source for the exposure signal ...

a c d e h i j m n o q r

UserVarPtr info

Return values:
M_CONTINUOUS, M_HARDWARE_PORT0, M_HARDWARE_PORT1, M_HARDWARE_PORT2, M_HARDWARE_PORT3, M_HARDWARE_PORT4, M_HARDWARE_PORT5, M_HARDWARE_PORT6, M_HARDWARE_PORT7, M_HARDWARE_PORT8, M_HARDWARE_PORT9, M_HARDWARE_PORT10, M_HARDWARE_PORT11, M_HSYNC, M_NULL, M_ROTARY_ENCODER, M_SOFTWARE, M_TIMER1, M_TIMER2, M_VSYNC (details)
Open Collapse M_GRAB_EXPOSURE_TIME

Returns the time (in nsec) for the active portion of the exposure signal (that is, the exposure time). Returns the time (in nsec) for the active portion of the exposure signal (that is, the exposure time) ...

a c d e f h i j m n o q r

UserVarPtr info

Data type: double

Return values:
Please see MdigControl() with M_GRAB_EXPOSURE_TIME.

Open Collapse M_GRAB_EXPOSURE_TIME_DELAY

Returns the delay (in nsec) between the trigger and the start of exposure. Returns the delay (in nsec) between the trigger and the start of exposure ...

a c d e f h i j m n o q r

UserVarPtr info

Data type: double

Return values:
Please see MdigControl() with M_GRAB_EXPOSURE_TIME_DELAY.

Open Collapse M_GRAB_EXPOSURE_TRIGGER_MODE

Returns the trigger activation mode for specified timer. Returns the trigger activation mode for specified timer ...

a c d e h i j m n o q r

UserVarPtr info

Return values:
M_EDGE_FALLING, M_EDGE_RISING (details)

[Combination constants]
[All except Matrox CronosPlus, Matrox Meteor-II /1394, Matrox Meteor-II /Standard, Matrox Morphis, and Matrox Orion]

One of the following values can be added to the M_GRAB_EXPOSURE... and M_GRAB_EXPOSURE_FORMAT inquire types.

Open Collapse Value | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_TIMER1 | Specifies to inquire the first on-board exposure timer. Specifies to inquire the first on-board exposure timer ... This is the default value. |  | a |  | c | d | e | f |  | h | i | j |  |  | m | n | o |  | q | r
 |  | Specifics |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  | The DCF establishes on which signals the exposure timer routes its exposure signal. |  |  |  | d | e |  |  |  |  |  |  |  | m | n | o |  | q | r
 |  | The first on-board exposure timer is dedicated to the CCD. |  |  |  |  |  | f |  |  |  |  |  |  |  |  |  |  |  |
Open Collapse M_TIMER2 | Specifies to inquire the second on-board exposure timer. Specifies to inquire the second on-board exposure timer ... |  | a |  | c | d | e | f |  | h | i | j |  |  | m | n | o |  | q | r
 |  | Specifics |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  | The DCF establishes on which signals the exposure timer routes its exposure signal. |  |  |  | d | e |  |  |  |  |  |  |  | m | n | o |  | q | r
 |  | The second on-board exposure timer is dedicated to the control of the IND_USER/STB_OUT0 (strobe) signal, available on the external auxiliary I/O connector 0 (HD-44). |  |  |  |  |  | f |  |  |  |  |  |  |  |  |  |  |  |

UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type MIL_TEXT_CHAR
  • double
  • long
  • MIL_ID

Specifies the address in which to write the requested information. Since the MdigInquire() function also returns the requested information, you can set this parameter to M_NULL.

Return value
The returned value is the requested information, usually cast to a long. For inquire types cast to MIL_TEXT_CHAR, the returned value is M_NULL.
Examples
[Matrox Helios XA, Matrox Helios XCL, Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

The following example uses M_USER_BIT_MODE + M_BIT_MASK(Bit_encoded_value). The returned value is also a bit-encoded value identifying the mode of the specified user-defined signals as being either input (0) or output (1). For example, to inquire the mode of user-defined signal 6, 7, and 8, use:

MdigInquire(MilDigitizer, M_USER_BIT_MODE+M_BIT_MASK(0x1C0), &UserBits);

If 6 and 7 are set to input and 8 is set to output, the return value will be 0x100.

The following example uses M_USER_BIT_VALUE + M_BIT_MASK(Bit_encoded_value). The returned value is also a bit-encoded value defining the state of the specified user-defined signals as being on (1) or off (0). For example, to inquire the value of user-defined signals 9, 10, 11, and 12, use:

MdigInquire(MilDigitizer, M_USER_BIT_VALUE+M_BIT_MASK(0x1E00), &UserBits);

If 9 and 10 are set to 1 and 11 and 12 are set to 0, the return value will be 0x0600.

CAMERA LOCK CAMERA LOCKED CAMERA LOCK CAMERA LOCK FORMAT SIZE PROCESS FRAME RATE PROCESS FRAME COUNT BLACK REF WHITE REF CAMERA LOCK INPUT FILTER GRAB INPUT GAIN GRAB AUTOMATIC INPUT GAIN USER OUT FORMAT BLACK REF WHITE REF USER IN FORMAT USER OUT FORMAT USER BIT FORMAT GRAB TRIGGER FORMAT USER BIT FORMAT GRAB EXPOSURE FORMAT USER BIT FORMAT USER BIT MODE USER BIT VALUE USER BIT INTERRUPT MODE USER BIT INTERRUPT STATE USER BIT MODE USER BIT VALUE USER BIT VALUE UART READ STRING UART STRING DELIMITER DEFAULT UART STRING DELIMITER UART READ STRING UART WRITE STRING UART READ STRING GRAB TRIGGER FORMAT GRAB EXPOSURE FORMAT USER BIT MODE USER BIT VALUE BAYER COEFFICIENTS ID BAYER CONVERSION BLACK REF BRIGHTNESS BRIGHTNESS REF CAMERA COLOR LOCK CAMERA LOCK CAMERA LOCK SENSITIVITY CAMERA LOCKED CAMERA PRESENT CAMERA UNLOCK SENSITIVITY CAMERALINK CCn SOURCE CAPTURE QUALITY CAPTURE SIZE CHANNEL CHANNEL M SIGNAL CHANNEL M SYNC CHANNEL NUM COLOR MODE CONTRAST REF COUPLING MODE FIELD START EVEN HANDLER PTR FIELD START EVEN HANDLER USER PTR FIELD START HANDLER PTR FIELD START HANDLER USER PTR FIELD START ODD HANDLER PTR FIELD START ODD HANDLER USER PTR FOCUS FORMAT FORMAT SUPPORTED FORMAT SUPPORTED LENGTH FORMAT SUPPORTED NUM FORMAT SIZE FRAME START HANDLER PTR FRAME START HANDLER USER PTR GAIN GAMMA GRAB AUTOMATIC INPUT GAIN GRAB DIRECTION X GRAB DIRECTION Y GRAB END HANDLER PTR GRAB END HANDLER USER PTR GRAB FAIL CHECK GRAB FAIL RETRY NUMBER GRAB FAIL STATUS GRAB FIELD END EVEN HANDLER PTR GRAB FIELD END EVEN HANDLER USER PTR GRAB FIELD END HANDLER PTR GRAB FIELD END HANDLER USER PTR GRAB FIELD END ODD HANDLER PTR GRAB FIELD END ODD HANDLER USER PTR GRAB FIELD NUM GRAB IN PROGRESS GRAB INPUT GAIN GRAB MODE GRAB PERIOD GRAB SAMPLING POSITION GRAB SCALE QUALITY GRAB SCALE X GRAB SCALE Y GRAB START HANDLER PTR GRAB START HANDLER USER PTR GRAB START MODE GRAB TIMEOUT GRAB WAIT GRAB WINDOW RANGE HOOK MASTER THREAD HANDLE HOOK MASTER THREAD ID HUE HUE REF INIT FLAG INPUT FILTER INPUT MODE INTERPOLATION MODE IRIS LAST GRAB IN TRUE BUFFER GRAB CONTINUOUS END TRIGGER LUT ID MODEL MODEL LENGTH NATIVE CAMERA ID NATIVE CONTROL ID NATIVE ID NATIVE LAST GRAB OSB ID NUMBER OPTICAL FILTER OWNER SYSTEM PAN PROCESS FRAME COUNT PROCESS FRAME MISSED PROCESS FRAME RATE ROTARY ENCODER POSITION ROTARY ENCODER POSITION TRIGGER ROTARY ENCODER DIRECTION ROTARY ENCODER FRAME END POSITION SATURATION SATURATION REF SCAN MODE SERIAL NUMBER 0 SERIAL NUMBER 1 SHARPNESS SHUTTER SIGN SIZE BAND SIZE BAND LUT SIZE BIT SIZE X SIZE Y SOURCE COMPENSATION SOURCE OFFSET X SOURCE OFFSET Y SOURCE SIZE X SOURCE SIZE Y SYNCHRONIZE ON STARTED TARGET TEMPERATURE TILT TYPE VCR INPUT TYPE VENDOR VENDOR LENGTH WHITE BALANCE WHITE BALANCE U WHITE BALANCE V WHITE REF ZOOM CH0 REF CH1 REF CH2 REF CH3 REF FAST CH0 CH1 CH2 CH3 CHn LUMINANCE CHROMINANCE CH0 CH1 VOLTAGE MAX VALUE MIN VALUE USER BIT COUNT USER BIT COUNT IN USER BIT COUNT OUT USER BIT FORMAT USER BIT INTERRUPT MODE USER BIT INTERRUPT STATE USER BIT MODE USER BIT VALUE USER IN FORMAT USER OUT FORMAT CCn UART DATA LENGTH UART DATA PENDING UART PARITY UART READ STRING LENGTH UART READ STRING MAXIMUM LENGTH UART SPEED UART STOP BITS UART STRING DELIMITER UART TIMEOUT UART WRITE STRING LENGTH CH0 CH1 GRAB TRIGGER GRAB TRIGGER FORMAT GRAB TRIGGER MODE GRAB TRIGGER SOURCE HARDWARE PORTn AUTO EXPOSURE GRAB EXPOSURE GRAB EXPOSURE CLOCK FREQUENCY GRAB EXPOSURE CLOCK SOURCE GRAB EXPOSURE FORMAT GRAB EXPOSURE MODE GRAB EXPOSURE SOURCE GRAB EXPOSURE TIME GRAB EXPOSURE TIME DELAY GRAB EXPOSURE TRIGGER MODE TIMER1 TIMER2


MdigLut

Example | Availability | MdigInquire | MdigProcess
There are no examples containing MdigLut().
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Orion
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris

Not supported on:
Not supported on Matrox Meteor-II /1394
Not supported on Matrox Meteor-II /Standard
Not supported on Matrox CronosPlus
Not supported on Matrox Morphis
Synopsis
Copy a LUT buffer to a digitizer's physical LUT.
Syntax
void MdigLut(
MIL_ID DigId,
MIL_ID LutBufId
)
Description

This function copies a LUT buffer to the specified digitizer's physical LUT. MIL uses the data format (DCF) of the digitizer to determine whether a physical LUT is supported. If it is not, an error is generated.

To create a LUT buffer, use MbufAlloc...() with an M_LUT attribute.

The following table indicates how the digitizer's physical LUT is configured.

Configuration of the digitizer's LUT | Determining factor
Number of entries in the digitizer's physical LUT | Data being grabbed (DCF)
Depth (8- or 16-bit) | LUT buffer
Number of bands | DCF & LUT buffer

The digitizer's physical LUT is typically configured to have the same number of components (bands) as either the LUT buffer or the data to be grabbed (determined by the digitizer's DCF), depending on which has more bands. The digitizer's physical LUT is also configured to have the same number of entries as the maximum possible value per band of the data to grab. The depth of a digitizer's physical LUT is configured to be either 8- or 16-bits per band, depending on if the LUT buffer depth is 8-bit or 16-bit, respectively. Cameras, however, are not so limited. When dealing with a 10- or 12-bit camera, use a 16-bit destination grab buffer and load the digitizer's physical LUT with the difference zero padded. Note that if the digitizer's physical LUT cannot support the depth of the LUT buffer, an error will occur.

If the destination grab buffer depth is larger than that of the digitizer's physical LUT, the destination grab buffer's least significant bits are set to zero when the data is grabbed. If the digitizer's physical LUT depth is greater than that of the destination grab buffer, the most-significant bits of the data (the non-zero values) are used when the data is grabbed.

To copy the data from a LUT buffer to the digitizer's physical LUT, the number of entries in the LUT buffer must match those of the digitizer's physical LUT.

LUT buffer data is loaded into the digitizer's physical LUT, as follows:

LUT buffer | Digitizer's physical LUT | Result
1 band | 1 band | The LUT buffer is copied directly into the digitizer's physical LUT.
1 band | 3 band | The LUT buffer is copied into each component of the digitizer's physical LUT.
3 band | 1 band | The first band of the LUT buffer is copied into the digitizer's physical LUT.
3 band | 3 band | Each of the LUT buffer's bands are copied into the corresponding component of the digitizer's physical LUT.
[Matrox Genesis]

Note that if 32-bit data is grabbed, the digitizer's physical LUT is not used.

[All except Matrox CronosPlus, Matrox Genesis, Matrox Iris, Matrox Meteor-II /1394, Matrox Meteor-II /Standard, and Matrox Morphis]

Note that if 14-, 16-, or 32-bit data is grabbed, the digitizer's physical LUT is not used.

[Matrox Orion]

Regardless of the depth at which data is grabbed, YUV data bypasses the digitizer's physical LUT.

The digitizer's physical LUT is not available on Matrox Orion /Standard or /Dual for 4Sight-II.

[Matrox Corona-II]

If 12-, 14-, or 16-bit digital data is grabbed, the digitizer's physical LUT is not available.

Regardless of the depth at which data is grabbed, YUV data bypasses the digitizer's physical LUT.

Parameters
DigId

Specifies the identifier of the digitizer.

LutBufId

Specifies the LUT buffer identifier. This parameter should be set to one of the following values:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_DEFAULT

 Specifies that the digitizer's physical LUT is not used.  Specifies that the digitizer's physical LUT is not used ...

a

c
d
e
f

h
i
j

m
n
o
p
q
r

  Open   Collapse  MIL LUT buffer identifier

 Specifies a LUT buffer.  Specifies a LUT buffer ...

a

c
d
e
f

h
i
j

m
n
o
p
q
r

Specifics

 When grabbing 8-bit data, the digitizer's physical LUT has 256 entries.

a

c

e
f

h
i
j

n
o
p

r

 When grabbing 10-bit data, the digitizer's physical LUT has 1024 entries.

a

 When grabbing 10-, 12-, or 13-bit data, the digitizer's physical LUT has 8192 entries.

c

 When grabbing 10-bit data, the digitizer's physical LUT has 1024 entries.

 When grabbing 12-bit data, the digitizer's physical LUT has 4096 entries.

d
e

h

m
n
o

q
r

LUT   DEFAULT


MdigProcess

See Also | Example | Availability | MdigLut | MdigReference
User Guide:
Cameras and video sources
Multiple cameras
Grabbing to the display
Optimizing application performance when grabbing
Grabbing a sequence of frames in real-time

Reference:
MbufFree
MdigGetHookInfo
MsysControl
mdigdoublebuffering.c
mdiggrabsequence.c
mdigprocess.c
mdigprocessmultiple.c
Available in MIL-Lite

Available in MIL
Synopsis
Grabs a sequence of images and processes them with a user-defined function as they are grabbed.
Syntax
void MdigProcess(
MIL_ID DigId,
MIL_ID *DestImageArrayPtr,
long ImageCount,
long Operation,
long OperationFlag,
MDIGHOOKFCTPTR HookHandlerPtr,
void *UserDataPtr
)
Description

This function uses the specified digitizer to acquire images and store them sequentially in a list of buffers. It also hooks a user-defined function to the modification of any buffer in the specified list. So every time a new frame is grabbed in a buffer in the list, the user-defined function is called.

If set synchronously, MdigProcess() will block the thread until the list of sequential grabs has completed. If set asynchronously, the buffers are prepared, and then control is returned to the calling thread while, in the background, the grabs will begin.

The grabs can stop either at the end of the list of buffers or after a predefined number of grabs occur. Note that this can cause round-robin grabbing if the predefined number is greater than the number of buffers available. If there is no preset end to the list of grabs (using MdigProcess() with M_START), MdigProcess() grabs round-robin through the list of buffers; you must use MdigProcess() with M_STOP to issue a stop command, otherwise an endless loop is created.

When grabbing round-robin, if the average time it takes to process a frame is greater than the frame rate of a camera, frames will eventually be missed.

The buffers are filled with the grabbed data in the order in which they are stored in the list. The index of the buffer modified can be inquired using MdigGetHookInfo() with M_MODIFIED_BUFFER + M_BUFFER_INDEX. The MIL identifier of the buffer modified can be inquired using MdigGetHookInfo() with M_MODIFIED_BUFFER + M_BUFFER_ID.

Note that, if running on a computer with multiple CPUs, use MsysControl() with M_MODIFIED_BUFFER_HOOK_MODE set to M_MULTI_THREAD to run from multiple instances of the user-defined function, launched by modifications to different buffers on separate threads, up to the number of CPUs present in the computer.

It is not recommended to change the digitizer settings of the digitizer currently being used when grabs are still pending.

Parameters
DigId

Specifies the identifier of the digitizer to be used to perform the grabs.

DestImageArrayPtr

Specifies the address of the array containing the identifiers of the buffers in which to place the grabbed images. The buffers should be of an appropriate type and depth to hold the grabbed images. To allocate each buffer, use MbufAlloc...() with M_GRAB. When a buffer is no longer required, release it, using MbufFree().

ImageCount

Specifies the number of buffers in the array of destination image buffers.

Operation

Specifies the type of operation to perform.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_SEQUENCE

 Grabs in a list of buffers. By default, the sequence will stop once the end of the list of destination buffers is reached. See combination values below to specify the grab count.  Grabs in a list of buffers ...

  Open   Collapse  M_START

 Starts grabbing round-robin into the list of buffers. The grabs will continue until stopped (using MdigProcess() with M_STOP).  Starts grabbing round-robin into the list of buffers ...

  Open   Collapse  M_STOP

 Stops the grab. By default, it also cancels all grabs that might have been queued. Note that cancelled grabs will not trigger the hooked function, but the events for the previous grabs are still processed. See combination values below to change this default behavior.  Stops the grab ...

 To stop a grab started in synchronous mode, the Operation parameter must be set to M_STOP and the MdigProcess() function, called from a separate thread.

      [Combination constants]

 The following value can be added to M_STOP.

  Open   Collapse  Value
Description

  Open   Collapse  M_WAIT

 Stops queuing new grabs and waits for all previously queued grabs to finish before returning control to the Host.  Stops queuing new grabs and waits for all previously queued grabs to finish before returning control to the Host.

      [Combination constants]

 The following value can be added to M_SEQUENCE.

  Open   Collapse  Value
Description

  Open   Collapse  M_COUNT(n)

 Stops grabbing when the grab count (n) is reached. If the grab count is greater than the buffer count, the grab will be done in round-robin style. By default, the grab count is equal to the number of buffers in the destination image array. n can be a maximum of 2 to the power of 28.  Stops grabbing when the grab count (n) is reached ...

 OperationFlag

 Controls the order in which processing occurs.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default execution mode.  Specifies the default execution mode ...

 If the Operation parameter is set to M_START, the default is the same as M_ASYNCHRONOUS.

 If the Operation parameter is set to M_SEQUENCE, the default is the same as M_SYNCHRONOUS.

 If the Operation parameter is set to M_STOP, the default is the same as M_SYNCHRONOUS unless MdigProcess() is called from the user-defined function, in which case the default is the same as M_ASYNCHRONOUS. Note that when the Operation parameter is set to M_STOP, M_DEFAULT is the only possible setting for the OperationFlag parameter.

  Open   Collapse  M_ASYNCHRONOUS

 Allows your thread to continue after initiating the start of the grabs, rather than waiting for MdigProcess() to finish.  Allows your thread to continue after initiating the start of the grabs, rather than waiting for MdigProcess() to finish.

  Open   Collapse  M_SYNCHRONOUS

 Synchronizes your thread with the end of MdigProcess().  Synchronizes your thread with the end of MdigProcess().

 HookHandlerPtr

 Specifies the address of the function that is called when a buffer is modified in the array of destination image buffers.

 The hook-handler function, pointed to by HookHandlerPtr, must be declared as follows:

long MFTYPE HookHandler(
long HookType,

MIL_ID EventId,

void MPTYPE *UserDataPtr

        )

HookType

 Type of event that generated the call (M_MODIFIED_BUFFER).

EventId

 Event identifier. You can pass the identifier to MdigGetHookInfo() to inquire about the hooked event.

UserDataPtr

 User data pointer that was passed (as UserDataPtr) to MdigProcess().

 Upon successful completion, the hook-handler function should return M_NULL. Note MFTYPE and MBUFHOOKFCTPTR are reserved MIL predefined types for functions and data pointers.

 If the hook-handler function modifies the buffer that called it, the hook-handler function for that buffer will not be called again until that buffer is modified by either some other function or a new grab. This is to avoid infinite recursive calls being generated. If, however, the hook-handler function modifies another buffer which has another function hooked, that function will be called.

 UserDataPtr

 Specifies the address of the user data that you want to make available to the hook-handler function. This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.

START STOP MODIFIED BUFFER BUFFER INDEX MODIFIED BUFFER BUFFER ID MODIFIED BUFFER HOOK MODE MULTI THREAD GRAB STOP STOP STOP SEQUENCE START ASYNCHRONOUS SEQUENCE SYNCHRONOUS STOP SYNCHRONOUS ASYNCHRONOUS STOP DEFAULT MODIFIED BUFFER     SEQUENCE START STOP WAIT COUNT(n)  DEFAULT ASYNCHRONOUS SYNCHRONOUS


MdigReference

See Also | Example | Availability | MdigProcess
User Guide:
Multiple cameras
Reference levels, lookup tables, and scaling
Grabbing

Reference:
MdigControl
There are no examples containing MdigReference().
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Solios XA
Partially supported on Matrox Iris

Not supported on:
Not supported on Matrox Meteor-II /Camera Link
Not supported on Matrox Meteor-II /Digital
Not supported on Matrox Helios XCL
Not supported on Matrox Odyssey XCL
Not supported on Matrox Odyssey XD
Not supported on Matrox Solios XCL
Synopsis
Select a digitization reference level.
Syntax
void MdigReference(
MIL_ID DigId,
long ReferenceType,
double ReferenceLevel
)
Description

This function sets (if available) the reference levels used to digitize the analog signal received from a camera. This function is specific to analog input devices. Depending on the type of digitizer and input signal, some reference types are not applicable.

[Matrox Helios XA, Matrox Odyssey XA, and Matrox Solios XA]

The following settings are for the XA only. Refer to Adjusting the reference levels, in the Frame Grabbers chapter of your board's Installation and Hardware Guide. There are three ways to change the input signal's gain:

The first method is to set M_BLACK_REF and M_WHITE_REF to specific values (between M_MIN_LEVEL and M_MAX_LEVEL). This method is commonly used interactively (for example, in an application that allows you to change the settings until you are satisfied with the image quality). Note that the black reference level must always be less than the white level. Do not use MdigControl() with M_GRAB_INPUT_GAIN if you are using this method since the gain will be adjusted automatically.

The second method is to set the black and the white reference levels in Volts. By adding M_VOLTAGE to the ReferenceType, the optimum levels for the offset and gain controllers will be calculated automatically. This is more useful if you know the actual input signal voltages.

The third method is to set M_BLACK_REF and then call MdigControl() with M_GRAB_INPUT_GAIN set to a value from M_MIN_LEVEL to M_MAX_LEVEL. This method corresponds more closely to the actual hardware that controls the reference levels. The hardware has an offset controller followed by a gain controller; the analog-to-digital converter cannot be programmed directly with the reference levels. Note that when using this method, you should not specify a white reference level because it would cause the gain to be altered.

Parameters
DigId

Specifies the identifier of the digitizer on which to set the reference level. An error is generated if the specified digitizer does not support the type of programmable digitization reference levels specified.

ReferenceType

Specifies the reference level type to adjust for the specified digitizer.

This parameter can be set to one of the following:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_BLACK_REF

 Sets the input signal's digitization black reference level. Note that when setting black and white reference levels, always set black reference levels first.  Sets the input signal's digitization black reference level ...

a

c
d

f

j

m

p
q

Specifics

 Note that some consecutive ReferenceLevel settings might produce the same result due to the fact that there are only 98 distinct adjustments (adjustments of 10.23 mV each).

a

j

p

 There are 255 distinct adjustments of 9.80 mV each. Note that the white level should be higher than the black level.

c

 The minimum voltage is 0.6V. The maximum voltage is 1.6V.

a

j

p

 The minimum voltage is 0.0V. The maximum voltage is 2.5V.

c

 The minimum voltage level is -1 V. The maximum voltage level is +1 V. Note that the white level should be higher than the black level.

d

m

q

 This is only available when grabbing from the RGB section of the Matrox Orion.

p

  Open   Collapse  M_BRIGHTNESS_REF

 Sets the brightness level for composite input signals.  Sets the brightness level for composite input signals ...

b

g

k
l

p

Specifics

 Note that M_BRIGHTNESS_REF is only available when grabbing monochrome or color data using the decoder section of Matrox Orion.

p

  Open   Collapse  M_CONTRAST_REF

 Sets the contrast level for composite input signals.  Sets the contrast level for composite input signals ...

b

g

k
l

p

Specifics

 Note that M_CONTRAST_REF is only available when grabbing monochrome or color data using the decoder section of Matrox Orion.

p

  Open   Collapse  M_HUE_REF

 Sets the hue level for composite input signals.  Sets the hue level for composite input signals ...

M_HUE_REF is available when grabbing color data (not monochrome data).

b

g

k
l

p

Specifics

 Note that M_HUE_REF is only available when using the decoder section of Matrox Orion.

p

  Open   Collapse  M_SATURATION_REF

 Sets the saturation level for composite input signals.  Sets the saturation level for composite input signals ...

M_SATURATION_REF is available when grabbing color data (not monochrome data).

b

g

k
l

p

Specifics

M_SATURATION_REF is only available when grabbing using the decoder section of Matrox Orion.

p

  Open   Collapse  M_WHITE_REF

 Sets the input signal's digitization white reference level. Note that when setting black and white reference levels, always set black reference levels first.  Sets the input signal's digitization white reference level ...

a

c
d

j

m

p
q

Specifics

 Note that some consecutive ReferenceLevel settings might produce the same result due to the fact that there are only 98 distinct adjustments (adjustments of 10.23 mV each).

a

j

p

 There are 255 distinct adjustments of 9.80 mV each. Note that the white level should be higher than the black level.

c

 The minimum voltage is 1.6V. The maximum voltage is 2.6V.

a

j

p

 The minimum voltage is 0.0V. The maximum voltage is 2.5V.

c

 The minimum voltage level is -1 V. The maximum voltage level is +1 V. Note, the white level should be higher than the black level.

d

m

q

      [Combination constants]

[Matrox Corona-II, Matrox Helios XA, Matrox Meteor-II /Multi-Channel, Matrox Odyssey XA, Matrox Orion, and Matrox Solios XA]

 When using RGB or multi-tap input and setting ReferenceType to M_BLACK_REF or M_WHITE_REF, you can control the reference level of a specific acquisition path by combining it with one of the following:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_CH0_REF

 Sets the reference level on acquisition path 0.  Sets the reference level on acquisition path 0.

a

d

j

m

p
q

  Open   Collapse  M_CH1_REF

 Sets the reference level on acquisition path 1.  Sets the reference level on acquisition path 1.

a

d

j

m

p
q

  Open   Collapse  M_CH2_REF

 Sets the reference level on acquisition path 2.  Sets the reference level on acquisition path 2.

a

d

j

m

p
q

  Open   Collapse  M_CH3_REF

 Sets the reference level on acquisition path 3.  Sets the reference level on acquisition path 3.

d

m

q

      [Combination constants]

[Matrox Helios XA, Matrox Odyssey XA, and Matrox Solios XA]

 To specify M_BLACK_REF or M_WHITE_REF in volts, add the following value.

  Open   Collapse  Value
Description

  Open   Collapse  M_VOLTAGE

 Sets the reference level in Volts.  Sets the reference level in Volts.

 ReferenceLevel

 Specifies the level of reference.

 The smallest voltage increment supported by your board can differ such that consecutive reference-level settings might produce the same result.

 Note, some digitizers might take a few milliseconds before the reference level stabilizes.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_DEFAULT

 Sets the reference levels to the defaults for the specified digitizer data format.  Sets the reference levels to the defaults for the specified digitizer data format ...

a
b
c
d

f
g

j
k
l
m

p
q

Specifics

 When using M_VOLTAGE, the reference levels are from -1.0V to +1.0V

d

m

q

  Open   Collapse  M_MAX_LEVEL

 Sets the value to the maximum level.  Sets the value to the maximum level.

a
b
c
d

f
g

j
k
l
m

p
q

  Open   Collapse  M_MIN_LEVEL

 Sets the value to the minimum level.  Sets the value to the minimum level.

a
b
c
d

f
g

j
k
l
m

p
q

  Open   Collapse  M_MIN_LEVEL <= Value <= M_MAX_LEVEL

 Sets a value between M_MIN_LEVEL and M_MAX_LEVEL, inclusive.  Sets a value between M_MIN_LEVEL and M_MAX_LEVEL, inclusive ...

 To calculate the value to pass to MdigReference(), use the following equation with the appropriate voltages for your particular board.

a
b
c
d

f
g

j
k
l
m

p
q

Specifics

 If not using M_BLACK_REF + M_VOLTAGE or M_WHITE_REF + M_VOLTAGE, this value will map to a value within the given range.

d

m

q

  Open   Collapse  Minimum voltage <= Value <= Maximum voltage

 Sets a value between the minimum voltage and the maximum voltage, inclusive. Note that this value can only be used with M_BLACK_REF + M_VOLTAGE or M_WHITE_REF + M_VOLTAGE.  Sets a value between the minimum voltage and the maximum voltage, inclusive ...

 The reference levels are from -1.0V to +1.0V (for example, use 0.7 for 700 mV).

d

m

q

BLACK REF WHITE REF MIN LEVEL MAX LEVEL GRAB INPUT GAIN VOLTAGE BLACK REF GRAB INPUT GAIN MIN LEVEL MAX LEVEL BRIGHTNESS REF CONTRAST REF HUE REF HUE REF SATURATION REF SATURATION REF BLACK REF WHITE REF BLACK REF WHITE REF VOLTAGE MIN LEVEL MAX LEVEL BLACK REF VOLTAGE WHITE REF VOLTAGE BLACK REF VOLTAGE WHITE REF VOLTAGE   BLACK REF BRIGHTNESS REF CONTRAST REF  HUE REF SATURATION REF WHITE REF  CH0 REF CH1 REF CH2 REF CH3 REF  VOLTAGE  DEFAULT MAX LEVEL MIN LEVEL MIN LEVEL <= Value <= M MAX LEVEL


disp

Mdisp functions

Example | Availability
There are no examples containing disp().
Available in MIL-Lite

Available in MIL
Synopsis
The display module allows you to display images and manipulate their display. The display module offers many display effects, such as annotation, LUTs, and panning and zooming
Functions
  • MdispAlloc
  • MdispControl
  • MdispFree
  • MdispHookFunction
  • MdispInquire
  • MdispLut
  • MdispPan
  • MdispSelect
  • MdispSelectWindow
  • MdispZoom


MdispAlloc

See Also | Example | Availability | MdispControl
User Guide:
Allocating an application and its systems
Allocating and displaying an image buffer
Overview
Types of displays
Displaying multiple buffers
Annotating the displayed image non-destructively
Displaying

Reference:
MdispFree
MdispLut
MdispSelect
MsysAlloc
channel_switch.c
dtkobjecttracking.c
mdblgrab.c
mdiggrabmultiple.c
mdigmultdestination.c
mdigmultformat.c
mdigprocessmultiple.c
mdispwindow.c
mgenlc.c
mmet2dig.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Allocate a display.
Syntax
MIL_ID MdispAlloc(
MIL_ID SystemId,
long DispNum,
MIL_TEXT_PTR DispFormat,
long InitFlag,
MIL_ID *DisplayIdPtr
)
Description

This function allocates a display on the specified system so that it can be used by subsequent MIL display functions. Use MdispSelect() to display an image buffer using this newly allocated display.

When you have completely finished using a display, you should free it, using MdispFree().

[Matrox Iris]

There can be 31 remote displays allocated simultaneously.

Parameters
SystemId

Specifies the system on which to allocate the display. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 DispNum

 Specifies the number (or rank) of the display.  This parameter must be set to the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Allows MIL to find the best device to use for a windowed display or an auxiliary display. If your imaging board has a display section, and it is available, MIL will typically use it for display purposes.  Allows MIL to find the best device to use for a windowed display or an auxiliary display ...

 DispFormat

 Specifies the display format appropriate for the auxiliary display. Note that DispFormat does not have any effect on window displays.  This parameter can be set to the following value:

  Open   Collapse  Value
Description

  Open   Collapse  "M_DEFAULT"

 Specifies the default video configuration format (VCF) for the auxiliary display, which can be set during installation and later modified using the MILConfig utility (Defaults tab).  Specifies the default video configuration format (VCF) for the auxiliary display, which can be set during installation and later modified using the MILConfig utility (Defaults tab).

[Matrox Iris]

 For remote displays, DispFormat parameter can be set tot he following:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  "REMOTEVIEW"

 Sets the display format to the most appropriate type of display available.  Sets the display format to the most appropriate type of display available ...

This is the default value.

f

  Open   Collapse  "REMOTEVIEW:MONO"

 Sets the display format to monochrome.  Sets the display format to monochrome.

f

  Open   Collapse  "REMOTEVIEW:PSEUDO"

 Sets the display format to pseudo-color. To display the monochrome data in color, a pseudo-color remote display must be allocated. This will transfer the data as 8-bit pixels with an associated 256 * 32-bit entries in a physical LUT.  Sets the display format to pseudo-color ...

 This display format can support a default 256 monochrome LUT with upper 10 and lower 10 LUT entries programmed with Windows reserved 32-bit color values. Note that MdispLut() cannot change this default LUT.

f

  Open   Collapse  "REMOTEVIEW:RGB"

 Sets the display format to RGB.  Sets the display format to RGB.

f

[All except
        Matrox Iris]

 For auxiliary displays that do not use an encoder, the DispFormat parameter can be set to the following:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  "VCF Filename"

 Sets the display format to the format specified by the selected VCF file. The file typically has a VCF extension.  Sets the display format to the format specified by the selected VCF file ...

 If the graphics controller driving the auxiliary screen is a Matrox Millennium G400 (or higher), you can allocate the auxiliary display on the graphics controller; in which case, the file name string can be specified in, for example, the "1024x768x32@60hz.vcf" format. For the current list of video configuration format (VCF) files, see the MATROX IMAGING\DRIVERS\HOST\VCF directory.

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The file name string must be specified in, for example, the "CM001_60.VCF" or "1280x1024x8PP" format. For the current list of VCF files, see the GENESIS\VCF directory.

c

[Matrox Corona-II and Matrox Orion]

 For auxiliary displays that use the encoder in the on-board display section of the Matrox imaging board, the DispFormat parameter can be set to one of the following. Note that encoders on other display boards are not supported.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  "M_CCIR"

 Enables the encoder in composite format without colorburst.  Enables the encoder in composite format without colorburst.

a

p

  Open   Collapse  "M_NTSC"

 Enables the encoder in composite format with colorburst.  Enables the encoder in composite format with colorburst ...

 This display format will produce both composite and Y/C outputs.

a

p

  Open   Collapse  "M_NTSC_RGB"

 Enables the encoder in RGB format with synchronization on green.  Enables the encoder in RGB format with synchronization on green.

a

p

  Open   Collapse  "M_NTSC_YC"

 Enables the encoder in Y/C formats with colorburst.  Enables the encoder in Y/C formats with colorburst ...

 This display format will produce both composite and Y/C outputs.

a

p

  Open   Collapse  "M_PAL"

 Enables the encoder in composite format with colorburst.  Enables the encoder in composite format with colorburst ...

 This display format will produce both composite and Y/C outputs.

a

p

  Open   Collapse  "M_PAL_RGB"

 Enables the encoder in RGB format with sync on green.  Enables the encoder in RGB format with sync on green.

a

p

  Open   Collapse  "M_PAL_YC"

 Enables the encoder in Y/C formats with colorburst.  Enables the encoder in Y/C formats with colorburst ...

 This display format will produce both composite and Y/C outputs.

a

p

  Open   Collapse  "M_RS170"

 Enables the encoder in composite format without colorburst.  Enables the encoder in composite format without colorburst.

a

p

 InitFlag

 Specifies your display's type.  This parameter can be set to one of the following:

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_DEFAULT

 Specifies the default display type, which can be set using the MILConfig utility. Typically, the default display type is M_WINDOWED.  Specifies the default display type, which can be set using the MILConfig utility ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_AUXILIARY

 Specifies that the image buffer that will be selected for display has no window associated with it. The image buffer is presented at the top-left corner on an auxiliary screen, which is any output device that is not used for the Windows desktop. You are responsible for moving and tracking this type of display, if required. This type of display is only supported with Matrox graphics controllers and only if you have an auxiliary screen.  Specifies that the image buffer that will be selected for display has no window associated with it ...

 It is possible to have more than one auxiliary display. Note, however, that only one auxiliary display is possible per graphics controller.

 When using a Matrox Millennium G400 (or higher) graphics controller, you must use the second video output controller for your auxiliary display. However, if the Windows desktop is driven by another graphics controller in your computer, the first video output controller of your Matrox Millenniun G400 (or higher) graphics controller can be used for auxiliary display instead.

 When using the second video output controller of a Matrox Millennium G400 (or higher) graphics controller for your auxiliary display, your display driver's DualHead mode must be disabled; otherwise, both the display driver and the MIL driver will attempt to access the second video output controller, and the auxiliary display will not work.

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_WINDOWED

 Specifies that the image buffer that will be selected for display purposes will be presented in its own window on the Windows desktop screen(s). The display window is tracked and updated with the image buffer selected for display; that is, if the window moves or is occluded, the window is updated with the image buffer accordingly.  Specifies that the image buffer that will be selected for display purposes will be presented in its own window on the Windows desktop screen(s) ...

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

 To force the display's overlay buffer to be compatible with GDI operations when the overlay-display mechanism is enabled, add the following value to the InitFlag parameter. If the overlay buffer is forced to be compatible with GDI operations, then you can allocate and use a device context (DC) for drawing in the buffer. Note that performing MIL operations on the display's overlay buffer can be done more efficiently when the display's overlay buffer is not forced to be GDI compatible.

  Open   Collapse  Value
Description

  Open   Collapse  M_GDI_OVERLAY

 Specifies that the display's overlay buffer will be forced to be compatible with GDI operations.  Specifies that the display's overlay buffer will be forced to be compatible with GDI operations.

 DisplayIdPtr

 Specifies the address of the variable in which to write the display identifier.  Since the MdispAlloc() function also returns the display identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the display identifier. If allocation fails, M_NULL is returned.

Remark

  •  Integrated with an on-board TV/video encoder, Matrox 4Sight-II also supports video encoded formats. To see the information regarding the supported encoded video formats if you have a Matrox 4Sight-II, select the Matrox Orion as your board type in the Customizing options section in
          Chapter 0: About Matrox MIL help.
    •

WINDOWED  DEFAULT HOST   DEFAULT  DEFAULT"      CCIR"  NTSC"  NTSC RGB"  NTSC YC" PAL" PAL RGB" PAL YC" RS170"   DEFAULT AUXILIARY WINDOWED GDI OVERLAY


MdispControl

See Also | Example | Availability | MdispAlloc | MdispFree
User Guide:
Types of displays
Screen tearing
Panning and zooming
Annotating the displayed image non-destructively

Reference:
MdispInquire
MdispPan
MdispSelect
MdispSelectWindow
MdispZoom
mblob.c
mcal.c
mcode.c
mdigautofocus.c
mdigmultdestination.c
mdigmultformat.c
mdispoverlay.c
mdispwindowleveling.c
medge.c
mgenlc.c
mgrabbayer.c
mimfft.c
mimhistogram.c
mmeas.c
mmod.c
mmodeltracking.c
mocr.c
mpat.c
mstr.c
Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Partially supported on:
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Control a MIL display setting.
Syntax
void MdispControl(
MIL_ID DisplayId,
long ControlType,
double ControlValue
)
Description

This function allows you to control the specified MIL display setting.

Parameters
DisplayId

Specifies the identifier of the target display.

ControlType

Specifies the type of display setting to control. The control types for windowed displays can control the default MIL or user-specified window of the display (MdispSelect() or MdispSelectWindow()).

See the Parameter associations section for possible values.

ControlValue

Specifies the new value to assign to the display setting specified by the ControlType parameter.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

The following ControlType and corresponding ControlValue parameter settings are available for windowed and auxiliary displays.

Open Collapse ControlType Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
ControlValue
Open Collapse M_COLOR_MODE

Sets the color mode of the Matrox Genesis main frame buffer. Sets the color mode of the Matrox Genesis main frame buffer ...

c
M_BLUE

Displays in monochrome using the blue band of the Matrox Genesis main frame buffer.

c
M_COLOR

Displays the Matrox Genesis main frame buffer in true color.

This is the default value.

 c
M_GREEN

Displays in monochrome using the green band of the Matrox Genesis main frame buffer.

c
M_RED

Displays in monochrome using the red band of the Matrox Genesis main frame buffer.

c
Open Collapse M_INTERPOLATION_MODE

Sets the type of interpolation used to display a zoomed image. Sets the type of interpolation used to display a zoomed image ...

a b c d e g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is M_FAST.

a b c d e g h i j k l m n o p q r
M_FAST

Specifies to use the fastest interpolation mode available to update the display.

a b c d e g h i j k l m n o p q r
M_NEAREST_NEIGHBOR

Specifies the nearest neighbor interpolation.

a b c d e g h i j k l m n o p q r
Open Collapse M_NO_TEARING

Sets the no-tearing mode for the selected display. This mode requires special hardware, such as a Matrox Millennium G400, G450, or G550 graphics controller. If the hardware does not support the selected mode, MIL will not generate an error; instead, it will compensate by using the only mode available which is the mode in which tearing can occur. Use MdispInquire() with the M_NO_TEARING_ACTIVE inquire type to determine if the graphics controller is using the selected mode. Sets the no-tearing mode for the selected display ...

For more information on screen tearing, see the Screen tearing section in Chapter 16: Displaying an image.

a b c d e g h i j k l m n o p q r
M_DEFAULT

Specifies that the default no-tearing mode is applied. The default no-tearing mode is M_DISABLE except when the encoder is displaying a continuous grab on an auxiliary display. In this case, the default no-tearing mode is M_ENABLE.

a b c d e g h i j k l m n o p q r
M_ADVANCED

Specifies an advanced no-tearing mechanism. With this mode, screen tearing does not occur regardless of whether the rate at which display memory is updated is slower, equal, or faster than the rate at which the screen is refreshed. When more than one update to the display occurs between two vertical synchronization pulses of the screen, the updates are queued using multiple buffers.

Note that during a vertical synchronization pulse of the screen, only one update is copied to the screen. By default, MIL copies every update in the queue to the screen; this results in a lag in the time it takes for the updates to be displayed. To avoid this lag, MIL can skip certain updates in the queue. To specify which updates to skip, see combination values below.

a b c d e g h i j k l m n o p q r
M_BASIC

Specifies a basic no-tearing mechanism. Note that when the rate at which the display is updated is faster than the rate at which the screen is refreshed, screen tearing can still occur.

a b c d e g h i j k l m n o p q r
M_DISABLE

Specifies not to use a no-tearing mechanism to update the display.

a b c d e g h i j k l m n o p q r
M_ENABLE

Specifies the optimal no-tearing mode for the current situation (varies depending on such factors as the board used and CPU availability).

a b c d e g h i j k l m n o p q r
M_GRAB_CONTINUOUS_ONLY

Specifies that a no-tearing mechanism be used only when the display is updated by a continuous grab. All other display updates are not made with a no-tearing mechanism (that is, updates that are necessary due to modifications made to the display's overlay buffer or the buffer selected to the display). Note that when the display is updated by a continuous grab, screen tearing can still occur if the rate at which the display is updated is faster than the rate at which the screen is refreshed.

a b c d e g h i j k l m n o p q r
Open Collapse M_OVERLAY

Sets whether MIL's overlay-display mechanism is enabled. This mechanism allows you to annotate displayed image buffers non-destructively. For more information on MIL's overlay buffers, see the Annotating the displayed image non-destructively section in Chapter 16: Displaying an image. Sets whether MIL's overlay-display mechanism is enabled ...

Once enabled, use MdispInquire() with the M_OVERLAY_ID inquire type to determine the MIL identifier of the overlay buffer. Note that once created, the overlay buffer is like any other image buffer. That is, you can perform operations on it as you would on a normal buffer (except for grabbing).

a b c d e f g h i j k l m n o p q r
Specifics

The display's overlay buffer will always be 1 band.

c
M_DISABLE

Disables MIL's overlay-display mechanism.

This is the default value.

 a b c d e f g h i j k l m n o p q r
M_ENABLE

Enables MIL's overlay-display mechanism.

a b c d e f g h i j k l m n o p q r
Open Collapse M_OVERLAY_CLEAR

Sets the value to which the overlay buffer associated with the display should be cleared. The buffer is cleared to the specified value immediately after this control type setting is changed. Sets the value to which the overlay buffer associated with the display should be cleared ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is M_TRANSPARENT_COLOR.

a b c d e f g h i j k l m n o p q r
M_RGB888(
long red,
long green,
long blue
)

Specifies the RGB value to which the display's overlay buffer will be cleared for a non 8-bit display mode.

a b c d e f g h i j k l m n o p q r

Parameters
red

Specifies the red value of the RGB value.

green

Specifies the green value of the RGB value.

blue

Specifies the blue value of the RGB value.

8-bit value

Specifies the value to which the display's overlay buffer will be cleared for an 8-bit display mode.

a b c d e f g h i j k l m n o p q r
M_TRANSPARENT_COLOR

Specifies that the display's overlay buffer will be cleared to the transparency color. Set the transparency color with the M_TRANSPARENT_COLOR control type.

a b c d e f g h i j k l m n o p q r
Open Collapse M_OVERLAY_SHOW

Sets whether the display's overlay buffer is visible. Sets whether the display's overlay buffer is visible ...

a b c d e f g h i j k l m n o p q r
M_DISABLE

Specifies that the overlay buffer is not visible. Display the image buffer selected on the display only.

a b c d e f g h i j k l m n o p q r
M_ENABLE

Specifies that the overlay buffer is visible. Annotations or other changes made to the overlay buffer in a color other than the transparency color will annotate the image selected to the display. Set the transparency color with the M_TRANSPARENT_COLOR control type.

This is the default value.

 a b c d e f g h i j k l m n o p q r
M_OPAQUE

Specifies that only the overlay buffer is visible. The image buffer selected will be hidden.

a b c d e g h i j k l m n o p q r
Open Collapse M_THREAD_PRIORITY

Sets the priority given to update the display. This control type is only available for MIL displays selected using the MdispSelect() function. Sets the priority given to update the display ...

a b c d e g h i j k l m n o p q r
1 to 6

Specifies the thread priority as low (idle).

a b c d e g h i j k l m n o p q r
7 to 10

Specifies the thread priority as normal.

a b c d e g h i j k l m n o p q r
11 to 15

Specifies the thread priority as high.

a b c d e g h i j k l m n o p q r
16; 22 to 26; 31

Specifies the thread priority as real-time.

a b c d e g h i j k l m n o p q r
Open Collapse M_TITLE

Sets the display's title to a specified string. For windowed displays, set whether the window's title bar is visible with the M_WINDOW_TITLE_BAR control type. For auxiliary displays, the title bar is not visible but the display's title can still be inquired. If no string is specified, the window is given a default title ("MIL Display #x"). Sets the display's title to a specified string ...

a b c d e f g h i j k l m n o p q r
M_PTR_TO_DOUBLE(
void MPTYPE *PTR
)

Specifies the address of the character array in which the window title is stored.

a b c d e f g h i j k l m n o p q r

Parameters
PTR

The address of the character array in which to read the window title.

Open Collapse M_TRANSPARENT_COLOR

Sets the transparency (keying) color. Pixels of the image buffer selected to the display are displayed only where the corresponding pixels of the overlay buffer are set to the transparency color. Sets the transparency (keying) color ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the optimal transparency color.

a b c d e f g h i j k l m n o p q r
M_RGB888(
long Red,
long Green,
long Blue
)

Specifies the RGB value to which to set the transparency color for a non 8-bit display mode. The red, green, and blue values must be values between 0 and 255, inclusive.

a b c d e f g h i j k l m n o p q r

Parameters
Red

Specifies the red value of an RGB value.

Green

Specifies the green value of an RGB value.

Blue

Specifies the blue value of an RGB value.

8-bit Value

Specifies the transparency color for an 8-bit display mode.

a b c d e f g h i j k l m n o p q r
Open Collapse M_UPDATE

Sets whether MIL should update the display. This control type can be used to temporarily disable display updates when the image buffer is being modified by more than one operation; the display can then be updated at the end of all operations. Sets whether MIL should update the display ...

a b c d e f g h i j k l m n o p q r
M_DISABLE

Disallows display updates.

a b c d e f g h i j k l m n o p q r
M_ENABLE

Allows display updates.

This is the default value.

 a b c d e f g h i j k l m n o p q r
Open Collapse M_VIEW_BIT_SHIFT

Sets the number of bits by which to bit-shift the pixel values of the image buffer selected to the display, when the M_VIEW_MODE control type is set to M_BIT_SHIFT. Sets the number of bits by which to bit-shift the pixel values of the image buffer selected to the display, when theM_VIEW_MODE control type is set to M_BIT_SHIFT ...

a b c d e g h i j k l m n o p q r
Value

Specifies the number of bits. This value should be set to the number of significant bits in the image buffer minus 8. For example, if a 16-bit image buffer contains data grabbed from a 10-bit digitizer, a shift of 2 should be used.

The default value is 0.

a b c d e g h i j k l m n o p q r
Open Collapse M_VIEW_MODE

Sets the view mode of the display. The view mode establishes how an image buffer gets remapped to the display; this is especially useful when displaying a non 8-bit image buffer. Sets the view mode of the display ...

a b c d e g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is M_TRANSPARENT.

a b c d e g h i j k l m n o p q r
M_AUTO_SCALE

This value is only available in MIL.

Remaps the pixel values to the display so that the minimum and maximum values in the image (not the full range of the image buffer) are set to 0 and 255, respectively. If the image buffer contains a single value, the displayed value is determined by linearly re-mapping the full range of the image buffer to that of the display (for example, (0 to 64K) to (0 to 255)).

a b c d e g h i j k l m n o p q r
M_BIT_SHIFT

Bit-shifts the pixel values of the image buffer by the specified number of bits upon updating the display. Specify the number of bits with the M_VIEW_BIT_SHIFT control type.

a b c d e g h i j k l m n o p q r
M_MULTI_BYTES

Displays each byte of the image buffer in separate display pixels. In other words, each pixel of a 16-bit image buffer will occupy two consecutive display pixels. Each pixel of a 32-bit image buffer will occupy four consecutive display pixels. This mode is only supported for 16-bit and 32-bit 1-band buffer. This mode is primarily useful when grabbing from a multi-tap camera.

a b c d e g h i j k l m n o p q r
M_TRANSPARENT

Specifies that no pixel remapping will be performed. Note that only the 8 least-significant bits of the image buffer will be displayed.

a b c d e g h i j k l m n o p q r

[All except Matrox Iris]

The following ControlType and corresponding ControlValue parameter settings are available for all windowed displays:

Open Collapse ControlType Description
ControlValue
Open Collapse M_CENTER_DISPLAY

Sets whether a selected image buffer will be centered in the display, both in X and Y. Sets whether a selected image buffer will be centered in the display, both in X and Y ...

If enabled, the image buffer will be offset by ( (WindowSizeX - BufferSizeX)/2, (WindowSizeY - BufferSizeY)/2 ) in the window.

M_DEFAULT

Specifies the default value. The default value is M_ENABLE for a MIL default window except if the window is maximized. The default value is M_DISABLE for an user-defined window.

M_DISABLE

Specifies that the image buffer will not be centered in the display.

M_ENABLE

Specifies that the image buffer will be centered in the display, both in X and Y.

Open Collapse M_FILL_DISPLAY

Sets whether the display will be filled with the selected image buffer using an automatically calculated zoom factor. Sets whether the display will be filled with the selected image buffer using an automatically calculated zoom factor ...

M_DISABLE

Specifies that the display will not be filled with the image buffer using an automatically calculated zoom factor. Other zoom factors can be applied, using MdispZoom().

This is the default value.
M_ENABLE

Specifies that the display will be fliled with the image buffer using an automatically calculated zoom factor.

This setting overrides zoom factors (MdispZoom()), disables the window's zoom buttons (M_WINDOW_ZOOM), and overrides pan and scroll settings (MdispPan()).

Open Collapse M_UPDATE_SYNCHRONIZATION

Sets the update mode currently used by the display for Windows paint messages. Sets the update mode currently used by the display for Windows paint messages ...

This feature is especially useful in applications where buffers are displayed in user-defined windows and the reception of paint messages generate buffer modifications.

M_DEFAULT

Specifies the default update mode. The default mode corresponds to M_SYNCHRONOUS for a MIL default window. For a user-defined window, if the user-defined window thread is the same as the current one, the update mode is M_SYNCHRONOUS; otherwise, it is M_ASYNCHRONOUS.

M_ASYNCHRONOUS

Specifies that the paint message is queued and that the application's window procedure (WndProc) will update the display whenever possible. Basically, when a paint message is issued, MIL calls the Windows InvalidateRect() function. For more information on InvalidateRect(), refer to the MSDN library.

M_SYNCHRONOUS

Specifies that the display is updated immediately upon reception of a paint message. Basically, when a paint message is issued, MIL calls the Windows InvalidateRect() function followed by the Windows UpdateWindow() function. For more information on InvalidateRect() and UpdateWindow(), refer to the MSDN library.

Open Collapse M_WINDOW_PALETTE_NOCOLLAPSE

Sets how the Windows palette manager loads colors from the logical palette to the output LUTs. Sets how the Windows palette manager loads colors from the logical palette to the output LUTs ...

M_DISABLE

Loads each component of the logical palette directly "as is" in the corresponding output LUT. This can result in a color occurring more than once in the output LUTs.

This is the default value.
M_ENABLE

Attempts the best color usage of the logical palette when realizing the output LUTs. It tries to map colors from the logical palette into the currently-realized output LUTs, to reduce the number of requested new entries.

Open Collapse M_WINDOW_RANGE

Sets whether the optimization of display updates is available by restricting the displayed image buffer values to between 10 and 245. Sets whether the optimization of display updates is available by restricting the displayed image buffer values to between 10 and 245 ...

M_DISABLE

Restricts the displayed image buffer values to those outside the Windows reserved color. Pixels in the range of 0-10 and 245-255 are mapped to either 0 or 255, respectively.

This is the default value.
M_ENABLE

Uses the full range of the displayed image buffer values (0-255).

Open Collapse M_WINDOW_SNAP_X

Sets the horizontal resolution of the grid used by the display window's movements. Sets the horizontal resolution of the grid used by the display window's movements ...

Value

Specifies the number of pixels that make up one cell of the grid. For example, a value of 4 creates a grid in which the allowed X-positions are 0, 4, 8, 12, and so on. Values can be positive or negative integers. Positive snap values adjust the X-coordinate to the closest right pixel; negative ones adjust it to the closest left pixel.

The default value is 1.

Open Collapse M_WINDOW_SNAP_Y

Sets the vertical resolution of the grid used by the display window's movements. Sets the vertical resolution of the grid used by the display window's movements ...

Value

Specifies the number of pixels that make up one cell of the grid. For example, a value of 4 creates a grid in which the allowed Y-positions are 0, 4, 8, 12, and so on. Values can be positive or negative integers. Positive snap values adjust the Y-coordinate to the closest top pixel; negative ones adjust it to the closest bottom pixel.

The default value is 1.

Open Collapse M_WINDOW_UPDATE_ON_PAINT

Sets when the display will be updated. Sets when the display will be updated ...

M_DEFAULT

Allows MIL to decide which message to receive before updating the display.

M_DISABLE

Updates the display on reception of a WM_ERASEBKGND message in Windows.

M_ENABLE

Updates the display on reception of a WM_PAINT message in Windows.

[All except Matrox Iris]

The following ControlType and corresponding ControlValue parameter settings are only available for MIL windowed displays (selected using MdispSelect()), and are not available for user windowed displays (selected using MdispSelectWindow()):

Open Collapse ControlType Description
ControlValue
Open Collapse M_WINDOW_INITIAL_POSITION_X

Sets the initial, left-most, X-coordinate of the window. Sets the initial, left-most, X-coordinate of the window ...

Value

Specifies the X-coordinate, in pixels.

Open Collapse M_WINDOW_INITIAL_POSITION_Y

Sets the initial, top-most, Y-coordinate of the window. Sets the initial, top-most, Y-coordinate of the window ...

Value

Specifies the Y-coordinate, in pixels.

Open Collapse M_WINDOW_KEYBOARD_USE

Sets whether to activate the keys associated with the display's window. Sets whether to activate the keys associated with the display's window ...

The default key usage is:

+ | Increases the X and Y zoom factors.
- | Decreases the X and Y zoom factors.
Page-up | Scrolls the image buffer up to the previous display section.
Page-down | Scrolls the image buffer down to the next display section.
Up arrow | Scrolls the image buffer up to the previous line.
Down arrow | Scrolls the image buffer down to the next line.
Left arrow | Pans the image buffer left by one pixel.
Right arrow | Pans the image buffer right by one pixel.
Ctrl-Up arrow | Scrolls the image buffer up to the previous display section.
Ctrl-Down arrow | Scrolls the image buffer down to the next display section.
Ctrl-Left arrow | Pans the image buffer left to the previous display section.
Ctrl-Right arrow | Pans the image buffer right to the next display section.
M_DISABLE

Does not activate the keys associated with the display's window.

M_ENABLE

Activates the keys associated with the display's window.

This is the default value.
Open Collapse M_WINDOW_MAXBUTTON

Sets whether the window's maximize button is visible. Sets whether the window's maximize button is visible ...

M_DISABLE

Specifies that the button is not visible.

M_ENABLE

Specifies that the button is visible.

This is the default value.
Open Collapse M_WINDOW_MENU_BAR

Sets whether the window's menu bar is visible. Sets whether the window's menu bar is visible ...

M_DISABLE

Specifies that the menu bar is not visible.

M_ENABLE

Specifies that the menu bar is visible.

This is the default value.
Open Collapse M_WINDOW_MENU_BAR_CHANGE

Sets whether the presence of the menu bar can be toggled. Sets whether the presence of the menu bar can be toggled ...

M_DISABLE

Disallows toggling.

M_ENABLE

Allows toggling.

This is the default value.
Open Collapse M_WINDOW_MINBUTTON

Sets whether the window's minimize button is visible. Sets whether the window's minimize button is visible ...

M_DISABLE

Specifies that the button is not visible.

M_ENABLE

Specifies that the button is visible.

This is the default value.
Open Collapse M_WINDOW_MOVE

Sets whether window movement is allowed. Sets whether window movement is allowed ...

M_DISABLE

Disallows window movement.

M_ENABLE

Allows window movement.

This is the default value.
Open Collapse M_WINDOW_OVERLAP

Sets whether the window can be overlapped by another. Sets whether the window can be overlapped by another ...

M_DISABLE

Disallows the window from being overlapped by another (keep window on top).

M_ENABLE

Allows the window to be overlapped by another.

This is the default value.
Open Collapse M_WINDOW_RESIZE

Sets whether window resizing is allowed. Sets whether window resizing is allowed ...

M_DISABLE

Disallows window resizing.

M_ENABLE

Allows window resizing.

This is the default value.
M_FULL_SIZE

Forces a full-size display. Resizing is disallowed.

M_NORMAL_SIZE

Same as M_ENABLE.

Open Collapse M_WINDOW_SCROLLBAR

Sets whether the scroll bars are visible. Sets whether the scroll bars are visible ...

M_DISABLE

Specifies that the scroll bars are not visible.

M_ENABLE

Specifies that the window's scroll bars are visible.

This is the default value.
Open Collapse M_WINDOW_SYSBUTTON

Sets whether the window's system buttons are visible. The system buttons refer to the collection of the window's minimize, maximize, and close buttons. Sets whether the window's system buttons are visible ...

To individually set whether the minimize and maximize buttons are visible, change the M_WINDOW_MAXBUTTON or M_WINDOW_MINBUTTON control type settings.

M_DISABLE

Specifies that the button is not visible.

M_ENABLE

Specifies that the button is visible.

This is the default value.
Open Collapse M_WINDOW_TITLE_BAR

Sets whether the window's title bar is visible. Sets whether the window's title bar is visible ...

M_DISABLE

Specifies that the title bar is not visible.

M_ENABLE

Specifies that the title bar is visible.

This is the default value.
Open Collapse M_WINDOW_TITLE_BAR_CHANGE

Sets whether the presence of the window's title bar can be toggled. Sets whether the presence of the window's title bar can be toggled ...

M_DISABLE

Disallows toggling.

M_ENABLE

Allows toggling. Double-clicking on the image will toggle between Title On and Title Off. If the title bar is present, you can also right-click on the title bar to select Title Off.

This is the default value.
Open Collapse M_WINDOW_ZOOM

Sets whether to allow window zoom buttons (+, -). Sets whether to allow window zoom buttons (+, -) ...

M_DISABLE

Disallows window zoom buttons (+, -).

M_ENABLE

Allows window zooming buttons (+,-).

This is the default value.

[Matrox Corona-II and Matrox Orion]

The following ControlType and corresponding ControlValue parameter settings can be specified only when using the encoder. Otherwise, an error will occur.

Open Collapse ControlType |  | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
 | ControlValue
Open Collapse M_ENCODER_FILTER |  | Sets a filter for luminance. Sets a filter for luminance ... |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_DEFAULT | Same as M_LOW_PASS_0. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_LOW_PASS_0 | Specifies a low-pass filter type A. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_LOW_PASS_1 | Specifies a low-pass filter type B. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_LOW_PASS_2 | Specifies a 5.5 MHz low-pass filter. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_NOTCH | Specifies a subcarrier frequency low-pass filter. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
Open Collapse M_ENCODER_PEDESTAL |  | Sets whether a pedestal is to be generated in the composite video signal. Sets whether a pedestal is to be generated in the composite video signal ... |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_DEFAULT | Same as M_ENABLE. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_DISABLE | Does not generate a pedestal in the output. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_ENABLE | Generates a pedestal in the composite video signal. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
Open Collapse M_SYNC_TYPE |  | Sets the type of output synchronization signal. This control type is only supported when the display format is RGB. Sets the type of output synchronization signal ... |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_DEFAULT | Specifies the default output synchronization signal. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 |  |  | Specifics |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  |  | Same as M_GREEN. | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  |  | Same as M_ALL. |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_ALL | Specifies that the output synchronization signal is sent to all channels (Red, Blue, Green and Separate). |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_DISABLE | Specifies that the encoder output does not contain a synchronization signal. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_GREEN | Specifies that the output synchronization signal is on green. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |
 | M_SEPARATE | Specifies that the synchronization and data signals are output on separate signals: the output synchronization signal is on pin 12, and the composite data signal is on pin 10 of the HD-44 connector. |  | a |  |  |  |  |  |  |  |  |  |  |  |  |  |  | p |  |

[Combination constants]
[All except Matrox Iris]

One of the following can be added to the M_ADVANCED setting of the M_NO_TEARING control type to specify which display updates, if any, are skipped (not copied to the screen). The combination value specified has an effect when the rate at which the display is updated is faster than the rate at which the screen is refreshed and more than one update to the display has occurred between two vertical synchronization pulses of the screen.

Open Collapse Value Description
Open Collapse M_NO_SKIP

 Specifies that none of the updates are skipped and every update waits to be copied to the screen. Note that since only one display update is copied to the screen during a vertical synchronization pulse of the screen, this produces a lag in the time it takes for the updates to be displayed.  Specifies that none of the updates are skipped and every update waits to be copied to the screen ...

This is the default value.

  Open   Collapse  M_SKIP_NEWEST

 Specifies that the newest updates are skipped and the update which is currently the oldest is copied to the screen. By skipping these updates to the screen, the lag in the time for the updates to be displayed is avoided.  Specifies that the newest updates are skipped and the update which is currently the oldest is copied to the screen ...

  Open   Collapse  M_SKIP_OLDEST

 Specifies that the oldest updates are skipped and the update which is currently the newest is copied to the screen. By skipping these updates to the screen, the lag in the time for the updates to be displayed is avoided.  Specifies that the oldest updates are skipped and the update which is currently the newest is copied to the screen ...

NO TEARING ACTIVE OVERLAY ID TRANSPARENT COLOR TRANSPARENT COLOR WINDOW TITLE BAR VIEW MODE BIT SHIFT VIEW BIT SHIFT ENABLE DISABLE WINDOW ZOOM SYNCHRONOUS SYNCHRONOUS ASYNCHRONOUS ENABLE WINDOW MAXBUTTON WINDOW MINBUTTON LOW PASS 0 GREEN ALL NO TEARING    COLOR MODE  BLUE  COLOR  GREEN  RED  INTERPOLATION MODE DEFAULT FAST NEAREST NEIGHBOR NO TEARING ADVANCED BASIC DEFAULT DISABLE ENABLE GRAB CONTINUOUS ONLY OVERLAY DISABLE
                      ENABLE  OVERLAY CLEAR DEFAULT TRANSPARENT COLOR     OVERLAY SHOW  DISABLE ENABLE OPAQUE THREAD PRIORITY      TITLE   TRANSPARENT COLOR DEFAULT     UPDATE DISABLE ENABLE VIEW BIT SHIFT   VIEW MODE DEFAULT  AUTO SCALE
                      BIT SHIFT MULTI BYTES TRANSPARENT CENTER DISPLAY DEFAULT ENABLE DISABLE FILL DISPLAY ENABLE DISABLE UPDATE SYNCHRONIZATION DEFAULT
                      ASYNCHRONOUS SYNCHRONOUS WINDOW PALETTE NOCOLLAPSE  DISABLE
                      ENABLE  WINDOW RANGE  DISABLE ENABLE WINDOW SNAP X   WINDOW SNAP Y   WINDOW UPDATE ON PAINT  DEFAULT  DISABLE  ENABLE  WINDOW INITIAL POSITION X   WINDOW INITIAL POSITION Y   WINDOW KEYBOARD USE  DISABLE ENABLE WINDOW MAXBUTTON  DISABLE ENABLE WINDOW MENU BAR  DISABLE ENABLE WINDOW MENU BAR CHANGE  DISABLE ENABLE WINDOW MINBUTTON  DISABLE ENABLE WINDOW MOVE  DISABLE ENABLE WINDOW OVERLAP  DISABLE ENABLE WINDOW RESIZE  DISABLE ENABLE FULL SIZE NORMAL SIZE WINDOW SCROLLBAR  DISABLE ENABLE WINDOW SYSBUTTON  DISABLE ENABLE WINDOW TITLE BAR  DISABLE ENABLE WINDOW TITLE BAR CHANGE  DISABLE ENABLE WINDOW ZOOM  DISABLE ENABLE ENCODER FILTER  DEFAULT  LOW PASS 0
                         LOW PASS 1
                         LOW PASS 2
                         NOTCH  ENCODER PEDESTAL  DEFAULT  DISABLE  ENABLE SYNC TYPE DEFAULT  ALL DISABLE  GREEN
                         SEPARATE  NO SKIP SKIP NEWEST SKIP OLDEST


MdispFree

See Also | Example | Availability | MdispControl | MdispHookFunction
User Guide:
Allocating an application and its systems
Removing a buffer from the display

Reference:
MdispAlloc
channel_switch.c
dtkobjecttracking.c
mdblgrab.c
mdiggrabmultiple.c
mdigmultdestination.c
mdigmultformat.c
mdigprocessmultiple.c
mdispwindow.c
mgenlc.c
mmet2dig.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Free a display.
Syntax
void MdispFree(
MIL_ID DisplayId
)
Description

This function deallocates a display previously allocated with MdispAlloc().

Parameter
DisplayId

Specifies the identifier of the display.


MdispHookFunction

See Also | Example | Availability | MdispFree | MdispInquire
Reference:
There are no examples containing MdispHookFunction().
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Genesis
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Orion
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL

Not supported on:
Not supported on Matrox Iris
Synopsis
Hook a function to a display event.
Syntax
void MdispHookFunction(
MIL_ID DisplayId,
long HookType,
MDISPHOOKFCTPTR HookHandlerPtr,
void *UserDataPtr
)
Description

This function allows you to attach or detach a user-defined function to a specified display event. Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.

Note that functions hooked to an event execute on a distinct thread. This permits the functions to run asynchronously from the operation that fired the event and from functions hooked to other events. Although there is a small queue to permit a certain amount of overlap, hooked functions should not take longer to execute than the period in which two of their associated events can occur. You cannot determine the instance of the event that fired the function, and even if this were possible, this information would generally not be very useful. Typically, a hooked function performs the minimum number of operations required and, if necessary, performs longer processes by launching other threads.

You can hook more than one function to an event by making separate calls to MdispHookFunction() for each function that you want to hook. MIL automatically chains and keeps an internal list of all these hooked functions. When a function is hooked, this new function is added to the end of the list. When the event happens, all user-defined functions in the list will be executed in the same order that they were hooked to the event. You can also remove any function from the list; in this case, MIL preserves the order of the remaining functions in the list.

Parameters
DisplayId

Specifies the identifier of the target display.

HookType

Specifies the display event type. This parameter can be set to the following:

Open Collapse Value Description
Open Collapse M_FRAME_START

 Calls the hook-handler function each time a new frame is displayed. You can only hook to this event if DirectDraw is enabled and you are using a windowed display.  Calls the hook-handler function each time a new frame is displayed ...

      [Combination constants]

 The value below can be added to M_FRAME_START.

  Open   Collapse  Value
Description

  Open   Collapse  M_UNHOOK

 Unhooks a hooked function.  Unhooks a hooked function.

 HookHandlerPtr

 Specifies the address of the function that should be called when an event occurs.  The hook-handler function, pointed to by HookHandlerPtr, must be declared as follows:

long MFTYPE HookHandler(
long HookType,

MIL_ID EventId,

void *UserDataPtr

        )

HookType

 Type of event hooked.

EventId

 Reserved for future use.

UserDataPtr

 Data pointer that was passed to MdispHookFunction().

 Upon successful completion, the hook-handler function should return M_NULL. Note, MFTYPE and MDISPHOOKFCTPTR are reserved MIL predefined types for functions and data pointers.

 UserDataPtr

 Specifies the address of the user data that you want to make available to the hook-handler function.  This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.

FRAME START   FRAME START UNHOOK


MdispInquire

See Also | Example | Availability | MdispHookFunction | MdispLut
User Guide:
Screen tearing
Annotating the displayed image non-destructively
Palettes and output LUTs for windowed display (256-color)

Reference:
MdispAlloc
MdispControl
MdispSelect
MdispSelectWindow
MdispZoom
mblob.c
mcal.c
mcode.c
mdigautofocus.c
mdispoverlay.c
mdispwindow.c
mdispwindowleveling.c
medge.c
mgrabbayer.c
mimfft.c
mimhistogram.c
mmeas.c
mmod.c
mmodeltracking.c
mocr.c
mpat.c
mstr.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Inquire about a display setting.
Syntax
long MdispInquire(
MIL_ID DisplayId,
long InquireType,
void *UserVarPtr
)
Description

This function inquires about a specified display setting.

Parameters
DisplayId

Specifies the identifier of the display.

InquireType

Specifies the type of display setting about which to inquire. This parameter can be set to one of the following values.

The following InquireType parameter settings are available for windowed and auxiliary displays.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_COLOR_MODE

Returns the display color mode. Returns the display color mode ...

c

UserVarPtr info

Return values:
M_BLUE, M_COLOR, M_GREEN, M_RED (details)
Open Collapse M_DISPLAY_TYPE

Returns the display type. Values can be returned as a combination, for example, M_WINDOWED + M_MIL_WINDOW. Values, other than the ones mentioned below, might be added for auxiliary displays. These values are for internal use, and you should ignore them. Returns the display type ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_AUXILIARY | Display is auxiliary.
M_MIL_WINDOW | Display is a MIL display, selected using the MdispSelect() function.
M_USER_WINDOW | Display is an user-defined display, selected using the MdispSelectWindow() function.
M_WINDOWED | Display is windowed.
Open Collapse M_ENCODER_FILTER

Returns the filter selected for luminance. Returns the filter selected for luminance ...

Use this inquire type only when using the encoder. Otherwise, an error will occur.

a p

UserVarPtr info

Return values:
M_LOW_PASS_0, M_LOW_PASS_1, M_LOW_PASS_2, M_NOTCH (details)
Open Collapse M_ENCODER_PEDESTAL

Returns whether a pedestal should be generated in the composite video signal. Returns whether a pedestal should be generated in the composite video signal ...

Use this inquire type only when using the encoder. Otherwise, an error will occur.

a p

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_FILL_DISPLAY

Returns whether a selected buffer will be zoomed to fill the display. Returns whether a selected buffer will be zoomed to fill the display ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_FORMAT

Returns the display's data format. Returns the display's data format ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: array of type MIL_TEXT_CHAR
Array size: Call MdispInquire() with the InquireType parameter set to M_FORMAT_SIZE.

Return values:
"M_CCIR", "M_DEFAULT", "M_NTSC", "M_NTSC_RGB", "M_NTSC_YC", "M_PAL", "M_PAL_RGB", "M_PAL_YC", "M_RS170", "REMOTEVIEW", "REMOTEVIEW:MONO", "REMOTEVIEW:PSEUDO", "REMOTEVIEW:RGB", "VCF Filename" (details)
Open Collapse M_FORMAT_SIZE

Returns the number of characters in the data format string. Returns the number of characters in the data format string.

a b c d e f g h i j k l m n o p q r
Open Collapse M_INIT_FLAG

Returns the initialization flag specified upon allocating the display. Returns the initialization flag specified upon allocating the display ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_AUXILIARY, M_DEFAULT, M_WINDOWED (details)
Open Collapse M_INTERPOLATION_MODE

Returns the type of interpolation used to display a zoomed image. Returns the type of interpolation used to display a zoomed image ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DEFAULT, M_FAST, M_NEAREST_NEIGHBOR (details)
Open Collapse M_KEY_SUPPORTED

Returns whether transparency (keying) is supported by hardware. Returns whether transparency (keying) is supported by hardware ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_NO | Transparency (keying) is not supported.
M_YES | Transparency (keying) is supported.
Open Collapse M_LUT_ID

Returns the identifier of the LUT buffer associated with the display. Returns the identifier of the LUT buffer associated with the display ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DEFAULT, M_PSEUDO, MIL LUT buffer identifier (details)
Open Collapse M_LUT_SUPPORTED

Returns whether a LUT is supported by the display. Returns whether a LUT is supported by the display ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_NO | LUT is not supported.
M_YES | LUT is supported.
Open Collapse M_NATIVE_CONTROL_ID

Returns the identifier of the Native Library control buffer that is associated with the MIL display. Returns the identifier of the Native Library control buffer that is associated with the MIL display.

c
Open Collapse M_NATIVE_ID

Returns the identifier of the Native Library display that corresponds to the MIL display. Returns the identifier of the Native Library display that corresponds to the MIL display.

c
Open Collapse M_NO_TEARING

Returns the no-tearing mode specified for the selected display. Returns the no-tearing mode specified for the selected display ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_ADVANCED, M_BASIC, M_DEFAULT, M_DISABLE, M_ENABLE, M_GRAB_CONTINUOUS_ONLY (details)
M_ADVANCED + M_NEWEST_SKIP | Specifies that the newest updates are skipped and the update which is currently the oldest is copied to the screen.
M_ADVANCED + M_NO_SKIP | Specifies that none of the updates are skipped and every update waits to be copied to the screen.
M_ADVANCED + M_OLDEST_SKIP | Specifies that the oldest updates are skipped and the update which is currently the newest is copied to the screen.
Open Collapse M_NO_TEARING_ACTIVE

Returns whether MIL is currently using the graphics controller hardware to update the display with no-tearing. Returns whether MIL is currently using the graphics controller hardware to update the display with no-tearing ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_NO | MIL is not currently using the graphics controller hardware to update the display with no-tearing. This value is always returned when MdispControl() with M_NO_TEARING is set to M_DISABLE.
M_YES | MIL is currently using the graphics controller hardware to update the display with no-tearing. Note that depending on the no-tearing mode specified using MdispControl() with M_NO_TEARING, screen-tearing might still occur when the rate at which the display is updated is higher than the refresh rate of the screen.
Open Collapse M_NUMBER

Returns the display's rank in the system. Returns the display's rank in the system ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DEFAULT (details)
Open Collapse M_OVERLAY

Returns whether or not the overlay mechanism is enabled for the display. Returns whether or not the overlay mechanism is enabled for the display ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_OVERLAY_ID

Returns the identifier of the overlay buffer associated with the display or M_NULL. Returns the identifier of the overlay buffer associated with the display or M_NULL ...

Note that the overlay buffer is a normal buffer and, knowing its MIL identifier, you can perform operations on it as you would on a normal buffer (except for grabbing).

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: MIL_ID
Open Collapse M_OVERLAY_SHOW

Returns the visible state of the overlay. Returns the visible state of the overlay ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE, M_OPAQUE (details)
Open Collapse M_OWNER_SYSTEM

Returns the identifier of the system on which the display has been allocated. Returns the identifier of the system on which the display has been allocated ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DEFAULT_HOST, MIL system identifier (details)
Open Collapse M_PIXEL_FORMAT

Returns the pixel format of the current display resolution set by your graphics controller. Allocating a displayable image buffer with the same format will ensure maximum performance with regards to display updates. Returns the pixel format of the current display resolution set by your graphics controller ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_BGR24
M_BGR32
M_MONO8
M_RGB15
M_RGB16
M_YUV16_UYVY
M_YUV16_YUYV

Open Collapse M_SELECTED

Returns the identifier of the image buffer currently displayed. M_NULL is returned if no buffer is currently being displayed. Returns the identifier of the image buffer currently displayed ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIGN

Returns the display's data range. Returns the display's data range ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_UNSIGNED Data range is unsigned.

Open Collapse M_SIZE_BAND

Returns the number of color bands that the display is capable of displaying. Returns the number of color bands that the display is capable of displaying.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_BAND_LUT

Returns the number of color bands of the LUT (if any) associated with the display. Returns the number of color bands of the LUT (if any) associated with the display.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SIZE_BIT

Returns the number of bits (depth) of the display per band. Returns the number of bits (depth) of the display per band.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SYNC_TYPE

Returns which output signal has the synchronization signal encoded. Returns which output signal has the synchronization signal encoded ...

Use this inquire type only when using the encoder. Otherwise, an error will occur.

a p

UserVarPtr info

Return values:
M_ALL, M_DEFAULT, M_DISABLE, M_GREEN, M_SEPARATE (details)
Open Collapse M_TITLE

Returns the display's title. Returns the display's title ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Data type: array of type MIL_TEXT_CHAR
Array size: Determine by calling MdispInquire() with M_TITLE_SIZE.

Return values:
Please see MdispControl() with M_TITLE.

Open Collapse M_TITLE_SIZE

Returns the number of characters in the display's title. Returns the number of characters in the display's title.

a b c d e f g h i j k l m n o p q r
Open Collapse M_TRANSPARENT_COLOR

Returns the transparency (keying) color. Returns the transparency (keying) color ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
8-bit Value, M_DEFAULT (details)
Open Collapse M_TYPE

Returns the display's data type and depth. Returns the display's data type and depth ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
depth value + M_UNSIGNED Data type is unsigned. Depth size is returned in bits.

Open Collapse M_UPDATE

Returns whether MIL should update the display. Returns whether MIL should update the display ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_VIEW_BIT_SHIFT

Returns the number of bits by which the buffer data gets shifted when M_VIEW_MODE is set to M_BIT_SHIFT. Returns the number of bits by which the buffer data gets shifted when M_VIEW_MODE is set to M_BIT_SHIFT ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see MdispControl() with M_VIEW_BIT_SHIFT.

Open Collapse M_VIEW_MODE

Returns how a buffer gets remapped to the display (view mode). Returns how a buffer gets remapped to the display (view mode) ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_AUTO_SCALE, M_BIT_SHIFT, M_DEFAULT, M_MULTI_BYTES, M_TRANSPARENT (details)
Open Collapse M_ZOOM_FACTOR_X

Returns the zoom factor (set using MdispZoom()) in X. Returns the zoom factor (set using MdispZoom()) in X ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Data type: double

Return values:
0.0 < Value <= 16.0 (details)
Open Collapse M_ZOOM_FACTOR_Y

Returns the zoom factor (set using MdispZoom()) in Y. Returns the zoom factor (set using MdispZoom()) in Y ...

a b c d e g h i j k l m n o p q r

UserVarPtr info

Data type: double

Return values:
0.0 < Value <= 16.0 (details)
[All except Matrox Iris]

The following inquire types are only available for windowed displays:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_CENTER_DISPLAY

Returns whether a selected image buffer should be centered in the display. Returns whether a selected image buffer should be centered in the display ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_GDI_COMPATIBLE_OVERLAY

Returns whether the display's overlay buffer is forced to be compatible with GDI operations. You specify this when allocating the display, using MdispAlloc(). Returns whether the display's overlay buffer is forced to be compatible with GDI operations ...

UserVarPtr info

Return values:
M_DISABLE | Returns that the display's overlay buffer might not be compatible with GDI operations.
M_ENABLE | Returns that the display's overlay buffer is forced to be compatible with GDI operations.
Open Collapse M_UPDATE_SYNCHRONIZATION

Returns the update mode currently used by the display for Windows paint messages. Returns the update mode currently used by the display for Windows paint messages ...

UserVarPtr info

Return values:
M_ASYNCHRONOUS, M_DEFAULT, M_SYNCHRONOUS (details)
Open Collapse M_WINDOW_PALETTE_NOCOLLAPSE

Returns whether the Windows palette is forced to be non-collapsed. Returns whether the Windows palette is forced to be non-collapsed ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_RANGE

Returns whether displayed buffer values are restricted to values between 10 and 245 to allow the optimization of display updates. Returns whether displayed buffer values are restricted to values between 10 and 245 to allow the optimization of display updates ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

[All except Matrox Iris]

The following are only available for MIL windowed displays (selected using MdispSelect()) and are not available for user windowed displays (selected using MdispSelectWindow()):

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_WINDOW_HANDLE | Returns the Windows handle (HWND) of the display's window. Returns the Windows handle (HWND) of the display's window.
Open Collapse M_WINDOW_MAXBUTTON | Returns whether the window's maximize button should be visible. Returns whether the window's maximize button should be visible ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_MENU_BAR | Returns whether the menu bar should be present. Returns whether the menu bar should be present ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_MENU_BAR_CHANGE | Returns whether the presence of the menu bar can be toggled. Returns whether the presence of the menu bar can be toggled ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_MINBUTTON | Returns whether the window's minimize button should be visible. Returns whether the window's minimize button should be visible ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_MOVE | Returns whether window movement is allowed. Returns whether window movement is allowed ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_OVERLAP | Returns whether the window can be overlapped by another. Returns whether the window can be overlapped by another ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_RESIZE | Returns whether window resizing is allowed. Returns whether window resizing is allowed ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE, M_FULL_SIZE, M_NORMAL_SIZE (details)
Open Collapse M_WINDOW_SCROLLBAR | Returns whether the window's scroll bars should be visible. Returns whether the window's scroll bars should be visible ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_SIZE_X | Returns the width of the display's window client area. Returns the width of the display's window client area.
Open Collapse M_WINDOW_SIZE_Y | Returns the height of the display's window client area. Returns the height of the display's window client area.
Open Collapse M_WINDOW_SYSBUTTON | Returns whether the window system buttons (minimize, maximize, and close buttons) should be visible. Returns whether the window system buttons (minimize, maximize, and close buttons) should be visible ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_TITLE_BAR | Returns whether the title bar should be visible. Returns whether the title bar should be visible ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_TITLE_BAR_CHANGE | Returns whether the presence of the window's title bar can be toggled. Returns whether the presence of the window's title bar can be toggled ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_WINDOW_ZOOM | Returns whether window zooming is allowed. Returns whether window zooming is allowed ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)

[All except Matrox Iris]

The information returned by the following inquire types has no meaning unless the display is selected to the screen (MdispSelect() or MdispSelectWindow()):

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_PAN_OFFSET_X | Returns the number of pixels in X by which the image buffer is panned. Returns the number of pixels in X by which the image buffer is panned ...
 |  | UserVarPtr info Data type: double Return values: Please see the XOffset parameter of MdispPan().
Open Collapse M_PAN_OFFSET_Y | Returns the number of pixels in Y by which to the image buffer is panned. Returns the number of pixels in Y by which to the image buffer is panned ...
 |  | UserVarPtr info Data type: double Return values: Please see the YOffset parameter of MdispPan().
Open Collapse M_SIZE_X | Returns the display's width. For windowed displays, the returned value is equal to the width of the buffer and not the client area of the window. For auxiliary displays, the returned width is that specified in the VCF file. Returns the display's width ...
Open Collapse M_SIZE_Y | Returns the display's height. For windowed displays, the returned value is equal to the height of the buffer and not the client area of the window. For auxiliary displays, the returned height is that specified in the VCF file. Returns the display's height ...
Open Collapse M_THREAD_PRIORITY | Returns the thread priority. This inquire type is only available for MIL displays selected using the MdispSelect() function. Returns the thread priority ...
 |  | UserVarPtr info Return values: 1 to 6, 7 to 10, 11 to 15, 16; 22 to 26; 31 (details)

[All except Matrox Iris]

The following inquire types are only available with M_WINDOWED displays. The information returned by these inquire types has no meaning unless the display is selected to the screen (MdispSelect() or MdispSelectWindow()):

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_WINDOW_OFFSET_X | Returns the X-offset of the display's window client area, relative to the top-left of the screen (of the primary monitor). Returns the X-offset of the display's window client area, relative to the top-left of the screen (of the primary monitor).
Open Collapse M_WINDOW_OFFSET_Y | Returns the Y-offset of the display's window client area, relative to the top-left of the screen (of the primary monitor). Returns the Y-offset of the display's window client area, relative to the top-left of the screen (of the primary monitor).
Open Collapse M_WINDOW_PAN_X | Returns the position of the horizontal scroll bar in the display's window. Returns the position of the horizontal scroll bar in the display's window.
Open Collapse M_WINDOW_PAN_Y | Returns the position of the vertical scroll bar in the display's window. Returns the position of the vertical scroll bar in the display's window.
Open Collapse M_WINDOW_ZOOM_FACTOR_X | Returns the display's X-zoom factor (as controlled by zoom buttons). Returns the display's X-zoom factor (as controlled by zoom buttons) ...
 |  | UserVarPtr info Data type: double
Open Collapse M_WINDOW_ZOOM_FACTOR_Y | Returns the display's Y-zoom factor (as controlled by zoom buttons). Returns the display's Y-zoom factor (as controlled by zoom buttons) ...
 |  | UserVarPtr info Data type: double

UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type MIL_TEXT_CHAR
  • double
  • long
  • MIL_ID

Specifies the address in which to write the requested information. Since the MdispInquire() function also returns the requested information, you can set this parameter to M_NULL.

Return value
Except for the inquire types that require an address of an array, the returned value is the setting of the requested display setting, cast to long. For the inquire types requiring an address of an array, the returned value is M_NULL.
FORMAT SIZE NO TEARING NO TEARING TITLE SIZE VIEW MODE BIT SHIFT WINDOWED COLOR MODE DISPLAY TYPE ENCODER FILTER ENCODER PEDESTAL FILL DISPLAY FORMAT FORMAT SIZE INTERPOLATION MODE INIT FLAG KEY SUPPORTED LUT ID LUT SUPPORTED NATIVE CONTROL ID NATIVE ID NO TEARING NO TEARING ACTIVE NUMBER OVERLAY OVERLAY ID OVERLAY SHOW OWNER SYSTEM PIXEL FORMAT SELECTED SIGN SIZE BAND SIZE BAND LUT SIZE BIT SYNC TYPE TITLE TITLE SIZE TRANSPARENT COLOR TYPE UPDATE VIEW BIT SHIFT VIEW MODE ZOOM FACTOR X ZOOM FACTOR Y CENTER DISPLAY GDI COMPATIBLE OVERLAY UPDATE SYNCHRONIZATION WINDOW PALETTE NOCOLLAPSE WINDOW RANGE WINDOW HANDLE WINDOW MAXBUTTON WINDOW MENU BAR WINDOW MENU BAR CHANGE WINDOW MINBUTTON WINDOW MOVE WINDOW OVERLAP WINDOW RESIZE WINDOW SCROLLBAR WINDOW SIZE X WINDOW SIZE Y WINDOW SYSBUTTON WINDOW TITLE BAR WINDOW TITLE BAR CHANGE WINDOW ZOOM THREAD PRIORITY PAN OFFSET X PAN OFFSET Y SIZE X SIZE Y WINDOW OFFSET X WINDOW OFFSET Y WINDOW PAN X WINDOW PAN Y WINDOW ZOOM FACTOR X WINDOW ZOOM FACTOR Y


MdispLut

See Also | Example | Availability | MdispInquire | MdispPan
User Guide:
Histogram equalization
Palettes and output LUTs for windowed display (256-color)
Displaying

Reference:
MbufAlloc1d
MbufAllocColor
MdispSelect
mdispwindowleveling.c
mimprocessing.c
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Genesis
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Orion
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL

Partially supported on:
Partially supported on Matrox Iris
Synopsis
Associate a LUT buffer with a display.
Syntax
void MdispLut(
MIL_ID DisplayId,
MIL_ID LutBufId
)
Description

This function associates a LUT buffer with the specified display. If and when the display is selected, the change required to produce the display (LUT) effect occurs. For windowed displays, MIL indirectly programs the physical output LUTs through the use of a Windows palette. MIL checks the target display to determine whether or not a LUT is supported. If not, an error is generated.

LUT buffers used for display have the following restrictions:

  • If the LUT buffer values are changed while the image is selected on the display, the changes will not take effect until the next call is made to MdispLut(). That is, the LUT is not automatically updated when the LUT buffer is modified.
  • In general, the LUT buffer will not be used when displaying a 3-band 8-bit image under a non-8-bit display resolution.
  • The LUT buffer must have one or three bands. Note that the number of LUT buffer entries must be the same as the maximum number of intensities that can be represented in the displayed buffer. In other words, if you want to invert an 8-bit grayscale image (that is, an image that can have 256 intensities), your LUT must also have 256 entries.

Note that, to obtain good results, the specified color values must be carefully selected to provide the best color match for displaying your image. If the specified values closely match the RGB values that occur frequently in the image to be displayed, very good results can be obtained.

For a detailed description of managing LUT buffers and achieving the appropriate display effect, see the Lookup tables in general section in Chapter 15: Lookup tables and the Palettes and output LUTs for windowed display (256-color) section in Chapter 16: Displaying an image.

Parameters
DisplayId

Specifies the identifier of the display to which the LUT buffer is copied.

LutBufId

Specifies the identifier of a previously allocated LUT buffer (with an M_LUT attribute). This parameter should be set to one of the following values:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_DEFAULT

 Specifies that MIL will automatically select the optimal LUT buffer to associate with the display.  Specifies that MIL will automatically select the optimal LUT buffer to associate with the display ...

 For windowed displays, a good default logical palette for the realization of the physical output LUTs is specified. The default logical palette takes into consideration the number of bands of the image, and produces the best performance versus visual quality compromise possible.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_PSEUDO

 Specifies the default pseudo-color LUT buffer as the LUT buffer to associate with the display. The data is loaded in each component of the logical palette for windowed displays. When this LUT is used and displaying an 8-bit image buffer, each gray intensity is displayed in a different color.  Specifies the default pseudo-color LUT buffer as the LUT buffer to associate with the display ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  MIL LUT buffer identifier

 Specifies the identifier of the custom LUT buffer (allocated with MbufAlloc1d() or MbufAllocColor() with M_LUT) to associate with the display.  Specifies the identifier of the custom LUT buffer (allocated with MbufAlloc1d() or MbufAllocColor() with M_LUT) to associate with the display ...

 If you associate a one-band LUT buffer with a windowed display, and then select the display (MdispSelect()), the same data is loaded in each component of the logical palette.

 If you associate a three-band color LUT buffer (RGB) for a windowed display, and then select the display, each band of the LUT buffer is loaded into its corresponding component of the logical palette.

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

LUT LUT   DEFAULT PSEUDO


MdispPan

Example | Availability | MdispLut | MdispSelect
There are no examples containing MdispPan().
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Genesis
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Orion
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL

Not supported on:
Not supported on Matrox Iris
Synopsis
Pan and scroll a display.
Syntax
void MdispPan(
MIL_ID DisplayId,
double XOffset,
double YOffset
)
Description

This function associates pan and scroll values with the specified display. When an image buffer is selected for display, it will be panned and scrolled on the display according to these values.

Note, the offsets (XOffset and YOffset) are in image pixels (not pixels), so they are not affected by the current zoom factor. For example, if the display has an associated zoom factor of 4, panning by an offset of one image pixel results in panning by 4 on the display.

Parameters
DisplayId

Specifies the identifier of the display.

XOffset

Specifies the number of pixels by which to pan an image buffer when it is displayed. Specify the pan relative to the top-left corner of the image buffer. Specify a positive offset value to pan the image to the left.

YOffset

Specifies the number of pixels by which to scroll an image buffer when it is displayed. Specify the scroll relative to the top-left corner of the image buffer. Specify a positive offset value to scroll the image upwards.


MdispSelect

See Also | Example | Availability | MdispPan | MdispSelectWindow
User Guide:
Allocating and displaying an image buffer
Attribute
Manipulating and controlling certain data buffer areas
Overview
Removing a buffer from the display
Displaying multiple buffers
Displaying an image in a user-defined window
Grabbing to the display
Displaying

Reference:
MdispControl
MdispPan
MdispZoom
channel_switch.c
dtkaddconstantmain.c
dtkobjecttracking.c
dtkremap.c
mblob.c
mbufbayercolorfilter.c
mbufcolor.c
mcal.c
mcode.c
mdblgrab.c
mdigautofocus.c
mdiggrabmultiple.c
mdiggrabsequence.c
mdigmultdestination.c
mdigmultformat.c
mdigprocessmultiple.c
mdigsubtract.c
mdispoverlay.c
mdispselect.c
mdispwindow.c
mdispwindowleveling.c
medge.c
mfunc.c
mgenlc.c
mheliosconcurent.c
mimconvolve.c
mimfft.c
mimhistogram.c
mimmorphic.c
mimperimeter.c
mimpolar.c
mimprocessing.c
mimsegment.c
mimwarp.c
mmeas.c
mmet2dig.c
mmod.c
mmorphisjpeg2000.c
mnatfct.c
mocr.c
mpat.c
mstr.c
mthread.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Select an image buffer to display.
Syntax
void MdispSelect(
MIL_ID DisplayId,
MIL_ID ImageBufId
)
Description

This function outputs the content of the specified image buffer to the specified MIL display. You can only display one buffer at a time on a specific display.

For a windowed display, a call to MdispSelect() creates a window surrounding the image. The window is created to fit the image if the image is smaller in size than the desktop. Otherwise, the right and bottom portion of the image, the part that exceeds the desktop, is not displayed. You can control the displayed area using MdispControl(), MdispPan(), or MdispZoom(). For example, you can center the selected image in the display using MdispControl() with M_CENTER_DISPLAY.

For an auxiliary display, the image is displayed at the top-left corner of an auxiliary screen. The border outside the image is blanked out if the image is smaller in size than the screen area (if the hardware supports this). Otherwise, the right and bottom portion of the image, the part that exceeds the display size, is not displayed. You can control the displayed area using MdispPan() or MdispZoom().

Use MdispSelect() with M_NULL to stop displaying the currently selected image buffer on the specified display. For windowed displays, the display is closed. For auxiliary displays, the display is blanked.

You can only remove the entire image buffer from the display. Therefore, when displaying a parent buffer, you cannot remove one of its child buffers from the display.

Note that it is not necessary to stop displaying the image buffer before selecting another buffer for display.

Parameters
DisplayId

Specifies the identifier of the display.

ImageBufId

Specifies the image buffer to display. To be displayable, this buffer must be an image buffer that has an M_IMAGE + M_DISP attribute.

Set this parameter to M_NULL to stop displaying the currently selected image buffer on the specified display.

CENTER DISPLAY IMAGE DISP


MdispSelectWindow

See Also | Example | Availability | MdispSelect | MdispZoom
User Guide:
Displaying an image in a user-defined window

Reference:
MdispSelect
mdispwindow.c
Available in MIL-Lite

Available in MIL
Synopsis
Select an image buffer to display in a user-defined window.
Syntax
void MdispSelectWindow(
MIL_ID DisplayId,
MIL_ID ImageBufId,
HWND ClientWindowHandle
)
Description

This function displays the specified image buffer contents in the specified user window, using the specified MIL display.

This function is valid only in a Windows environment.

Parameters
DisplayId

Specifies the identifier of the display.

ImageBufId

Specifies the image buffer to display. To be displayable, this buffer must be an image buffer that has an M_IMAGE + M_DISP attribute.

If the specified image buffer is smaller in size than the target window size, the border outside the image is not modified. If the specified buffer is larger in size than the target window, the right and bottom portion of the buffer, the part that exceeds the window, is not displayed.

ClientWindowHandle

Specifies the handle of the user-defined window or child window. This window must have been created with the Windows API functions. If this parameter is set to zero, this function behaves like MdispSelect().

IMAGE DISP


MdispZoom

See Also | Example | Availability | MdispSelectWindow
User Guide:
Panning and zooming

Reference:
MdispPan
mimconvolve.c
Available in MIL-Lite

Available in MIL
Synopsis
Zoom a display.
Syntax
void MdispZoom(
MIL_ID DisplayId,
double XFactor,
double YFactor
)
Description

This function associates a zoom factor with the specified display. When an image buffer is selected for display, it will be zoomed according to this factor. The image buffer will be displayed starting from its top-left corner, unless it has been panned and/or scrolled, using MdispPan().

Parameters
DisplayId

Specifies the identifier of the display.

XFactor

Sets the X zoom factor. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse 0.0 < Value <= 16.0

 Specifies the zoom factor.  Specifies the zoom factor.

 YFactor

 Sets the Y zoom factor.  This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  0.0 < Value <= 16.0

 Specifies the zoom factor.  Specifies the zoom factor.


edge

Medge functions

Example | Availability
There are no examples containing edge().
Not available in MIL-Lite

Available in MIL
Synopsis
The MIL Edge Finder module provides powerful operations that allow you to extract geometric primitives in images such as object contours or thin curvilinear shapes. The module offers many settings including image processing controls, feature controls, and annotations controls. It also provides analysis capabilities allowing for the advanced manipulations of results. The Edge Finder module can also be used in conjunction with the MIL Geometric Model Finder module; that is, you can define models from the result of an edge extraction, or you can find occurrences in the result of an edge extraction. The Edge Finder module offers complete support for calibration. Extraction of edges can be performed in the calibrated real-world such that, even without physically correcting your images, results are in real-world units.
Functions
  • MedgeAlloc
  • MedgeAllocResult
  • MedgeCalculate
  • MedgeControl
  • MedgeDraw
  • MedgeFree
  • MedgeGetNeighbors
  • MedgeGetResult
  • MedgeInquire
  • MedgeMask
  • MedgePut
  • MedgeRestore
  • MedgeSave
  • MedgeSelect
  • MedgeStream


MedgeAlloc

See Also | Example | Availability | MedgeAllocResult
User Guide:
Steps to performing an edge extraction and analysis
Extracting the edges
Customizing the edge extraction settings
Calculating and retrieving results

Reference:
MedgeCalculate
MedgeControl
MedgeFree
MsysAlloc
medge.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate an Edge Finder context.
Syntax
MIL_ID MedgeAlloc(
MIL_ID SystemId,
long EdgeFinderType,
long ControlFlag,
MIL_ID *ContextIdPtr
)
Description

This function allocates an Edge Finder context on the specified system. An Edge Finder context contains all the information necessary to perform an MedgeCalculate() operation, including global processing settings, and edge features to calculate. When the Edge Finder context is no longer required, you should release its memory, using MedgeFree().

Edge Finder context settings can be adjusted using MedgeControl().

Parameters
SystemId

Specifies the system on which to allocate the Edge Finder context.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 EdgeFinderType

 Specifies the type of Edge Finder context.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_CONTOUR

 Specifies a contour context type, which is used to find object contours in images.  Specifies a contour context type, which is used to find object contours in images.

  Open   Collapse  M_CREST

 Specifies a crest context type, which is used to find thin line crests in images.  Specifies a crest context type, which is used to find thin line crests in images.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 ContextIdPtr

 Specifies the address of the variable in which to write the Edge Finder context identifier.  Since the MedgeAlloc() function also returns the edeg finder context identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the Edge Finder context's identifier. If allocation fails, M_NULL is returned.

 DEFAULT HOST   CONTOUR CREST


MedgeAllocResult

See Also | Example | Availability | MedgeAlloc | MedgeCalculate
User Guide:
Defining and adding models to your Model Finder context
Search targets
Steps to performing an edge extraction and analysis
Calculating and retrieving results

Reference:
MedgeCalculate
MedgeFree
MsysAlloc
medge.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate an Edge Finder result buffer.
Syntax
MIL_ID MedgeAllocResult(
MIL_ID SystemId,
long ControlFlag,
MIL_ID *EdgeResultIdPtr
)
Description

This function allocates an Edge Finder result buffer, on the specified system, to store results obtained from an MedgeCalculate() operation. When the Edge Finder result buffer is no longer required, release its memory, using MedgeFree().

Parameters
SystemId

Specifies the system on which to allocate the Edge Finder result buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 EdgeResultIdPtr

 Specifies the address of the variable in which to write the Edge Finder result buffer identifier.  Since the MedgeAllocResult() function also returns the Edge Finder result buffer identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the Edge Finder result buffer identifier. If allocation fails, M_NULL is returned.

 DEFAULT HOST


MedgeCalculate

See Also | Example | Availability | MedgeAllocResult | MedgeControl
User Guide:
Defining and adding models to your Model Finder context
Search targets
Steps to performing an edge extraction and analysis
Basic concepts
Calculating and retrieving results
Advanced edge extraction
Interfacing with the Geometric Model Finder module

Reference:
MedgeAlloc
MedgeAllocResult
MedgeControl
MedgeSelect
medge.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Iris
Synopsis
Perform edge extraction and feature calculations.
Syntax
void MedgeCalculate(
MIL_ID ContextId,
MIL_ID SourceImageId,
MIL_ID SourceDeriv1Id,
MIL_ID SourceDeriv2Id,
MIL_ID SourceDeriv3Id,
MIL_ID EdgeResultId,
long ControlFlag
)
Description

This function extracts edges and calculates edge features in the source image buffer or in the derivative image buffers. You can also use this function to perform post-calculations on included edges of an Edge Finder result buffer.

Results are stored in the specified Edge Finder result buffer. Select which edge features to calculate with MedgeControl(). Include, exclude, or delete edges that meet a specified criterion with MedgeSelect(). Note that to calculate new features and/or select features of a new set of edges, MedgeCalculate() must be called after MedgeControl() and/or MedgeSelect().

If the source image or derivative images are calibrated, results are calculated in the world coordinate system, otherwise they are calculated in the image coordinate system.

If the source image or derivative images are calibrated, you can retrieve results in real-world or in pixel units. However, in the presence of distortion, some results are meaningless when converted from real-world to pixel units (for example, Feret angles). For example, if an edge appears warped in the source image, but the calibration object of the source image compensates for this during the extraction, the resulting Feret angles are meaningful in the real-world coordinate system, and meaningless in the image coordinate system.

Calculations are typically done on a source image buffer (SourceImageId), where MedgeCalculate() calculates the required derivative image buffers that are used to extract edges. In this case, the derivative image buffers (SourceDeriv1Id, SourceDeriv2Id, and SourceDeriv3Id) must be set to M_NULL. However, if you specify your own derivative image buffers, the edge extraction process is done with them instead. In this case, SourceImageId must be set to M_NULL. Note that, when specifying your own derivative image buffers, the majority of processing control settings remain in effect, except for filter settings (for example, M_FILTER_SMOOTHNESS).

To avoid repeatedly calculating time-consuming edge features for all edges in a source image, MedgeCalculate() can also perform post-calculations on included edges of an Edge Finder result buffer. That is, once the results of a calculation have been stored in an Edge Finder result buffer, you can select a subset of edges from that Edge Finder result buffer (with MedgeSelect()) and/or add new features for calculation to that Edge Finder result buffer (with MedgeControl()), and then perform the post-calculation with MedgeCalculate(). In this case, processing time greatly decreases since calculations are not unnecessarily repeated. The operation of selecting edges and adding new features can be repeated until the required result is calculated. To perform post-calculations on the included edges of an Edge Finder result buffer, set SourceImageId, SourceDeriv1Id, SourceDeriv2Id, and SourceDeriv3Id to M_NULL.

Note that there are some restrictions when post-calculating edges; for more information, see the Post-calculation subsection in the Calculating and retrieving results section in Chapter 9: Edge Finder.

Parameters
ContextId

Specifies the Edge Finder context to use for the extraction. The Edge Finder context must have been previously allocated on the required system using MedgeAlloc().

SourceImageId

Specifies the source image buffer from which to extract edges. Typically, the source image buffer should be 1-band 8-bit unsigned. Other buffer depths and types are generally accepted, but can slightly decrease performance. Note that 3-band source image buffers are only supported when extracting edge contours. When the source image buffer is 32-bit float, Edge Finder uses floating-point precision calculations.

If you specify your own derivative image buffers, or if you are performing post-calculations on the included edges of an Edge Finder result buffer, this parameter must be set to M_NULL.

SourceDeriv1Id

Specifies the X-source derivative image buffer used to extract edges. When the Edge Finder context type is M_CONTOUR, SourceDeriv1Id specifies the first derivative of the image in the X-direction. When the Edge Finder context type is M_CREST, SourceDeriv1Id specifies the second derivative of the image in the X-direction.

Derivative image buffers must be 1-band 16-bit signed or 1-band 32-bit float. In addition, all derivative image buffers must be consistent (for example, they must have the same scaling factor), and they must be of the same type and size. When the derivative image buffers are 32-bit float, Edge Finder uses floating-point precision calculations.

If you specify a source image buffer, or if you are performing post-calculations on the included edges of an Edge Finder result buffer, this parameter must be set to M_NULL.

SourceDeriv2Id

Specifies the Y-source derivative image buffer used to extract edges. When the Edge Finder context type is M_CONTOUR, SourceDeriv2Id specifies the first derivative of the image in the Y-direction. When the Edge Finder context type is M_CREST, SourceDeriv2Id specifies the second derivative of the image in the Y-direction.

Derivative image buffers must be 1-band 16-bit signed or 1-band 32-bit float. In addition, all derivative image buffers must be consistent (for example, they must have the same scaling factor), and they must be of the same type and size. When the derivative image buffers are 32-bit float, Edge Finder uses floating-point precision calculations.

If you specify a source image buffer, or if you are performing post-calculations on the included edges of an Edge Finder result buffer, this parameter must be set to M_NULL.

SourceDeriv3Id

Specifies the source cross-derivative image buffer used to extract edges. The cross-derivative can only be specified if the Edge Finder context type is M_CREST. If the Edge Finder context type is M_CONTOUR, set SourceDeriv3Id to M_NULL.

Derivative image buffers must be 1-band 16-bit signed or 1-band 32-bit float. In addition, all derivative image buffers must be consistent (for example, they must have the same scaling factor), and they must be of the same type and size. When the derivative image buffers are 32-bit float, Edge Finder uses floating-point precision calculations.

If you specify a source image buffer, or if you are performing post-calculations on the included edges of an Edge Finder result buffer, this parameter must be set to M_NULL.

EdgeResultId

Specifies the Edge Finder result buffer in which to write the results of the extraction. The Edge Finder result buffer must have been previously allocated on the required system using MedgeAllocResult().

[Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

The Edge Finder result buffer (EdgeResultId) must be allocated on the same system as the Edge Finder context (ContextId). If it is not, an error will occur.

ControlFlag

Specifies whether optimal performance during Edge Finder calculations is ensured. This parameter can only be used when providing derivative image buffers. When providing a source image buffer, optimal performance is always ensured; therefore, this parameter must be set to M_DEFAULT.

When providing derivative image buffers, this parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that optimal performance is not ensured.  Specifies that optimal performance is not ensured.

  Open   Collapse  M_NO_CHECK

 Specifies that optimal performance is ensured. M_NO_CHECK should only be used if each derivative image buffer has pixel values that do not go beyond the range of positive or negative 1024 (that is, signed 10-bit values). This ensures optimal performance since Edge Finder does not have to verify unnecessary values.  Specifies that optimal performance is ensured. M_NO_CHECK should only be used if each derivative image buffer has pixel values that do not go beyond the range of positive or negative 1024 (that is, signed 10-bit values) ...

FILTER SMOOTHNESS CONTOUR CREST CONTOUR CREST CREST CONTOUR NO CHECK        DEFAULT  NO CHECK


MedgeControl

See Also | Example | Availability | MedgeCalculate | MedgeDraw
User Guide:
Defining and adding models to your Model Finder context
Search targets
Steps to performing an edge extraction and analysis
Extracting the edges
Customizing the edge extraction settings
Edge features
Calculating and retrieving results
Advanced edge extraction
Interfacing with the Geometric Model Finder module

Reference:
MedgeAlloc
MedgeAllocResult
MedgeCalculate
MedgeDraw
MedgeGetNeighbors
MedgeInquire
MedgeMask
MedgeSelect
medge.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Genesis
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Orion
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Synopsis
Control an Edge Finder context or an Edge Finder result buffer setting.
Syntax
void MedgeControl(
MIL_ID ContextOrResultId,
long ControlType,
double ControlValue
)
Description

This function sets the specified control for either an Edge Finder context, or an Edge Finder result buffer. For Edge Finder contexts, these settings control the execution of MedgeCalculate() operations and select which edge features MedgeCalculate() should calculate. For Edge Finder result buffers, these settings control the post manipulation of results. For example, to draw a zoomed region of the source image that was used to calculate results, the drawing control values must be appropriately set. Similarly, to select edges based on the proximity of an edge or edges to a specified point, M_NEAREST_NEIGHBOR_RADIUS must be appropriately set. For more information, see MedgeDraw() or MedgeSelect().

All control settings can typically be inquired with MedgeInquire().

For new context settings to take effect, you must calculate the settings, using MedgeCalculate().

Note that some control settings have post-calculation restrictions. For more information, see the Post-calculation subsection in the Calculating and retrieving results section in Chapter 9: Edge Finder.

Parameters
ContextOrResultId

Specifies either the Edge Finder context or the Edge Finder result buffer whose settings you want to modify. The Edge Finder context or the Edge Finder result buffer must have been previously allocated on the required system using MedgeAlloc() or MedgeAllocResult(), respectively.

ControlType

Specifies the setting to change.

See the Parameter associations section for possible values.

ControlValue

Specifies the setting's new value.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

The following ControlType and corresponding ControlValue parameter settings are used to control the Edge Finder context operation settings and can be specified for both M_CONTOUR and M_CREST Edge Finder contexts, unless otherwise specified.

Open Collapse ControlType Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
ControlValue
Open Collapse M_ACCURACY

Sets the edgel accuracy of the edge extraction. Accuracy depends on the image's dynamic range, sharpness, and noise. The best accuracy is achieved in well-contrasted noise-free images. Sets the edgel accuracy of the edge extraction ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_HIGH.

a b c d e f g h i j k l m n o p q r
M_DISABLE

Specifies that edgel accuracy will be disabled. Edgels will be calculated with pixel accuracy.

a b c d e f g h i j k l m n o p q r
M_HIGH

Specifies high accuracy. Edgels will be calculated with subpixel accuracy.

a b c d e f g h i j k l m n o p q r
M_VERY_HIGH

Specifies very high accuracy. Edgels will be calculated with very precise subpixel accuracy. M_VERY_HIGH uses a classical camera model to compensate for any pixel-distortion aberration.

a b c d e f g h i j k l m n o p q r
Open Collapse M_CHAIN_ALL_NEIGHBORS

Sets how edge chains are built. Sets how edge chains are built ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_DISABLE.

a b c d e f g h i j k l m n o p q r
M_DISABLE

Specifies that edge chains are built using an 8-connected lattice. That is, each pixel can be connected to a maximum of two neighboring pixels.

a b c d e f g h i j k l m n o p q r
M_ENABLE

Specifies that edge chains are built using an 8-connected lattice, and all the available neighboring edgels. That is, each pixel can be connected to more than two neighboring pixels. Enabling M_CHAIN_ALL_NEIGHBORS can result in slightly longer, though more accurate, calculations.

a b c d e f g h i j k l m n o p q r
Open Collapse M_DETAIL_LEVEL

Sets the level of details to extract from the image. The detail level determines what is considered an edge/background. A higher detail level will include more edges than a lower detail level. Sets the level of details to extract from the image ...

Essentially, M_DETAIL_LEVEL sets the threshold mode of the Edge Finder context. Note that an M_DETAIL_LEVEL setting overrides an M_THRESHOLD_MODE setting.

Typically, M_DETAIL_LEVEL is used when interfacing with the MIL Geometric Model Finder module. Otherwise, M_THRESHOLD_MODE should be used instead.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_MEDIUM.

a b c d e f g h i j k l m n o p q r
M_HIGH

Sets the detail level to high.

a b c d e f g h i j k l m n o p q r
M_MEDIUM

Sets the detail level to medium.

a b c d e f g h i j k l m n o p q r
M_VERY_HIGH

Sets the detail level to very high.

a b c d e f g h i j k l m n o p q r
Open Collapse M_EXTRACTION_SCALE

Sets the image scale at which to extract the edges. Sets the image scale at which to extract the edges ...

Sets the scale of the image at which to do the edge extraction. Once the extraction is complete, the results are scaled to the original scale of the image.

A lower extraction scale speeds up the the search but can result in a less reliable result, including, the loss of important details and/or a reduction in the accuracy of the search results.

M_EXTRACTION_SCALE is for advanced users of the EdgeFinder module. The default setting usually provides the most accurate search results.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is 1.0.

a b c d e f g h i j k l m n o p q r
0 < Value <= 1

Specifies the extraction scale.

a b c d e f g h i j k l m n o p q r
Open Collapse M_FILTER_MODE

Sets the mode in which to perform the edge extraction filter. Typically, M_FILTER_MODE only affects M_DERICHE and M_SHEN filter types. The filter type is set using MedgeControl() with M_FILTER_TYPE. Sets the mode in which to perform the edge extraction filter ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default filter mode. The default is typically set to the most efficient mode.

If special hardware is available to perform the convolution, the default is M_KERNEL.

If special hardware is not available to perform the convolution, the default is M_RECURSIVE.

a b c d e f g h i j k l m n o p q r
M_KERNEL

Specifies the use of a non-recursive implementation of the filter.

In this case, a kernel is used to perform the neighborhood operation. To set the size of the filter's convolution kernel, use MedgeControl() with M_KERNEL_WIDTH. Note that the size of the kernel can be constrained by the available hardware resources.

When using an Infinite Impulse Response (IIR) filter in this mode, the filtering is done using a kernel approximation (Finite Impulse Response) of the filter.

Typically, you would only use M_KERNEL if dedicated hardware is available to perform the convolution.

a b c d e f g h i j k l m n o p q r
Specifics

When using an IIR filter, this mode is not as efficient as M_RECURSIVE for large kernels.

a b c f g h i j k l m n o p q r
M_RECURSIVE

Specifies the use of a recursive implementation of an Infinite Impulse Response (IIR) filter, when applicable.

If this mode actually used a kernel, the kernel size would be theoretically infinite.

a b c d e f g h i j k l m n o p q r
Open Collapse M_FILTER_SMOOTHNESS

Sets the degree of smoothness (strength of denoising) applied by the filter during the neighborhood operation. Sets the degree of smoothness (strength of denoising) applied by the filter during the neighborhood operation ...

M_FILTER_SMOOTHNESS only has an effect if MedgeControl() with M_FILTER_TYPE is set to M_DERICHE or M_SHEN.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is 50.0.

a b c d e f g h i j k l m n o p q r
0.0 to 100.0

Specifies the smoothness value.

A value of 100.0 results in a strong noise reduction effect, while a value of 0.0 has almost no noise reduction effect.

a b c d e f g h i j k l m n o p q r
Open Collapse M_FILTER_TYPE

Sets the type of filter used when performing the neighborhood operation used to extract edges. The type of filter determines the distribution of the neighborhoods' influence. Sets the type of filter used when performing the neighborhood operation used to extract edges ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_SHEN.

a b c d e f g h i j k l m n o p q r
M_DERICHE

Specifies a Canny-Deriche infinite support filter. This is an exponential weighting function, of the general form:

Canny-Deriche is considered to be an Infinite Impulse Response (IIR) filter.

For the Canny-Deriche filter, the neighborhoods' influence decreases much slower as the distance from the central pixel increases, compared to the Shen-Castan filter (M_SHEN).

M_DERICHE can be used with both M_CONTOUR and M_CREST Edge Finder contexts. Typically, M_DERICHE is used for unusually thick crests.

M_DERICHE allows you to use Edge Finder's smoothing capabilities. To do so, use MedgeControl() with M_FILTER_SMOOTHNESS.

M_DERICHE allows you to control the filter mode used to calculate edges. To do so, use MedgeControl() with M_FILTER_MODE.

a b c d e f g h i j k l m n o p q r
M_FREI_CHEN

Specifies a Frei Chen filter. This is a Finite Impulse Response (FIR) filter that can be represented with the following convolution kernels:

M_FREI_CHEN can only be used with M_CONTOUR Edge Finder contexts. Also, when using M_FREI_CHEN, you cannot smooth images using MedgeControl() with M_FILTER_SMOOTHNESS.

a b c d e f g h i j k l m n o p q r
M_PREWITT

Specifies a Prewitt filter. This is a Finite Impulse Response (FIR) filter that can be represented with the following convolution kernels:

M_PREWITT can only be used with M_CONTOUR Edge Finder contexts. Also, when using M_PREWITT, you cannot smooth images using MedgeControl() with M_FILTER_SMOOTHNESS.

a b c d e f g h i j k l m n o p q r
M_SHEN

Specifies a Shen-Castan infinite support exponential filter. This is an exponential weighting function, of the general form:

Shen-Castan is considered to be an Infinite Impulse Response (IIR) filter.

For the Shen-Castan filter, the neighborhoods' influence decreases much faster as the distance from the central pixel increases, compared to the Canny-Deriche filter (M_DERICHE).

M_SHEN can be used with both M_CONTOUR and M_CREST Edge Finder contexts. Typically, M_SHEN performs an excellent edge extraction on most images; however, if you are extracting unusually thick crests that yield inappropriate results, you should use M_DERICHE.

M_SHEN allows you to use Edge Finder's smoothing capabilities. To do so, use MedgeControl() with M_FILTER_SMOOTHNESS.

M_SHEN allows you to control the filter mode used to calculate edges. To do so, use MedgeControl() with M_FILTER_MODE.

a b c d e f g h i j k l m n o p q r
M_SOBEL

Specifies a Sobel filter. This is a Finite Impulse Response (FIR) filter that can be represented with the following convolution kernels:

M_SOBEL can only be used with M_CONTOUR Edge Finder contexts. Also, when using M_SOBEL, you cannot smooth images using MedgeControl() with M_FILTER_SMOOTHNESS.

a b c d e f g h i j k l m n o p q r
Open Collapse M_FLOAT_MODE

Sets whether to force all the processing of edge extraction operations to be performed using floating-point precision calculations. Sets whether to force all the processing of edge extraction operations to be performed using floating-point precision calculations ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_DISABLE.

a b c d e f g h i j k l m n o p q r
M_DISABLE

Specifies that all edge extractions are not forced to be performed using floating-point precision calculations.

a b c d e f g h i j k l m n o p q r
M_ENABLE

Specifies that all edge extractions are forced to be performed using floating-point precision calculations.

a b c d e f g h i j k l m n o p q r
Open Collapse M_KERNEL_DEPTH

Sets the depth of the convolution kernel used for the kernel filtering mode. M_KERNEL_DEPTH is ignored unless MedgeControl() with M_FILTER_MODE is set to M_KERNEL. Sets the depth of the convolution kernel used for the kernel filtering mode ...

Typically, M_KERNEL_DEPTH only affects Infinite Impulse Response (IIR) type filters, which you can set using MedgeControl() with M_FILTER_TYPE.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default depth of the convolution kernel. The default is 8-bit.

a b c d e f g h i j k l m n o p q r
8

Specifies an 8-bit kernel depth. This is faster, though less accurate, than using a 16-bit kernel depth.

a b c d e f g h i j k l m n o p q r
16

Specifies a 16-bit kernel depth. This is slower, though more accurate, than using an 8-bit kernel depth.

a b c d e f g h i j k l m n o p q r
Open Collapse M_KERNEL_WIDTH

Sets the maximum X and Y size of the convolution kernel used for kernel filtering modes. Sets the maximum X and Y size of the convolution kernel used for kernel filtering modes ...

The size of the kernel can be constrained by the available hardware resources. Larger kernels result in longer processing times.

M_KERNEL_WIDTH is ignored unless MedgeControl() with M_FILTER_MODE is set to M_KERNEL.

Typically, M_KERNEL_WIDTH only affects Infinite Impulse Response (IIR) type filters, which you can set using MedgeControl() with M_FILTER_TYPE.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_AUTO.

a b c d e f g h i j k l m n o p q r
M_AUTO

Specifies the maximum X and Y size of the convolution kernel automatically, for a given smoothness factor. You can set the smoothness factor using MedgeControl() with M_FILTER_SMOOTHNESS.

The size of the kernel, for a given smoothness factor, is calculated as the size beyond which the quantified filter values are zero. If the smoothness factor calls for a kernel size that is beyond the limits of your hardware, the smoothness will be sacrificed to achieve the largest possible kernel size.

a b c d e f g h i j k l m n o p q r
Value >= 3

Specifies the maximum X and Y size of the convolution kernel directly. Only odd integer values are accepted.

If your hardware cannot handle the kernel size, the effective smoothness factor will be saturated to the maximum possible value for the specified kernel size. You can set the smoothness factor using MedgeControl() with M_FILTER_SMOOTHNESS.

a b c d e f g h i j k l m n o p q r
Open Collapse M_MAGNITUDE_TYPE

Sets how to calculate the magnitude of the edge at each edgel position. Sets how to calculate the magnitude of the edge at each edgel position ...

Note that for M_CONTOUR Edge Finder contexts, the magnitude is the norm of the gradient vector at the edgel position. For M_CREST Edge Finder contexts, the magnitude is equal to the maximum eigenvalue of the Hessian matrix at the edgel position.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value.

For M_CONTOUR Edge Finder contexts, the default is M_SQR_NORM. For M_CREST Edge Finder contexts, the default is M_NORM.

a b c d e f g h i j k l m n o p q r
M_NORM

Specifies that the magnitude will be used.

a b c d e f g h i j k l m n o p q r
M_SQR_NORM

Specifies that the square of the magnitude will be used.

This value optimizes the edge extraction operation while still preserving a very good edgel position accuracy. M_SQR_NORM is calculated faster than M_NORM, though it is less accurate.

a b c d e f g h i j k l m n o p q r
Open Collapse M_OVERSCAN

Sets the type of overscan used to handle the source image's bordering pixels. Sets the type of overscan used to handle the source image's bordering pixels ...

M_OVERSCAN is ignored if MedgeControl() with M_FILTER_MODE is set to M_RECURSIVE.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that MIL automatically selects the type of overscan that optimizes speed and logic according to the specified operation and the current processing system.

a b c d e f g h i j k l m n o p q r
M_DISABLE

Specifies that no overscan will be used. When overscan is disabled, the border pixels of the source image are not processed by the neighborhood operation if additional processing time is needed.

a b c d e f g h i j k l m n o p q r
M_MIRROR

Specifies that the border pixels of a source image are processed using overscan pixel values that mirror the source buffer pixel values. That is, the overscan pixel values will be a mirror copy of the source buffer's borders. For example:

a b c d e f g h i j k l m n o p q r
M_REPLACE

Specifies that the border pixels of a source image are processed using overscan pixel values set to the overscan replacement value (MedgeControl() with M_OVERSCAN_REPLACE_VALUE).

a b c d e f g h i j k l m n o p q r
M_TRANSPARENT

Specifies that the border pixels of a source image are processed using transparent overscan pixel values. That is, the overscan pixel values will be those of the parent buffer. If they are not available, a mirror type overscan is used instead.

a b c d e f g h i j k l m n o p q r
Open Collapse M_OVERSCAN_REPLACE_VALUE

Sets a replacement value for the overscan pixel values. Note that M_OVERSCAN_REPLACE_VALUE is ignored unless M_OVERSCAN with MedgeControl() is set to M_REPLACE. In addition, M_OVERSCAN_REPLACE_VALUE is ignored if MedgeControl() with M_FILTER_MODE is set to M_RECURSIVE. Sets a replacement value for the overscan pixel values ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is 0.

a b c d e f g h i j k l m n o p q r
M_REPLACE_MAX

Specifies that the overscan neighborhood pixel values will be set to the maximum value of the source image buffer.

a b c d e f g h i j k l m n o p q r
M_REPLACE_MIN

Specifies that the overscan neighborhood pixel values will be set to the minimum value of the source image buffer.

a b c d e f g h i j k l m n o p q r
Value

Specifies the value of the overscan neighborhood pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_THRESHOLD_HIGH

Sets the upper bound of the hysteresis threshold value. M_THRESHOLD_HIGH is ignored unless MedgeControl() with M_THRESHOLD_MODE is set to M_USER_DEFINED. Note that lower threshold values result in a more sensitive edgel detection; that is, a higher (or equal) number of edgels are detected. Sets the upper bound of the hysteresis threshold value ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is 0.0.

a b c d e f g h i j k l m n o p q r
Value

Specifies the upper bound of the hysteresis threshold.

a b c d e f g h i j k l m n o p q r
Open Collapse M_THRESHOLD_LOW

Sets the lower bound of the hysteresis threshold value. M_THRESHOLD_LOW is ignored unless MedgeControl() with M_THRESHOLD_MODE is set to M_USER_DEFINED. Sets the lower bound of the hysteresis threshold value ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies the default value. The default value is 0.0.

a b c d e f g h i j k l m n o p q r
Value

Specifies the lower bound of the hysteresis threshold.

a b c d e f g h i j k l m n o p q r
Open Collapse M_THRESHOLD_MODE

Sets the threshold of the edge extraction. The Edge Finder module uses a classical hysteresis threshold to extract relevant edges in the image. Threshold values can either be set manually or determined automatically by the Edge Finder module. Note that lower threshold values result in a more sensitive edgel detection; that is, a higher (or equal) number of edgels are detected. Sets the threshold of the edge extraction ...

When interfacing with the MIL Geometric Model Finder module, you should use M_DETAIL_LEVEL to set the threshold mode. Note that an M_DETAIL_LEVEL setting overrides an M_THRESHOLD_MODE setting.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_HIGH.

a b c d e f g h i j k l m n o p q r
M_DISABLE

Specifies no threshold. All edges are extracted.

a b c d e f g h i j k l m n o p q r
M_HIGH

Specifies a high threshold. M_HIGH should be used for images with some contrast variations, noise, and non-uniform illumination. M_HIGH always results in a lower (or equal) number of edgels than M_MEDIUM.

a b c d e f g h i j k l m n o p q r
M_LOW

Specifies a low threshold. All edges over a minimum noise-based estimated threshold are extracted. M_LOW always results in a lower (or equal) number of edgels than M_DISABLE.

a b c d e f g h i j k l m n o p q r
M_MEDIUM

Specifies a medium threshold. M_MEDIUM should be used for multi-contrast images, or for images with a lot of noise or non-uniform illumination. M_MEDIUM always results in a lower (or equal) number of edgels than M_LOW.

a b c d e f g h i j k l m n o p q r
M_USER_DEFINED

Specifies that the threshold values will be user-defined. Set the threshold values with M_THRESHOLD_LOW and M_THRESHOLD_HIGH.

a b c d e f g h i j k l m n o p q r
M_VERY_HIGH

Specifies a very high threshold. Only the strongest edges in the image are extracted. M_VERY_HIGH always results in a lower (or equal) number of edgels than M_HIGH.

a b c d e f g h i j k l m n o p q r
Open Collapse M_THRESHOLD_TYPE

Sets the type of hysteresis threshold used when performing the edge extraction. Sets the type of hysteresis threshold used when performing the edge extraction ...

Edge chains are built such that the magnitude values of all connected edgels are stronger than a lower bound threshold value and such that at least one of the edgel's magnitude in each edge chain is stronger than a upper bound threshold value.

Note that M_THRESHOLD_TYPE sets how to use the lower and upper threshold bounds, while M_THRESHOLD_MODE defines what the bounds are.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_HYSTERESIS.

a b c d e f g h i j k l m n o p q r
M_FULL_HYSTERESIS

Specifies that the lower bound threshold value is 0.

a b c d e f g h i j k l m n o p q r
M_HYSTERESIS

Specifies that both the lower bound threshold value and the upper bound threshold value will be used.

a b c d e f g h i j k l m n o p q r
M_NO_HYSTERESIS

Specifies that the lower bound threshold value is equal to the upper bound threshold value.

a b c d e f g h i j k l m n o p q r
Open Collapse M_TIMEOUT

Sets the maximum edge extraction and calculation time for MedgeCalculate(), in msec. Sets the maximum edge extraction and calculation time for MedgeCalculate(), in msec ...

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_DISABLE.

a b c d e f g h i j k l m n o p q r
M_DISABLE

Specifies an infinite amount of edge extraction and calculation time.

a b c d e f g h i j k l m n o p q r
Value > 0

Specifies the maximum edge extraction and calculation time, in msec.

a b c d e f g h i j k l m n o p q r

The following ControlType and corresponding ControlValue settings are used to control the Edge Finder context operation settings and can only be specified for M_CREST Edge Finder contexts.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_FOREGROUND_VALUE |  | Sets the color of the line crests to extract from the image. Sets the color of the line crests to extract from the image ...
 | M_DEFAULT | Same as M_FOREGROUND_BLACK.
 | M_ANY | Specifies that the line crests are both lighter and darker than the image's background color. This corresponds to both valley-like and ridge-like lines extracted from the image.
 | M_FOREGROUND_BLACK | Specifies that the line crests are darker than the image's background color. This corresponds to valley-like lines extracted from the image (a valley-like Gaussian profile).
 | M_FOREGROUND_WHITE | Specifies that the line crests are lighter than the image's background color. This corresponds to ridge-like lines extracted from the image (a ridge-like Gaussian profile).

The following ControlType and corresponding ControlValue parameter settings are used to save internal buffers in the Edge Finder result buffer and can be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

Open Collapse ControlType Description
ControlValue
Open Collapse M_SAVE_ANGLE

Sets whether the internal angle buffer, used when extracting edges, is saved in the Edge Finder result buffer. Note that the angle value is not meaningful in the whole image; it is only meaningful for edges whose magnitude value is above the lower bound threshold value. Sets whether the internal angle buffer, used when extracting edges, is saved in the Edge Finder result buffer ...

Note that the angle is measured between the horizontal axis and the perpendicular direction of the edge chain at each edgel location. For more information on angle convention in MIL, see the Internal processing buffers subsection in the Calculating and retrieving results section in Chapter 9: Edge Finder.

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the angle buffer will not be saved.

M_ENABLE

Specifies that the angle buffer will be saved.

Open Collapse M_SAVE_CHAIN_ANGLE

Sets whether the angle value of the edge at each edgel position is saved in the Edge Finder result buffer. Sets whether the angle value of the edge at each edgel position is saved in the Edge Finder result buffer ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the angle values will not be saved.

M_ENABLE

Specifies that the angle values will be saved.

Open Collapse M_SAVE_CHAIN_MAGNITUDE

Sets whether the magnitude value of the edge at each edgel position is saved in the Edge Finder result buffer. Sets whether the magnitude value of the edge at each edgel position is saved in the Edge Finder result buffer ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the magnitude values will not be saved.

M_ENABLE

Specifies that the magnitude values will be saved.

Open Collapse M_SAVE_DERIVATIVES

Sets whether the internal derivative buffers used when extracting edges are saved in the Edge Finder result buffer. Sets whether the internal derivative buffers used when extracting edges are saved in the Edge Finder result buffer ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the derivative buffers will not be saved.

M_ENABLE

Specifies that the derivative buffers will be saved.

Open Collapse M_SAVE_IMAGE

Sets whether the source image is saved in the Edge Finder result buffer. Sets whether the source image is saved in the Edge Finder result buffer ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the image will not be saved.

M_ENABLE

Specifies that the image will be saved.

Open Collapse M_SAVE_MAGNITUDE

Sets whether the internal magnitude buffer, used when extracting edges, is saved in the Edge Finder result buffer. For M_CONTOUR Edge Finder contexts, the magnitude is the norm of the gradient vector at the edgel position. For M_CREST Edge Finder contexts, the magnitude is equal to the maximum eigenvalue of the Hessian matrix at the edgel position. Sets whether the internal magnitude buffer, used when extracting edges, is saved in the Edge Finder result buffer ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the magnitude buffer will not be saved.

M_ENABLE

Specifies that the magnitude buffer will be saved.

Open Collapse M_SAVE_MASK

Sets whether the mask buffer is saved in the Edge Finder result buffer. For more information, see MedgeMask(). Sets whether the mask buffer is saved in the Edge Finder result buffer ...

M_DEFAULT

Same as M_DISABLE.

M_DISABLE

Specifies that the mask will not be saved.

M_ENABLE

Specifies that the mask will be saved.

The following ControlType and corresponding ControlValue parameter settings are used to control the edge features calculated for each edge and can be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_AVERAGE_STRENGTH |  | Sets whether to calculate the average strength of each edge. This is the average energy of each edge, which is defined as the energy of the edge (M_STRENGTH) divided by its number of edgels. Sets whether to calculate the average strength of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the average strength will not be calculated.
 | M_ENABLE | Specifies that the average strength will be calculated.
Open Collapse M_BOX_X_MAX |  | Sets whether to calculate the extreme right edgel coordinate of each edge. Sets whether to calculate the extreme right edgel coordinate of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the extreme right edgel coordinate will not be calculated.
 | M_ENABLE | Specifies that the extreme right edgel coordinate will be calculated.
Open Collapse M_BOX_X_MIN |  | Sets whether to calculate the extreme left edgel coordinate of each edge. Sets whether to calculate the extreme left edgel coordinate of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the extreme left edgel coordinate will not be calculated.
 | M_ENABLE | Specifies that the extreme left edgel coordinate will be calculated.
Open Collapse M_BOX_Y_MAX |  | Sets whether to calculate the extreme bottom edgel coordinate of each edge. Sets whether to calculate the extreme bottom edgel coordinate of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the extreme bottom edgel coordinate will not be calculated.
 | M_ENABLE | Specifies that the extreme bottom edgel coordinate will be calculated.
Open Collapse M_BOX_Y_MIN |  | Sets whether to calculate the extreme top edgel coordinate of each edge. Sets whether to calculate the extreme top edgel coordinate of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the extreme top edgel coordinate will not be calculated.
 | M_ENABLE | Specifies that the extreme top edgel coordinate will be calculated.
Open Collapse M_CENTER_OF_GRAVITY_X |  | Sets whether to calculate the X-position of each edge's center of gravity. This is equal to the average position of edgel positions in X. Sets whether to calculate the X-position of each edge's center of gravity ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X-position of the center of gravity will not be calculated.
 | M_ENABLE | Specifies that the X-position of the center of gravity will be calculated.
Open Collapse M_CENTER_OF_GRAVITY_Y |  | Sets whether to calculate the Y-position of each edge's center of gravity. This is equal to the average position of edgel positions in Y. Sets whether to calculate the Y-position of each edge's center of gravity ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Y-position of the center of gravity will not be calculated.
 | M_ENABLE | Specifies that the Y-position of the center of gravity will be calculated.
Open Collapse M_CIRCLE_FIT_CENTER_X |  | Sets whether to calculate the X-coordinate of the center of the circle that is the best fit for each edge. Sets whether to calculate the X-coordinate of the center of the circle that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X-coordinate will not be calculated.
 | M_ENABLE | Specifies that the X-coordinate will be calculated.
Open Collapse M_CIRCLE_FIT_CENTER_Y |  | Sets whether to calculate the Y-coordinate of the center of the circle that is the best fit for each edge. Sets whether to calculate the Y-coordinate of the center of the circle that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Y-coordinate will not be calculated.
 | M_ENABLE | Specifies that the Y-coordinate will be calculated.
Open Collapse M_CIRCLE_FIT_COVERAGE |  | Sets whether to calculate the coverage of the circle that is the best fit for each edge. The coverage describes the portion of the circle covered by the edge. The value returned is between 0.0 and 1.0, inclusive, where 0 equals no coverage, 0.5 equals 50 percent coverage, and 1.0 equals 100 percent coverage. Sets whether to calculate the coverage of the circle that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the coverage of the circle will not be calculated.
 | M_ENABLE | Specifies that the coverage of the circle will be calculated.
Open Collapse M_CIRCLE_FIT_ERROR |  | Sets whether to calculate the fit error of the circle that is the best fit for each edge. This is calculated as the average quadratic error. Sets whether to calculate the fit error of the circle that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the fit error of the circle will not be calculated.
 | M_ENABLE | Specifies that the fit error of the circle will be calculated.
Open Collapse M_CIRCLE_FIT_RADIUS |  | Sets whether to calculate the radius of the circle that is the best fit for each edge. Sets whether to calculate the radius of the circle that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the radius will not be calculated.
 | M_ENABLE | Specifies that the radius will be calculated.
Open Collapse M_CLOSURE |  | Sets whether to calculate if each edge forms a closed chain. Sets whether to calculate if each edge forms a closed chain ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the edge's closure state will not be calculated.
 | M_ENABLE | Specifies that the edge's closure state will be calculated.
Open Collapse M_CONVEX_PERIMETER |  | Sets whether to calculate the convex elongation of each edge. This is an approximation of the perimeter of the convex hull of an edge. It is derived from several Feret diameters; therefore, a larger number of Ferets gives a more accurate result (see M_NUMBER_OF_FERETS). Sets whether to calculate the convex elongation of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the convex elongation will not be calculated.
 | M_ENABLE | Specifies that the convex elongation will be calculated.
Open Collapse M_ELLIPSE_FIT_ANGLE |  | Sets whether to calculate the angle of the ellipse that is the best fit for each edge. Sets whether to calculate the angle of the ellipse that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the angle will not be calculated.
 | M_ENABLE | Specifies that the angle will be calculated.
Open Collapse M_ELLIPSE_FIT_CENTER_X |  | Sets whether to calculate the X-coordinate of the center of the ellipse that is the best fit for each edge. Sets whether to calculate the X-coordinate of the center of the ellipse that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X-coordinate will not be calculated.
 | M_ENABLE | Specifies that the X-coordinate will be calculated.
Open Collapse M_ELLIPSE_FIT_CENTER_Y |  | Sets whether to calculate the Y-coordinate of the center of the ellipse that is the best fit for each edge. Sets whether to calculate the Y-coordinate of the center of the ellipse that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Y-coordinate will not be calculated.
 | M_ENABLE | Specifies that the Y-coordinate will be calculated.
Open Collapse M_ELLIPSE_FIT_COVERAGE |  | Sets whether to calculate the coverage of the ellipse that is the best fit for each edge. The coverage describes the portion of the ellipse covered by the edge. The value returned is between 0.0 and 1.0, inclusive, where 0.0 equals no coverage, 0.5 equals 50 percent coverage, and 1.0 equals 100 percent coverage. Sets whether to calculate the coverage of the ellipse that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the coverage of the ellipse will not be calculated.
 | M_ENABLE | Specifies that the coverage of the ellipse will be calculated.
Open Collapse M_ELLIPSE_FIT_ERROR |  | Sets whether to calculate the fit error of the ellipse that is the best fit for each edge. This is calculated as the average quadratic error. Sets whether to calculate the fit error of the ellipse that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the fit error of the ellipse will not be calculated.
 | M_ENABLE | Specifies that the fit error of the ellipse will be calculated.
Open Collapse M_ELLIPSE_FIT_MAJOR_AXIS |  | Sets whether to calculate the major axis of the ellipse that is the best fit for each edge. The major axis is the line passing through the foci, center, and vertices of an ellipse. It is also the principle axis of symmetry. Sets whether to calculate the major axis of the ellipse that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the major axis will not be calculated.
 | M_ENABLE | Specifies that the major axis will be calculated.
Open Collapse M_ELLIPSE_FIT_MINOR_AXIS |  | Sets whether to calculate the minor axis of the ellipse that is the best fit for each edge. The minor axis is the line through the center of an ellipse that is perpendicular to the major axis. The minor axis is an axis of symmetry. Sets whether to calculate the minor axis of the ellipse that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the minor axis will not be calculated.
 | M_ENABLE | Specifies that the minor axis will be calculated.
Open Collapse M_FAST_LENGTH |  | Sets whether to quickly calculate the length of each edge. M_FAST_LENGTH gives a coarser but faster approximation of the edge's length than M_LENGTH. M_FAST_LENGTH is equal to: Sets whether to quickly calculate the length of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that a fast length will not be calculated.
 | M_ENABLE | Specifies that a fast length will be calculated.
Open Collapse M_FERET_ELONGATION |  | Sets whether to calculate the Feret elongation of each edge. This is a measure of the shape of each edge. It is equal to M_FERET_MAX_DIAMETER / M_FERET_MIN_DIAMETER. It is accurate for reasonably compact objects, but becomes less accurate for very elongated objects (because M_FERET_MIN_DIAMETER becomes less accurate). Sets whether to calculate the Feret elongation of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Feret elongation will not be calculated.
 | M_ENABLE | Specifies that the Feret elongation will be calculated.
Open Collapse M_FERET_MAX_ANGLE |  | Sets whether to calculate the maximum Feret angle of each edge. This is the angle at which the maximum Feret diameter is found. Sets whether to calculate the maximum Feret angle of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the maximum Feret angle will not be calculated.
 | M_ENABLE | Specifies that the maximum Feret angle will be calculated.
Open Collapse M_FERET_MAX_DIAMETER |  | Sets whether to calculate the maximum Feret diameter of each edge. This is the largest Feret diameter found after checking a certain number of angles (see M_NUMBER_OF_FERETS). More angles will give a more accurate result, but will take longer to calculate. Sets whether to calculate the maximum Feret diameter of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the maximum Feret diameter will not be calculated.
 | M_ENABLE | Specifies that the maximum Feret diameter will be calculated.
Open Collapse M_FERET_MEAN_DIAMETER |  | Sets whether to calculate the average Feret diameter at all the angles checked (see M_NUMBER_OF_FERETS). Sets whether to calculate the average Feret diameter at all the angles checked (see M_NUMBER_OF_FERETS) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the average Feret diameter will not be calculated.
 | M_ENABLE | Specifies that the average Feret diameter will be calculated.
Open Collapse M_FERET_MIN_ANGLE |  | Sets whether to calculate the minimum Feret angle of each edge. This is the angle at which the minimum Feret diameter is found. Sets whether to calculate the minimum Feret angle of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the minimum Feret angle will not be calculated.
 | M_ENABLE | Specifies that the minimum Feret angle will be calculated.
Open Collapse M_FERET_MIN_DIAMETER |  | Sets whether to calculate the minimum Feret diameter of each edge. This is the smallest Feret diameter found after checking a certain number of angles (see M_NUMBER_OF_FERETS). More angles will give a more accurate result, but will take longer to calculate. Sets whether to calculate the minimum Feret diameter of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the minimum Feret diameter will not be calculated.
 | M_ENABLE | Specifies that the minimum Feret diameter will be calculated.
Open Collapse M_FERET_X |  | Sets whether to calculate the X-Feret value of each edge. This is the dimension of the minimum bounding box of an edge in the horizontal direction; that is, M_BOX_X_MAX - M_BOX_X_MIN. Sets whether to calculate the X-Feret value of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X-Feret value will not be calculated.
 | M_ENABLE | Specifies that the X-Feret value will be calculated.
Open Collapse M_FERET_Y |  | Sets whether to calculate the Y-Feret value of each edge. This is the dimension of the minimum bounding box of an edge in the vertical direction; that is, M_BOX_Y_MAX - M_BOX_Y_MIN. Sets whether to calculate the Y-Feret value of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Y-Feret value will not be calculated.
 | M_ENABLE | Specifies that the Y-Feret value will be calculated.
Open Collapse M_FIRST_POINT_X |  | Sets whether to calculate the X-coordinate of each edge's first point (starting point). Together with M_FIRST_POINT_Y, these values define a unique point for each edge, which is always the first point of each edge chain. Sets whether to calculate the X-coordinate of each edge's first point (starting point) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the first point's X-coordinate will not be calculated.
 | M_ENABLE | Specifies that the first point's X-coordinate will be calculated.
Open Collapse M_FIRST_POINT_Y |  | Sets whether to calculate the Y-coordinate of each edge's first point (starting point). Together with M_FIRST_POINT_X, these values define a unique point for each edge, which is always the first point of each edge chain. Sets whether to calculate the Y-coordinate of each edge's first point (starting point) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the first point's Y-coordinate will not be calculated.
 | M_ENABLE | Specifies that the first point's Y-coordinate will be calculated.
Open Collapse M_GENERAL_FERET |  | Sets whether to calculate the general Feret of each edge. This is the Feret diameter calculated at M_GENERAL_FERET_ANGLE. Sets whether to calculate the general Feret of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the general Feret will not be calculated.
 | M_ENABLE | Specifies that the general Feret will be calculated.
Open Collapse M_LABEL_VALUE |  | Sets whether to calculate the label value of each edge in an image. The label value is a positive integer greater or equal to one; each edge in an image has a unique label value. Sets whether to calculate the label value of each edge in an image ...
 | M_DEFAULT | Same as M_ENABLE.
 | M_DISABLE | Specifies that the label value will not be calculated.
 | M_ENABLE | Specifies that the label value will be calculated.
Open Collapse M_LENGTH |  | Sets whether to calculate the length of each edge. M_LENGTH gives a more accurate but slower approximation of the edge's length than M_FAST_LENGTH. Sets whether to calculate the length of each edge. M_LENGTH gives a more accurate but slower approximation of the edge's length than M_FAST_LENGTH ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the length of each edge will not be calculated.
 | M_ENABLE | Specifies that the length of each edge will be calculated.
Open Collapse M_LINE_FIT_A |  | Sets whether to calculate the A variable of the line that is the best fit for each edge. The line fit approximation is based on the following equation: Ax + By + C = 0. Sets whether to calculate the A variable of the line that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the A variable will not be calculated.
 | M_ENABLE | Specifies that the A variable will be calculated.
Open Collapse M_LINE_FIT_B |  | Sets whether to calculate the B variable of the line that is the best fit for each edge. The line fit approximation is based on the following equation: Ax + By + C = 0. Sets whether to calculate the B variable of the line that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the B variable will not be calculated.
 | M_ENABLE | Specifies that the B variable will be calculated.
Open Collapse M_LINE_FIT_C |  | Sets whether to calculate the C variable of the line that is the best fit for each edge. The line fit approximation is based on the following equation: Ax + By + C = 0. Sets whether to calculate the C variable of the line that is the best fit for each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the C variable will not be calculated.
 | M_ENABLE | Specifies that the C variable will be calculated.
Open Collapse M_LINE_FIT_ERROR |  | Sets whether to calculate the fit error of the line that is the best fit for each edge. This is calculated as the average quadratic error. The line fit approximation is based on the following equation: Ax + By + C = 0. Sets whether to calculate the fit error of the line that is the best fit for each edge. This is calculated as the average quadratic error ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the fit error will not be calculated.
 | M_ENABLE | Specifies that the fit error will be calculated.
Open Collapse M_MOMENT_ELONGATION |  | Sets whether to calculate the moment elongation of each edge. M_MOMENT_ELONGATION is defined as the ratio of the principle values of the edge's inertial matrix, which corresponds to the principal directions of the edge shape. Sets whether to calculate the moment elongation of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the moment elongation will not be calculated.
 | M_ENABLE | Specifies that the moment elongation will be calculated.
Open Collapse M_MOMENT_ELONGATION_ANGLE |  | Sets whether to calculate the angle of the principle axis along each edge's moment elongation (M_MOMENT_ELONGATION). Sets whether to calculate the angle of the principle axis along each edge's moment elongation (M_MOMENT_ELONGATION) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the angle of the moment elongation will not be calculated.
 | M_ENABLE | Specifies that the angle of the moment elongation will be calculated.
Open Collapse M_POSITION_X |  | Sets whether to calculate the X-position of each edge. The position of the edge is defined by the middle edgel of the edge chain. Sets whether to calculate the X-position of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X-position will not be calculated.
 | M_ENABLE | Specifies that the X-position will be calculated.
Open Collapse M_POSITION_Y |  | Sets whether to calculate the Y-position of each edge. The position of the edge is defined by the middle edgel of the edge chain. Sets whether to calculate the Y-position of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Y-position will not be calculated.
 | M_ENABLE | Specifies that the Y-position will be calculated.
Open Collapse M_SIZE |  | Sets whether to calculate the number of edgels of each edge. Sets whether to calculate the number of edgels of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the number of edgels will not be calculated.
 | M_ENABLE | Specifies that the number of edgels will be calculated.
Open Collapse M_STRENGTH |  | Sets whether to calculate the strength of each edge. This is the energy of each edge, which is defined as the sum of the square of the edgels' magnitude values. Sets whether to calculate the strength of each edge. This is the energy of each edge, which is defined as the sum of the square of the edgels' magnitude values ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the strength will not be calculated.
 | M_ENABLE | Specifies that the strength will be calculated.
Open Collapse M_TORTUOSITY |  | Sets whether to calculate the tortuosity measure of each edge. The tortuosity measure is equal to the diagonal length of the edge's bounding box (M_BOX), divided by the length of the edge (M_LENGTH). Therefore, a non-tortuous edge (a straight line) will have a tortuosity of 1.0 while a tortuous edge will have its tortuosity decreasing toward zero. Sets whether to calculate the tortuosity measure of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the tortuosity measure will not be calculated.
 | M_ENABLE | Specifies that the tortuosity measure will be calculated.
Open Collapse M_X_MAX_AT_Y_MAX |  | Sets whether to calculate the maximum X-coordinate at the maximum Y-coordinate of each edge. Together with M_BOX_Y_MAX, this is one of four contact points on the convex perimeter of the edge. Sets whether to calculate the maximum X-coordinate at the maximum Y-coordinate of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X-maximum at Y-maximum will not be calculated.
 | M_ENABLE | Specifies that the X-maximum at Y-maximum will be calculated.
Open Collapse M_X_MIN_AT_Y_MIN |  | Sets whether to calculate the minimum X-coordinate at the minimum Y-coordinate of each edge. Together with M_BOX_Y_MIN, this is one of four contact points on the convex perimeter of the edge. Sets whether to calculate the minimum X-coordinate at the minimum Y-coordinate of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X-minimum at Y-minimum will not be calculated.
 | M_ENABLE | Specifies that the X-minimum at Y-minimum will be calculated.
Open Collapse M_Y_MAX_AT_X_MIN |  | Sets whether to calculate the maximum Y-coordinate at the minimum X-coordinate of each edge. Together with M_BOX_X_MIN, this is one of four contact points on the convex perimeter of the edge. Sets whether to calculate the maximum Y-coordinate at the minimum X-coordinate of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Y-maximum at X-minimum will not be calculated.
 | M_ENABLE | Specifies that the Y-maximum at X-minimum will be calculated.
Open Collapse M_Y_MIN_AT_X_MAX |  | Sets whether to calculate the minimum Y-coordinate at the maximum X-coordinate of each edge. Together with M_BOX_X_MAX, this is one of four contact points on the convex perimeter of the edge. Sets whether to calculate the minimum Y-coordinate at the maximum X-coordinate of each edge ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Y-minimum at X-maximum will not be calculated.
 | M_ENABLE | Specifies that the Y-minimum at X-maximum will be calculated.

[Combination constants]

To specify a sorting key for the result retrieval, add one of the sorting values below to an edge feature control type. Note that only one edge feature can be selected as the first, second, or third sorting key.

Open Collapse Value Description
Open Collapse M_NO_SORT

 Removes the specified sorting key.  Removes the specified sorting key.

  Open   Collapse  M_SORTn_DOWN

 Specifies the feature as the nth sorting key (in descending order), where n stands for an integer between 1 and 3.  Specifies the feature as the nth sorting key (in descending order), where n stands for an integer between 1 and 3.

  Open   Collapse  M_SORTn_UP

 Specifies the feature as the nth sorting key (in ascending order), where n stands for an integer between 1 and 3.  Specifies the feature as the nth sorting key (in ascending order), where n stands for an integer between 1 and 3.

 The following values allow you to select groups of edge features for calculation in a single call.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_ALL_FEATURES |  | Sets whether to calculate all edge features. Sets whether to calculate all edge features ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that all edge features will not be calculated.
 | M_ENABLE | Specifies that all edge features will be calculated.
Open Collapse M_BOX |  | Sets whether to calculate the four extreme edgel coordinates of each edge (M_BOX_X_MIN, M_BOX_X_MAX, M_BOX_Y_MIN, and M_BOX_Y_MAX). Sets whether to calculate the four extreme edgel coordinates of each edge (M_BOX_X_MIN, M_BOX_X_MAX, M_BOX_Y_MIN, and M_BOX_Y_MAX) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that all the extreme edgel coordinates will not be calculated.
 | M_ENABLE | Specifies that all the extreme edgel coordinates will be calculated.
Open Collapse M_CENTER_OF_GRAVITY |  | Sets whether to calculate the X- and Y-coordinates of the center of gravity of each edge (M_CENTER_OF_GRAVITY_X and M_CENTER_OF_GRAVITY_Y). Sets whether to calculate the X- and Y-coordinates of the center of gravity of each edge (M_CENTER_OF_GRAVITY_X and M_CENTER_OF_GRAVITY_Y) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that both the X- and Y-coordinates of the center of gravity will not be calculated.
 | M_ENABLE | Specifies that both the X- and Y-coordinates of the center of gravity will be calculated.
Open Collapse M_CIRCLE_FIT |  | Sets whether to calculate the circle fit values of each edge (M_CIRCLE_FIT_CENTER_X, M_CIRCLE_FIT_CENTER_Y, M_CIRCLE_FIT_RADIUS, M_CIRCLE_FIT_ERROR, and M_CIRCLE_FIT_COVERAGE). Sets whether to calculate the circle fit values of each edge (M_CIRCLE_FIT_CENTER_X, M_CIRCLE_FIT_CENTER_Y, M_CIRCLE_FIT_RADIUS, M_CIRCLE_FIT_ERROR, and M_CIRCLE_FIT_COVERAGE) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that all the circle fit values will not be calculated.
 | M_ENABLE | Specifies that all the circle fit values will be calculated.
Open Collapse M_CONTACT_POINTS |  | Sets whether to calculate the minimum/maximum X-coordinate at the minimum/maximum Y-coordinate of each edge (M_X_MIN_AT_Y_MIN, M_X_MAX_AT_Y_MAX, M_Y_MAX_AT_X_MIN, and M_Y_MIN_AT_X_MAX). Together with its corresponding extreme edgel coordinate, these points represent four contact points on the convex perimeter of the edge. For example, M_X_MIN_AT_Y_MIN and M_BOX_Y_MIN is one of the four contact points. Sets whether to calculate the minimum/maximum X-coordinate at the minimum/maximum Y-coordinate of each edge (M_X_MIN_AT_Y_MIN, M_X_MAX_AT_Y_MAX, M_Y_MAX_AT_X_MIN, and M_Y_MIN_AT_X_MAX) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the four contact points will not be calculated.
 | M_ENABLE | Specifies that the four contact points will be calculated.
Open Collapse M_ELLIPSE_FIT |  | Sets whether to calculate the ellipse fit values of each edge (M_ELLIPSE_FIT_ANGLE, M_ELLIPSE_FIT_CENTER_X, M_ELLIPSE_FIT_CENTER_Y, M_ELLIPSE_FIT_COVERAGE, M_ELLIPSE_FIT_ERROR, M_ELLIPSE_FIT_MINOR_AXIS, and M_ELLIPSE_FIT_MAJOR_AXIS). Sets whether to calculate the ellipse fit values of each edge (M_ELLIPSE_FIT_ANGLE, M_ELLIPSE_FIT_CENTER_X, M_ELLIPSE_FIT_CENTER_Y, M_ELLIPSE_FIT_COVERAGE, M_ELLIPSE_FIT_ERROR, M_ELLIPSE_FIT_MINOR_AXIS, and M_ELLIPSE_FIT_MAJOR_AXIS) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that all the ellipse fit values will not be calculated.
 | M_ENABLE | Specifies that all the ellipse fit values will be calculated.
Open Collapse M_FERET_BOX |  | Sets whether to calculate the X- and Y-Feret values of each edge (M_FERET_X and M_FERET_Y). Sets whether to calculate the X- and Y-Feret values of each edge (M_FERET_X and M_FERET_Y) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X- and Y-Feret values will not be calculated.
 | M_ENABLE | Specifies that the X- and Y-Feret values will be calculated.
Open Collapse M_FIRST_POINT |  | Sets whether to calculate the X- and Y-coordinate of each edge's first point (M_FIRST_POINT_X, and M_FIRST_POINT_Y). Sets whether to calculate the X- and Y-coordinate of each edge's first point (M_FIRST_POINT_X, and M_FIRST_POINT_Y) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the X- and Y-coordinate of each edge's first point will not be calculated.
 | M_ENABLE | Specifies that the X- and Y-coordinate of each edge's first point will be calculated.
Open Collapse M_LINE_FIT |  | Sets whether to calculate the line fit values of each edge (M_LINE_FIT_A, M_LINE_FIT_B, M_LINE_FIT_C, and M_LINE_FIT_ERROR). Sets whether to calculate the line fit values of each edge (M_LINE_FIT_A, M_LINE_FIT_B, M_LINE_FIT_C, and M_LINE_FIT_ERROR) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that all the line fit values will not be calculated.
 | M_ENABLE | Specifies that all the line fit values will be calculated.
Open Collapse M_POSITION |  | Sets whether to calculate both the X- and Y-position of each edge (M_POSITION_X and M_POSITION_Y). Sets whether to calculate both the X- and Y-position of each edge (M_POSITION_X and M_POSITION_Y) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that both the X- and Y-position will not be calculated.
 | M_ENABLE | Specifies that both the X- and Y-position will be calculated.

 The following ControlType and corresponding ControlValue parameter settings are used to calculate Feret values and can be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_GENERAL_FERET_ANGLE

 Sets the angle at which to calculate the M_GENERAL_FERET value.  Sets the angle at which to calculate the M_GENERAL_FERET value ...

 M_DEFAULT

Specifies the default value. The default value is 0.0 °.

 0.0 to 360.0

 Specifies the angle, in degrees.

 M_MOMENT_ELONGATION_ANGLE

 Sets whether to calculate the moment elongation of each edge. M_MOMENT_ELONGATION_ANGLE is defined as the ratio of the principle values of the edge's inertial matrix, which corresponds to the principal directions of the edge shape.

 An offset can be added to the M_MOMENT_ELONGATION_ANGLE. For example, if you want to get the general feret measure to be perpindicular to the moment elongation angle the value would be M_MOMENT_ELONGATION_ANGLE+90.

  Open   Collapse   M_NUMBER_OF_FERETS

 Sets the number of Ferets used to calculate M_FERET_MAX_DIAMETER, M_FERET_MIN_DIAMETER, M_FERET_MAX_ANGLE, M_FERET_MEAN_DIAMETER, M_FERET_MIN_ANGLE, M_FERET_ELONGATION, and M_CONVEX_PERIMETER. The first Feret angle used is always 0°, and the difference between successive angles is 180° / number of Ferets.  Sets the number of Ferets used to calculate M_FERET_MAX_DIAMETER, M_FERET_MIN_DIAMETER, M_FERET_MAX_ANGLE, M_FERET_MEAN_DIAMETER, M_FERET_MIN_ANGLE, M_FERET_ELONGATION, and M_CONVEX_PERIMETER ...

 Note that increasing the number of Ferets increases the accuracy of the results; however, it also increases the processing time.

 M_DEFAULT

Specifies the default value. The default value is 8.

 Value

 Specifies the number of Ferets.

 The following ControlType and corresponding ControlValue parameter settings are used when performing post-calculations on extracted edges and can typically be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_APPROXIMATION_TOLERANCE |  | Sets the resolution of edge approximation. Sets the resolution of edge approximation ...
 | M_DEFAULT | Specifies the default value. The default value is 50.0.
 | 0.0 to 100.0 | Specifies the resolution. When set to 0.0, a very fine edge approximation is performed. When set to 100.0, a coarse edge approximation is performed.
Open Collapse M_CHAIN_APPROXIMATION |  | Sets the simple geometric feature used when performing the edge approximation. Sets the simple geometric feature used when performing the edge approximation ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the edge approximation will not be performed. In this case, only the edge map is calculated.
 | M_LINE | Specifies that the edge approximation will be performed using a polygonal segmentation of each edge. In this case, both the edge map and the edge approximation is calculated.
Open Collapse M_FILL_GAP_ANGLE |  | Sets the aperture angle where Edge Finder searches for edge extremity candidates when filling edge gaps. That is, M_FILL_GAP_ANGLE, along with M_FILL_GAP_DISTANCE, define a region where two chain extremities can be linked. Note that two chain extremities can only be linked if both are included in the search region of the other. Sets the aperture angle where Edge Finder searches for edge extremity candidates when filling edge gaps ...
 | M_DEFAULT | Specifies the default value. The default value is 360.0 °.
 | 0.0 to 360.0 | Specifies the aperture angle, in degrees.
Open Collapse M_FILL_GAP_CANDIDATE |  | Sets whether to join an edge extremity with the other extremity of the same edge, or with an extremity of any edge. Sets whether to join an edge extremity with the other extremity of the same edge, or with an extremity of any edge ...
 | M_DEFAULT | Same as M_ANY.
 | M_ANY | Specifies that the extremity of an edge can be connected with the extremity of any edge.
 | M_SAME | Specifies that the extremity of an edge can only be connected with the other extremity of the same edge.
Open Collapse M_FILL_GAP_CONTINUITY |  | Sets the continuity constraint used when performing edge gap filling, when more than one edge extremity candidate is present. Among the whole set of extremity candidate edgels found, the one which fulfills the continuity criteria best is chosen to fill the gap. Sets the continuity constraint used when performing edge gap filling, when more than one edge extremity candidate is present ...
 | M_DEFAULT | Specifies the default value. The default value is 50.0.
 | 0.0 to 100.0 | Specifies the continuity constraint. When set to 0.0, the closest candidate is chosen to link edge segments together. When set to 100.0, the candidate that gives the most continuous result (minimum curvature) is chosen.
Open Collapse M_FILL_GAP_DISTANCE |  | Sets the maximum distance radius where Edge Finder searches for edge extremity candidates when filling edge gaps. That is, M_FILL_GAP_DISTANCE, along with M_FILL_GAP_ANGLE, define a region where two chain extremities can be linked. Note that two chain extremities can only be linked if both are included in the search region of the other. Sets the maximum distance radius where Edge Finder searches for edge extremity candidates when filling edge gaps ...
 | M_DEFAULT | Specifies the default value. The default value is 0.0 pixels.
 | M_INFINITE | Specifies an infinite maximum distance radius.
 | Value | Specifies the maximum distance radius, in pixels. Note that generally, large values should not be set. Typically, you would set M_FILL_GAP_DISTANCE to a value in the range of 2 to 5 pixels.
Open Collapse M_FILL_GAP_POLARITY |  | Sets the use of the edge polarity to perform the filling of edge gaps. Sets the use of the edge polarity to perform the filling of edge gaps ...
 | M_DEFAULT | Same as M_ANY.
 | M_ANY | Specifies that gaps between edges will be filled, regardless of their polarity.
 | M_REVERSE | Specifies that gaps between edges that have reverse polarity will be filled. Note that M_REVERSE is not available for M_CREST Edge Finder contexts.
 | M_SAME | Specifies that gaps between edges that have the same polarity will be filled. Note that M_SAME is not available for M_CREST Edge Finder contexts.

 The following ControlType and corresponding ControlValue parameter settings can be specified for an Edge Finder result buffer.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_DRAW_CROSS_SIZE |  | Sets the size of the cross used to identify certain features when drawing with MedgeDraw(). This cross is used to draw the edge's edgels (M_DRAW_EDGELS), mid-point (M_DRAW_POSITION), and center of gravity (M_DRAW_CENTER_OF_GRAVITY). Sets the size of the cross used to identify certain features when drawing with MedgeDraw() ... For more information, see MedgeDraw().
 | M_DEFAULT | Specifies the default value. The default value is 4.0 pixels.
 | Value | Specifies the size of the cross, in pixels.
Open Collapse M_DRAW_RELATIVE_ORIGIN_X |  | Sets the X-coordinate of the drawing region's top-left corner in the source image. Sets the X-coordinate of the drawing region's top-left corner in the source image ... For more information, see MedgeDraw().
 | M_DEFAULT | Specifies the default value. The default value is 0.0 pixels.
 | Value | Specifies the relative X-offset, in pixels.
Open Collapse M_DRAW_RELATIVE_ORIGIN_Y |  | Sets the Y-coordinate of the drawing region's top-left corner in the source image. Sets the Y-coordinate of the drawing region's top-left corner in the source image ... For more information, see MedgeDraw().
 | M_DEFAULT | Specifies the default value. The default value is 0.0 pixels.
 | Value | Specifies the relative Y-offset, in pixels.
Open Collapse M_DRAW_SCALE_X |  | Sets the scale factor in the X-direction. This value is used when performing zoomed drawings of results. Sets the scale factor in the X-direction ... For more information, see MedgeDraw().
 | M_DEFAULT | Specifies the default value. The default value is 1.0.
 | Value | Specifies the scale factor in the X-direction.
Open Collapse M_DRAW_SCALE_Y |  | Sets the scale factor in the Y-direction. This value is used when performing zoomed drawings of results. Sets the scale factor in the Y-direction ... For more information, see MedgeDraw().
 | M_DEFAULT | Specifies the default value. The default value is 1.0.
 | Value | Specifies the scale factor in the Y-direction.
Open Collapse M_MODEL_FINDER_COMPATIBLE |  | Sets whether the Edge Finder result buffer can be used with a Model Finder context. When used together, you can define models from the result of an edge extraction, or you can find model occurrences in the result of an edge extraction. Sets whether the Edge Finder result buffer can be used with a Model Finder context ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Specifies that the Edge Finder result buffer cannot be used with a Model Finder context.
 | M_ENABLE | Specifies that the Edge Finder result buffer can be used with a Model Finder context.
Open Collapse M_NEAREST_NEIGHBOR_RADIUS |  | Sets the radius distance used to select the closest edge or edges from a point. For more information, see the MedgeSelect() Condition parameter values M_NEAREST_NEIGHBOR and M_ALL_NEAREST_NEIGHBORS. Sets the radius distance used to select the closest edge or edges from a point ...
 | M_DEFAULT | Specifies the default value. The default value is 2.0 pixels.
 | Value | Specifies the radius distance, in pixels.

 The following ControlType and corresponding ControlValue parameter settings are used to set closest-edgel constraints for MedgeGetNeighbors(). This function retrieves the coordinates of edgels, from an Edge Finder result buffer, that meet the constraints set below, and correspond to the closest neighbors from a list of user-specified source points.

 The following values can only be specified for an Edge Finder result buffer.

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_NEIGHBOR_ANGLE

 Sets the gradient angle that an edgel must have, before being considered a candidate, when finding the closest edgels to a list of points.  Sets the gradient angle that an edgel must have, before being considered a candidate, when finding the closest edgels to a list of points ...

M_NEIGHBOR_ANGLE is based on a source angle, which you must provide for each source point, with MedgeGetNeighbors(). Note that you can set a tolerance for this angle, using MedgeControl() with M_NEIGHBOR_ANGLE_TOLERANCE.

M_NEIGHBOR_ANGLE can only be used if the internal angle buffer (MedgeControl() with M_SAVE_ANGLE) was initially saved.

 M_DEFAULT

Same as M_ANY.

 M_ANY

 Specifies that the edgel candidate can have any gradient angle. Note that M_ANY is equivalent to setting M_NEIGHBOR_ANGLE_TOLERANCE to 360.0°. In this case, you need not provide the source angle(s) in MedgeGetNeighbors().

 M_REVERSE

 Specifies that the gradient angle of the edgel candidate must have the reverse angle (+ 180°) of the source point.

 M_SAME

 Specifies that the gradient angle of the edgel candidate must have the same angle as the source point.

 M_SAME_OR_REVERSE

 Specifies that the gradient angle of the edgel candidate must either have the same, or the reverse angle of the source point.

  Open   Collapse   M_NEIGHBOR_ANGLE_TOLERANCE

 Sets the angular tolerance to use for the angle constraint (M_NEIGHBOR_ANGLE), when finding the closest edgels to a list of points. Only edgels that have a gradient angle that falls within this angular range can be returned.  Sets the angular tolerance to use for the angle constraint (M_NEIGHBOR_ANGLE), when finding the closest edgels to a list of points ...

 Note that M_NEIGHBOR_ANGLE_TOLERANCE is ignored if M_NEIGHBOR_ANGLE is set to M_ANY.

 M_DEFAULT

Specifies the default value. The default value is 180.0 °.

 0.0 to 360.0

 Specifies the angular tolerance, in degrees. This value is applied to the angle constraint. Note that setting M_NEIGHBOR_ANGLE_TOLERANCE to 360.0° is equivalent to setting M_NEIGHBOR_ANGLE to M_ANY.

  Open   Collapse   M_NEIGHBOR_MAXIMUM_NUMBER

 Sets the maximum number of edgels that can be returned (for each point), when finding the closest edgels to a list of points.  Sets the maximum number of edgels that can be returned (for each point), when finding the closest edgels to a list of points ...

 M_DEFAULT

Specifies the default value. The default value is 1.

 Value

 Specifies the maximum number of edgels.

  Open   Collapse   M_NEIGHBOR_MINIMUM_SPACING

 Sets the minimum distance separating closest edgel candidates within the same edge, when finding the closest edgels to a list of points.  Sets the minimum distance separating closest edgel candidates within the same edge, when finding the closest edgels to a list of points ...

 M_DEFAULT

Same as M_INFINITE.

 M_INFINITE

 Specifies no minimum distance separating two edgel candidates.

 Value > = 1

 Specifies the minimum distance, in edgels.

  Open   Collapse   M_SEARCH_ANGLE

 Sets the search angle constraint (applied the Edge Finder result buffer), when finding the closest edgels to a list of points. Only edgels that are located along this angle can be returned.  Sets the search angle constraint (applied the Edge Finder result buffer), when finding the closest edgels to a list of points ...

M_SEARCH_ANGLE is relative to the source angle set with MedgeGetNeighbors(). Note that you can set the angular tolerance and the angular orientation for M_SEARCH_ANGLE, using MedgeControl() with M_SEARCH_ANGLE_TOLERANCE and M_SEARCH_ANGLE_SIGN, respectively.

M_SEARCH_ANGLE, M_SEARCH_ANGLE_TOLERANCE, and M_SEARCH_ANGLE_SIGN limit the search region for potential edgel candidates to an angular sector within the Edge Finder result buffer. Only edgels that are located within this region can be returned.

 M_DEFAULT

Specifies the default value. The default value is 0.0 °.

 0.0 to 360.0

 Specifies the angle, in degrees.

  Open   Collapse   M_SEARCH_ANGLE_SIGN

 Sets the orientation to use for the search angle constraint, when finding the closest edgels to a list of points. The orientation is relative to the source angle set with MedgeGetNeighbors(). For example, if the source angle is 45°, then the reverse orientation would be 225°.  Sets the orientation to use for the search angle constraint, when finding the closest edgels to a list of points ...

 Note that you can set the search angle and the angular tolerance for M_SEARCH_ANGLE_SIGN, using MedgeControl() with M_SEARCH_ANGLE and M_SEARCH_ANGLE_TOLERANCE, respectively.

M_SEARCH_ANGLE, M_SEARCH_ANGLE_TOLERANCE, and M_SEARCH_ANGLE_SIGN limit the search region for potential edgel candidates to an angular sector within the Edge Finder result buffer. Only edgels that are located within this region can be returned.

 M_DEFAULT

Same as M_SAME.

 M_REVERSE

 Specifies that the orientation of the angle must be the reverse (+ 180°) of the source angle. That is, the angle used will look flipped when compared to the source angle.

 M_SAME

 Specifies that the orientation of the angle must be the same as the source angle.

 M_SAME_OR_REVERSE

 Specifies that the orientation of the angle can be the same as, or the reverse of, the source angle.

  Open   Collapse   M_SEARCH_ANGLE_TOLERANCE

 Sets the angular tolerance to use for the search angle constraint, when finding the closest edgels to a list of points. Only edgels that are located within this angular range (in the Edge Finder result buffer) can be returned.  Sets the angular tolerance to use for the search angle constraint, when finding the closest edgels to a list of points ...

 Note that you can set the search angle and the angular orientation for M_SEARCH_ANGLE_TOLERANCE, using MedgeControl() with M_SEARCH_ANGLE and M_SEARCH_ANGLE_SIGN, respectively.

M_SEARCH_ANGLE, M_SEARCH_ANGLE_TOLERANCE, and M_SEARCH_ANGLE_SIGN limit the search region for potential edgel candidates to an angular sector within the Edge Finder result buffer. Only edgels that are located within this region can be returned.

 M_DEFAULT

Specifies the default value. The default value is 360.0 °.

 0.0 to 360.0

 Specifies the angle, in degrees.

  Open   Collapse   M_SEARCH_RADIUS_MAX

 Sets the maximum radius distance in the Edge Finder result buffer that will be searched for the closest edgels. You must use MedgeGetNeighbors() to specify the source point from which the radius is measured.  Sets the maximum radius distance in the Edge Finder result buffer that will be searched for the closest edgels ...

 Used together, M_SEARCH_RADIUS_MAX and M_SEARCH_RADIUS_MIN define a ring-like region, in the Edge Finder result buffer, that will be used to find the closest edgels. All edgels that fall outside this ring will be ignored.

 M_DEFAULT

Same as M_INFINITE.

 M_INFINITE

 Specifies a maximum distance radius that spans all edgels in the Edge Finder result buffer.

 Value

 Specifies the maximum distance radius, in pixels.

  Open   Collapse   M_SEARCH_RADIUS_MIN

 Sets the minimum radius distance in the Edge Finder result buffer that will be searched for the closest edgels. You must use MedgeGetNeighbors() to specify the source point from which the radius is measured.  Sets the minimum radius distance in the Edge Finder result buffer that will be searched for the closest edgels ...

 Used together, M_SEARCH_RADIUS_MAX and M_SEARCH_RADIUS_MIN define a ring-like region, in the Edge Finder result buffer, that will be used to find the closest edgels. All edgels that fall outside this ring will be ignored.

 M_DEFAULT

Specifies the default value. The default value is 0 pixels.

 Value

 Specifies the minimum distance radius, in pixels.

NEAREST NEIGHBOR RADIUS CONTOUR CREST VERY HIGH CHAIN ALL NEIGHBORS DETAIL LEVEL DETAIL LEVEL THRESHOLD MODE DETAIL LEVEL THRESHOLD MODE EXTRACTION SCALE  SHEN DERICHE CONTOUR CREST DERICHE DERICHE FILTER SMOOTHNESS DERICHE FILTER MODE FREI CHEN CONTOUR FREI CHEN FILTER SMOOTHNESS PREWITT CONTOUR PREWITT FILTER SMOOTHNESS DERICHE SHEN CONTOUR CREST SHEN DERICHE SHEN FILTER SMOOTHNESS SHEN FILTER MODE SOBEL CONTOUR SOBEL FILTER SMOOTHNESS FILTER MODE DERICHE SHEN FILTER TYPE KERNEL RECURSIVE KERNEL WIDTH KERNEL RECURSIVE KERNEL WIDTH FILTER MODE KERNEL KERNEL WIDTH FILTER TYPE FILTER SMOOTHNESS FILTER SMOOTHNESS KERNEL DEPTH FILTER MODE KERNEL KERNEL DEPTH FILTER TYPE FILTER SMOOTHNESS FILTER TYPE DERICHE SHEN OVERSCAN FILTER MODE RECURSIVE OVERSCAN REPLACE VALUE OVERSCAN REPLACE VALUE OVERSCAN REPLACE OVERSCAN REPLACE VALUE FILTER MODE RECURSIVE CONTOUR CREST CONTOUR SQR NORM CREST NORM SQR NORM NORM THRESHOLD HIGH THRESHOLD MODE USER DEFINED THRESHOLD LOW THRESHOLD MODE USER DEFINED DETAIL LEVEL DETAIL LEVEL THRESHOLD MODE THRESHOLD LOW THRESHOLD HIGH VERY HIGH HIGH HIGH HIGH MEDIUM MEDIUM MEDIUM LOW LOW DISABLE THRESHOLD TYPE THRESHOLD MODE CREST CONTOUR CREST CONTOUR CREST CONTOUR CREST STRENGTH NUMBER OF FERETS FAST LENGTH LENGTH FAST LENGTH FERET MAX DIAMETER FERET MIN DIAMETER FERET MIN DIAMETER NUMBER OF FERETS NUMBER OF FERETS NUMBER OF FERETS BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN FIRST POINT Y FIRST POINT X GENERAL FERET ANGLE LENGTH FAST LENGTH MOMENT ELONGATION MOMENT ELONGATION BOX LENGTH BOX Y MAX BOX Y MIN BOX X MIN BOX X MAX BOX X MIN BOX X MAX BOX Y MIN BOX Y MAX CENTER OF GRAVITY X CENTER OF GRAVITY Y CIRCLE FIT CENTER X CIRCLE FIT CENTER Y CIRCLE FIT RADIUS CIRCLE FIT ERROR CIRCLE FIT COVERAGE X MIN AT Y MIN X MAX AT Y MAX Y MAX AT X MIN Y MIN AT X MAX X MIN AT Y MIN BOX Y MIN ELLIPSE FIT ANGLE ELLIPSE FIT CENTER X ELLIPSE FIT CENTER Y ELLIPSE FIT COVERAGE ELLIPSE FIT ERROR ELLIPSE FIT MINOR AXIS ELLIPSE FIT MAJOR AXIS FERET X FERET Y FIRST POINT X FIRST POINT Y LINE FIT A LINE FIT B LINE FIT C LINE FIT ERROR POSITION X POSITION Y CONTOUR CREST GENERAL FERET MOMENT ELONGATION ANGLE MOMENT ELONGATION ANGLE FERET MAX DIAMETER FERET MIN DIAMETER FERET MAX ANGLE FERET MEAN DIAMETER FERET MIN ANGLE FERET ELONGATION CONVEX PERIMETER CONTOUR CREST FILL GAP ANGLE FILL GAP DISTANCE FILL GAP DISTANCE FILL GAP ANGLE FILL GAP DISTANCE REVERSE CREST SAME CREST DRAW EDGELS DRAW POSITION DRAW CENTER OF GRAVITY NEAREST NEIGHBOR ALL NEAREST NEIGHBORS NEIGHBOR ANGLE NEIGHBOR ANGLE TOLERANCE NEIGHBOR ANGLE SAVE ANGLE ANY NEIGHBOR ANGLE TOLERANCE NEIGHBOR ANGLE NEIGHBOR ANGLE TOLERANCE NEIGHBOR ANGLE ANY NEIGHBOR ANGLE TOLERANCE NEIGHBOR ANGLE ANY SEARCH ANGLE SEARCH ANGLE SEARCH ANGLE TOLERANCE SEARCH ANGLE SIGN SEARCH ANGLE TOLERANCE SEARCH ANGLE SEARCH ANGLE SIGN SEARCH ANGLE SIGN SEARCH ANGLE SEARCH ANGLE TOLERANCE SEARCH ANGLE SEARCH ANGLE TOLERANCE SEARCH ANGLE SIGN SEARCH RADIUS MAX SEARCH RADIUS MIN    ACCURACY DEFAULT DISABLE VERY HIGH HIGH CHAIN ALL NEIGHBORS DEFAULT DISABLE ENABLE DETAIL LEVEL DEFAULT VERY HIGH  HIGH MEDIUM EXTRACTION SCALE DEFAULT  FILTER TYPE DEFAULT DERICHE FREI CHEN PREWITT  SHEN SOBEL FILTER MODE DEFAULT RECURSIVE KERNEL KERNEL WIDTH DEFAULT  AUTO KERNEL DEPTH DEFAULT   FILTER SMOOTHNESS DEFAULT  OVERSCAN DEFAULT MIRROR REPLACE TRANSPARENT DISABLE OVERSCAN REPLACE VALUE DEFAULT REPLACE MAX REPLACE MIN  FLOAT MODE DEFAULT DISABLE ENABLE TIMEOUT DEFAULT DISABLE  MAGNITUDE TYPE DEFAULT
                      NORM SQR NORM THRESHOLD HIGH DEFAULT  THRESHOLD LOW DEFAULT  THRESHOLD MODE DEFAULT DISABLE USER DEFINED VERY HIGH HIGH MEDIUM LOW THRESHOLD TYPE  DEFAULT FULL HYSTERESIS HYSTERESIS NO HYSTERESIS FOREGROUND VALUE  DEFAULT
                         ANY FOREGROUND BLACK FOREGROUND WHITE SAVE ANGLE  DEFAULT
                         DISABLE ENABLE SAVE CHAIN ANGLE  DEFAULT
                         DISABLE ENABLE SAVE CHAIN MAGNITUDE  DEFAULT
                         DISABLE ENABLE SAVE DERIVATIVES DEFAULT
                         DISABLE ENABLE SAVE IMAGE  DEFAULT
                         DISABLE ENABLE SAVE MAGNITUDE DEFAULT
                         DISABLE ENABLE SAVE MASK DEFAULT
                         DISABLE ENABLE AVERAGE STRENGTH DEFAULT
                         DISABLE ENABLE BOX X MAX DEFAULT
                         DISABLE ENABLE BOX X MIN DEFAULT
                         DISABLE ENABLE BOX Y MAX DEFAULT
                         DISABLE ENABLE BOX Y MIN DEFAULT
                         DISABLE ENABLE CENTER OF GRAVITY X DEFAULT
                         DISABLE ENABLE CENTER OF GRAVITY Y DEFAULT
                         DISABLE ENABLE CIRCLE FIT CENTER X DEFAULT
                         DISABLE ENABLE CIRCLE FIT CENTER Y DEFAULT
                         DISABLE ENABLE CIRCLE FIT COVERAGE DEFAULT
                         DISABLE ENABLE CIRCLE FIT ERROR DEFAULT
                         DISABLE ENABLE CIRCLE FIT RADIUS DEFAULT
                         DISABLE ENABLE CLOSURE DEFAULT
                         DISABLE ENABLE CONVEX PERIMETER DEFAULT
                         DISABLE ENABLE ELLIPSE FIT ANGLE DEFAULT
                         DISABLE ENABLE ELLIPSE FIT CENTER X DEFAULT
                         DISABLE ENABLE ELLIPSE FIT CENTER Y DEFAULT
                         DISABLE ENABLE ELLIPSE FIT COVERAGE DEFAULT
                         DISABLE ENABLE ELLIPSE FIT ERROR DEFAULT
                         DISABLE ENABLE ELLIPSE FIT MAJOR AXIS DEFAULT
                         DISABLE ENABLE ELLIPSE FIT MINOR AXIS DEFAULT
                         DISABLE ENABLE FAST LENGTH DEFAULT
                         DISABLE ENABLE FERET ELONGATION DEFAULT
                         DISABLE ENABLE FERET MAX ANGLE  DEFAULT
                         DISABLE ENABLE FERET MAX DIAMETER  DEFAULT
                         DISABLE ENABLE FERET MEAN DIAMETER DEFAULT
                         DISABLE ENABLE FERET MIN ANGLE  DEFAULT
                         DISABLE ENABLE FERET MIN DIAMETER DEFAULT
                         DISABLE ENABLE FERET X DEFAULT
                         DISABLE ENABLE FERET Y DEFAULT
                         DISABLE ENABLE FIRST POINT X DEFAULT
                         DISABLE ENABLE FIRST POINT Y DEFAULT
                         DISABLE ENABLE GENERAL FERET DEFAULT
                         DISABLE ENABLE LABEL VALUE DEFAULT
                         DISABLE ENABLE LENGTH DEFAULT
                         DISABLE ENABLE LINE FIT A DEFAULT
                         DISABLE ENABLE LINE FIT B DEFAULT
                         DISABLE ENABLE LINE FIT C DEFAULT
                         DISABLE ENABLE LINE FIT ERROR DEFAULT
                         DISABLE ENABLE MOMENT ELONGATION DEFAULT
                         DISABLE ENABLE MOMENT ELONGATION ANGLE DEFAULT
                         DISABLE ENABLE POSITION X  DEFAULT
                         DISABLE ENABLE POSITION Y DEFAULT
                         DISABLE ENABLE SIZE DEFAULT
                         DISABLE ENABLE STRENGTH DEFAULT
                         DISABLE ENABLE TORTUOSITY DEFAULT
                         DISABLE ENABLE X MAX AT Y MAX DEFAULT
                         DISABLE ENABLE X MIN AT Y MIN DEFAULT
                         DISABLE ENABLE Y MAX AT X MIN DEFAULT
                         DISABLE ENABLE Y MIN AT X MAX  DEFAULT
                         DISABLE ENABLE NO SORT SORTn DOWN  SORTn UP  ALL FEATURES DEFAULT
                         DISABLE ENABLE BOX DEFAULT
                         DISABLE ENABLE CENTER OF GRAVITY DEFAULT
                         DISABLE ENABLE CIRCLE FIT DEFAULT
                         DISABLE ENABLE CONTACT POINTS DEFAULT
                         DISABLE ENABLE ELLIPSE FIT DEFAULT
                         DISABLE ENABLE FERET BOX DEFAULT
                         DISABLE ENABLE FIRST POINT DEFAULT
                         DISABLE ENABLE LINE FIT DEFAULT
                         DISABLE ENABLE POSITION DEFAULT
                         DISABLE ENABLE GENERAL FERET ANGLE DEFAULT MOMENT ELONGATION ANGLE  NUMBER OF FERETS DEFAULT  APPROXIMATION TOLERANCE DEFAULT  CHAIN APPROXIMATION DEFAULT
                         DISABLE LINE FILL GAP ANGLE DEFAULT
                          FILL GAP CANDIDATE DEFAULT ANY SAME FILL GAP CONTINUITY DEFAULT
                          FILL GAP DISTANCE DEFAULT
                         INFINITE  FILL GAP POLARITY DEFAULT ANY REVERSE SAME  DRAW CROSS SIZE DEFAULT  DRAW RELATIVE ORIGIN X  DEFAULT  DRAW RELATIVE ORIGIN Y DEFAULT  DRAW SCALE X DEFAULT  DRAW SCALE Y DEFAULT  MODEL FINDER COMPATIBLE DEFAULT DISABLE ENABLE NEAREST NEIGHBOR RADIUS  DEFAULT  SEARCH RADIUS MAX DEFAULT
                         INFINITE  SEARCH RADIUS MIN DEFAULT
                          NEIGHBOR MAXIMUM NUMBER DEFAULT
                          NEIGHBOR MINIMUM SPACING DEFAULT
                         INFINITE  NEIGHBOR ANGLE DEFAULT
                         ANY SAME REVERSE SAME OR REVERSE NEIGHBOR ANGLE TOLERANCE DEFAULT
                          SEARCH ANGLE DEFAULT
                          SEARCH ANGLE TOLERANCE DEFAULT
                          SEARCH ANGLE SIGN DEFAULT
                         SAME OR REVERSE SAME REVERSE


MedgeDraw

See Also | Example | Availability | MedgeControl | MedgeFree
User Guide:
Steps to performing an edge extraction and analysis
Calculating and retrieving results

Reference:
MedgeAllocResult
MedgeControl
MedgeGetResult
MgraAlloc
medge.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Iris
Synopsis
Draw specific edge results in the destination image buffer.
Syntax
void MedgeDraw(
MIL_ID GraphContId,
MIL_ID EdgeResultId,
MIL_ID DestImageId,
long Operation,
long IndexOrLabel,
long ControlFlag
)
Description

This function draws specific edge results in the destination buffer.

To draw edge results, the required information must be available for the specified edge or group of edges, in the Edge Finder result buffer. To verify availability, call MedgeGetResult() with the required edge result combined with M_AVAILABLE.

You can also draw from a zoomed region of the source image that was used to calculate results by specifying the appropriate values for MedgeControl() with M_DRAW_RELATIVE_ORIGIN_X, M_DRAW_RELATIVE_ORIGIN_Y, M_DRAW_SCALE_X, and M_DRAW_SCALE_Y. The relative origin values specify, in pixels, the coordinates of the top-left corner of the region in the source image, while the scale values specify the X- and Y-scaling factors used to fill the destination buffer. Note that these control types are applied to an Edge Finder result buffer.

Note that if edges are calculated using a calibrated source image, Edge Finder takes the calibration into account; that is, drawings are done in the real world (using pixel units).

Parameters
GraphContId

Specifies the graphics context to use when drawing. This parameter should be set to one of the following:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default graphics context.  Specifies the default graphics context.

  Open   Collapse  MIL graphics context identifier

 Specifies a valid graphics context identifier, which you have allocated using MgraAlloc().  Specifies a valid graphics context identifier, which you have allocated using MgraAlloc().

 EdgeResultId

 Specifies the identifier of the Edge Finder result buffer from which to extract the results to draw.  The Edge Finder result buffer must have been previously allocated on the required system using MedgeAllocResult().

[Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

 The Edge Finder result buffer (EdgeResultId) must be allocated on the same system as the graphics context buffer (GraphContId). If it is not, an error will occur.

 DestImageId

 Specifies the identifier of the destination image buffer in which to draw.  This destination image can be any supported MIL image. You can also choose to annotate an image non-destructively, by drawing into its display's overlay buffer. When using MedgeDraw() to draw results extracted from a calibrated source image, the destination drawing buffer need not be calibrated to the same world. MedgeDraw() draws all the requested results according to the calibrated source image.

 Operation

 Specifies the type of operation to perform.  The possible Operation parameter values in the table below can be added together to draw multiple feature results at once.

 Note that only one internal drawing buffer can be drawn at a time; for example, you cannot combine M_DRAW_ANGLE and M_DRAW_MAGNITUDE in the same operation.

  Open   Collapse  Value
Description

  Open   Collapse  M_DRAW_ANGLE

 Draws the internal angle buffer.  Draws the internal angle buffer ...

 Note that to perform this operation, the angle buffer must have been previously saved in the result buffer by enabling M_SAVE_ANGLE in MedgeControl().

  Open   Collapse  M_DRAW_BOX

 Draws a bounding box around each edge.  Draws a bounding box around each edge ...

 Note that to perform this operation, the M_BOX feature in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_CENTER_OF_GRAVITY

 Draws a cross at the center of gravity of each edge.  Draws a cross at the center of gravity of each edge ...

 You can modify the cross size by setting MedgeControl() with M_DRAW_CROSS_SIZE to an appropriate value.

 Note that to perform this operation, the M_CENTER_OF_GRAVITY feature in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_CIRCLE_FIT

 Draws the circle fit of each edge.  Draws the circle fit of each edge ...

 Note that to perform this operation, the M_CIRCLE_FIT feature in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_CROSS_DERIVATIVE

 Draws the internal cross-derivative buffer of the source image.  Draws the internal cross-derivative buffer of the source image ...

M_DRAW_CROSS_DERIVATIVE is only relevant for M_CREST Edge Finder contexts.

 Note that to perform this operation, the derivatives must have been previously saved in the result buffer by enabling M_SAVE_DERIVATIVES in MedgeControl().

  Open   Collapse  M_DRAW_EDGE

 Draws each edge.  Draws each edge.

  Open   Collapse  M_DRAW_EDGELS

 Draws a cross at each edgel.  Draws a cross at each edgel ...

 You can modify the cross size by setting MedgeControl() with M_DRAW_CROSS_SIZE to an appropriate value.

  Open   Collapse  M_DRAW_ELLIPSE_FIT

 Draws the ellipse fit of each edge.  Draws the ellipse fit of each edge ...

 Note that to perform this operation, the M_ELLIPSE_FIT feature in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_FERET_MAX

 Draws the edges' maximum Feret, using an H-type line (|-|). This line is drawn on contact with the edge's two extrema edgels, at the maximum Feret diameter's angle.  Draws the edges' maximum Feret, using an H-type line (|-|) ...

 Note that to perform this operation, the M_FERET_MAX_DIAMETER and M_FERET_MAX_ANGLE features in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_FERET_MIN

 Draws the edges' minimum Feret, using an H-type line (|-|). This line is drawn on contact with the edge's two extrema edgels, at the minimum Feret diameter's angle.  Draws the edges' minimum Feret, using an H-type line (|-|) ...

 Note that to perform this operation, the M_FERET_MIN_DIAMETER and M_FERET_MIN_ANGLE features in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_FIRST_DERIVATIVE_X

 Draws the internal first derivative buffer of the source image, in the X-direction.  Draws the internal first derivative buffer of the source image, in the X-direction ...

M_DRAW_FIRST_DERIVATIVE_X is only relevant for M_CONTOUR Edge Finder contexts.

 Note that to perform this operation, the derivatives must have been previously saved in the result buffer by enabling M_SAVE_DERIVATIVES in MedgeControl().

  Open   Collapse  M_DRAW_FIRST_DERIVATIVE_Y

 Draws the internal first derivative buffer of the source image, in the Y-direction.  Draws the internal first derivative buffer of the source image, in the Y-direction ...

M_DRAW_FIRST_DERIVATIVE_Y is only relevant for M_CONTOUR Edge Finder contexts.

 Note that to perform this operation, the derivatives must have been previously saved in the result buffer by enabling M_SAVE_DERIVATIVES in MedgeControl().

  Open   Collapse  M_DRAW_GENERAL_FERET

 Draws the edges' general Feret, using an H-type line (|-|). This line is drawn on contact with the edge's two extrema edgels, at the general Feret diameter's angle.  Draws the edges' general Feret, using an H-type line (|-|) ...

 Note that to perform this operation, the M_GENERAL_FERET feature in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_IMAGE

 Draws the source image.  Draws the source image ...

 Note that to perform this operation, the source image must have been previously saved in the result buffer by enabling M_SAVE_IMAGE in MedgeControl().

  Open   Collapse  M_DRAW_INDEX

 Draws each edge's index value.  Draws each edge's index value.

  Open   Collapse  M_DRAW_LABEL

 Draws each edge's label value.  Draws each edge's label value ...

 Note that to perform this operation, the M_LABEL_VALUE feature in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_LINE_FIT

 Draws the line fit of each edge.  Draws the line fit of each edge ...

 Note that to perform this operation, the M_LINE_FIT feature in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_MAGNITUDE

 Draws the internal magnitude buffer.  Draws the internal magnitude buffer ...

 Note that to perform this operation, the magnitude buffer must have been previously saved in the result buffer by enabling M_SAVE_MAGNITUDE in MedgeControl().

  Open   Collapse  M_DRAW_MASK

 Draws the mask buffer.  Draws the mask buffer ...

 Note that to perform this operation, the mask buffer must have been previously saved in the result buffer by enabling M_SAVE_MASK in MedgeControl().

  Open   Collapse  M_DRAW_POSITION

 Draws a cross at the center of each edge.  Draws a cross at the center of each edge ...

 You can modify the cross size by setting MedgeControl() with M_DRAW_CROSS_SIZE to an appropriate value.

 Note that to perform this operation, the M_POSITION feature in MedgeControl() must be calculated.

  Open   Collapse  M_DRAW_SECOND_DERIVATIVE_X

 Draws the internal second derivative buffer of the source image, in the X-direction.  Draws the internal second derivative buffer of the source image, in the X-direction ...

M_DRAW_SECOND_DERIVATIVE_X can only be used with M_CREST Edge Finder contexts.

 Note that to perform this operation, the derivatives must have been previously saved in the result buffer by enabling M_SAVE_DERIVATIVES in MedgeControl().

  Open   Collapse  M_DRAW_SECOND_DERIVATIVE_Y

 Draws the internal second derivative buffer of the source image, in the Y-direction.  Draws the internal second derivative buffer of the source image, in the Y-direction ...

M_DRAW_SECOND_DERIVATIVE_Y can only be used with M_CREST Edge Finder contexts.

 Note that to perform this operation, the derivatives must have been previously saved in the result buffer by enabling M_SAVE_DERIVATIVES in MedgeControl().

  Open   Collapse  M_DRAW_SEGMENTS

 Draws the segments of the edge approximation.  Draws the segments of the edge approximation ...

 Note that to perform this operation, edge approximations must have been previously calculated by setting MedgeControl() with M_CHAIN_APPROXIMATION to M_LINE.

  Open   Collapse  M_DRAW_VERTICES

 Draws the segment intersections (or vertices) of the edge approximation.  Draws the segment intersections (or vertices) of the edge approximation ...

 Note that to perform this operation, edge approximations must have been previously calculated by setting MedgeControl() with M_CHAIN_APPROXIMATION to M_LINE.

      [Combination constants]

 The value below can be added to M_DRAW_CENTER_OF_GRAVITY, M_DRAW_POSITION, M_DRAW_FERET_MIN, M_DRAW_FERET_MAX, and M_DRAW_GENERAL_FERET to draw the operation's numerical value.

  Open   Collapse  Value
Description

  Open   Collapse  M_DRAW_VALUE

 Specifies that the operation's numerical value is drawn. For example, if you add M_DRAW_VALUE to M_DRAW_CENTER_OF_GRAVITY, the center of gravity's coordinates are drawn within parenthesis, and centered above the drawing cross.  Specifies that the operation's numerical value is drawn ...

 IndexOrLabel

 Specifies the edge(s) to draw.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_INCLUDED_EDGES.  Same as M_INCLUDED_EDGES.

  Open   Collapse  M_ALL_EDGES

 Specifies all edges.  Specifies all edges.

  Open   Collapse  M_EXCLUDED_EDGES

 Specifies all currently excluded edges.  Specifies all currently excluded edges.

  Open   Collapse  M_INCLUDED_EDGES

 Specifies all currently included edges.  Specifies all currently included edges.

  Open   Collapse  Value

 Specifies either the edge's index or label. For more information, see combination values below.  Specifies either the edge's index or label ...

 Valid index values must fall within the following range: 0 to the number of included edges in the Edge Finder result buffer - 1. You can retrieve valid label values using MedgeGetResult() with M_LABEL_VALUE.

      [Combination constants]

 To indicate whether you are providing an index or a label value, you can add one of the following to the edge value:

  Open   Collapse  Value
Description

  Open   Collapse  M_TYPE_INDEX

 Specifies an edge using its index value.  Specifies an edge using its index value ...

 Note that only included edges (M_INCLUDED_EDGES) can be drawn.

This is the default value.

  Open   Collapse  M_TYPE_LABEL

 Specifies an edge using its label value.  Specifies an edge using its label value.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

DRAW RELATIVE ORIGIN X DRAW RELATIVE ORIGIN Y DRAW SCALE X DRAW SCALE Y DRAW ANGLE DRAW MAGNITUDE SAVE ANGLE BOX CIRCLE FIT CENTER OF GRAVITY DRAW CROSS DERIVATIVE CREST ELLIPSE FIT FERET MAX DIAMETER FERET MAX ANGLE FERET MIN DIAMETER FERET MIN ANGLE DRAW FIRST DERIVATIVE X CONTOUR DRAW FIRST DERIVATIVE Y CONTOUR GENERAL FERET SAVE IMAGE LABEL VALUE LINE FIT SAVE MAGNITUDE SAVE MASK POSITION DRAW SECOND DERIVATIVE X CREST DRAW SECOND DERIVATIVE Y CREST CHAIN APPROXIMATION LINE CHAIN APPROXIMATION LINE SAVE DERIVATIVES DRAW CROSS SIZE DRAW CENTER OF GRAVITY DRAW POSITION DRAW FERET MIN DRAW FERET MAX DRAW GENERAL FERET DRAW VALUE DRAW CENTER OF GRAVITY INCLUDED EDGES LABEL VALUE INCLUDED EDGES  DEFAULT     DRAW ANGLE DRAW BOX DRAW CIRCLE FIT DRAW CENTER OF GRAVITY DRAW CROSS DERIVATIVE DRAW EDGE DRAW EDGELS  DRAW ELLIPSE FIT DRAW FERET MAX DRAW FERET MIN DRAW FIRST DERIVATIVE X DRAW FIRST DERIVATIVE Y DRAW GENERAL FERET DRAW IMAGE DRAW INDEX DRAW LABEL DRAW LINE FIT DRAW MAGNITUDE DRAW MASK DRAW POSITION DRAW SECOND DERIVATIVE X DRAW SECOND DERIVATIVE Y DRAW SEGMENTS DRAW VERTICES DRAW VALUE  DEFAULT  ALL EDGES EXCLUDED EDGES  INCLUDED EDGES   TYPE INDEX TYPE LABEL


MedgeFree

See Also | Example | Availability | MedgeDraw | MedgeGetNeighbors
User Guide:
Steps to performing an edge extraction and analysis

Reference:
MedgeAlloc
MedgeAllocResult
medge.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free an Edge Finder context or an Edge Finder result buffer.
Syntax
void MedgeFree(
MIL_ID ObjectId
)
Description

This function deletes the specified Edge Finder context or Edge Finder result buffer identifier, and releases any memory associated with it.

All Edge Finder contexts and all Edge Finder result buffers allocated on a particular system must be freed before the system can be freed.

Parameter
ObjectId

Specifies the identifier of the Edge Finder context or Edge Finder result buffer to free. These must have been successfully allocated (with MedgeAlloc() or MedgeAllocResult()) prior to calling this function.


MedgeGetNeighbors

See Also | Example | Availability | MedgeFree | MedgeGetResult
User Guide:
Steps to performing an edge extraction and analysis
Advanced edge extraction

Reference:
McalControl
MedgeControl
There are no examples containing MedgeGetNeighbors().
Not available in MIL-Lite

Available in MIL
Synopsis
Get edgels from an Edge Finder result buffer that are the closest neighbors to a list of user-specified point coordinates.
Syntax
void MedgeGetNeighbors(
MIL_ID EdgeResultId,
long SizeOfArray,
double *SrcArrayXPtr,
double *SrcArrayYPtr,
double *SrcArrayAnglePtr,
double *DstArrayXPtr,
double *DstArrayYPtr,
long *DstArrayIndexPtr,
long *DstArrayLabelPtr,
long ControlFlag
)
Description

This function retrieves the coordinates of edgels, from an Edge Finder result buffer, that correspond to the closest neighbors from a list of user-specified source point coordinates. You can also set a series of constraints that potential results must adhere to before being returned. To do so, use the appropriate settings in MedgeControl().

If no edgel(s) have been found, M_NULL is returned.

User-specified coordinates and constraints must be specified in the same world that edgels have been calculated in. For example, if edgels have been calculated using a calibrated source image, values must be specified in the same real world units. Note that you can change the output coordinate system using McalControl() with M_OUTPUT_COORDINATE_SYSTEM set to M_PIXEL or M_WORLD.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set the DstArrayXPtr, DstArrayYPtr, DstArrayIndexPtr and DstArrayLabelPtr parameters to M_NULL. When all these result parameters are set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when at least one result parameter is passed an array. You must ensure that the DstArray...Ptr() arrays are sufficiently large to hold all the requested results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
EdgeResultId

Specifies the identifier of the Edge Finder result buffer from which to search for edgel candidates.

SizeOfArray

Specifies the number of points provided. This value represents how many user-specified point coordinates will be searched for in the Edge Finder result buffer.

SrcArrayXPtr

Specifies the address of the array containing the X-coordinate(s) of the source point(s).

SrcArrayYPtr

Specifies the address of the array containing the Y-coordinate(s) of the source point(s).

SrcArrayAnglePtr

Specifies the address of the array containing the constraint angle(s) used to refine the search for edgel candidates.

If no value is required, set this parameter to M_NULL.

DstArrayXPtr

Specifies the address of the variable in which the X-coordinate(s) of the edgel(s) found in the Edge Finder result buffer is to be written.

If no value is required, set this parameter to M_NULL.

DstArrayYPtr

Specifies the address of the variable in which the Y-coordinate(s) of the edgel(s) found in the Edge Finder result buffer is to be written.

If no value is required, set this parameter to M_NULL.

DstArrayIndexPtr

Specifies the address of the variable in which the index of the edgel(s) found in the Edge Finder result buffer is to be written.

If no value is required, set this parameter to M_NULL.

DstArrayLabelPtr

Specifies the address of the variable in which the label of the edgel(s) found in the Edge Finder result buffer is to be written.

If no value is required, set this parameter to M_NULL.

ControlFlag

Specifies the accuracy with which to return edgels.

Open Collapse Value Description
Open Collapse M_DEFAULT

Same as M_GET_EDGELS.

  Open   Collapse  M_GET_EDGELS

 Specifies that edgels are returned with normal accuracy. In this case, only edgels explicitly located in the Edge Finder result buffer can be returned.  Specifies that edgels are returned with normal accuracy ...

  Open   Collapse  M_GET_SUBEDGELS

 Specifies that edgels are returned with high accuracy. In this case, a point between two edgels can be returned.  Specifies that edgels are returned with high accuracy ...

 When using M_GET_SUBEDGELS, the M_NEIGHBOR_MAXIMUM_NUMBER constraint in MedgeControl() must be set to 1.

OUTPUT COORDINATE SYSTEM PIXEL WORLD GET SUBEDGELS NEIGHBOR MAXIMUM NUMBER           DEFAULT  GET EDGELS GET SUBEDGELS


MedgeGetResult

See Also | Example | Availability | MedgeGetNeighbors | MedgeInquire
User Guide:
Steps to performing an edge extraction and analysis
Edge features
Calculating and retrieving results
Advanced edge extraction

Reference:
McalControl
MedgeCalculate
MedgeControl
medge.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get results of the included edges from an Edge Finder result buffer.
Syntax
void MedgeGetResult(
MIL_ID EdgeResultId,
long EdgeIndexOrLabelValue,
long ResultType,
void *FirstResultArrayPtr,
void *SecondResultArrayPtr
)
Description

This function retrieves the results of a specified type from an Edge Finder result buffer, after an MedgeCalculate() call.

The following result types can be retrieved from the Edge Finder result buffer:

  • General results related to the edge extraction and edge processing.
  • Edge chain results.
  • Edge feature results.

If your source image has been associated with a calibration object, positional results are either returned in real-world or pixel units. To specify the units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to either M_WORLD (the default) or M_PIXEL. All positional results are relative to the center of the top-left pixel in the source image or the origin of the world-coordinate system if the image is calibrated.

Note that if your image is calibrated, results are calculated in the real world; therefore, retrieving results in pixel units instead of world units will typically be slower.

Note that in the presence of distortion, some results are meaningless when converted from real-world to pixel units (for example, the Feret angles). For example, if an edge appears warped in the source image, but the calibration object of the source image compensates for this during the extraction, the resulting Feret angles are meaningful in the real-world coordinate system, and meaningless in the image coordinate system.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set the FirstResultArrayPtr and SecondResultArrayPtr parameters to M_NULL. When both result parameters are set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when at least one result parameter is passed an array. You must ensure that result arrays are sufficiently large to hold all the requested results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Note, if the request queued does not return results in the second result array, the second array pointer is not padded for that particular request when the queue is executed.

Parameters
EdgeResultId

Specifies the identifier of the Edge Finder result buffer from which to get results.

EdgeIndexOrLabelValue

Specifies the edge(s) from which to get results. This parameter can be set to one of the following values.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Same as M_ALL.  Same as M_ALL.

  Open   Collapse  M_ALL

 Specifies all edges. That is, the target array(s) will be filled with the specified type of result for all the included edges. Note that target array values are ordered by edge indices.  Specifies all edges ...

  Open   Collapse  Value

 Specifies either the edge's index or label. Index values must fall within the following range: 0 to the number of included edges in the Edge Finder result buffer - 1. Label values can be returned with the result type M_LABEL_VALUE.  Specifies either the edge's index or label ...

      [Combination constants]

 To indicate whether you are providing an index or a label value, you can add one of the following values to the edge value:

  Open   Collapse  Value
Description

  Open   Collapse  M_TYPE_INDEX

 Specifies an edge using its index value.  Specifies an edge using its index value ...

This is the default value.

  Open   Collapse  M_TYPE_LABEL

 Specifies an edge using its label value.  Specifies an edge using its label value.

 ResultType

 Specifies the type of result to retrieve.

 To retrieve general results related to the edge extraction and edge processing, the ResultType parameter must be set to one of the values below. Note that, unless otherwise specified, results are only returned to FirstResultArrayPtr; when this is the case, SecondResultArrayPtr must be set to M_NULL.

Unless otherwise specified, the following values require that you pass

                  the FirstResultArrayPtr parameter the address of
                  an
                    array of type double (This array must be of size 1.) and

                  the SecondResultArrayPtr parameter the address of
                  an
                    array of type double (This array must be of size 1.).

  Open   Collapse  Value
Description

  Open   Collapse   M_ANGLE_ID

 Returns the identifier of the internal angle buffer. The angles are from 0° to 360° (counter-clockwise) and are mapped to the entire range of 0.0 to 255.0. Note that to perform this operation, the internal angle buffer must have been previously saved by enabling M_SAVE_ANGLE in MedgeControl(). Also note that the angle value is not meaningful in the whole image; it is only meaningful for pixels whose magnitude value is above the lower bound threshold value.  Returns the identifier of the internal angle buffer ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

  Open   Collapse   M_CONTEXT_TYPE

 Returns the type of the Edge Finder context that was used to extract edges.  Returns the type of the Edge Finder context that was used to extract edges ...

FirstResultArrayPtr info

Return values:
M_CONTOUR, M_CREST (details)

  Open   Collapse   M_CROSS_DERIVATIVE_ID

 Returns the identifier of the internal cross derivative buffer. Note that to perform this operation, the internal cross derivative buffer must have been previously saved by enabling M_SAVE_DERIVATIVES in MedgeControl().  Returns the identifier of the internal cross derivative buffer ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

 When provided by Edge Finder, derivative buffers are always consistent (for example, they have the same scaling factor) and are always normalized to 10-bit images such that the maximum output value is 1024 for 8-bit source images. When you provide the derivative buffers, they should respect these limitations for best performance (see MedgeCalculate()).

  Open   Collapse   M_FIRST_DERIVATIVE_X_ID

 Returns the identifier of the internal first derivative buffer in the X-direction. Note that to perform this operation, the internal first derivative buffer must have been previously saved by enabling M_SAVE_DERIVATIVES in MedgeControl().  Returns the identifier of the internal first derivative buffer in the X-direction ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

 When provided by Edge Finder, derivative buffers are always consistent (for example, they have the same scaling factor) and are always normalized to 10-bit images such that the maximum output value is 1024 for 8-bit source images. When you provide the derivative buffers, they should respect these limitations for best performance (see MedgeCalculate()).

  Open   Collapse   M_FIRST_DERIVATIVE_Y_ID

 Returns the identifier of the internal first derivative buffer in the Y-direction. Note that to perform this operation, the internal first derivative buffer must have been previously saved by enabling M_SAVE_DERIVATIVES in MedgeControl().  Returns the identifier of the internal first derivative buffer in the Y-direction ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

 When provided by Edge Finder, derivative buffers are always consistent (for example, they have the same scaling factor) and are always normalized to 10-bit images such that the maximum output value is 1024 for 8-bit source images. When you provide the derivative buffers, they should respect these limitations for best performance (see MedgeCalculate()).

  Open   Collapse   M_FIRST_DERIVATIVES_ID

 Returns the identifier of the internal first derivative buffers in both the X- and Y-directions. Note that to perform this operation, the internal first derivative buffers must have been previously saved by enabling M_SAVE_DERIVATIVES in MedgeControl().  Returns the identifier of the internal first derivative buffers in both the X- and Y-directions ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

 When provided by Edge Finder, derivative buffers are always consistent (for example, they have the same scaling factor) and are always normalized to 10-bit images such that the maximum output value is 1024 for 8-bit source images. When you provide the derivative buffers, they should respect these limitations for best performance (see MedgeCalculate()).

FirstResultArrayPtr info

Return values:

 MIL first derivative buffer identifier
 Internal buffer identifier of the first derivative buffer, in the X-direction.

SecondResultArrayPtr info

Return values:

 MIL first derivative buffer identifier
 Internal buffer identifier of the first derivative buffer, in the Y-direction.

  Open   Collapse   M_IMAGE_ID

 Returns the source image's internal buffer identifier. Note that to perform this operation, the source image must have been previously saved by enabling M_SAVE_IMAGE in MedgeControl().  Returns the source image's internal buffer identifier ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

  Open   Collapse   M_MAGNITUDE_ID

 Returns the identifier of the internal magnitude buffer. Note that to perform this operation, the internal magnitude buffer must have been previously saved by enabling the MedgeControl() M_SAVE_MAGNITUDE control type.  Returns the identifier of the internal magnitude buffer. Note that to perform this operation, the internal magnitude buffer must have been previously saved by enabling the MedgeControl() M_SAVE_MAGNITUDE control type ...

 The magnitude buffer is calculated according to MedgeControl() with M_MAGNITUDE_TYPE. If M_MAGNITUDE_TYPE is set to M_SQR_NORM, magnitude values are truncated on 15.0 bits. If M_MAGNITUDE_TYPE is set to M_NORM, magnitude values are truncated on 8.7 bits, with fixed-point precision. 32-bit float buffers use the same conventions, but with floating-point precision.

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

  Open   Collapse   M_MASK_ID

 Returns the mask's internal buffer identifier. Note that to perform this operation, the mask buffer must have been previously saved by enabling M_SAVE_MASK in MedgeControl().  Returns the mask's internal buffer identifier ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

FirstResultArrayPtr info

Return values:
M_NULL, MIL image buffer identifier (details)

  Open   Collapse   M_SECOND_DERIVATIVE_X_ID

 Returns the identifier of the internal second derivative buffer in the X-direction. Note that to perform this operation, the internal second derivative buffer must have been previously saved by enabling M_SAVE_DERIVATIVES in MedgeControl().  Returns the identifier of the internal second derivative buffer in the X-direction ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

 When provided by Edge Finder, derivative buffers are always consistent (for example, they have the same scaling factor) and are always normalized to 10-bit images such that the maximum output value is 1024 for 8-bit source images. When you provide the derivative buffers, they should respect these limitations for best performance (see MedgeCalculate()).

  Open   Collapse   M_SECOND_DERIVATIVE_Y_ID

 Returns the identifier of the internal second derivative buffer in the Y-direction. Note that to perform this operation, the internal second derivative buffer must have been previously saved by enabling M_SAVE_DERIVATIVES in MedgeControl().  Returns the identifier of the internal second derivative buffer in the Y-direction ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

 When provided by Edge Finder, derivative buffers are always consistent (for example, they have the same scaling factor) and are always normalized to 10-bit images such that the maximum output value is 1024 for 8-bit source images. When you provide the derivative buffers, they should respect these limitations for best performance (see MedgeCalculate()).

  Open   Collapse   M_SECOND_DERIVATIVES_ID

 Returns the identifier of the internal second derivative buffers in both the X- and Y-directions. Note that to perform this operation, the internal second derivative buffers must have been previously saved by enabling M_SAVE_DERIVATIVES in MedgeControl().  Returns the identifier of the internal second derivative buffers in both the X- and Y-directions ...

 On remote systems, the internal buffer identifier might not be available, and M_NULL is returned instead. In this case, you can access the buffer using conventional MIL techniques. For more information, see the Internal processing buffers subsection in the Calculating and retrieving results section in
          Chapter 9: Edge Finder.

 When provided by Edge Finder, derivative buffers are always consistent (for example, they have the same scaling factor) and are always normalized to 10-bit images such that the maximum output value is 1024 for 8-bit source images. When you provide the derivative buffers, they should respect these limitations for best performance (see MedgeCalculate()).

FirstResultArrayPtr info

Return values:

 MIL second derivative buffer identifier
 Internal buffer identifier of the second derivative buffer, in the X-direction.

SecondResultArrayPtr info

Return values:

 MIL second derivative buffer identifier
 Internal buffer identifier of the second derivative buffer, in the Y-direction.

  Open   Collapse   M_SIZE_X

 Returns the width of the image from which the edges were extracted, in pixels.  Returns the width of the image from which the edges were extracted, in pixels.

  Open   Collapse   M_SIZE_Y

 Returns the height of the image from which the edges were extracted, in pixels.  Returns the height of the image from which the edges were extracted, in pixels.

  Open   Collapse   M_THRESHOLD_HIGH

 Returns the upper bound value, used by the hysteresis threshold to extract edges.  Returns the upper bound value, used by the hysteresis threshold to extract edges ...

FirstResultArrayPtr info

Return values:
M_DEFAULT, Value (details)

  Open   Collapse   M_THRESHOLD_LOW

 Returns the lower bound value, used by the hysteresis threshold to extract edges.  Returns the lower bound value, used by the hysteresis threshold to extract edges ...

FirstResultArrayPtr info

Return values:
M_DEFAULT, Value (details)

  Open   Collapse   M_THRESHOLDS

 Returns both the lower and upper bound values, used by the hysteresis threshold to extract edges.  Returns both the lower and upper bound values, used by the hysteresis threshold to extract edges ...

FirstResultArrayPtr info

Return values:

M_DEFAULT, Value (details)

SecondResultArrayPtr info

Return values:

M_DEFAULT, Value (details)

  Open   Collapse   M_TIMEOUT_END

 Returns whether the timeout limit was reached. You can set the timeout limit using MedgeControl() with M_TIMEOUT. By default, there is no limit.  Returns whether the timeout limit was reached ...

FirstResultArrayPtr info

Return values:
M_FALSE | Specifies that the timeout limit has not been reached.
M_TRUE | Specifies that the timeout limit has been reached.

      [Combination constants]

 The following values can be added to the specified internal processing buffer to retrieve information about its contents. Note that results are only returned to FirstResultArrayPtr; therefore, SecondResultArrayPtr must be set to M_NULL.

  Open   Collapse  Value
Description

  Open   Collapse   M_SIGN

 Returns the buffer range.  Returns the buffer range ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

Return values:
M_SIGNED | Buffer range is signed.
M_UNSIGNED | Buffer range is unsigned.

  Open   Collapse   M_SIZE_BAND

 Returns the number of buffer color bands.  Returns the number of buffer color bands ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

  Open   Collapse   M_SIZE_BIT

 Returns the depth per band, in bits.  Returns the depth per band, in bits ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

  Open   Collapse   M_SIZE_X

 Returns the width of the buffer, in pixels.  Returns the width of the buffer, in pixels ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

  Open   Collapse   M_SIZE_Y

 Returns the height of the buffer, in pixels.  Returns the height of the buffer, in pixels ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

  Open   Collapse   M_TYPE

 Returns the buffer data type and depth. Depth is returned in bits.  Returns the buffer data type and depth ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

Return values:
1 + M_UNSIGNED | 1-bit unsigned data.
8 + M_SIGNED | 8-bit signed data.
8 + M_UNSIGNED | 8-bit unsigned data.
16 + M_SIGNED | 16-bit signed data.
16 + M_UNSIGNED | 16-bit unsigned data.
32 + M_FLOAT | 32-bit float data.
32 + M_SIGNED | 32-bit signed data.
32 + M_UNSIGNED | 32-bit unsigned data.

 To retrieve edge chain results, the ResultType parameter can be set to one of the values below. If EdgeIndexOrLabelValue is set to an index value or a label value, the edge chain result for the specified edge is returned. If EdgeIndexOrLabelValue is set to M_ALL, the edge chain result for all the included edges in the Edge Finder result buffer is returned. Note that, unless otherwise specified, results are only returned to FirstResultArrayPtr; when this is the case, SecondResultArrayPtr must be set to M_NULL.

Unless otherwise specified, the following values require that you pass

                  the FirstResultArrayPtr parameter the address of
                  an
                    array of type double (Use M_NUMBER_OF_CHAINED_EDGELS to determine
                the size of the array.) and

                  the SecondResultArrayPtr parameter the address of
                  an
                    array of type double (Use M_NUMBER_OF_CHAINED_EDGELS to determine
                the size of the array.).

  Open   Collapse  Value
Description

  Open   Collapse   M_BULGES

 Returns the bulge values between vertices. Note that to retrieve bulge values, the chain approximation (M_CHAIN_APPROXIMATION) must have been previously performed (see MedgeControl()).  Returns the bulge values between vertices ...

 The bulge determines the circular arc that lies between the current vertex and the next vertex; it is equal to the tangent of 1/4 the angle between consecutive vertices, and is negative for a clockwise arc. For example, the bulge of a straight line is 0 while the bulge of a semicircle is 1.

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_VERTICES to determine the size of the array.

  Open   Collapse   M_CHAIN

 Returns the coordinates of the edge(s)'s edgels.  Returns the coordinates of the edge(s)'s edgels ...

 Note that this value can be used in combination with M_PACKED; see below.

FirstResultArrayPtr info

Return values:

 X-coordinate value
 The edgels' X-coordinates.

SecondResultArrayPtr info

Return values:

 Y-coordinate value
 The edgels' Y-coordinates.

  Open   Collapse   M_CHAIN_ANGLE

 Returns the angle values of the edge(s)'s edgels.  Returns the angle values of the edge(s)'s edgels.

  Open   Collapse   M_CHAIN_CODE

 Returns the edge(s)'s chain code. The chain code describes how edgels are connected using the following neighbor code:

 Returns the edge(s)'s chain code ...

  Open   Collapse   M_CHAIN_INDEX

 Returns the index of each edgel's edge.  Returns the index of each edgel's edge.

  Open   Collapse   M_CHAIN_MAGNITUDE

 Returns the magnitude values of the edge(s)'s edgels.  Returns the magnitude values of the edge(s)'s edgels.

  Open   Collapse   M_CHAIN_MAGNITUDE + M_CHAIN_ANGLE

 Returns the magnitude values and the angle values of the edge(s)'s edgels.  Returns the magnitude values and the angle values of the edge(s)'s edgels ...

 Note that M_CHAIN_MAGNITUDE + M_CHAIN_ANGLE can be used in combination with M_PACKED; see below.

FirstResultArrayPtr info

Return values:

 Magnitude value
 The magnitude values of the edge(s)'s edgels.

SecondResultArrayPtr info

Return values:

 Angle value
 The angle values of the edge(s)'s edgels.

  Open   Collapse   M_CHAIN_X

 Returns the X-coordinates of the edge(s)'s edgels.  Returns the X-coordinates of the edge(s)'s edgels.

  Open   Collapse   M_CHAIN_Y

 Returns the Y-coordinates of the edge(s)'s edgels.  Returns the Y-coordinates of the edge(s)'s edgels.

  Open   Collapse   M_NUMBER_OF_CHAINED_EDGELS

 Returns the number of edgels in the edge(s).  Returns the number of edgels in the edge(s) ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

  Open   Collapse   M_NUMBER_OF_CHAINS

 Returns the number of included edges.  Returns the number of included edges ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

  Open   Collapse   M_NUMBER_OF_VERTICES

 Returns the number of vertices in the chain approximation.  Returns the number of vertices in the chain approximation ...

 This value is not valid if MedgeControl() with M_CHAIN_APPROXIMATION is disabled.

FirstResultArrayPtr info

Data type: array of type double
Array size:  This array must be of size 1.

  Open   Collapse   M_VERTICES

 Returns the coordinates of the vertices in the chain approximation.  Returns the coordinates of the vertices in the chain approximation ...

 Note that this value can be used in combination with M_PACKED; see below.

 This value is not valid if MedgeControl() with M_CHAIN_APPROXIMATION is disabled.

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_VERTICES to determine the size of the array.

Return values:

 X-coordinate value
 The X-coordinates of the vertices in the chain approximation.

SecondResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_VERTICES to determine the size of the array.

Return values:

 Y-coordinate value
 The Y-coordinates of the vertices in the chain approximation.

  Open   Collapse   M_VERTICES_CHAIN_INDEX

 Returns the index of the vertices' corresponding edge, in a chain approximation.  Returns the index of the vertices' corresponding edge, in a chain approximation ...

 This value is not valid if MedgeControl() with M_CHAIN_APPROXIMATION is disabled.

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_VERTICES to determine the size of the array.

  Open   Collapse   M_VERTICES_INDEX

 Returns the index of the vertices' corresponding edgels, in a chain approximation.  Returns the index of the vertices' corresponding edgels, in a chain approximation ...

 This value is not valid if MedgeControl() with M_CHAIN_APPROXIMATION is disabled.

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_VERTICES to determine the size of the array.

  Open   Collapse   M_VERTICES_X

 Returns the X-coordinates of the vertices in the chain approximation.  Returns the X-coordinates of the vertices in the chain approximation ...

 This value is not valid if MedgeControl() with M_CHAIN_APPROXIMATION is disabled.

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_VERTICES to determine the size of the array.

  Open   Collapse   M_VERTICES_Y

 Returns the Y-coordinates of the vertices in the chain approximation.  Returns the Y-coordinates of the vertices in the chain approximation ...

 This value is not valid if MedgeControl() with M_CHAIN_APPROXIMATION is disabled.

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_VERTICES to determine the size of the array.

 To retrieve edge feature results, the ResultType parameter must be set to one of the values below. Note that the specified feature must have already been calculated with MedgeCalculate().

 If EdgeIndexOrLabelValue is set to an index value or a label value, the edge feature for the specified edge is returned. If EdgeIndexOrLabelValue is set to M_ALL, the edge feature for all the included edges in the Edge Finder result buffer is returned. Note that, unless otherwise specified, results are only returned to FirstResultArrayPtr; when this is the case, SecondResultArrayPtr must be set to M_NULL.

Unless otherwise specified, the following values require that you pass

                  the FirstResultArrayPtr parameter the address of
                  an
                    array of type double (Use M_NUMBER_OF_CHAINS to determine the size
                of the array.) and

                  the SecondResultArrayPtr parameter the address of
                  an
                    array of type double (Use M_NUMBER_OF_CHAINS to determine the size
                of the array.).

  Open   Collapse  Value
Description

  Open   Collapse   M_AVERAGE_STRENGTH

 Returns the average strength value of each edge.  Returns the average strength value of each edge.

  Open   Collapse   M_BOX_X_MAX

 Returns the X-coordinate of each edge's extreme right edgel.  Returns the X-coordinate of each edge's extreme right edgel.

  Open   Collapse   M_BOX_X_MIN

 Returns the X-coordinate of each edge's extreme left edgel.  Returns the X-coordinate of each edge's extreme left edgel.

  Open   Collapse   M_BOX_Y_MAX

 Returns the Y-coordinate of each edge's extreme bottom edgel.  Returns the Y-coordinate of each edge's extreme bottom edgel.

  Open   Collapse   M_BOX_Y_MIN

 Returns the Y-coordinate of each edge's extreme top edgel.  Returns the Y-coordinate of each edge's extreme top edgel.

  Open   Collapse   M_CENTER_OF_GRAVITY

 Returns the coordinates of each edge's center of gravity.  Returns the coordinates of each edge's center of gravity ...

 Note that this value can be used in combination with M_PACKED; see below.

FirstResultArrayPtr info

Return values:

 X-coordinate value
 The X-coordinate of each edge's center of gravity.

SecondResultArrayPtr info

Return values:

 Y-coordinate value
 The Y-coordinate of each edge's center of gravity.

  Open   Collapse   M_CENTER_OF_GRAVITY_X

 Returns the X-coordinate of each edge's center of gravity.  Returns the X-coordinate of each edge's center of gravity.

  Open   Collapse   M_CENTER_OF_GRAVITY_Y

 Returns the Y-coordinate of each edge's center of gravity.  Returns the Y-coordinate of each edge's center of gravity.

  Open   Collapse   M_CIRCLE_FIT_CENTER_X

 Returns the X-coordinate of the center of the circle that is the best fit for each edge.  Returns the X-coordinate of the center of the circle that is the best fit for each edge.

  Open   Collapse   M_CIRCLE_FIT_CENTER_Y

 Returns the Y-coordinate of the center of the circle that is the best fit for each edge.  Returns the Y-coordinate of the center of the circle that is the best fit for each edge.

  Open   Collapse   M_CIRCLE_FIT_COVERAGE

 Returns the coverage of the circle that is the best fit for each edge. The coverage describes the portion of the circle covered by the edge.  Returns the coverage of the circle that is the best fit for each edge ...

FirstResultArrayPtr info

Return values:

 0.0 to 1.0
 The lower the value, the lower the coverage. For example, 0 equals no coverage, 0.5 equals 50 percent coverage, and 1.0 equals 100 percent coverage.

  Open   Collapse   M_CIRCLE_FIT_ERROR

 Returns the fit error of the circle that is the best fit for each edge. This is calculated as the average quadratic error.  Returns the fit error of the circle that is the best fit for each edge ...

  Open   Collapse   M_CIRCLE_FIT_RADIUS

 Returns the radius of the circle that is the best fit for each edge.  Returns the radius of the circle that is the best fit for each edge.

  Open   Collapse   M_CLOSURE

 Returns the closure status of each edge.  Returns the closure status of each edge ...

FirstResultArrayPtr info

Return values:
M_FALSE | Specifies an open edge.
M_TRUE | Specifies a closed edge.

  Open   Collapse   M_CONVEX_PERIMETER

 Returns the convex elongation of each edge.  Returns the convex elongation of each edge.

  Open   Collapse   M_ELLIPSE_FIT_ANGLE

 Returns the angle of the ellipse that is the best fit for each edge.  Returns the angle of the ellipse that is the best fit for each edge.

  Open   Collapse   M_ELLIPSE_FIT_CENTER_X

 Returns the X-coordinate of the center of the ellipse that is the best fit for each edge.  Returns the X-coordinate of the center of the ellipse that is the best fit for each edge.

  Open   Collapse   M_ELLIPSE_FIT_CENTER_Y

 Returns the Y-coordinate of the center of the ellipse that is the best fit for each edge.  Returns the Y-coordinate of the center of the ellipse that is the best fit for each edge.

  Open   Collapse   M_ELLIPSE_FIT_COVERAGE

 Returns the coverage of the ellipse that is the best fit for each edge. The coverage describes the portion of the ellipse covered by the edge.  Returns the coverage of the ellipse that is the best fit for each edge ...

FirstResultArrayPtr info

Return values:

 0.0 to 1.0
 The lower the value, the lower the coverage. For example, 0.0 equals no coverage, 0.5 equals 50 percent coverage, and 1.0 equals 100 percent coverage.

  Open   Collapse   M_ELLIPSE_FIT_ERROR

 Returns the fit error of the ellipse that is the best fit for each edge.  Returns the fit error of the ellipse that is the best fit for each edge.

  Open   Collapse   M_ELLIPSE_FIT_MAJOR_AXIS

 Returns the major axis of the ellipse that is the best fit for each edge. The major axis divides the ellipse across its long dimension into two equal halves.  Returns the major axis of the ellipse that is the best fit for each edge ...

  Open   Collapse   M_ELLIPSE_FIT_MINOR_AXIS

 Returns the minor axis of the ellipse that is the best fit for each edge. The minor axis divides the ellipse across its short dimension into two equal halves, perpendicular to the major axis.  Returns the minor axis of the ellipse that is the best fit for each edge ...

  Open   Collapse   M_FAST_LENGTH

 Returns the fast length of each edge.  Returns the fast length of each edge.

  Open   Collapse   M_FERET_BOX

 Returns the X- and Y-Feret values of each edge. The X-Feret is the dimension of the minimum bounding box of an edge in the horizontal direction. The Y-Feret is the dimension of the minimum bounding box of an edge in the vertical direction.  Returns the X- and Y-Feret values of each edge ...

 Note that this value can be used in combination with M_PACKED; see below.

FirstResultArrayPtr info

Return values:

 X-Feret value
 The X-Feret value of each edge.

SecondResultArrayPtr info

Return values:

 Y-Feret value
 The Y-Feret value of each edge.

  Open   Collapse   M_FERET_ELONGATION

 Returns the Feret elongation of each edge. It is accurate for reasonably compact objects, but becomes less accurate for very elongated objects.  Returns the Feret elongation of each edge ...

  Open   Collapse   M_FERET_MAX_ANGLE

 Returns the maximum Feret angle of each edge, in degrees. This is the angle at which the maximum Feret diameter is found. Positive values indicate a counter-clockwise displacement from the positive X-axis.  Returns the maximum Feret angle of each edge, in degrees ...

  Open   Collapse   M_FERET_MAX_DIAMETER

 Returns the maximum Feret diameter of each edge.  Returns the maximum Feret diameter of each edge.

  Open   Collapse   M_FERET_MEAN_DIAMETER

 Returns the average Feret diameter at all the angles checked (see M_NUMBER_OF_FERETS).  Returns the average Feret diameter at all the angles checked (see M_NUMBER_OF_FERETS).

  Open   Collapse   M_FERET_MIN_ANGLE

 Returns the minimum Feret angle of each edge.  Returns the minimum Feret angle of each edge.

  Open   Collapse   M_FERET_MIN_DIAMETER

 Returns the minimum Feret diameter of each edge.  Returns the minimum Feret diameter of each edge.

  Open   Collapse   M_FERET_X

 Returns the X-Feret value of each edge. This is the dimension of the minimum bounding box of an edge in the horizontal direction.  Returns the X-Feret value of each edge ...

  Open   Collapse   M_FERET_Y

 Returns the Y-Feret value of each edge. This is the dimension of the minimum bounding box of an edge in the vertical direction.  Returns the Y-Feret value of each edge ...

  Open   Collapse   M_FIRST_POINT

 Returns the coordinates of each edge's first point.  Returns the coordinates of each edge's first point ...

 Note that this value can be used in combination with M_PACKED; see below.

FirstResultArrayPtr info

Return values:

 X-coordinate value
 The first point X-coordinate of each edge.

SecondResultArrayPtr info

Return values:

 Y-coordinate value
 The first point Y-coordinate of each edge.

  Open   Collapse   M_FIRST_POINT_X

 Returns the X-coordinate of each edge's first point.  Returns the X-coordinate of each edge's first point.

  Open   Collapse   M_FIRST_POINT_Y

 Returns the Y-coordinate of each edge's first point.  Returns the Y-coordinate of each edge's first point.

  Open   Collapse   M_GENERAL_FERET

 Returns the general Feret of each edge. This is the Feret diameter calculated at M_GENERAL_FERET_ANGLE, which is set in MedgeControl().  Returns the general Feret of each edge ...

  Open   Collapse   M_LABEL_VALUE

 Returns the label value of each edge in an image. The label value is a positive integer greater or equal to one; each edge in an image has a unique label value.  Returns the label value of each edge in an image ...

  Open   Collapse   M_LENGTH

 Returns the length of each edge. M_LENGTH gives a more accurate but slower approximation of the edge's length than M_FAST_LENGTH.  Returns the length of each edge.M_LENGTH gives a more accurate but slower approximation of the edge's length than M_FAST_LENGTH ...

  Open   Collapse   M_LINE_FIT_A

 Returns the A variable of the line that is the best fit for each edge.  Returns the A variable of the line that is the best fit for each edge.

  Open   Collapse   M_LINE_FIT_B

 Returns the B variable of the line that is the best fit for each edge.  Returns the B variable of the line that is the best fit for each edge.

  Open   Collapse   M_LINE_FIT_C

 Returns the C variable of the line that is the best fit for each edge.  Returns the C variable of the line that is the best fit for each edge.

  Open   Collapse   M_LINE_FIT_ERROR

 Returns the fit error of the line that is the best fit for each edge. This is calculated as the average quadratic error.  Returns the fit error of the line that is the best fit for each edge ...

  Open   Collapse   M_MOMENT_ELONGATION

 Returns the moment elongation of each edge.  Returns the moment elongation of each edge ...

FirstResultArrayPtr info

Return values:

 0.0 to 1.0
 For example, a straight edge has a null elongation value, while a circular edge has an elongation of 1.0.

  Open   Collapse   M_MOMENT_ELONGATION_ANGLE

 Returns the angle of the principle axis along each edge's moment elongation.  Returns the angle of the principle axis along each edge's moment elongation.

  Open   Collapse   M_POSITION

 Returns the X- and Y-position of each edge. The position of the edge is defined by the middle edgel of the edge.  Returns the X- and Y-position of each edge ...

 Note that this value can be used in combination with M_PACKED; see below.

FirstResultArrayPtr info

Return values:

 X-position value
 The X-position of each edge.

SecondResultArrayPtr info

Return values:

 Y-position value
 The Y-position of each edge.

  Open   Collapse   M_POSITION_X

 Returns the X-position of each edge. The position of the edge is defined by the middle edgel of the edge.  Returns the X-position of each edge ...

  Open   Collapse   M_POSITION_Y

 Returns the Y-position of each edge. The position of the edge is defined by the middle edgel of the edge.  Returns the Y-position of each edge ...

  Open   Collapse   M_SIZE

 Returns the number of edgels in each edge.  Returns the number of edgels in each edge.

  Open   Collapse   M_STRENGTH

 Returns the strength value of each edge.  Returns the strength value of each edge.

  Open   Collapse   M_TORTUOSITY

 Returns the tortuosity measure of each edge.  Returns the tortuosity measure of each edge.

  Open   Collapse   M_X_MAX_AT_Y_MAX

 Returns the maximum X-coordinate at the maximum Y-coordinate of each edge. Together with M_BOX_Y_MAX, this is one of four contact points on the convex perimeter of the edge.  Returns the maximum X-coordinate at the maximum Y-coordinate of each edge ...

  Open   Collapse   M_X_MIN_AT_Y_MIN

 Returns the minimum X-coordinate at the minimum Y-coordinate of each edge. Together with M_BOX_Y_MIN, this is one of four contact points on the convex perimeter of the edge.  Returns the minimum X-coordinate at the minimum Y-coordinate of each edge ...

  Open   Collapse   M_Y_MAX_AT_X_MIN

 Returns the maximum Y-coordinate at the minimum X-coordinate of each edge. Together with M_BOX_X_MIN, this is one of four contact points on the convex perimeter of the edge.  Returns the maximum Y-coordinate at the minimum X-coordinate of each edge ...

  Open   Collapse   M_Y_MIN_AT_X_MAX

 Returns the minimum Y-coordinate at the maximum X-coordinate of each edge. Together with M_BOX_X_MAX, this is one of four contact points on the convex perimeter of the edge.  Returns the minimum Y-coordinate at the maximum X-coordinate of each edge ...

      [Combination constants]

 For edge feature results, the following value can be added to verify if the result is available in the result buffer.

  Open   Collapse  Value
Description

  Open   Collapse   M_AVAILABLE

 Returns whether an edge feature result type is available to be retrieved.  Returns whether an edge feature result type is available to be retrieved ...

FirstResultArrayPtr info

Return values:
M_NULL | The result is not available to be retrieved.
Value | The result is available to be retrieved.

SecondResultArrayPtr info

Return values:

    Must be set to M_NULL.

      [Combination constants]

 One of the following values can be added to M_FERET_MAX_DIAMETER, M_FERET_MIN_DIAMETER, or M_GENERAL_FERET to retrieve indices of the edgels from which the specified Feret was calculated.

  Open   Collapse  Value
Description

  Open   Collapse   M_FIRST_FERET_INDEX

 Returns the first index of the edgel from which the specified Feret was calculated.  Returns the first index of the edgel from which the specified Feret was calculated ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_CHAINS to determine the size of the array.

SecondResultArrayPtr info

Return values:

    Must be set to M_NULL.

  Open   Collapse   M_FIRST_FERET_INDEX + M_SECOND_FERET_INDEX

 Returns the first and second index of the edgel from which the specified Feret was calculated.  Returns the first and second index of the edgel from which the specified Feret was calculated ...

 Note that M_FIRST_FERET_INDEX + M_SECOND_FERET_INDEX can be used in combination with M_PACKED; see below.

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_CHAINS to determine the size of the array.

Return values:

 First index value
 First edgel index.

SecondResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_CHAINS to determine the size of the array.

Return values:

 Second index value
 Second edgel index.

  Open   Collapse   M_SECOND_FERET_INDEX

 Returns the second index of the edgel from which the specified Feret was calculated.  Returns the second index of the edgel from which the specified Feret was calculated ...

FirstResultArrayPtr info

Data type: array of type double
Array size:  Use M_NUMBER_OF_CHAINS to determine the size of the array.

SecondResultArrayPtr info

Return values:

    Must be set to M_NULL.

      [Combination constants]

 To pack values, you can add the value below to the specified result type.

 If you pack values, result types that return values in both FirstResultArrayPtr and SecondResultArrayPtr will be returned together, interlaced in FirstResultArrayPtr. For example, if you decide to pack MedgeGetResult() with M_CENTER_OF_GRAVITY, FirstResultArrayPtr will contain both the X- and Y-coordinates of the edge's center of gravity (XY XY XY ...).

Open Collapse Value | Description
Open Collapse M_PACKED | Returns the specified values in a packed format. Note that only result types that return values in both FirstResultArrayPtr and SecondResultArrayPtr can be packed. Returns the specified values in a packed format ...

      [Combination constants]

 To retrieve statistics about results, add one of the following values to the specified result type. Note that results are only returned to FirstResultArrayPtr; therefore, SecondResultArrayPtr must be set to M_NULL.

Open Collapse Value | Description
Open Collapse M_MAX | Returns the maximum value of the requested result type. Returns the maximum value of the requested result type ...
 |  | FirstResultArrayPtr info Data type: array of type double Array size: This array must be of size 1.
Open Collapse M_MAX_ABS | Returns the maximum absolute value of the requested result type. Returns the maximum absolute value of the requested result type ...
 |  | FirstResultArrayPtr info Data type: array of type double Array size: This array must be of size 1.
Open Collapse M_MEAN | Returns the mean value of the requested result type. Returns the mean value of the requested result type ...
 |  | FirstResultArrayPtr info Data type: array of type double Array size: This array must be of size 1.
Open Collapse M_MIN | Returns the minimum value of the requested result type. Returns the minimum value of the requested result type ...
 |  | FirstResultArrayPtr info Data type: array of type double Array size: This array must be of size 1.
Open Collapse M_MIN_ABS | Returns the minimum absolute value of the requested result type. Returns the minimum absolute value of the requested result type ...
 |  | FirstResultArrayPtr info Data type: array of type double Array size: This array must be of size 1.
Open Collapse M_STANDARD_DEVIATION | Returns the standard deviation of the requested result type. Returns the standard deviation of the requested result type ...
 |  | FirstResultArrayPtr info Data type: array of type double Array size: This array must be of size 1.

      [Combination constants]

 The following values can be added to the ResultType parameter to cast the requested results to a required data type.

Open Collapse Value | Description
Open Collapse M_TYPE_DOUBLE | Casts the requested results to a double. Casts the requested results to a double ... This is the default value.
 |  | FirstResultArrayPtr and SecondResultArrayPtr info Data type: array of type double Array size: Array size depends on the result being cast.
Open Collapse M_TYPE_LONG | Casts the requested results to a long. Casts the requested results to a long ...
 |  | FirstResultArrayPtr and SecondResultArrayPtr info Data type: array of type long Array size: Array size depends on the result being cast.
Open Collapse M_TYPE_MIL_ID | Casts the requested results to a MIL_ID. Casts the requested results to a MIL_ID ...
 |  | FirstResultArrayPtr and SecondResultArrayPtr info Data type: array of type MIL_ID Array size: Array size depends on the result being cast.

 FirstResultArrayPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type double
    •

  • array of type long
    •

  • array of type MIL_ID
    •

 Specifies the address of the first array in which to write the requested information.

 SecondResultArrayPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type double
    •

 Specifies the address of the second array in which to write the requested information. If nothing is to be written, set SecondResultArrayPtr to M_NULL.

OUTPUT COORDINATE SYSTEM WORLD PIXEL ALL LABEL VALUE SAVE ANGLE SAVE DERIVATIVES SAVE DERIVATIVES SAVE DERIVATIVES SAVE DERIVATIVES SAVE IMAGE SAVE MAGNITUDE MAGNITUDE TYPE MAGNITUDE TYPE SQR NORM MAGNITUDE TYPE NORM SAVE MASK SAVE DERIVATIVES SAVE DERIVATIVES SAVE DERIVATIVES TIMEOUT NUMBER OF CHAINED EDGELS NUMBER OF CHAINED EDGELS ALL CHAIN APPROXIMATION NUMBER OF VERTICES PACKED CHAIN MAGNITUDE CHAIN ANGLE PACKED PACKED NUMBER OF VERTICES NUMBER OF VERTICES NUMBER OF VERTICES NUMBER OF VERTICES NUMBER OF VERTICES NUMBER OF VERTICES CHAIN APPROXIMATION NUMBER OF CHAINS NUMBER OF CHAINS ALL PACKED PACKED NUMBER OF FERETS PACKED GENERAL FERET ANGLE LENGTH FAST LENGTH PACKED BOX Y MAX BOX Y MIN BOX X MIN BOX X MAX FERET MAX DIAMETER FERET MIN DIAMETER GENERAL FERET NUMBER OF CHAINS FIRST FERET INDEX SECOND FERET INDEX PACKED NUMBER OF CHAINS NUMBER OF CHAINS NUMBER OF CHAINS CENTER OF GRAVITY   DEFAULT ALL  TYPE INDEX TYPE LABEL  ANGLE ID CONTEXT TYPE CROSS DERIVATIVE ID FIRST DERIVATIVE X ID FIRST DERIVATIVE Y ID FIRST DERIVATIVES ID IMAGE ID MAGNITUDE ID MASK ID SECOND DERIVATIVE X ID SECOND DERIVATIVE Y ID SECOND DERIVATIVES ID SIZE X SIZE Y THRESHOLD HIGH THRESHOLD LOW THRESHOLDS TIMEOUT END SIZE X SIZE Y SIZE BAND SIGN TYPE SIZE BIT BULGES CHAIN CHAIN ANGLE CHAIN CODE CHAIN INDEX  CHAIN MAGNITUDE CHAIN MAGNITUDE  M CHAIN ANGLE CHAIN X CHAIN Y NUMBER OF CHAINED EDGELS NUMBER OF CHAINS NUMBER OF VERTICES VERTICES VERTICES X VERTICES Y VERTICES INDEX VERTICES CHAIN INDEX AVERAGE STRENGTH BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN CENTER OF GRAVITY CENTER OF GRAVITY X CENTER OF GRAVITY Y CIRCLE FIT CENTER X CIRCLE FIT CENTER Y CIRCLE FIT COVERAGE CIRCLE FIT ERROR CIRCLE FIT RADIUS CLOSURE CONVEX PERIMETER ELLIPSE FIT ANGLE ELLIPSE FIT CENTER X ELLIPSE FIT CENTER Y ELLIPSE FIT COVERAGE ELLIPSE FIT ERROR ELLIPSE FIT MAJOR AXIS ELLIPSE FIT MINOR AXIS FAST LENGTH FERET BOX FERET ELONGATION FERET MAX ANGLE FERET MAX DIAMETER FERET MEAN DIAMETER FERET MIN ANGLE FERET MIN DIAMETER FERET X FERET Y FIRST POINT FIRST POINT X FIRST POINT Y GENERAL FERET LABEL VALUE LENGTH LINE FIT A LINE FIT B LINE FIT C LINE FIT ERROR MOMENT ELONGATION MOMENT ELONGATION ANGLE POSITION POSITION X POSITION Y SIZE STRENGTH TORTUOSITY X MAX AT Y MAX X MIN AT Y MIN Y MAX AT X MIN Y MIN AT X MAX AVAILABLE FIRST FERET INDEX FIRST FERET INDEX  M SECOND FERET INDEX SECOND FERET INDEX PACKED MIN MIN ABS MAX MAX ABS MEAN STANDARD DEVIATION TYPE DOUBLE TYPE LONG TYPE MIL ID


MedgeInquire

See Also | Example | Availability | MedgeGetResult | MedgeMask
User Guide:
Edge features

Reference:
MedgeAlloc
MedgeAllocResult
MedgeCalculate
MedgeControl
MedgeGetNeighbors
MedgeGetResult
MedgeMask
MedgeSelect
There are no examples containing MedgeInquire().
Not available in MIL-Lite

Available in MIL
Synopsis
Inquire about an Edge Finder context or an Edge Finder result buffer.
Syntax
long MedgeInquire(
MIL_ID ContextOrResultId,
long InquireType,
void *UserVarPtr
)
Description

This function inquires information about the specified Edge Finder context or Edge Finder result buffer.

Note that for an Edge Finder result buffer, this function only retrieves information about result buffer settings (set with MedgeControl(), for example). To retrieve results from the Edge Finder result buffer, use MedgeGetResult().

Parameters
ContextOrResultId

Specifies either the Edge Finder context or the Edge Finder result buffer about which to inquire information. Both the Edge Finder context and the Edge Finder result buffer must have been previously allocated on the system using MedgeAlloc() or MedgeAllocResult(), respectively.

InquireType

Specifies the context or result setting about which to inquire.

To inquire about the operation settings for both M_CONTOUR and M_CREST Edge Finder contexts, set this parameter to one of the following values:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_ACCURACY

Returns the edgel accuracy of the edge extraction. Returns the edgel accuracy of the edge extraction ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_HIGH, M_VERY_HIGH (details)
Open Collapse M_CHAIN_ALL_NEIGHBORS

Returns whether edge chains are built using all the available neighboring edgels. Returns whether edge chains are built using all the available neighboring edgels ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_EXTRACTION_SCALE

Returns the image scale with which to extract the edges. Returns the image scale with which to extract the edges ...

Returns the scale of the image at which to do the edge extraction. Once the extraction is complete, the results are scaled to the original scale of the image.

A lower extraction scale speeds up the the search but can result in a less reliable result, including, the loss of important details and/or a reduction in the accuracy of the search results.

M_EXTRACTION_SCALE is for advanced users of the EdgeFinder module. The default setting usually provides the most accurate search results.

UserVarPtr info

Return values:
0 < Value <= 1, M_DEFAULT (details)
Open Collapse M_FILTER_MODE

Returns the mode in which to perform the edge extraction filter. Returns the mode in which to perform the edge extraction filter ...

UserVarPtr info

Return values:
M_DEFAULT, M_KERNEL, M_RECURSIVE (details)
Open Collapse M_FILTER_SMOOTHNESS

Returns the degree of smoothness (strength of denoising) of the edge extraction filter. Returns the degree of smoothness (strength of denoising) of the edge extraction filter ...

UserVarPtr info

Return values:
0.0 to 100.0, M_DEFAULT (details)
Open Collapse M_FILTER_TYPE

Returns the type of filter used when performing the edge extraction. Returns the type of filter used when performing the edge extraction ...

UserVarPtr info

Return values:
M_DEFAULT, M_DERICHE, M_FREI_CHEN, M_PREWITT, M_SHEN, M_SOBEL (details)
Open Collapse M_FLOAT_MODE

Returns whether the entire edge extraction process is forced to be performed using floating-point precision calculations. Returns whether the entire edge extraction process is forced to be performed using floating-point precision calculations ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_KERNEL_DEPTH

Returns the depth of the convolution kernel used for kernel filtering mode. Returns the depth of the convolution kernel used for kernel filtering mode ...

UserVarPtr info

Return values:
8, 16, M_DEFAULT (details)
Open Collapse M_KERNEL_SIZE

Returns the actual size (same in X and Y) of the convolution kernel used for kernel filtering mode. Note that the kernel size can change according to the filter type and smoothness factor, the kernel's width and depth, and whether you are using floating-point calculations. Returns the actual size (same in X and Y) of the convolution kernel used for kernel filtering mode ...

Open Collapse M_KERNEL_WIDTH

Returns the maximum size (same in X and Y) of the convolution kernel set for kernel filtering mode. Returns the maximum size (same in X and Y) of the convolution kernel set for kernel filtering mode ...

UserVarPtr info

Return values:
M_AUTO, M_DEFAULT, Value >= 3 (details)
Open Collapse M_MAGNITUDE_TYPE

Returns the type of magnitude value used to calculate the magnitude of the edge at each edgel position. Returns the type of magnitude value used to calculate the magnitude of the edge at each edgel position ...

UserVarPtr info

Return values:
M_DEFAULT, M_NORM, M_SQR_NORM (details)
Open Collapse M_MODIFICATION_COUNT

Returns the current value of the modification counter. The modification counter is increased by one each time settings for the context are modified. The modification counter is initialized to a number that is unique to the Edge Finder context and is given its own unique range. If the context is freed, this number will not be reassigned to a new context. Returns the current value of the modification counter. The modification counter is increased by one each time settings for the context are modified ...

This feature can be useful when designing your application. For example, if the modification counter has changed, you can prompt the user to save before closing the application.

Open Collapse M_OVERSCAN

Returns the type of overscan used by the convolution filters when extracting edges for kernel filtering mode. Returns the type of overscan used by the convolution filters when extracting edges for kernel filtering mode ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_MIRROR, M_REPLACE, M_TRANSPARENT (details)
Open Collapse M_OVERSCAN_REPLACE_VALUE

Returns the replacement value for the overscan pixel values when using replacement type overscan. Returns the replacement value for the overscan pixel values when using replacement type overscan ...

UserVarPtr info

Return values:
M_DEFAULT, M_REPLACE_MAX, M_REPLACE_MIN, Value (details)
Open Collapse M_THRESHOLD_HIGH

Returns the user-defined upper bound of the hysteresis threshold. Returns the user-defined upper bound of the hysteresis threshold ...

UserVarPtr info

Return values:
M_DEFAULT, Value (details)
Open Collapse M_THRESHOLD_LOW

Returns the user-defined lower bound of the hysteresis threshold. Returns the user-defined lower bound of the hysteresis threshold ...

UserVarPtr info

Return values:
M_DEFAULT, Value (details)
Open Collapse M_THRESHOLD_MODE

Returns the threshold mode of the edge extraction. Note that lower threshold values result in a more sensitive edgel detection. Returns the threshold mode of the edge extraction ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_HIGH, M_LOW, M_MEDIUM, M_USER_DEFINED, M_VERY_HIGH (details)
Open Collapse M_THRESHOLD_TYPE

Returns the type of the hysteresis threshold used when performing the edge extraction. Returns the type of the hysteresis threshold used when performing the edge extraction ...

UserVarPtr info

Return values:
M_DEFAULT, M_FULL_HYSTERESIS, M_HYSTERESIS, M_NO_HYSTERESIS (details)
Open Collapse M_TIMEOUT

Returns the maximum edge extraction and calculation time for MedgeCalculate(). Returns the maximum edge extraction and calculation time for MedgeCalculate() ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, Value > 0 (details)

To inquire about the operation settings for M_CREST Edge Finder contexts, set this parameter to the value below.

The following values require that you pass the value listed in the data-type area to the UserVarPtr parameter.

Open Collapse Value | Description
Open Collapse M_FOREGROUND_VALUE | Returns the color used to extract line crests from the image. Returns the color used to extract line crests from the image ...
 |  | UserVarPtr info Data type: double Return values: M_ANY, M_DEFAULT, M_FOREGROUND_BLACK, M_FOREGROUND_WHITE (details)

To inquire whether internal buffers have been saved in the Edge Finder result buffer, set this parameter to one of the values below. These values can be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_SAVE_ANGLE | Returns whether the internal angle buffer used to extract edges is saved in the Edge Finder result buffer. Returns whether the internal angle buffer used to extract edges is saved in the Edge Finder result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_SAVE_CHAIN_ANGLE | Returns whether the angle value at each edgel position is saved in the Edge Finder result buffer. Returns whether the angle value at each edgel position is saved in the Edge Finder result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_SAVE_CHAIN_MAGNITUDE | Returns whether the magnitude value at each edgel position is saved in the Edge Finder result buffer. Returns whether the magnitude value at each edgel position is saved in the Edge Finder result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_SAVE_DERIVATIVES | Returns whether the internal derivative buffers used to extract edges are saved in the Edge Finder result buffer. Returns whether the internal derivative buffers used to extract edges are saved in the Edge Finder result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_SAVE_IMAGE | Returns whether the source image is saved in the Edge Finder result buffer. Returns whether the source image is saved in the Edge Finder result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_SAVE_MAGNITUDE | Returns whether the internal magnitude buffer used to extract edges is saved in the Edge Finder result buffer. Returns whether the internal magnitude buffer used to extract edges is saved in the Edge Finder result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_SAVE_MASK | Returns whether the mask buffer is saved in the Edge Finder result buffer. Returns whether the mask buffer is saved in the Edge Finder result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)

To inquire about which edge features will be calculated for each edge, set this parameter to one of the values below. These values can be specified for both M_CONTOUR and M_CREST Edge Finder contexts. Note that, when an edge feature has been calculated, M_ENABLE is returned.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_AVERAGE_STRENGTH | Returns whether the average strength value of each edge will be calculated. Returns whether the average strength value of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_BOX_X_MAX | Returns whether the extreme right edgel coordinate of each edge will be calculated. Returns whether the extreme right edgel coordinate of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_BOX_X_MIN | Returns whether the extreme left edgel coordinate of each edge will be calculated. Returns whether the extreme left edgel coordinate of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_BOX_Y_MAX | Returns whether the extreme bottom edgel coordinate of each edge will be calculated. Returns whether the extreme bottom edgel coordinate of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_BOX_Y_MIN | Returns whether the extreme top edgel coordinate of each edge will be calculated. Returns whether the extreme top edgel coordinate of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CENTER_OF_GRAVITY_X | Returns whether the X-position of each edge's center of gravity will be calculated. Returns whether the X-position of each edge's center of gravity will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CENTER_OF_GRAVITY_Y | Returns whether the Y-position of each edge's center of gravity will be calculated. Returns whether the Y-position of each edge's center of gravity will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CIRCLE_FIT_CENTER_X | Returns whether the X-coordinate of the center of the circle that is the best fit for each edge will be calculated. Returns whether the X-coordinate of the center of the circle that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CIRCLE_FIT_CENTER_Y | Returns whether the Y-coordinate of the center of the circle that is the best fit for each edge will be calculated. Returns whether the Y-coordinate of the center of the circle that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CIRCLE_FIT_COVERAGE | Returns whether the coverage of the circle that is the best fit for each edge will be calculated. Returns whether the coverage of the circle that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CIRCLE_FIT_ERROR | Returns whether the fit error of the circle that is the best fit for each edge will be calculated. Returns whether the fit error of the circle that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CIRCLE_FIT_RADIUS | Returns whether the radius of the circle that is the best fit for each edge will be calculated. Returns whether the radius of the circle that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CLOSURE | Returns whether the closure of each edge will be calculated. Returns whether the closure of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_CONVEX_PERIMETER | Returns whether the convex elongation of each edge will be calculated. Returns whether the convex elongation of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_ELLIPSE_FIT_ANGLE | Returns whether the angle of the ellipse that is the best fit for each edge will be calculated. Returns whether the angle of the ellipse that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_ELLIPSE_FIT_CENTER_X | Returns whether the X-coordinate of the center of the ellipse that is the best fit for each edge will be calculated. Returns whether the X-coordinate of the center of the ellipse that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_ELLIPSE_FIT_CENTER_Y | Returns whether the Y-coordinate of the center of the ellipse that is the best fit for each edge will be calculated. Returns whether the Y-coordinate of the center of the ellipse that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_ELLIPSE_FIT_COVERAGE | Returns whether the coverage of the ellipse that is the best fit for each edge will be calculated. Returns whether the coverage of the ellipse that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_ELLIPSE_FIT_ERROR | Returns whether the fit error of the ellipse that is the best fit for each edge will be calculated. Returns whether the fit error of the ellipse that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_ELLIPSE_FIT_MAJOR_AXIS | Returns whether the major axis of the ellipse that is the best fit for each edge will be calculated. Returns whether the major axis of the ellipse that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_ELLIPSE_FIT_MINOR_AXIS | Returns whether the minor axis the ellipse that is the best fit for each edge will be calculated. Returns whether the minor axis the ellipse that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FAST_LENGTH | Returns whether the length of each edge will be quickly calculated. Returns whether the length of each edge will be quickly calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FERET_ELONGATION | Returns whether the Feret elongation of each edge will be calculated. Returns whether the Feret elongation of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FERET_MAX_ANGLE | Returns whether the maximum Feret angle of each edge will be calculated. Returns whether the maximum Feret angle of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FERET_MAX_DIAMETER | Returns whether the maximum Feret diameter of each edge will be calculated. Returns whether the maximum Feret diameter of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FERET_MEAN_DIAMETER | Returns whether the average Feret diameter of each edge will be calculated. Returns whether the average Feret diameter of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FERET_MIN_ANGLE | Returns whether the minimum Feret angle of each edge will be calculated. Returns whether the minimum Feret angle of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FERET_MIN_DIAMETER | Returns whether the minimum Feret diameter of each edge will be calculated. Returns whether the minimum Feret diameter of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FERET_X | Returns whether the X-Feret value of each edge will be calculated. Returns whether the X-Feret value of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FERET_Y | Returns whether the Y-Feret value of each edge will be calculated. Returns whether the Y-Feret value of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FIRST_POINT_X | Returns whether the X-coordinate of each edge's first point (starting point) will be calculated. Returns whether the X-coordinate of each edge's first point (starting point) will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FIRST_POINT_Y | Returns whether the Y-coordinate of each edge's first point (starting point) will be calculated. Returns whether the Y-coordinate of each edge's first point (starting point) will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_GENERAL_FERET | Returns whether the general Feret of each edge will be calculated. Returns whether the general Feret of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_LABEL_VALUE | Returns whether the label value of each edge in an image will be calculated. Returns whether the label value of each edge in an image will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_LENGTH | Returns whether the length of each edge will be calculated. Returns whether the length of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_LINE_FIT_A | Returns whether the A variable of the line that is the best fit for each edge will be calculated. Returns whether the A variable of the line that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_LINE_FIT_B | Returns whether the B variable of the line that is the best fit for each edge will be calculated. Returns whether the B variable of the line that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_LINE_FIT_C | Returns whether the C variable of the line that is the best fit for each edge will be calculated. Returns whether the C variable of the line that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_LINE_FIT_ERROR | Returns whether the fit error of the line that is the best fit for each edge will be calculated. Returns whether the fit error of the line that is the best fit for each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_MOMENT_ELONGATION | Returns whether the moment elongation of each edge will be calculated. Returns whether the moment elongation of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_MOMENT_ELONGATION_ANGLE | Returns whether the angle of the principle axis along each edge's moment elongation will be calculated. Returns whether the angle of the principle axis along each edge's moment elongation will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_POSITION_X | Returns whether the X-position of each edge will be calculated. Returns whether the X-position of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_POSITION_Y | Returns whether the Y-position of each edge will be calculated. Returns whether the Y-position of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_SIZE | Returns whether the number of edgels in each edge will be calculated. Returns whether the number of edgels in each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_STRENGTH | Returns whether the strength value of each edge will be calculated. Returns whether the strength value of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_TORTUOSITY | Returns whether the tortuosity measure of each edge will be calculated. Returns whether the tortuosity measure of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_X_MAX_AT_Y_MAX | Returns whether the X-maximum at Y-maximum contact point of each edge will be calculated. Returns whether the X-maximum at Y-maximum contact point of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_X_MIN_AT_Y_MIN | Returns whether the X-minimum at Y-minimum contact point of each edge will be calculated. Returns whether the X-minimum at Y-minimum contact point of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_Y_MAX_AT_X_MIN | Returns whether the Y-maximum at X-minimum contact point of each edge will be calculated. Returns whether the Y-maximum at X-minimum contact point of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_Y_MIN_AT_X_MAX | Returns whether the Y-minimum at X-maximum contact point of each edge will be calculated. Returns whether the Y-minimum at X-maximum contact point of each edge will be calculated ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)

To inquire about the corresponding edge feature associated with the specified sorting key, set this parameter to one of the values below. These values can be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_SORTn_DOWN | Returns the feature associated with the nth sorting key (in descending order), where n stands for an integer between 1 and 3. If no feature has been associated, M_NULL is returned. Returns the feature associated with the nth sorting key (in descending order), where n stands for an integer between 1 and 3 ...
Open Collapse M_SORTn_UP | Returns the feature associated with the nth sorting key (in ascending order), where n stands for an integer between 1 and 3. If no feature has been associated, M_NULL is returned. Returns the feature associated with the nth sorting key (in ascending order), where n stands for an integer between 1 and 3 ...

To inquire about general Edge Finder context settings, set this parameter to one of the values below. These values can be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_CONTEXT_TYPE | Returns the type of the Edge Finder context. Returns the type of the Edge Finder context ...
 |  | UserVarPtr info Return values: M_CONTOUR, M_CREST (details)
Open Collapse M_FILTER_POWER | Returns the power of the filter used to extract edges. This indicates the decreasing factor of the noise variance. As the following image illustrates, h represents the filter values, and the sum is computed through the filter support (which can be either finite or infinite): Returns the power of the filter used to extract edges. This indicates the decreasing factor of the noise variance ...
Open Collapse M_MASK_SIZE_X | Returns the X-size of the mask, in pixels. If no mask has been set (MedgeMask()), M_NULL is returned. Returns the X-size of the mask, in pixels ...
Open Collapse M_MASK_SIZE_Y | Returns the Y-size of the mask, in pixels. If no mask has been set (MedgeMask()), M_NULL is returned. Returns the Y-size of the mask, in pixels ...

To inquire about the values used to calculate Feret settings, set this parameter to one of the values below. These values can be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

The following values require that you pass the value listed in the data-type area to the UserVarPtr parameter.

Open Collapse Value | Description
Open Collapse M_GENERAL_FERET_ANGLE | Returns the angle at which to calculate M_GENERAL_FERET. Returns the angle at which to calculate M_GENERAL_FERET ...
 |  | UserVarPtr info Data type: double Return values: 0.0 to 360.0, M_DEFAULT, M_MOMENT_ELONGATION_ANGLE (details)
Open Collapse M_NUMBER_OF_FERETS | Returns the number of Ferets used to calculate M_FERET_MAX_DIAMETER, M_FERET_MIN_DIAMETER, M_FERET_MAX_ANGLE, M_FERET_MIN_ANGLE, M_FERET_ELONGATION, and M_CONVEX_PERIMETER. Returns the number of Ferets used to calculate M_FERET_MAX_DIAMETER, M_FERET_MIN_DIAMETER, M_FERET_MAX_ANGLE, M_FERET_MIN_ANGLE, M_FERET_ELONGATION, and M_CONVEX_PERIMETER ...
 |  | UserVarPtr info Data type: double Return values: M_DEFAULT, Value (details)

To inquire about the settings used when performing post-calculations on extracted edges, set this parameter to one of the values below. These values can be specified for both M_CONTOUR and M_CREST Edge Finder contexts.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_APPROXIMATION_TOLERANCE | Returns the resolution of the edge approximation. Returns the resolution of the edge approximation ...
 |  | UserVarPtr info Return values: 0.0 to 100.0, M_DEFAULT (details)
Open Collapse M_CHAIN_APPROXIMATION | Returns the simple geometric features used to approximate edges. Returns the simple geometric features used to approximate edges ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_LINE (details)
Open Collapse M_FILL_GAP_ANGLE | Returns the aperture angle where Edge Finder searches for edge extremity candidates when filling edge gaps. Returns the aperture angle where Edge Finder searches for edge extremity candidates when filling edge gaps ...
 |  | UserVarPtr info Return values: 0.0 to 360.0, M_DEFAULT (details)
Open Collapse M_FILL_GAP_CANDIDATE | Returns whether an edge extremity is filled with the other extremity of the same edge, or with an extremity of any edge. Returns whether an edge extremity is filled with the other extremity of the same edge, or with an extremity of any edge ...
 |  | UserVarPtr info Return values: M_ANY, M_DEFAULT, M_SAME (details)
Open Collapse M_FILL_GAP_CONTINUITY | Returns the continuity constraint used when performing edge gap filling, when more than one edge extremity candidate is present. Returns the continuity constraint used when performing edge gap filling, when more than one edge extremity candidate is present ...
 |  | UserVarPtr info Return values: 0.0 to 100.0, M_DEFAULT (details)
Open Collapse M_FILL_GAP_DISTANCE | Returns the maximum distance radius where Edge Finder searches for edge extremity candidates when filling edge gaps. Returns the maximum distance radius where Edge Finder searches for edge extremity candidates when filling edge gaps ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_INFINITE, Value (details)
Open Collapse M_FILL_GAP_POLARITY | Returns the polarity constraint used when performing the filling of edge gaps. Returns the polarity constraint used when performing the filling of edge gaps ...
 |  | UserVarPtr info Return values: M_ANY, M_DEFAULT, M_REVERSE, M_SAME (details)

To inquire about Edge Finder result buffer settings, set this parameter to one of the following values:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_DRAW_CROSS_SIZE | Returns the size of the cross used for certain drawing operations. For example, M_DRAW_EDGELS, M_DRAW_POSITION, and M_DRAW_CENTER_OF_GRAVITY are drawn using this cross. Returns the size of the cross used for certain drawing operations ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_DRAW_RELATIVE_ORIGIN_X | Returns the X-coordinate of the drawing region's top-left corner in the source image. Returns the X-coordinate of the drawing region's top-left corner in the source image ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_DRAW_RELATIVE_ORIGIN_Y | Returns the Y-coordinate of the drawing region's top-left corner in the source image. Returns the Y-coordinate of the drawing region's top-left corner in the source image ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_DRAW_SCALE_X | Returns the scale factor in the X-direction to perform zoomed drawings of results. Returns the scale factor in the X-direction to perform zoomed drawings of results ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_DRAW_SCALE_Y | Returns the scale factor in the Y-direction to perform zoomed drawings of results. Returns the scale factor in the Y-direction to perform zoomed drawings of results ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_MODEL_FINDER_COMPATIBLE | Returns whether the Edge Finder result buffer is ready to be used with a model finder context. Returns whether the Edge Finder result buffer is ready to be used with a model finder context ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_NEAREST_NEIGHBOR_RADIUS | Returns the radius distance used to select (MedgeSelect()) the closest edge or edges from a point. Returns the radius distance used to select (MedgeSelect()) the closest edge or edges from a point ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)

To inquire about Edge Finder result buffer settings used when performing closest-edgel operations with MedgeGetNeighbors(), set this parameter to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_NEIGHBOR_ANGLE | Returns the gradient angle that an edgel must have, before being considered a candidate, when finding the closest edgels to a list of points. Returns the gradient angle that an edgel must have, before being considered a candidate, when finding the closest edgels to a list of points ...
 |  | UserVarPtr info Return values: M_ANY, M_DEFAULT, M_REVERSE, M_SAME, M_SAME_OR_REVERSE (details)
Open Collapse M_NEIGHBOR_ANGLE_TOLERANCE | Returns the angular tolerance used for the angle constraint (M_NEIGHBOR_ANGLE), when finding the closest edgels to a list of points. Returns the angular tolerance used for the angle constraint (M_NEIGHBOR_ANGLE), when finding the closest edgels to a list of points ...
 |  | UserVarPtr info Return values: 0.0 to 360.0, M_DEFAULT (details)
Open Collapse M_NEIGHBOR_MAXIMUM_NUMBER | Returns the maximum number of closest edgel candidates that can be returned (for each source point), when finding the closest edgels to a list of points. Returns the maximum number of closest edgel candidates that can be returned (for each source point), when finding the closest edgels to a list of points ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_NEIGHBOR_MINIMUM_SPACING | Returns the minimum distance separating edgels within the same edge, in order for each to be considered potential candidates, when finding the closest edgels to a list of points. Returns the minimum distance separating edgels within the same edge, in order for each to be considered potential candidates, when finding the closest edgels to a list of points ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_INFINITE, Value > = 1 (details)
Open Collapse M_SEARCH_ANGLE | Returns the search angle constraint (applied the Edge Finder result buffer), when finding the closest edgels to a list of points. Returns the search angle constraint (applied the Edge Finder result buffer), when finding the closest edgels to a list of points ...
 |  | UserVarPtr info Return values: 0.0 to 360.0, M_DEFAULT (details)
Open Collapse M_SEARCH_ANGLE_SIGN | Returns the orientation to use for the search angle constraint, when finding the closest edgels to a list of points. Returns the orientation to use for the search angle constraint, when finding the closest edgels to a list of points ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_REVERSE, M_SAME, M_SAME_OR_REVERSE (details)
Open Collapse M_SEARCH_ANGLE_TOLERANCE | Returns the angular tolerance used for the search angle constraint, when finding the closest edgels to a list of points. Returns the angular tolerance used for the search angle constraint, when finding the closest edgels to a list of points ...
 |  | UserVarPtr info Return values: 0.0 to 360.0, M_DEFAULT (details)
Open Collapse M_SEARCH_RADIUS_MAX | Returns the maximum radius distance used to search for the closest edgel candidates that match source edgels. Returns the maximum radius distance used to search for the closest edgel candidates that match source edgels ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_INFINITE, Value (details)
Open Collapse M_SEARCH_RADIUS_MIN | Returns the minimum radius distance used to search for the closest edgel candidates that match source edgels. Returns the minimum radius distance used to search for the closest edgel candidates that match source edgels ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)

To inquire about the system on which either the Edge Finder context or Edge Finder result buffer has been allocated, set this parameter to the value below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_OWNER_SYSTEM | Returns the identifier of the system on which either the Edge Finder context or Edge Finder result buffer has been allocated. Returns the identifier of the system on which either the Edge Finder context or Edge Finder result buffer has been allocated ...
 |  | UserVarPtr info Return values: M_DEFAULT_HOST, MIL system identifier (details)

[Combination constants]

To inquire the default value of an inquire type, add the value below to the specified type.

Open Collapse Value | Description
Open Collapse M_DEFAULT | Returns the default value of the specified inquire type. Returns the default value of the specified inquire type ...
 |  | UserVarPtr info Data type: double

[Combination constants]

To inquire if an inquire type is sortable, or is supported for the Edge Finder context currently being inquired, add the value below to the specified inquire type. Note that to inquire if an inquire type is sortable, you must add M_SUPPORTED to the appropriate sort value (M_SORTn_UP or M_SORTn_DOWN) and the specified inquire type (for example, M_SIZE + M_SORTn_UP + M_SUPPORTED). If the inquire type is not supported for the Edge Finder context, or sortable, M_NULL is returned.

Open Collapse Value Description
Open Collapse M_SUPPORTED

Returns whether the specified inquire type is either sortable, or supported for the Edge Finder context. Returns whether the specified inquire type is either sortable, or supported for the Edge Finder context ...

UserVarPtr info

Data type: double

Return values:
M_NULL | Inquire type is not sortable, or is not supported.
Value | Inquire type is sortable, or is supported.

[Combination constants]

The values below can be added to the InquireType parameter to cast the requested information to a required data type. For example, M_THRESHOLD_HIGH + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_DOUBLE | Casts the requested information to a double. Casts the requested information to a double ... This is the default value.
 |  | UserVarPtr info Data type: double
Open Collapse M_TYPE_LONG | Casts the requested information to a long. Casts the requested information to a long ...
 |  | UserVarPtr info Data type: long
Open Collapse M_TYPE_MIL_ID | Casts the requested information to a MIL_ID. Note that M_TYPE_MIL_ID should only be used with M_OWNER_SYSTEM. Casts the requested information to a MIL_ID ...
 |  | UserVarPtr info Data type: MIL_ID
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • double
  • long
  • MIL_ID

Specifies the address in which the inquiry result will be written.

Return value
The return value is the required information, cast to a long.
CONTOUR CREST EXTRACTION SCALE CREST CONTOUR CREST CONTOUR CREST CONTOUR CREST CONTOUR CREST CONTOUR CREST GENERAL FERET FERET MAX DIAMETER FERET MIN DIAMETER FERET MAX ANGLE FERET MIN ANGLE FERET ELONGATION CONVEX PERIMETER CONTOUR CREST DRAW EDGELS DRAW POSITION DRAW CENTER OF GRAVITY NEIGHBOR ANGLE SUPPORTED SIZE SORTn UP SUPPORTED THRESHOLD HIGH TYPE LONG TYPE MIL ID OWNER SYSTEM ACCURACY CHAIN ALL NEIGHBORS EXTRACTION SCALE FILTER TYPE FILTER MODE KERNEL WIDTH KERNEL SIZE KERNEL DEPTH FILTER SMOOTHNESS MODIFICATION COUNT OVERSCAN OVERSCAN REPLACE VALUE FLOAT MODE TIMEOUT MAGNITUDE TYPE THRESHOLD HIGH THRESHOLD LOW THRESHOLD MODE THRESHOLD TYPE FOREGROUND VALUE SAVE ANGLE SAVE CHAIN ANGLE SAVE CHAIN MAGNITUDE SAVE DERIVATIVES SAVE IMAGE SAVE MAGNITUDE SAVE MASK AVERAGE STRENGTH BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN CENTER OF GRAVITY X CENTER OF GRAVITY Y CIRCLE FIT CENTER X CIRCLE FIT CENTER Y CIRCLE FIT COVERAGE CIRCLE FIT ERROR CIRCLE FIT RADIUS CLOSURE ELLIPSE FIT ANGLE ELLIPSE FIT CENTER X ELLIPSE FIT CENTER Y ELLIPSE FIT COVERAGE ELLIPSE FIT ERROR ELLIPSE FIT MAJOR AXIS ELLIPSE FIT MINOR AXIS CONVEX PERIMETER FAST LENGTH FERET ELONGATION FERET MAX ANGLE FERET MAX DIAMETER FERET MEAN DIAMETER FERET MIN ANGLE FERET MIN DIAMETER FERET X FERET Y FIRST POINT X FIRST POINT Y GENERAL FERET LABEL VALUE LENGTH LINE FIT A LINE FIT B LINE FIT C LINE FIT ERROR MOMENT ELONGATION MOMENT ELONGATION ANGLE POSITION X POSITION Y SIZE STRENGTH TORTUOSITY X MAX AT Y MAX X MIN AT Y MIN Y MAX AT X MIN Y MIN AT X MAX SORTn DOWN SORTn UP CONTEXT TYPE FILTER POWER MASK SIZE X MASK SIZE Y GENERAL FERET ANGLE NUMBER OF FERETS APPROXIMATION TOLERANCE CHAIN APPROXIMATION FILL GAP ANGLE FILL GAP CANDIDATE FILL GAP CONTINUITY FILL GAP DISTANCE FILL GAP POLARITY DRAW CROSS SIZE DRAW RELATIVE ORIGIN X DRAW RELATIVE ORIGIN Y DRAW SCALE X DRAW SCALE Y MODEL FINDER COMPATIBLE NEAREST NEIGHBOR RADIUS SEARCH RADIUS MAX SEARCH RADIUS MIN NEIGHBOR MAXIMUM NUMBER NEIGHBOR MINIMUM SPACING NEIGHBOR ANGLE NEIGHBOR ANGLE TOLERANCE SEARCH ANGLE SEARCH ANGLE TOLERANCE SEARCH ANGLE SIGN OWNER SYSTEM DEFAULT SUPPORTED TYPE DOUBLE TYPE LONG TYPE MIL ID


MedgeMask

See Also | Example | Availability | MedgeInquire | MedgePut
User Guide:
Advanced edge extraction

Reference:
MedgeAlloc
MedgeCalculate
There are no examples containing MedgeMask().
Not available in MIL-Lite

Available in MIL
Synopsis
Mask regions of the Edge Finder context.
Syntax
void MedgeMask(
MIL_ID ContextId,
MIL_ID MaskImageId,
long ControlFlag
)
Description

This function allows you to set a mask for an Edge Finder context. The mask is applied to the image that uses the context. Subsequent calls to MedgeCalculate() will therefore extract edges only in the context's unmasked regions.

You can also mask edges during post-calculation. In this case, masked edges are excluded from the result buffer and subsequent calculations. Note that partially masked edges are cropped.

Parameters
ContextId

Specifies the Edge Finder context in which to set the mask. The Edge Finder context must have been previously allocated on the required system using MedgeAlloc().

MaskImageId

Specifies the identifier of the image buffer used to identify the masked pixels in the Edge Finder context.

Open Collapse Value Description
Open Collapse M_NULL

 Specifies that the mask will be removed.  Specifies that the mask will be removed.

  Open   Collapse  MIL image buffer identifier

 Specifies the image buffer to use as a mask. If the size of the mask image is greater than the source image, the mask will be clipped.  Specifies the image buffer to use as a mask ...

 A masked pixel corresponds to a non-zero value in the mask buffer. Note that this buffer can be calibrated; however, this is not necessary, since the mask is applied on a pixel basis.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

  NULL


MedgePut

See Also | Example | Availability | MedgeMask | MedgeRestore
User Guide:
Steps to performing an edge extraction and analysis
Advanced edge extraction

Reference:
MedgeControl
There are no examples containing MedgePut().
Not available in MIL-Lite

Available in MIL
Synopsis
Put data from user-supplied arrays into an Edge Finder result buffer.
Syntax
void MedgePut(
MIL_ID EdgeResultId,
long NbEdgels,
long *ArrayIndexPtr,
double *ArrayXPtr,
double *ArrayYPtr,
double *ArrayAnglePtr,
double *ArrayMagnitudePtr,
long ControlFlag
)
Description

This function copies data from user-supplied arrays to a specified Edge Finder result buffer. This can be useful if you want to construct an Edge Finder result buffer that cannot be obtained from one image. You can therefore combine results from multiple Edge Finder result buffers to, for example, build a complete model to add to a Model Finder context.

If edgels are calculated with pixel accuracy, the distance between consecutive edgels should be one pixel. If edgels are calculated with subpixel accuracy, the distance between consecutive edgels should be one edgel. To change the accuracy edgels are calculated with, use MedgeControl() with M_ACCURACY.

Parameters
EdgeResultId

Specifies the identifier of the Edge Finder result buffer in which to put user-supplied data.

NbEdgels

Specifies the number of edgels to add to the Edge Finder result buffer.

ArrayIndexPtr

Specifies the address of the array containing the indices of the edgels' edges to add to the Edge Finder result buffer. If you do not want to provide this information, set this parameter to M_NULL. In this case, only one edge will be added.

ArrayXPtr

Specifies the address of the array containing the X-coordinate(s) of the edgel(s) to add to the Edge Finder result buffer.

ArrayYPtr

Specifies the address of the array containing the Y-coordinate(s) of the edgel(s) to add to the Edge Finder result buffer.

ArrayAnglePtr

Specifies the address of the array containing the orientation of the edgel(s) to add to the Edge Finder result buffer. If you do not want to provide this information, set this parameter to M_NULL.

ArrayMagnitudePtr

Specifies the address of the array containing the magnitude of the edgel(s) to add to the Edge Finder result buffer. If you do not want to provide this information, set this parameter to M_NULL.

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

ACCURACY


MedgeRestore

See Also | Example | Availability | MedgePut | MedgeSave
Reference:
MedgeSave
MsysAlloc
There are no examples containing MedgeRestore().
Not available in MIL-Lite

Available in MIL
Synopsis
Restore an Edge Finder context from disk.
Syntax
MIL_ID MedgeRestore(
MIL_TEXT_PTR Filename,
MIL_ID SystemId,
long ControlFlag,
MIL_ID *ContextIdPtr
)
Description

This function restores an Edge Finder context that was previously saved to a file, using MedgeSave(). This function restores all the Edge Finder context's settings that were in effect when the Edge Finder context was saved.

Parameters
Filename

Specifies the Edge Finder context file name and path. The function handles the opening and closing of the file.

SystemId

Specifies the system on which to restore the Edge Finder context.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 ContextIdPtr

 Specifies the address of the variable in which to write the Edge Finder context identifier.  Since the MedgeRestore() function also returns the Edge Finder context identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the Edge Finder context identifier. If allocation fails, M_NULL is returned.

  DEFAULT HOST


MedgeSave

See Also | Example | Availability | MedgeRestore | MedgeSelect
User Guide:
Steps to performing an edge extraction and analysis

Reference:
MedgeRestore
There are no examples containing MedgeSave().
Not available in MIL-Lite

Available in MIL
Synopsis
Save an Edge Finder context to a file, or save edge chains and/or edge approximations from an Edge Finder result buffer to a CAD (Computer-Aided Design) file.
Syntax
void MedgeSave(
MIL_TEXT_PTR FileName,
MIL_ID ContextOrResultId,
long ControlFlag
)
Description

This function saves all the information about the previously allocated Edge Finder context to disk. This information can be reloaded, using MedgeRestore(). However, any associated calibration objects are not saved.

This function also saves calculated edges (edge chains and/or edge approximations) included in a previously calculated Edge Finder result buffer to disk, in a standard DXF format CAD file.

Note that the Edge Finder context or the calculated edges are saved in real-world units if there is a calibration object associated to them. Otherwise, they are saved in pixel units.

Parameters
FileName

Specifies either the file name and path of the Edge Finder context, or the file name and path of the destination CAD file. For easier use with other Matrox Imaging software products, it is recommended that, when saving an Edge Finder context to a file, you use the MEF file extension, and when saving edge chains and/or edge approximations from an Edge Finder result buffer to a CAD file, you use the DXF file extension. In either case, if the file already exists, it will be overwritten. The function handles the opening and closing of this file.

ContextOrResultId

Specifies either the identifier of the Edge Finder context to save, or the identifier of the Edge Finder result buffer from which to save to a CAD file.

ControlFlag

Specifies whether to save edge chains or edge approximations to the DXF CAD file for Edge Finder result buffers. For Edge Finder contexts, this parameter must be set to M_DEFAULT.

For Edge Finder result buffers, this parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_CHAIN

 Specifies that edge chains will be saved.  Specifies that edge chains will be saved.

  Open   Collapse  M_CHAIN_APPROXIMATION

 Specifies that edge approximations will be saved.  Specifies that edge approximations will be saved.

 To save both edge chains and edge approximations, ControlFlag values can be combined (M_CHAIN + M_CHAIN_APPROXIMATION). Note that edge chains and edge approximations are saved in the DXF file in separate layers.

CHAIN CHAIN APPROXIMATION    CHAIN CHAIN APPROXIMATION


MedgeSelect

See Also | Example | Availability | MedgeSave | MedgeStream
User Guide:
Steps to performing an edge extraction and analysis
Calculating and retrieving results
Advanced edge extraction
Interfacing with the Geometric Model Finder module

Reference:
McalControl
MedgeCalculate
MedgeControl
medge.c
Not available in MIL-Lite

Available in MIL
Synopsis
Select edges for calculations and result retrieval.
Syntax
void MedgeSelect(
MIL_ID EdgeResultId,
long Operation,
long SelectionCriterion,
long Condition,
double Param1,
double Param2
)
Description

This function selects edges that meet a specified criterion. These edges will be included in or excluded from future operations (calculations and result retrieval), or deleted entirely from the Edge Finder result buffer. To call this function, MedgeCalculate() must have been called at least once.

If this function is not called at least once, all edges are included by default. If there is more than one call to this function, the effect of the calls is cumulative, unless M_INCLUDE_ONLY or M_EXCLUDE_ONLY is specified as the operation to perform.

Once an edge has been excluded, it can typically be re-included by specifying M_INCLUDE or M_INCLUDE_ONLY in a future call to this function (with the correct criterion). However, if you use the result buffer with different images (in a call to MedgeCalculate()), all results in the result buffer are discarded and all new edges are re-included.

Unlike most other MIL functions, if the edges have been calculated using a calibrated source image, you must specify relevant values in the real world. Note that you can change the output coordinate system using McalControl() with M_OUTPUT_COORDINATE_SYSTEM set to M_PIXEL or M_WORLD.

You can use this function to select edges based on one of the following:

  • A calculated edge feature (see MedgeControl()), where the edge selection depends on whether the specified edge feature meets the specified condition.
  • The inter-relationship of edges, where the edge selection depends on whether edges meet the specified box or chain condition of the specified edge or group of edges.
  • The current status of edges, where the edge selection depends on a specific edge, all edges, all included edges, or all excluded edges. The specified edge(s) will be included, included only, excluded, excluded only, or deleted. For example, you can include only (M_INCLUDE_ONLY) the excluded edges (M_EXCLUDED_EDGES), which will essentially swap the previously included and excluded edges.
  • The proximity of an edge or edges to a specified point, where the edge selection depends on the specified radius, and the nearest neighbor condition.

You can also use this function to crop and select a portion of a specified edge.

For more information on the different uses of this function, see the Calculating and retrieving results section in Chapter 9: Edge Finder and the Advanced edge extraction section in Chapter 9: Edge Finder.

Parameters
EdgeResultId

Specifies the identifier of the Edge Finder result buffer to be used in the edge selection process.

Operation

Specifies the operation to perform on the specified edges. Set this parameter to one of the following values.

Open Collapse Value Description
Open Collapse M_DELETE

 Deletes edges that meet the specified condition. M_DELETE affects only included edges, unless otherwise stated by the SelectionCriterion parameter.  Deletes edges that meet the specified condition ...

M_DELETE removes edges permanently from the Edge Finder result buffer and, consequently, prevents these edges from being re-included.

  Open   Collapse  M_EXCLUDE

 Excludes all edges that meet the specified condition.  Excludes all edges that meet the specified condition ...

M_EXCLUDE affects only the status of currently included edges.

  Open   Collapse  M_EXCLUDE_ONLY

 Excludes only those edges that meet the specified condition and includes all others.  Excludes only those edges that meet the specified condition and includes all others ...

 The exclusion does not consider the present status of edges (whether they are excluded), except for edges that have been deleted (M_DELETE), unless otherwise stated by the SelectionCriterion parameter.

  Open   Collapse  M_INCLUDE

 Includes all edges that meet the specified condition.  Includes all edges that meet the specified condition ...

M_INCLUDE affects only the status of currently excluded edges.

  Open   Collapse  M_INCLUDE_ONLY

 Includes only those edges that meet the specified condition and excludes all others.  Includes only those edges that meet the specified condition and excludes all others ...

 The inclusion does not consider the present status of edges (whether they are included), except for edges that have been deleted (M_DELETE), unless otherwise stated by the SelectionCriterion parameter.

 SelectionCriterion

 Specifies on what the selection criterion will be based.

 To specify an edge selection based on edge features, the SelectionCriterion parameter must be set to one of the values below. The specified feature will be used as part of the selection criterion. Note that the specified Edge Finder result buffer must already contain the results for the specified feature (for more information on each edge feature, see MedgeControl()).

  Open   Collapse  Value
Description

  Open   Collapse  M_AVERAGE_STRENGTH

 Uses the average strength.  Uses the average strength.

  Open   Collapse  M_BOX_X_MAX

 Uses the extreme right edgel coordinate.  Uses the extreme right edgel coordinate.

  Open   Collapse  M_BOX_X_MIN

 Uses the extreme left edgel coordinate.  Uses the extreme left edgel coordinate.

  Open   Collapse  M_BOX_Y_MAX

 Uses the extreme bottom edgel coordinate.  Uses the extreme bottom edgel coordinate.

  Open   Collapse  M_BOX_Y_MIN

 Uses the extreme top edgel coordinate.  Uses the extreme top edgel coordinate.

  Open   Collapse  M_CENTER_OF_GRAVITY_X

 Uses the center of gravity's X-position.  Uses the center of gravity's X-position.

  Open   Collapse  M_CENTER_OF_GRAVITY_Y

 Uses the center of gravity's Y-position.  Uses the center of gravity's Y-position.

  Open   Collapse  M_CIRCLE_FIT_CENTER_X

 Uses the X-coordinate of the center of the circle that is the best fit for each edge.  Uses the X-coordinate of the center of the circle that is the best fit for each edge.

  Open   Collapse  M_CIRCLE_FIT_CENTER_Y

 Uses the Y-coordinate of the center of the circle that is the best fit for each edge.  Uses the Y-coordinate of the center of the circle that is the best fit for each edge.

  Open   Collapse  M_CIRCLE_FIT_COVERAGE

 Uses the coverage of the circle that is the best fit for each edge.  Uses the coverage of the circle that is the best fit for each edge.

  Open   Collapse  M_CIRCLE_FIT_ERROR

 Uses the fit error of the circle that is the best fit for each edge.  Uses the fit error of the circle that is the best fit for each edge.

  Open   Collapse  M_CIRCLE_FIT_RADIUS

 Uses the radius of the circle that is the best fit for each edge.  Uses the radius of the circle that is the best fit for each edge.

  Open   Collapse  M_CLOSURE

 Uses the closure state.  Uses the closure state.

  Open   Collapse  M_CONVEX_PERIMETER

 Uses the convex elongation.  Uses the convex elongation.

  Open   Collapse  M_FAST_LENGTH

 Uses the quickly calculated length.  Uses the quickly calculated length.

  Open   Collapse  M_FERET_ELONGATION

 Uses the Feret elongation.  Uses the Feret elongation.

  Open   Collapse  M_FERET_MAX_ANGLE

 Uses the maximum Feret angle.  Uses the maximum Feret angle.

  Open   Collapse  M_FERET_MAX_DIAMETER

 Uses the maximum Feret diameter.  Uses the maximum Feret diameter.

  Open   Collapse  M_FERET_MEAN_DIAMETER

 Uses the average Feret diameter at all the angles checked (see M_NUMBER_OF_FERETS in MedgeControl()).  Uses the average Feret diameter at all the angles checked (see M_NUMBER_OF_FERETS in MedgeControl()).

  Open   Collapse  M_FERET_MIN_ANGLE

 Uses the minimum Feret angle.  Uses the minimum Feret angle.

  Open   Collapse  M_FERET_MIN_DIAMETER

 Uses the minimum Feret diameter.  Uses the minimum Feret diameter.

  Open   Collapse  M_FERET_X

 Uses the X-Feret value.  Uses the X-Feret value.

  Open   Collapse  M_FERET_Y

 Uses the Y-Feret value.  Uses the Y-Feret value.

  Open   Collapse  M_FIRST_POINT_X

 Uses the first point's X-coordinate.  Uses the first point's X-coordinate.

  Open   Collapse  M_FIRST_POINT_Y

 Uses the first point's Y-coordinate.  Uses the first point's Y-coordinate.

  Open   Collapse  M_GENERAL_FERET

 Uses the general Feret.  Uses the general Feret.

  Open   Collapse  M_LABEL_VALUE

 Uses the label value.  Uses the label value.

  Open   Collapse  M_LENGTH

 Uses the length.  Uses the length.

  Open   Collapse  M_LINE_FIT_A

 Uses the A variable of the line that is the best fit for each edge.  Uses the A variable of the line that is the best fit for each edge.

  Open   Collapse  M_LINE_FIT_B

 Uses the B variable of the line that is the best fit for each edge.  Uses the B variable of the line that is the best fit for each edge.

  Open   Collapse  M_LINE_FIT_C

 Uses the C variable of the line that is the best fit for each edge.  Uses the C variable of the line that is the best fit for each edge.

  Open   Collapse  M_LINE_FIT_ERROR

 Uses the fit error of the line that is the best fit for each edge.  Uses the fit error of the line that is the best fit for each edge.

  Open   Collapse  M_MOMENT_ELONGATION

 Uses the moment elongation.  Uses the moment elongation.

  Open   Collapse  M_POSITION_X

 Uses the X-position.  Uses the X-position.

  Open   Collapse  M_POSITION_Y

 Uses the Y-position.  Uses the Y-position.

  Open   Collapse  M_SIZE

 Uses the number of edgels.  Uses the number of edgels.

  Open   Collapse  M_STRENGTH

 Uses the strength.  Uses the strength.

  Open   Collapse  M_TORTUOSITY

 Uses the tortuosity measure.  Uses the tortuosity measure.

  Open   Collapse  M_X_MAX_AT_Y_MAX

 Uses the maximum X-coordinate at the maximum Y-coordinate.  Uses the maximum X-coordinate at the maximum Y-coordinate.

  Open   Collapse  M_X_MIN_AT_Y_MIN

 Uses the minimum X-coordinate at the minimum Y-coordinate.  Uses the minimum X-coordinate at the minimum Y-coordinate.

  Open   Collapse  M_Y_MAX_AT_X_MIN

 Uses the maximum Y-coordinate at the minimum X-coordinate.  Uses the maximum Y-coordinate at the minimum X-coordinate.

  Open   Collapse  M_Y_MIN_AT_X_MAX

 Uses the minimum Y-coordinate at the maximum X-coordinate.  Uses the minimum Y-coordinate at the maximum X-coordinate.

 To specify an edge selection based on the inter-relationship of edges, you must set the SelectionCriterion parameter to either a specific edge, or to a group of edges. In this case, the SelectionCriterion parameter defines the subset of edges to look inside (M_INSIDE_...) or outside (M_OUTSIDE...); that is, the edges to operate on are those relative to the edge(s) specified by the SelectionCriterion parameter. Note that some Operation and SelectionCriterion parameter values, when used together, do not have any effect, such as excluding (M_EXCLUDE) all the excluded edges (M_EXCLUDED_EDGES).

 To specify the edge(s), set SelectionCriterion to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL_EDGES

 Specifies all edges regardless of their present status, except for edges that have been deleted.  Specifies all edges regardless of their present status, except for edges that have been deleted.

  Open   Collapse  M_EXCLUDED_EDGES

 Specifies all currently excluded edges, except for edges that have been deleted.  Specifies all currently excluded edges, except for edges that have been deleted.

  Open   Collapse  M_INCLUDED_EDGES

 Specifies all currently included edges, except for edges that have been deleted.  Specifies all currently included edges, except for edges that have been deleted.

  Open   Collapse  M_SPECIFIC_EDGE

 Specifies a specific edge. Use Param1 to set the label value of the edge.  Specifies a specific edge ...

 To specify an edge selection based on the current status of edges, the SelectionCriterion parameter must specify the edge or the status of the edges on which to operate. Note that in this case, the SelectionCriterion parameter should be set to one of the same values as an edge selection based on the inter-relationship of edges (see above).

 To specify an edge selection based on the proximity of the edges to a point, the SelectionCriterion parameter must be set to M_NULL.

 To crop and select a portion of a specified edge, the SelectionCriterion parameter must be set to the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_CROP_CHAIN

 Specifies a chain cropping. This is done by specifying the chain to crop (Param1), the side of the chain to crop (Condition), and the edgel index position where you want the chain to be cropped (Param2). The newly created edge receives a new label and can be excluded, included, or deleted from the result buffer. The excluded part of the edge keeps its label value.  Specifies a chain cropping ...

 Condition

 Specifies the condition for the edge selection.

 To specify an edge selection based on edge features, the Condition parameter must either be set to a condition that uses one limit, or a condition that uses two limits.

 To crop and select a portion of a specified edge, the Condition parameter must be set to a condition that uses one limit.

 For conditions that use one limit, set the Condition parameter to one of the values below. Note that, unless otherwise specified, these values are valid for both feature-based and crop-based edge selections.

  Open   Collapse  Value
Description

  Open   Collapse  M_EQUAL

 Specifies that edges with values for the specified feature equal to Param1 are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges with values for the specified feature equal to Param1 are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 This value is not valid for crop-based edge selections.

  Open   Collapse  M_GREATER

 Specifies that edges with values for the specified feature greater than the specified limit value are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges with values for the specified feature greater than the specified limit value are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 For feature-based edge selections, the limit value is set with Param1. For crop-based edge selections, the limit value is set with Param2.

  Open   Collapse  M_GREATER_OR_EQUAL

 Specifies that edges with values for the specified feature greater than or equal to the specified limit value are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges with values for the specified feature greater than or equal to the specified limit value are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 For feature-based edge selections, the limit value is set with Param1. For crop-based edge selections, the limit value is set with Param2.

  Open   Collapse  M_LESS

 Specifies that edges with values for the specified feature less than the specified limit value are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges with values for the specified feature less than the specified limit value are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 For feature-based edge selections, the limit value is set with Param1. For crop-based edge selections, the limit value is set with Param2.

  Open   Collapse  M_LESS_OR_EQUAL

 Specifies that edges with values for the specified feature less than or equal to the specified limit value are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges with values for the specified feature less than or equal to the specified limit value are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 For feature-based edge selections, the limit value is set with Param1. For crop-based edge selections, the limit value is set with Param2.

  Open   Collapse  M_NOT_EQUAL

 Specifies that edges with values for the specified feature not equal to Param1 are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges with values for the specified feature not equal to Param1 are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 This value is not valid for crop-based edge selections.

 For conditions that use two limits, set the Condition parameter to one of the values below. Note that these values are only valid for feature-based edge selections.

  Open   Collapse  Value
Description

  Open   Collapse  M_IN_RANGE

 Specifies that edges with values for the specified feature in the range Param1 to Param2, inclusive, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges with values for the specified feature in the range Param1 to Param2, inclusive, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.

  Open   Collapse  M_OUT_RANGE

 Specifies that edges with values for the specified feature less than Param1, or greater than Param2, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges with values for the specified feature less than Param1, or greater than Param2, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.

 To specify an edge selection based on the inter-relationship of edges, set the Condition parameter to one of the following box or chain values:

  Open   Collapse  Value
Description

  Open   Collapse  M_INSIDE_BOX

 Specifies that edges inside the bounding box of the specified edge, or inside the bounding box of the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges inside the bounding box of the specified edge, or inside the bounding box of the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.

  Open   Collapse  M_INSIDE_CHAIN

 Specifies that edges inside the specified edge, or inside edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges inside the specified edge, or inside edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 Note that if an edge is not closed, this value has no effect. For more information, see M_CLOSURE in MedgeControl(). Also, if an edge is not completely included by closed edge, it is considered as an outside or equal edge.

  Open   Collapse  M_INSIDE_OR_EQUAL_BOX

 Specifies that edges inside or equal to the bounding box of the specified edge, or inside or equal to the bounding box of the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges inside or equal to the bounding box of the specified edge, or inside or equal to the bounding box of the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.

  Open   Collapse  M_INSIDE_OR_EQUAL_CHAIN

 Specifies that edges inside or equal to the specified edge, or inside or equal to the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges inside or equal to the specified edge, or inside or equal to the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 Note that if an edge is not closed, this value has no effect. For more information, see M_CLOSURE in MedgeControl(). Also, if an edge is not completely included by closed edge, it is considered as an outside or equal edge.

  Open   Collapse  M_OUTSIDE_BOX

 Specifies that edges outside the bounding box of the specified edge, or outside the bounding box of the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges outside the bounding box of the specified edge, or outside the bounding box of the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.

  Open   Collapse  M_OUTSIDE_CHAIN

 Specifies that edges outside the specified edge, or outside edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges outside the specified edge, or outside edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 Note that if an edge is not closed, this value has no effect. For more information, see M_CLOSURE in MedgeControl(). Also, if an edge is not completely included by closed edge, it is considered as an outside or equal edge.

  Open   Collapse  M_OUTSIDE_OR_EQUAL_BOX

 Specifies that edges outside or equal to the bounding box of the specified edge, or outside or equal to the bounding box of the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges outside or equal to the bounding box of the specified edge, or outside or equal to the bounding box of the edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.

  Open   Collapse  M_OUTSIDE_OR_EQUAL_CHAIN

 Specifies that edges outside or equal to the specified edge, or outside or equal to edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that edges outside or equal to the specified edge, or outside or equal to edges of the specified group, are included, excluded, or deleted from future operations on the specified Edge Finder result buffer.

 To specify an edge selection based on the current status of edges, set Condition to M_NULL.

 To specify an edge selection based on the proximity of the edges to a point, set the Condition parameter to one of the following neighbor values:

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL_NEAREST_NEIGHBORS

 Specifies that the closest edges within the specified radius and location is included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that the closest edges within the specified radius and location is included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 Define the radius using MedgeControl() with M_NEAREST_NEIGHBOR_RADIUS.

  Open   Collapse  M_NEAREST_NEIGHBOR

 Specifies that the closest edge within the specified radius and location is included, excluded, or deleted from future operations on the specified Edge Finder result buffer.  Specifies that the closest edge within the specified radius and location is included, excluded, or deleted from future operations on the specified Edge Finder result buffer ...

 Define the radius using MedgeControl() with M_NEAREST_NEIGHBOR_RADIUS.

 Param1

 Specifies a value that is dependent on the feature and condition chosen.  If the edges have been calculated using a calibrated source image, you must specify the relevant values in the real world.

 To specify an edge selection based on edge features, where the condition uses one limit, set Param1 to the required condition limit. To specify an edge selection based on edge features, where the condition uses two limits, set Param1 to the high condition limit.

 To specify an edge selection based on the inter-relationship of edges, where SelectionCriterion is set to a specific edge (M_SPECIFIC_EDGE), set Param1 to the label value of the edge. To specify an edge selection based on the inter-relationship of edges, where SelectionCriterion is set to a group of edges (M_ALL_EDGES, M_EXCLUDED_EDGES, M_INCLUDED_EDGES), set Param1 to M_NULL.

 To specify an edge selection based on the current status of edges, set Param1 to M_NULL.

 To specify an edge selection based on the proximity of the edges to a point, set Param1 to the X-coordinate of this point.

 To crop and select a portion of a specified edge (M_CROP_CHAIN), set Param1 to the label value of the edge to crop.

 Param2

 Specifies a value that is dependent on the feature and condition chosen.  If the edges have been calculated using a calibrated source image, you must specify the relevant values in the real world.

 To specify an edge selection based on edge features, where the condition uses one limit, set Param2 to M_NULL. To specify an edge selection based on edge features, where the condition uses two limits, set Param2 to the low condition limit.

 To specify an edge selection based on the inter-relationship of edges, where SelectionCriterion is either set to a specific edge (M_SPECIFIC_EDGE), or to a group of edges (M_ALL_EDGES, M_EXCLUDED_EDGES, M_INCLUDED_EDGES), set Param2 to M_NULL.

 To specify an edge selection based on the current status of edges, set Param2 to M_NULL.

 To specify an edge selection based on the proximity of the edges to a point, set Param2 to the Y-coordinate of this point.

 To crop and select a portion of a specified edge (M_CROP_CHAIN), set Param2 to the edgel index where to split the edge.

INCLUDE ONLY EXCLUDE ONLY INCLUDE INCLUDE ONLY OUTPUT COORDINATE SYSTEM PIXEL WORLD INCLUDE ONLY EXCLUDED EDGES DELETE DELETE EXCLUDE DELETE INCLUDE DELETE NUMBER OF FERETS EXCLUDE EXCLUDED EDGES CLOSURE NEAREST NEIGHBOR RADIUS SPECIFIC EDGE ALL EDGES EXCLUDED EDGES INCLUDED EDGES CROP CHAIN SPECIFIC EDGE ALL EDGES EXCLUDED EDGES INCLUDED EDGES CROP CHAIN   DELETE  EXCLUDE  EXCLUDE ONLY  INCLUDE  INCLUDE ONLY   AVERAGE STRENGTH BOX X MAX BOX X MIN BOX Y MAX BOX Y MIN CENTER OF GRAVITY X CENTER OF GRAVITY Y CIRCLE FIT CENTER X CIRCLE FIT CENTER Y CIRCLE FIT COVERAGE CIRCLE FIT ERROR CIRCLE FIT RADIUS CLOSURE CONVEX PERIMETER FAST LENGTH FERET ELONGATION FERET MAX ANGLE FERET MAX DIAMETER FERET MEAN DIAMETER FERET MIN ANGLE FERET MIN DIAMETER FERET X FERET Y FIRST POINT X FIRST POINT Y GENERAL FERET LABEL VALUE LENGTH LINE FIT A LINE FIT B LINE FIT C LINE FIT ERROR MOMENT ELONGATION POSITION X POSITION Y SIZE STRENGTH TORTUOSITY X MAX AT Y MAX X MIN AT Y MIN Y MAX AT X MIN Y MIN AT X MAX ALL EDGES EXCLUDED EDGES INCLUDED EDGES
                   SPECIFIC EDGE CROP CHAIN  EQUAL GREATER GREATER OR EQUAL LESS LESS OR EQUAL NOT EQUAL IN RANGE OUT RANGE INSIDE BOX INSIDE OR EQUAL BOX INSIDE CHAIN INSIDE OR EQUAL CHAIN OUTSIDE BOX OUTSIDE OR EQUAL BOX OUTSIDE CHAIN OUTSIDE OR EQUAL CHAIN ALL NEAREST NEIGHBORS NEAREST NEIGHBOR


MedgeStream

See Also | Example | Availability | MedgeSelect
Reference:
MappInquire
MedgeSave
MsysAlloc
There are no examples containing MedgeStream().
Not available in MIL-Lite

Available in MIL
Synopsis
Load, restore, or save an Edge Finder context from/to a file or memory stream, or save calculated edges from an Edge Finder result buffer to a file or memory stream in CAD DXF format.
Syntax
void MedgeStream(
MIL_TEXT_PTR MemPtrOrFileName,
MIL_ID SystemId,
long Operation,
long StreamType,
double Version,
long ControlFlag,
MIL_ID *ContextOrResultIdPtr,
long *SizeByteVarPtr
)
Description

This function can load, restore, or save an Edge Finder context from/to a file or memory stream. Moreover, this function can save previously calculated edges (edge chains and/or edge approximations), stored in an Edge Finder result buffer, to a file or memory stream in a standard CAD DXF format.

Note that you cannot load or restore any CAD DXF file or memory stream using this function.

To inquire the number of bytes necessary to save an Edge Finder context or calculated edges to memory stream, you should call this function (MedgeStream()) first with M_INQUIRE_SIZE_BYTE.

Note that the content saved to memory stream is equivalent to the content saved to file. In addition, any file saved with MedgeSave() is equivalent to a file saved using this function.

You can use this and other MIL stream functions, for example, to save all required MIL objects, as well as any other custom data, for your application to a memory stream. Once in a memory stream, you can write the stream to a single file or transfer it over a network. You are responsible for concatenating the streams and for saving the stream to file.

Parameters
MemPtrOrFileName

Specifies the file or memory stream.

When the StreamType parameter is set to M_FILE, MemPtrOrFileName specifies the name and path of the file required for the operation. For easier use with other Matrox Imaging software products, when saving an Edge Finder context to a file, use the MEF file extension, and when saving calculated edges from an Edge Finder result buffer to a CAD file, use the DXF file extension. The function internally handles the opening and closing of the file. If the file already exists, it will be overwritten when M_SAVE is performed.

When the StreamType parameter is set to M_MEMORY, MemPtrOrFileName specifies the address of the block of memory required for the operation. The designated block must be large enough to stream the entire object. To know the required size for storing either Edge Finder context or calculated edges, call this function (MedgeStream()) first with M_INQUIRE_SIZE_BYTE.

When performing an M_INQUIRE_SIZE_BYTE operation, set this parameter to M_NULL.

SystemId

Specifies the system on which to restore the Edge Finder context. For M_INQUIRE_SIZE_BYTE, M_LOAD, and M_SAVE, SystemId is ignored and should be set to M_NULL.

For an M_RESTORE operation, this parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 Operation

 Specifies the operation to perform.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_INQUIRE_SIZE_BYTE

 Inquires the number of bytes required to save an Edge Finder context or calculated edges to a memory stream. This operation is not supported when the StreamType parameter is set to M_FILE.  Inquires the number of bytes required to save an Edge Finder context or calculated edges to a memory stream ...

  Open   Collapse  M_LOAD

 Loads the content of a specified file or memory stream into a previously allocated Edge Finder context.  Loads the content of a specified file or memory stream into a previously allocated Edge Finder context.

  Open   Collapse  M_RESTORE

 Restores an Edge Finder context from a file or memory stream and assigns it an identifier.  Restores an Edge Finder context from a file or memory stream and assigns it an identifier.

  Open   Collapse  M_SAVE

 Saves an Edge Finder context to a specified file or memory stream, or saves calculated edges from an Edge Finder result buffer to a file or memory stream in the standard CAD DXF format.  Saves an Edge Finder context to a specified file or memory stream, or saves calculated edges from an Edge Finder result buffer to a file or memory stream in the standard CAD DXF format.

 StreamType

 Specifies the type of stream holding the Edge Finder context or calculated edges.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_FILE

 Specifies a file stream.  Specifies a file stream.

  Open   Collapse  M_MEMORY

 Specifies a memory stream. You are responsible for allocating a block of memory for the stream.  Specifies a memory stream ...

 Version

 Specifies the MIL version of the Edge Finder context. For M_LOAD, M_RESTORE, and when saving calculated edges, this parameter is ignored and must be set to M_DEFAULT.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the version to current version of MIL.  Sets the version to current version of MIL.

  Open   Collapse  Value

 Sets the version to a specific version of MIL. This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.  Sets the version to a specific version of MIL ...

 The version specified must never be greater than the current MIL version, but must be greater or equal to 7.5. To know the current MIL version, call MappInquire() with M_VERSION.

 By supplying a specific version, you can control the Edge Finder context's accessibility. For instance, if you allocate an Edge Finder context using MIL 8.0 and set its version to 7.5, this object can be restored on a computer where MIL 7.5 is installed. However, all settings unique to the higher version will be ignored when opened in the lower version. Note that a program using MIL of a higher version can access a Edge Finder context stream created or designated with a lower or equal version. Settings that do not exist in the lower version will be filled with default values when the file or memory stream is restored.

 ControlFlag

 Specifies the function's control flag. For any operation on Edge Finder contexts, this parameter must be set to M_DEFAULT.

 For calculated edges from an Edge Finder result buffer, this parameter stipulates whether to save edge chains and/or edge approximations to the CAD DXF file or memory stream. In this case, this parameter must be set to one or a combination (M_CHAIN + M_CHAIN_APPROXIMATION) of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_CHAIN

 Specifies that edge chains will be saved.  Specifies that edge chains will be saved.

  Open   Collapse  M_CHAIN_APPROXIMATION

 Specifies that edge approximations will be saved.  Specifies that edge approximations will be saved.

 Note that edge chains and edge approximations are saved in the DXF file or memory stream in separate layers.

 ContextOrResultIdPtr

 Specifies the address of the variable in which to write or from which to read the identifier of the Edge Finder context or the Edge Finder result buffer.

 For M_INQUIRE_SIZE_BYTE and M_SAVE operations, ContextOrResultIdPtr specifies the address of the variable from which to read the Edge Finder context identifier or Edge Finder result buffer identifier.

 For an M_LOAD operation, ContextOrResultIdPtr specifies the address of the variable from which to read the identifier of the Edge Finder context where the file or memory stream content will be loaded.

 For an M_RESTORE operation, ContextOrResultIdPtr specifies the address of the variable in which to return the identifier of the restored Edge Finder context. If the operation is not successful, M_NULL is returned.

 SizeByteVarPtr

 Specifies the address of the variable in which to write the size of the Edge Finder context or calculated edges, in bytes.

 If the size is not required, you can set this parameter to M_NULL.

 Note that the size of Edge Finder context will vary depending on the MIL version specified.

INQUIRE SIZE BYTE FILE SAVE MEMORY INQUIRE SIZE BYTE INQUIRE SIZE BYTE INQUIRE SIZE BYTE LOAD SAVE RESTORE FILE LOAD  RESTORE DEFAULT INQUIRE SIZE BYTE SAVE VERSION CHAIN CHAIN APPROXIMATION INQUIRE SIZE BYTE SAVE LOAD RESTORE   DEFAULT HOST   INQUIRE SIZE BYTE LOAD RESTORE SAVE  FILE MEMORY  DEFAULT   CHAIN CHAIN APPROXIMATION


func

Mfunc functions

Example | Availability
There are no examples containing func().
Available in MIL-Lite

Available in MIL
Synopsis
The MIL Function Developer's Toolkit allows programmers to define functions to extend MIL's functionality. Using this toolkit, you can implement functions and integrate them directly into the MIL library, where they behave like standard MIL functions (for example, respecting error handling and tracing).
Functions
  • MfuncAlloc
  • MfuncAllocId
  • MfuncCall
  • MfuncErrorReport
  • MfuncFree
  • MfuncFreeId
  • MfuncInquire
  • MfuncParamCheck
  • MfuncParamDouble
  • MfuncParamId
  • MfuncParamIdPointer
  • MfuncParamLong
  • MfuncParamPointer
  • MfuncParamString
  • MfuncParamValue


MfuncAlloc

See Also | Example | Availability | MfuncAllocId
User Guide:
A user-defined MIL function
Associating a MIL identifier with a user-defined object

Reference:
MfuncFree
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
dtkaddconstantpamaster.c
dtkobjecttracking.c
dtkremap.c
dtksyncasyncfunctionsmaster.c
mfunc.c
mnatfct.c
Available in MIL-Lite

Available in MIL
Synopsis
Allocate a MIL function context for your user-defined function.
Syntax
MIL_ID MfuncAlloc(
MIL_TEXT_PTR FunctionName,
long ParameterNumber,
MFUNCFCTPTR SlaveFunctionPtr,
MIL_TEXT_PTR Reserved1,
MIL_TEXT_PTR Reserved2,
long SlaveFunctionOpcode,
long InitFlag,
MIL_ID *FuncIdPtr
)
Description

This function allows you to allocate a MIL function context for the current user-defined function. Call MfuncAlloc() in the master function of the user-defined function. MfuncAlloc() signals the creation of a user-defined MIL function context, and should be the first MIL function called in the master function. Once the function context is allocated, your function is known as a user-defined MIL function. A user-defined MIL function is considered a standard MIL function, respecting all of MIL environment controls, such as tracing and error handling.

Parameters
FunctionName

Specifies the name of the user-defined function. This is the same as the name of the current master function. This is also the name that you will use to call the user-defined MIL function in your application. The name of the function must be a null-terminated string.

ParameterNumber

Specifies the number of parameters passed to the current user-defined function. Note that the number of parameters should not exceed 16.

SlaveFunctionPtr

Specifies the address of the slave function. Note that you can set this parameter to M_NULL if the slave function will be executed on a system with an on-board processor.

The slave function must be declared as follows:

void MFTYPE SlaveFunction(
MIL_ID FunctionId
)
FunctionId
Specifies the identifier of the user-defined MIL function that references this slave function. This is the identifier returned by the MfuncAlloc() function.
Reserved1

This parameter is reserved for future use. Set this parameter to M_NULL.

Reserved2

This parameter is reserved for future use. Set this parameter to M_NULL.

SlaveFunctionOpcode

Allows you to assign an opcode to the slave function. The opcode will be used to locate the slave function when an application executes the user-defined MIL function. To specify an opcode, you must select a user module (see the table below), and combine it with an offset. For example, M_BAYER_COEFFICIENTS_ID M_USER_MODULE_3 +12.

Open Collapse Value Description
Open Collapse M_USER_MODULE_n

 Specifies the user module. Set n to a value between 1 and 8, inclusive.  Specifies the user module ...

      [Combination constants]

 Add a value from the range specified below to the SlaveFunctionOpcode parameter to specify the offset.

  Open   Collapse  Value
Description

  Open   Collapse  1 to 32

 Specifies the offset of the slave function opcode.  Specifies the offset of the slave function opcode.

 InitFlag

 Allows you to provide more information about the user-defined MIL function.  Any of the values described below can be used individually. If no value is specified, the function is considered to be M_ASYNCHRONOUS_FUNCTION + M_REMOTE.

 The values below allow you to set whether the slave function is executed asynchronously or synchronously.

  Open   Collapse  Value
Description

  Open   Collapse  M_ASYNCHRONOUS_FUNCTION

 Specifies that the user-defined function will not wait for the slave function to finish executing before executing the next function (typically MfuncFree()) in the master function.  Specifies that the user-defined function will not wait for the slave function to finish executing before executing the next function (typically MfuncFree()) in the master function ...

 This is the default value.

  Open   Collapse  M_SYNCHRONOUS_FUNCTION

 Specifies that the user-defined function will wait for the slave function to finish executing before executing the next function in the master function.  Specifies that the user-defined function will wait for the slave function to finish executing before executing the next function in the master function.

      [Combination constants]

 To set whether the slave function can be executed remotely (on a system with an on-board processor), use one of the values below. Both values can also be added to M_SYNCHRONOUS_FUNCTION, and only M_REMOTE can be added to M_ASYNCHRONOUS_FUNCTION (for example, M_ASYNCHRONOUS_FUNCTION + M_REMOTE).

  Open   Collapse  Value
Description

  Open   Collapse  M_LOCAL

 Specifies that the slave function must be executed by the Host processor. Note that MIL functions called from the slave function will still be executed on their target system.  Specifies that the slave function must be executed by the Host processor ...

 This value cannot be added to M_ASYNCHRONOUS_FUNCTION.

  Open   Collapse  M_REMOTE

 Specifies that the slave function will be executed remotely, if possible. If you select M_REMOTE, but do not compile your slave function with a cross-compiler specific to the on-board processor, an error will be generated. For more information, see the A user-defined MIL function section in
          Chapter 25: The MIL Function Developer's Toolkit.  Specifies that the slave function will be executed remotely, if possible ...

 This is the default value.

      [Combination constants]

 To set the type of the user-defined MIL function, use one of the values below. Note that both M_ALLOC and M_FREE imply that the user-defined function is M_SYNCHRONOUS_FUNCTION, and cannot be added to M_ASYNCHRONOUS_FUNCTION.

  Open   Collapse  Value
Description

  Open   Collapse  M_ALLOC

 Specifies that the user-defined function is an allocation function, used to allocate a user-defined MIL object on a required system.  Specifies that the user-defined function is an allocation function, used to allocate a user-defined MIL object on a required system.

  Open   Collapse  M_FREE

 Specifies that the user-defined function frees an object allocated using a user-defined MIL allocation function. Note that when this value is used, the user-defined MIL function must accept the MIL identifier of the object to free as its only parameter.  Specifies that the user-defined function frees an object allocated using a user-defined MIL allocation function ...

 FuncIdPtr

 Specifies the address of the variable in which to store the MIL identifier provided for the user-defined function. Since the MfuncAlloc() function also returns the MIL identifier, you can set this parameter to M_NULL.

Return value

 The returned value is a MIL identifier for the function; M_NULL on error.

BAYER COEFFICIENTS ID ASYNCHRONOUS FUNCTION REMOTE SYNCHRONOUS FUNCTION REMOTE ASYNCHRONOUS FUNCTION ASYNCHRONOUS FUNCTION REMOTE ASYNCHRONOUS FUNCTION REMOTE ALLOC FREE SYNCHRONOUS FUNCTION ASYNCHRONOUS FUNCTION        USER MODULE n   ASYNCHRONOUS FUNCTION SYNCHRONOUS FUNCTION LOCAL REMOTE ALLOC FREE


MfuncAllocId

See Also | Example | Availability | MfuncAlloc | MfuncCall
User Guide:
A user-defined MIL function
Associating a MIL identifier with a user-defined object

Reference:
MfuncInquire
There are no examples containing MfuncAllocId().
Available in MIL-Lite

Available in MIL
Synopsis
Associate a MIL identifier with a user-defined object.
Syntax
MIL_ID MfuncAllocId(
MIL_ID FunctionId,
long ObjectType,
void *ObjectPtr
)
Description

This function allows you to associate a MIL identifier with a user-defined object (such as, a structure or an array). You can associate a MIL identifier with a user object so that it is recognized by MIL and treated as a standard MIL object during tracing or error handling. Once the object is associated with an identifier, the object is known as a user-defined MIL object.

The parameters passed to MfuncAllocId() do not allow you to specify whether the user-defined object is allocated on the Host or on a system with an on-board processor. For information on creating user-defined objects on systems with on-board processors and associating these object with MIL identifiers, see the Associating a MIL identifier with a user-defined object section in Chapter 25: The MIL Function Developer's Toolkit.

You must also specify a MIL type for your object (ObjectType parameter). MIL allows up to 32 different user-defined MIL object types.

Use the MIL identifier to refer to the user-defined MIL object. To refer to the actual data grouped into this user-defined object, use the pointer to the object (ObjectPtr parameter).

To inquire about the type of this object, or the pointer to it, use the MfuncInquire() function.

Parameters
FunctionId

Specifies a MIL function identifier. This parameter can be set to the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default MIL function identifier. Use this value to create user-defined MIL objects outside of a user-defined MIL function.  Specifies the default MIL function identifier ...

  Open   Collapse  MIL function identifier

 Specifies the identifier of a user-defined MIL function.  Specifies the identifier of a user-defined MIL function.

 ObjectType

 Specifies the MIL type of the user-defined object to be associated with a MIL identifier.  To specify the type, you must specify one of the groups listed in the table below and combine it with an offset. The two object groups allow you to distinguish between custom created objects, especially when the created objects are to be used in different MIL modules.

  Open   Collapse  Value
Description

  Open   Collapse  M_USER_OBJECT_1

 Specifies that the user object falls under the first group of user object types.  Specifies that the user object falls under the first group of user object types.

  Open   Collapse  M_USER_OBJECT_2

 Specifies that the user object falls under the second group of user object types.  Specifies that the user object falls under the second group of user object types.

      [Combination constants]

 The following must be added to the ObjectType parameter to specify the offset. The offset allows you to distinguish between the different object types of the same group (for example, M_USER_OBJECT_1 + 0x0001).

  Open   Collapse  Value
Description

  Open   Collapse  Value

 Specifies the offset within the selected object type group. The value must have only one of its 16 least significant bits set.  Specifies the offset within the selected object type group ...

 ObjectPtr

 Specifies the address of the user-defined object that is to be associated with a MIL identifier.  Note that user-defined objects stored in the memory of an on-board processor are not accessible from Host, and vice versa.

 This object can be a structure, an array, or any other data type.

Return value

 The returned value is the MIL identifier associated with the user-defined object; M_NULL on error.

USER OBJECT 1  DEFAULT   USER OBJECT 1 USER OBJECT 2


MfuncCall

See Also | Example | Availability | MfuncAllocId | MfuncErrorReport
User Guide:
A user-defined MIL function

Reference:
MappControl
MfuncAlloc
MfuncParamId
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
dtkaddconstantpamaster.c
dtkaddconstantpaslave.c
dtkobjecttracking.c
dtkremap.c
dtksyncasyncfunctionsmaster.c
mfunc.c
Available in MIL-Lite

Available in MIL
Synopsis
Execute the slave function.
Syntax
long MfuncCall(
MIL_ID FunctionId
)
Description

This function executes the slave function of the user-defined MIL function on the target system. The target system is determined by the values of the user-defined MIL function parameters, registered in the master function. (For more information, see the Executing the slave function on a system with an on-board processor section in Chapter 25: The MIL Function Developer's Toolkit.) Call MfuncCall() from the master function of the user-defined MIL function. If tracing and error reporting are enabled, the tracing and error messages will be reported to screen. You can control the error handling and tracing behavior as you would with other MIL functions, using MappControl().

Note that if a MIL_ID parameter was registered in the master function with MfuncParamId(), the validity of that identifier will be checked during the execution of MfuncCall(). If the identifier is not valid, the slave function is not executed.

Parameter
FunctionId

Specifies the identifier of the user-defined MIL function.

The slave function executed using MfuncCall() must be declared as follows:

void MFTYPE SlaveFunction(
MIL_ID FunctionId
)
FunctionId
Specifies the identifier of the user-defined MIL function that references this slave function. This is the identifier returned by the MfuncAlloc() function.
Return value
The returned value is M_NULL if an error occurred; otherwise, not null.


MfuncErrorReport

See Also | Example | Availability | MfuncCall | MfuncFree
Reference:
MappControl
MappGetError
MfuncAlloc
MfuncFree
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
dtkaddconstantpamaster.c
dtkaddconstantpaslave.c
dtkobjecttracking.c
mfunc.c
mnatfct.c
Available in MIL-Lite

Available in MIL
Synopsis
Report an error message.
Syntax
long MfuncErrorReport(
MIL_ID FunctionId,
long ErrorCode,
MIL_TEXT_PTR ErrorMessage,
MIL_TEXT_PTR ErrorSubMessage1,
MIL_TEXT_PTR ErrorSubMessage2,
MIL_TEXT_PTR ErrorSubMessage3
)
Description

This function allows you to log an error message in a user-defined MIL function using the MIL error handling mechanism. You can call the MfuncErrorReport() function from both the slave and the master functions of your user-defined MIL function, but only after a call to MfuncAlloc() and before a call to MfuncFree(). When MfuncErrorReport() is called, MIL will treat your error as a normal MIL error. To report the logged messages to screen, you must enable error reporting using the MappControl() function. These errors can also be read using the standard MIL error functions (MappGetError()), which is especially useful when you want to keep error reporting disabled.

If you report an error with an error code set to M_NULL, you will reset any pending internal error that a MIL function call might have generated inside the user-defined MIL function. You must reset the pending error if you don't want the MIL error message to be reported. If you don't reset the pending error at the end of the slave function, and you don't report your own error, MIL will detect any pending error and report the error message, prefixed with the name of the user-defined MIL function.

Parameters
FunctionId

Specifies the MIL function identifier. This parameter can be set to the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default MIL function identifier. Use this value when MfuncErrorReport() is called from within a slave function.  Specifies the default MIL function identifier ...

  Open   Collapse  MIL function identifier

 Specifies the identifier of a user-defined function.  Specifies the identifier of a user-defined function.

 ErrorCode

 Assigns a numeric code to the user-defined MIL function's group of error messages.  To specify the error code, combine the value in the table below with an offset. For example, M_FUNC_ERROR + 65.

  Open   Collapse  Value
Description

  Open   Collapse  M_FUNC_ERROR

 Specifies a numeric code to a group of error messages. By specifying this value, you ensure that the error messages of the user-defined MIL function do not conflict with MIL specific errors.  Specifies a numeric code to a group of error messages ...

  Open   Collapse  M_NULL

 Specifies that no error message will be returned. Any pending internal error generated by a MIL function call inside the user-defined MIL function will be reset.  Specifies that no error message will be returned ...

      [Combination constants]

 Add a value from the range specified below to the ErrorCode parameter to specify the offset.

  Open   Collapse  Value
Description

  Open   Collapse  0 to 99

 Specifies the value of the offset.  Specifies the value of the offset.

 ErrorMessage

 Specifies the text of your error message; this is a null terminated string.  The error message, including the terminating null character, must not be longer than M_ERROR_MESSAGE_SIZE (128) characters.

 ErrorSubMessage1

 Specifies the text of your first error sub-message.  The error sub-message must be a null terminated string. The error message, including the terminating null character, must not be longer than M_ERROR_MESSAGE_SIZE (128) characters. If you do not want to use this error sub-message, pass M_NULL.

 ErrorSubMessage2

 Specifies the text of your second error sub-message.  For details on creating appropriate error sub-messages, see the description of the ErrorSubMessage1 parameter.

 ErrorSubMessage3

 Specifies the text of your third error sub-message.  For details on creating appropriate error sub-messages, see the description of the ErrorSubMessage1 parameter.

Return value

 The returned value is M_NULL if an error occurred during the error log operation; otherwise, not null.

 DEFAULT   FUNC ERROR NULL


MfuncFree

See Also | Example | Availability | MfuncErrorReport | MfuncFreeId
User Guide:
A user-defined MIL function

Reference:
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
dtkaddconstantpamaster.c
dtkobjecttracking.c
dtkremap.c
dtksyncasyncfunctionsmaster.c
mfunc.c
Available in MIL-Lite

Available in MIL
Synopsis
Free a MIL function context.
Syntax
void MfuncFree(
MIL_ID FunctionId
)
Description

This function frees the function context allocated for a user-defined MIL function. MfuncFree() must be the last MIL function called in the master function.

Parameter
FunctionId

Specifies the identifier of the user-defined MIL function whose function context you want to free.


MfuncFreeId

See Also | Example | Availability | MfuncFree | MfuncInquire
User Guide:
Associating a MIL identifier with a user-defined object

Reference:
MfuncAllocId
There are no examples containing MfuncFreeId().
Available in MIL-Lite

Available in MIL
Synopsis
Free the MIL identifier associated with a user-defined MIL object.
Syntax
void MfuncFreeId(
MIL_ID FunctionId,
MIL_ID ObjectId
)
Description

This function frees a MIL identifier associated with a user-defined object using the MfuncAllocId() function.

Parameters
FunctionId

Specifies a MIL function identifier. This parameter can be set to the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default MIL function identifier. Use M_DEFAULT to free user-defined MIL objects created outside of any particular user-defined MIL function.  Specifies the default MIL function identifier ...

  Open   Collapse  MIL function identifier

 Specifies the identifier of a user-defined MIL function.  Specifies the identifier of a user-defined MIL function.

 ObjectId

 Specifies the MIL identifier of the user-defined MIL object to free.

DEFAULT  DEFAULT


MfuncInquire

See Also | Example | Availability | MfuncFreeId | MfuncParamCheck
User Guide:
Associating a MIL identifier with a user-defined object

Reference:
MfuncAllocId
There are no examples containing MfuncInquire().
Available in MIL-Lite

Available in MIL
Synopsis
Retrieve information on a user-defined MIL object.
Syntax
long MfuncInquire(
MIL_ID ObjectId,
long InquireType,
void *UserVarPtr
)
Description

This function retrieves information on the specified user-defined MIL object. This object must have been associated with a MIL identifier using the MfuncAllocId() function.

Parameters
ObjectId

Specifies the identifier of the user-defined MIL object.

InquireType

Specifies the user-defined MIL object feature about which to inquire.

This parameter can be set to one of the following:

The following values require that you pass the value listed in the data-type area to the UserVarPtr parameter.

Open Collapse Value Description
Open Collapse M_OBJECT_PTR

Returns the pointer to the user-defined MIL object. Returns the pointer to the user-defined MIL object ...

UserVarPtr info

Data type: long
Open Collapse M_OBJECT_TYPE

Returns the type of the specified MIL object. Returns the type of the specified MIL object ...

UserVarPtr info

Data type: long

Return values:
M_APPLICATION | MIL application.
M_ARRAY | MIL array.
M_BLOB_FEATURE_LIST | MIL blob feature list.
M_BLOB_RESULT | MIL blob result.
M_CAL_PARENT | MIL calibration.
M_CODE_OBJECT | MIL code read.
M_COUNT_LIST | MIL count list.
M_DIGITIZER | MIL digitizer.
M_DISPLAY | MIL display.
M_EDGE_CONTOUR | MIL edge contour.
M_EDGE_CREST | MIL edge crest.
M_EDGE_RESULT | MIL edge result.
M_EVENT_LIST | MIL event list.
M_EXTREME_LIST | MIL extreme list.
M_GRAPHIC_CONTEXT | MIL graphics context.
M_HIST_LIST | MIL history list.
M_IMAGE | MIL image.
M_KERNEL | MIL kernel.
M_LUT | MIL LUT.
M_MEAS_CONTEXT | MIL measurement context.
M_MEAS_MARKER | MIL measurement marker.
M_MEAS_RESULT | MIL measurement result.
M_MOD_GEOMETRIC | MIL Model Finder context.
M_MOD_RESULT | MIL Model Finder result.
M_OCR_FONT | MIL OCR font.
M_OCR_RESULT | MIL OCR result.
M_PAT_MODEL | MIL pattern matching model.
M_PAT_RESULT | MIL pattern matching result.
M_PROJ_LIST | MIL project list.
M_STRUCT_ELEMENT | MIL structural element.
M_SYSTEM | MIL system object.
M_USER_OBJECT_1 | First user-defined object.
M_USER_OBJECT_2 | Second user-defined object.
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • long

Specifies the address in which to write the requested information.

Return value
Returns the setting of the object about which the inquiry was made.
OBJECT PTR OBJECT TYPE


MfuncParamCheck

See Also | Example | Availability | MfuncInquire | MfuncParamDouble
Reference:
MappControl
mnatfct.c
Available in MIL-Lite

Available in MIL
Synopsis
Verify whether parameter checking is required.
Syntax
long MfuncParamCheck(
MIL_ID FunctionId
)
Description

This function allows you to verify, from within your user-defined MIL function, whether parameter checking is enabled or disabled. To enable or disable the checking of parameters, use the MappControl() M_PARAMETER control type.

Call the MfuncParamCheck() function prior to checking the parameters of the specified user-defined MIL function. The return value of the MfuncParamCheck() function should dictate whether to execute the functions that perform the parameter checking, or not. Then, to save the parameter checking time for a time-critical user-defined MIL function, it is sufficient to disable parameter checking using MappControl() with M_CHECK_DISABLE.

Parameter
FunctionId

Specifies the identifier of the user-defined MIL function.

Return value
The returned value is M_NULL if no parameter checking is required; otherwise, checking is required.
PARAMETER CHECK DISABLE


MfuncParamDouble

See Also | Example | Availability | MfuncParamCheck | MfuncParamId
Reference:
MfuncAlloc
MfuncCall
There are no examples containing MfuncParamDouble().
Available in MIL-Lite

Available in MIL
Synopsis
Register a parameter of type double.
Syntax
void MfuncParamDouble(
MIL_ID FunctionId,
long ParamIndex,
double ParamValue
)
Description

This function allows you to register a type double parameter of the current user-defined MIL function. The MfuncParamDouble() function should be called in the master function after a call to MfuncAlloc() and before a call to MfuncCall().

Parameters
FunctionId

Specifies the identifier of the user-defined MIL function.

ParamIndex

Specifies the index of the parameter within the user-defined MIL function's parameter list. The index of the first parameter is considered to be one.

ParamValue

Specifies the value of the type double parameter.


MfuncParamId

See Also | Example | Availability | MfuncParamDouble | MfuncParamIdPointer
Reference:
MfuncAlloc
MfuncAllocId
MfuncCall
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
dtkaddconstantpamaster.c
dtkobjecttracking.c
dtkremap.c
dtksyncasyncfunctionsmaster.c
mfunc.c
mnatfct.c
Available in MIL-Lite

Available in MIL
Synopsis
Register a MIL_ID parameter.
Syntax
void MfuncParamId(
MIL_ID FunctionId,
long ParamIndex,
MIL_ID ParamValue,
long ParamIs,
long RequiredAttribute
)
Description

This function allows you to register a MIL_ID parameter of the specified user-defined MIL function. The MfuncParamId() function should be called in the master function after a call to MfuncAlloc() and before a call to MfuncCall().

Parameters
FunctionId

Specifies the identifier of the user-defined MIL function.

ParamIndex

Specifies the index of the parameter within the user-defined MIL function's parameter list. The index of the first parameter is considered to be one.

ParamValue

Specifies the MIL_ID of the MIL object passed to the MIL_ID parameter.

ParamIs

Specifies the type of the MIL object. The available object types are divided into two groups. When the specified object is of a type listed in the first group, you can specify a single or multiple object type(s) from this group. For example, if the object is expected to be of type M_ARRAY or M_COUNT_LIST, set the ParamIs parameter to M_ARRAY + M_COUNT_LIST. The object types of the second group cannot be used in combination with each other.

The first group of object types includes the following:

Open Collapse Value Description
Open Collapse M_APPLICATION

 Specifies an application object.  Specifies an application object.

  Open   Collapse  M_ARRAY

 Specifies an array object.  Specifies an array object.

  Open   Collapse  M_COUNT_LIST

 Specifies a count list object.  Specifies a count list object.

  Open   Collapse  M_DIGITIZER

 Specifies a digitizer object.  Specifies a digitizer object.

  Open   Collapse  M_DISPLAY

 Specifies a display object.  Specifies a display object.

  Open   Collapse  M_EVENT_LIST

 Specifies an event list object.  Specifies an event list object.

  Open   Collapse  M_EXTREME_LIST

 Specifies an extreme list object.  Specifies an extreme list object.

  Open   Collapse  M_GRAPHIC_CONTEXT

 Specifies a graphics context object.  Specifies a graphics context object.

  Open   Collapse  M_HIST_LIST

 Specifies a histogram list object.  Specifies a histogram list object.

  Open   Collapse  M_IMAGE

 Specifies an image object.  Specifies an image object.

  Open   Collapse  M_KERNEL

 Specifies a kernel object.  Specifies a kernel object.

  Open   Collapse  M_LUT

 Specifies a LUT object.  Specifies a LUT object.

  Open   Collapse  M_PROJ_LIST

 Specifies a project list object.  Specifies a project list object.

  Open   Collapse  M_STRUCT_ELEMENT

 Specifies a structuring element object.  Specifies a structuring element object.

  Open   Collapse  M_SYSTEM

 Specifies a system object.  Specifies a system object.

      [Combination constants]

 The second group of object types includes the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_BLOB_FEATURE_LIST

 Specifies a blob feature list object.  Specifies a blob feature list object.

  Open   Collapse  M_BLOB_RESULT

 Specifies a blob result object.  Specifies a blob result object.

  Open   Collapse  M_CAL_PARENT

 Specifies a calibration object.  Specifies a calibration object.

  Open   Collapse  M_CODE_OBJECT

 Specifies a code object.  Specifies a code object.

  Open   Collapse  M_EDGE_CONTOUR

 Specifies an edge contour object.  Specifies an edge contour object.

  Open   Collapse  M_EDGE_CREST

 Specifies an edge crest object.  Specifies an edge crest object.

  Open   Collapse  M_EDGE_RESULT

 Specifies an edge result object.  Specifies an edge result object.

  Open   Collapse  M_MEAS_CONTEXT

 Specifies a measurement context object.  Specifies a measurement context object.

  Open   Collapse  M_MEAS_MARKER

 Specifies a measurement marker object.  Specifies a measurement marker object.

  Open   Collapse  M_MEAS_RESULT

 Specifies a measurement result object.  Specifies a measurement result object.

  Open   Collapse  M_MOD_GEOMETRIC

 Specifies a Model Finder context object.  Specifies a Model Finder context object.

  Open   Collapse  M_MOD_RESULT

 Specifies a Model Finder result object.  Specifies a Model Finder result object.

  Open   Collapse  M_OCR_FONT

 Specifies a character recognition font object.  Specifies a character recognition font object.

  Open   Collapse  M_OCR_RESULT

 Specifies a character recognition result object.  Specifies a character recognition result object.

  Open   Collapse  M_PAT_MODEL

 Specifies a pattern matching model object.  Specifies a pattern matching model object.

  Open   Collapse  M_PAT_RESULT

 Specifies a pattern matching result object.  Specifies a pattern matching result object.

  Open   Collapse  M_USER_OBJECT_1

 Specifies an object from group one of the user-defined object types (MfuncAllocId()).  Specifies an object from group one of the user-defined object types (MfuncAllocId()).

  Open   Collapse  M_USER_OBJECT_2

 Specifies an object from group two of the user-defined object types (MfuncAllocId()).  Specifies an object from group two of the user-defined object types (MfuncAllocId()).

 RequiredAttribute

 Specifies the type of attributes that the MIL object must have, in order to be considered a valid MIL_ID for the specified function parameter.

 This parameter should be set to one or both (M_IN + M_OUT) of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_IN

 Specifies that the MIL_ID passed to ParamValue must be that of an input object.  Specifies that the MIL_ID passed to ParamValue must be that of an input object.

  Open   Collapse  M_OUT

 Specifies that the MIL_ID passed to ParamValue must be that of an output object.  Specifies that the MIL_ID passed to ParamValue must be that of an output object.

      [Combination constants]

 One or more of the values below can be added to the RequiredAttribute parameter if ParamIs is set to M_IMAGE. If you specify an M_IMAGE object (ParamValue) that does not correspond to any of the type(s) selected from the values listed below, an error is returned. If none of the values specified below are added, any M_IMAGE object will be accepted. Note that you cannot specify any of the following if the ParamIs parameter is set to a combination of values.

  Open   Collapse  Value
Description

  Open   Collapse  M_DISP

 Specifies that the buffer can be displayed.  Specifies that the buffer can be displayed.

  Open   Collapse  M_GRAB

 Specifies that the buffer can have data grabbed into it.  Specifies that the buffer can have data grabbed into it.

  Open   Collapse  M_PROC

MIL-lite with restriction (see remarks).

 Specifies that the buffer can be processed.  Specifies that the buffer can be processed.

ARRAY COUNT LIST ARRAY COUNT LIST IN OUT IMAGE IMAGE IMAGE     APPLICATION  ARRAY  COUNT LIST  DIGITIZER  DISPLAY  EVENT LIST  EXTREME LIST  GRAPHIC CONTEXT
                 HIST LIST  IMAGE  KERNEL  LUT  PROJ LIST  STRUCT ELEMENT  SYSTEM  BLOB FEATURE LIST
                   BLOB RESULT  CAL PARENT CODE OBJECT EDGE CONTOUR EDGE CREST EDGE RESULT MEAS CONTEXT  MEAS MARKER  MEAS RESULT  MOD GEOMETRIC MOD RESULT OCR FONT  OCR RESULT  PAT MODEL  PAT RESULT  USER OBJECT 1
                   USER OBJECT 2
                    IN OUT DISP GRAB PROC


MfuncParamIdPointer

See Also | Example | Availability | MfuncParamId | MfuncParamLong
Reference:
MfuncAlloc
MfuncAllocId
MfuncCall
There are no examples containing MfuncParamIdPointer().
Available in MIL-Lite

Available in MIL
Synopsis
Register a MIL_ID pointer parameter.
Syntax
void MfuncParamIdPointer(
MIL_ID FunctionId,
long ParamIndex,
MIL_ID *ParamValue,
long ParamIs,
long ParamAttribute
)
Description

This function allows you to register a parameter that accepts a pointer to a MIL_ID object, as a parameter of the specified user-defined MIL function. The MfuncParamIdPointer() function should be called in the master function after a call to MfuncAlloc() and before a call to MfuncCall().

Parameters
FunctionId

Specifies the identifier of the user-defined MIL function.

ParamIndex

Specifies the index of the parameter within the user-defined MIL function's parameter list. The index of the first parameter is considered to be one.

ParamValue

Specifies the address of the MIL_ID object passed to the MIL_ID pointer parameter.

ParamIs

Specifies the type of the MIL_ID object passed to the MIL_ID pointer parameter. The available object types are divided into two groups. When the specified object is of a type listed in the first group, you can specify a single or multiple object type(s) from this group. For example, if the object is expected to be of type M_ARRAY or M_COUNT_LIST, set the ParamIs parameter to M_ARRAY + M_COUNT_LIST. The object types of the second group cannot be used in combination with each other.

The first group of object types includes the following:

Open Collapse Value Description
Open Collapse M_APPLICATION

 Specifies an application object.  Specifies an application object.

  Open   Collapse  M_ARRAY

 Specifies an array object.  Specifies an array object.

  Open   Collapse  M_COUNT_LIST

 Specifies a count list object.  Specifies a count list object.

  Open   Collapse  M_DIGITIZER

 Specifies a digitizer object.  Specifies a digitizer object.

  Open   Collapse  M_DISPLAY

 Specifies a display object.  Specifies a display object.

  Open   Collapse  M_EVENT_LIST

 Specifies an event list object.  Specifies an event list object.

  Open   Collapse  M_EXTREME_LIST

 Specifies an extreme list object.  Specifies an extreme list object.

  Open   Collapse  M_GRAPHIC_CONTEXT

 Specifies a graphics context object.  Specifies a graphics context object.

  Open   Collapse  M_HIST_LIST

 Specifies a histogram list object.  Specifies a histogram list object.

  Open   Collapse  M_IMAGE

 Specifies an image object.  Specifies an image object.

  Open   Collapse  M_KERNEL

 Specifies a kernel object.  Specifies a kernel object.

  Open   Collapse  M_LUT

 Specifies a LUT object.  Specifies a LUT object.

  Open   Collapse  M_PROJ_LIST

 Specifies a project list object.  Specifies a project list object.

  Open   Collapse  M_STRUCT_ELEMENT

 Specifies a structuring element object.  Specifies a structuring element object.

  Open   Collapse  M_SYSTEM

 Specifies a system object.  Specifies a system object.

      [Combination constants]

 The second group of object types includes the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_BLOB_FEATURE_LIST

 Specifies a blob feature list object.  Specifies a blob feature list object.

  Open   Collapse  M_BLOB_RESULT

 Specifies a blob result object.  Specifies a blob result object.

  Open   Collapse  M_CAL_PARENT

 Specifies a calibration object.  Specifies a calibration object.

  Open   Collapse  M_CODE_OBJECT

 Specifies a code object.  Specifies a code object.

  Open   Collapse  M_EDGE_CONTOUR

 Specifies an edge contour object.  Specifies an edge contour object.

  Open   Collapse  M_EDGE_CREST

 Specifies an edge crest object.  Specifies an edge crest object.

  Open   Collapse  M_EDGE_RESULT

 Specifies an edge result object.  Specifies an edge result object.

  Open   Collapse  M_MEAS_CONTEXT

 Specifies a measurement context object.  Specifies a measurement context object.

  Open   Collapse  M_MEAS_MARKER

 Specifies a measurement marker object.  Specifies a measurement marker object.

  Open   Collapse  M_MEAS_RESULT

 Specifies a measurement result object.  Specifies a measurement result object.

  Open   Collapse  M_MOD_GEOMETRIC

 Specifies a Model Finder context object.  Specifies a Model Finder context object.

  Open   Collapse  M_MOD_RESULT

 Specifies a Model Finder result object.  Specifies a Model Finder result object.

  Open   Collapse  M_OCR_FONT

 Specifies a character recognition font object.  Specifies a character recognition font object.

  Open   Collapse  M_OCR_RESULT

 Specifies a character recognition result object.  Specifies a character recognition result object.

  Open   Collapse  M_PAT_MODEL

 Specifies a pattern matching model object.  Specifies a pattern matching model object.

  Open   Collapse  M_PAT_RESULT

 Specifies a pattern matching result object.  Specifies a pattern matching result object.

  Open   Collapse  M_USER_OBJECT_1

 Specifies an object from group one of the user-defined object types (MfuncAllocId()).  Specifies an object from group one of the user-defined object types (MfuncAllocId()).

  Open   Collapse  M_USER_OBJECT_2

 Specifies an object from group two of the user-defined object types (MfuncAllocId()).  Specifies an object from group two of the user-defined object types (MfuncAllocId()).

 ParamAttribute

 Specifies the attribute of the pointer parameter.  This parameter should be set to one or both (M_IN + M_OUT) of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_IN

 Specifies that the pointer parameter is pointing to a MIL_ID object that can be used for input.  Specifies that the pointer parameter is pointing to a MIL_ID object that can be used for input.

  Open   Collapse  M_OUT

 Specifies that the pointer parameter is pointing to a MIL_ID object that can be used for output.  Specifies that the pointer parameter is pointing to a MIL_ID object that can be used for output.

ARRAY COUNT LIST ARRAY COUNT LIST IN OUT     APPLICATION  ARRAY  COUNT LIST  DIGITIZER  DISPLAY  EVENT LIST  EXTREME LIST  GRAPHIC CONTEXT
                 HIST LIST  IMAGE  KERNEL  LUT  PROJ LIST  STRUCT ELEMENT  SYSTEM  BLOB FEATURE LIST
                   BLOB RESULT  CAL PARENT CODE OBJECT EDGE CONTOUR EDGE CREST EDGE RESULT MEAS CONTEXT  MEAS MARKER  MEAS RESULT  MOD GEOMETRIC MOD RESULT OCR FONT  OCR RESULT  PAT MODEL  PAT RESULT  USER OBJECT 1
                   USER OBJECT 2
                    IN  OUT


MfuncParamLong

See Also | Example | Availability | MfuncParamIdPointer | MfuncParamPointer
Reference:
MfuncAlloc
MfuncCall
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
dtkaddconstantpamaster.c
dtkremap.c
dtksyncasyncfunctionsmaster.c
mfunc.c
mnatfct.c
Available in MIL-Lite

Available in MIL
Synopsis
Register a parameter of type long.
Syntax
void MfuncParamLong(
MIL_ID FunctionId,
long ParamIndex,
long ParamValue
)
Description

This function allows you to register a type long parameter of the current user-defined MIL function. The MfuncParamLong() function should be called in the master function after a call to MfuncAlloc() and before a call to MfuncCall().

Parameters
FunctionId

Specifies the identifier of the user-defined MIL function.

ParamIndex

Specifies the index of the parameter within the user-defined MIL function's parameter list. The index of the first parameter is considered to be one.

ParamValue

Specifies the value of the type long parameter.


MfuncParamPointer

See Also | Example | Availability | MfuncParamLong | MfuncParamString
Reference:
MfuncAlloc
MfuncCall
MfuncParamIdPointer
dtksyncasyncfunctionsmaster.c
Available in MIL-Lite

Available in MIL
Synopsis
Register a pointer parameter.
Syntax
void MfuncParamPointer(
MIL_ID FunctionId,
long ParamIndex,
void *ParamValue,
long Size,
long Attribute
)
Description

This function allows you to register a pointer parameter of the current user-defined MIL function. The MfuncParamPointer() function should be called in the master function after a call to MfuncAlloc() and before a call to MfuncCall().

Note that to register a pointer parameter that specifies the address of a MIL_ID object, you must use the MfuncParamIdPointer() function.

Parameters
FunctionId

Specifies the identifier of the user-defined MIL function.

ParamIndex

Specifies the index of the parameter within the user-defined MIL function's parameter list. The index of the first parameter is considered to be one.

ParamValue

Specifies the address passed to the pointer parameter. Note that you should not use this parameter to point to data types that can be handled using the other provided MfuncParam...() functions.

Size

Specifies the size of the data, in bytes, pointed to by the ParamValue parameter.

Attribute

Specifies the attribute of the pointer parameter. This parameter should be set to one or both (M_IN + M_OUT) of the following values:

Open Collapse Value Description
Open Collapse M_IN

 Specifies that the parameter is pointing to a variable or a data structure that will be used for input.  Specifies that the parameter is pointing to a variable or a data structure that will be used for input.

  Open   Collapse  M_OUT

 Specifies that the parameter is pointing to a variable or a data structure that will be used for output.  Specifies that the parameter is pointing to a variable or a data structure that will be used for output.

IN OUT      IN OUT


MfuncParamString

See Also | Example | Availability | MfuncParamPointer | MfuncParamValue
Reference:
MfuncAlloc
MfuncCall
There are no examples containing MfuncParamString().
Available in MIL-Lite

Available in MIL
Synopsis
Register a null-terminated string parameter.
Syntax
void MfuncParamString(
MIL_ID FunctionId,
long ParamIndex,
MIL_TEXT_PTR ParamValue,
long Size,
long Attribute
)
Description

This function allows you to register a null-terminated string parameter of the current user-defined MIL function. The MfuncParamString() function should be called in the master function after a call to MfuncAlloc() and before a call to MfuncCall().

Parameters
FunctionId

Specifies the identifier of the user-defined MIL function.

ParamIndex

Specifies the index of the parameter within the user-defined MIL function's parameter list. The index of the first parameter is considered to be one.

ParamValue

Specifies the address passed to the string parameter.

Size

Specifies the size of the data pointed to by the ParamValue parameter. When the string parameter of the user-defined function is used for output (M_OUT), you must first inquire about the maximum size of the string that can be stored at the specified memory location, and then set the Size parameter to this value.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Calculates the size automatically. You can use M_DEFAULT only when the Attribute parameter is set to M_IN.  Calculates the size automatically ...

  Open   Collapse  Value

 Specifies the size of the data, in bytes.  Specifies the size of the data, in bytes.

 Attribute

 Specifies the attribute of the string parameter.  This parameter should be set to one or both (M_IN + M_OUT) of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_IN

 Specifies that the string parameter will be used for input.  Specifies that the string parameter will be used for input.

  Open   Collapse  M_OUT

 Specifies that the string parameter will be used for output.  Specifies that the string parameter will be used for output.

OUT DEFAULT IN IN OUT     DEFAULT   IN OUT


MfuncParamValue

Example | Availability | MfuncParamString
dtkaddconstantaltivec.c
dtkaddconstantc.c
dtkaddconstantonlaltivec.c
dtkaddconstantpaslave.c
dtkobjecttracking.c
dtkremap.c
dtksyncasyncfunctionsslave.c
mfunc.c
Available in MIL-Lite

Available in MIL
Synopsis
Read the value of the specified MIL function parameter.
Syntax
void MFTYPE MfuncParamValue(
MIL_ID FunctionId,
long ParamIndex,
void *ParamValuePtr
)
Description

This function allows you to read the value of a parameter registered in the master function of your user-defined MIL function, from the slave function. The requested value is written to the address specified by the ParamValuePtr parameter.

Parameters
FunctionId

Specifies the identifier of the user-defined MIL function.

ParamIndex

Specifies the index of the parameter within the user-defined MIL function's parameter list. The index of the first parameter is considered to be one.

ParamValuePtr

Specifies the address of the variable in which to write the value of the specified parameter. The type of the variable depends on the type of the parameter registered in the master function.

Return value
Returns the value of the specified parameter.


gen

Mgen functions

Example | Availability
There are no examples containing gen().
Available in MIL-Lite

Available in MIL
Synopsis
The basic data generation module provides a limited set of data generation tools that can be used to automatically generate predefined data in a data buffer (for example, generating ramp in a LUT buffer).
Functions
  • MgenLutFunction
  • MgenLutRamp
  • MgenWarpParameter


MgenLutFunction

See Also | Example | Availability | MgenLutRamp
User Guide:
Arithmetic with images
Loading and generating data into LUTs

Reference:
MbufAlloc1d
MbufAllocColor
There are no examples containing MgenLutFunction().
Available in MIL-Lite

Available in MIL
Synopsis
Generate data into a LUT buffer using a specified standard mathematical function.
Syntax
void MgenLutFunction(
MIL_ID LutBufId,
long Func,
double a,
double b,
double c,
long StartIndex,
double StartXValue,
long EndIndex
)
Description

This function generates a value for each LUT index within the specified index range (StartIndex to EndIndex inclusive), according to the specified mathematical function. Each function takes a value X. The StartXValue parameter specifies the initial X value. The remaining entries of the index range are generated by incrementing the value of X by 1 for each index.

Parameters
LutBufId

Specifies the identifier of the LUT in which to generate values. This parameter must be given a valid LUT buffer identifier. Allocate a LUT buffer, using MbufAlloc1d() or MbufAllocColor(). If the LUT is a multi-band LUT (allocated with MbufAllocColor()), the same data is written to all bands.

Func

Specifies the mathematical function to use for calculations. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_COS

 Uses the following formula for calculation: a cos
                     (bx) +
                     c.  Uses the following formula for calculation: a cos
                     (bx) +
                     c.

  Open   Collapse  M_EXP

 Uses the following formula for calculation: abx +
                     c.  Uses the following formula for calculation: abx +
                     c.

  Open   Collapse  M_LOG

 Uses the following formula for calculation: a log
                     b (x) +
                     c.  Uses the following formula for calculation: a log
                     b (x) +
                     c.

  Open   Collapse  M_QUAD

 Uses the following formula for calculation: ax2
                     + bx +
                     c.  Uses the following formula for calculation: ax2
                     + bx +
                     c.

  Open   Collapse  M_SIN

 Uses the following formula for calculation: a sin
                     (bx) +
                     c.  Uses the following formula for calculation: a sin
                     (bx) +
                     c.

  Open   Collapse  M_TAN

 Uses the following formula for calculation: a tan
                     (bx) +
                     c.  Uses the following formula for calculation: a tan
                     (bx) +
                     c.

 For M_SIN, M_COS, and M_TAN, X is considered to be in degrees. All results are converted to integer by truncation, except when using a floating-point LUT buffer. Note, if the given parameters cause an overflow or underflow, indeterminate results will be written in the destination LUT.

 a

 Specifies a function constant for the Func parameter.

 b

 Specifies a function constant for the Func parameter.

 c

 Specifies a function constant for the Func parameter.

 StartIndex

 Specifies the first LUT index entry for which to generate values.

 StartXValue

 Specifies the initial value of X in the function.

 EndIndex

 Specifies the last LUT index entry for which to generate values.  This index entry must be greater than or equal to the StartIndex value.

SIN COS TAN   COS  EXP  LOG QUAD SIN  TAN


MgenLutRamp

See Also | Example | Availability | MgenLutFunction | MgenWarpParameter
User Guide:
Arithmetic with images
Loading and generating data into LUTs
Palettes and output LUTs for windowed display (256-color)

Reference:
MbufAlloc1d
MbufAllocColor
MbufPut1d
MbufPutColor
MgenLutFunction
dtkremap.c
mdispwindowleveling.c
Available in MIL-Lite

Available in MIL
Synopsis
Generate ramp data into a LUT buffer.
Syntax
void MgenLutRamp(
MIL_ID LutId,
long StartIndex,
double StartValue,
long EndIndex,
double EndValue
)
Description

This function generates a ramp, inverse ramp, or a constant in the specified LUT buffer region (StartIndex to EndIndex). The increment between LUT entries is the difference between StartValue and EndValue, divided by the number of entries.

If you need to generate a more complex LUT, use MgenLutFunction() or generate the values with your Host system and load them into a MIL LUT buffer, using MbufPut1d() or MbufPutColor().

Parameters
LutId

Specifies the identifier of the LUT in which to generate values. This parameter must be given a valid LUT buffer identifier. Allocate a LUT buffer, using MbufAlloc1d() or MbufAllocColor().

StartIndex

Specifies the first LUT index entry for which to generate values. StartIndex must be less than or equal to EndIndex.

StartValue

Specifies the extreme value from which the increment is calculated; that is, the first LUT entry.

EndIndex

Specifies the last LUT index entry for which to generate values. EndIndex must be greater than or equal to StartIndex.

EndValue

Specifies the extreme value from which the increment is calculated; that is, the last LUT entry. If both StartValue and EndValue are the same, the entire LUT range is filled with this value. If EndValue is smaller than StartValue, an inverse ramp is generated. These parameters accept only integer values, except when using a floating-point LUT buffer.


MgenWarpParameter

See Also | Example | Availability | MgenLutRamp
User Guide:
Warping

Reference:
MimWarp
mimwarp.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Genesis

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Generate coefficients or LUTs used to warp an image.
Syntax
void MgenWarpParameter(
MIL_ID InWarpParameter,
MIL_ID OutXLutOrCoef,
MIL_ID OutYLut,
long OperationMode,
long Transform,
double Val1,
double Val2
)
Description

Generate coefficients or LUTs for use with MimWarp(). Specifically, this function can generate:

  • Coefficients (or LUTs) for a first-order polynomial warping (M_WARP_POLYNOMIAL).
  • Coefficients (or LUTs) for perspective warpings that map an arbitrary quadrilateral onto a rectangle (M_WARP_4_CORNER) or that map a rectangle onto an arbitrary quadrilateral (M_WARP_4_CORNER_REVERSE).
  • Lookup tables (LUTs) for 3x3 matrix-defined warpings (M_WARP_LUT).

For a first-order polynomial warping, coefficients can be generated for a rotation, a scaling, a shearing, or a translation. To combine coefficients (for example, to generate coefficients for a rotation and translation), you need to use separate calls to this function, using the previous output buffer as your current input buffer. After all coefficients are generated, pass the coefficient buffer to MimWarp().

Note that you can perform a first-order polynomial warping using LUTs. To generate the required LUTs, use LUT buffers for your output rather than a coefficient buffer while generating the last set of coefficients. In this case, the coefficients will not be saved. If you need to save the coefficients, use MgenWarpParameter() in M_WARP_LUT mode after you have generated all coefficients.

After generating coefficients for perspective warpings, you need to call MgenWarpParameter() in M_WARP_LUT mode, in order to generate the LUTs required by MimWarp(). Alternatively, you can have the LUTs generated on the first call, by using LUT buffers for your output rather than a coefficient buffer. In this case, the coefficients will not be saved.

A 3x3 matrix-defined warping is performed by associating each pixel position of the destination buffer, (xd,xd), with a specific point in the source buffer, (xs,xs), according to the following equation:

where

To perform a 3x3 matrix-defined warping, you must supply the 3x3 coefficients (a0...a2, b0...b2, c0...c2) to MgenWarpParameter(), which will generate the LUTs required by MimWarp() to perform the warping.

Parameters
InWarpParameter

Specifies the input buffer from which to generate coefficients or LUT entries.

When generating coefficients for a first-order polynomial warping, set InWarpParameter to M_NULL if this is your first call to MgenWarpParameter(). If you are combining coefficients and this is a second (or later) call, set InWarpParameter to the identifier of the previous output buffer.

When generating coefficients for perspective warpings that map an arbitrary quadrilateral onto a rectangle or that map a rectangle onto an arbitrary quadrilateral, InWarpParameter must be set to the identifier of a one-dimensional floating-point buffer with an M_ARRAY attribute.

The buffer must contain 12 entries; each entry corresponds to one of the following points.

Entry and its corresponding point | Entry and its corresponding point
entry [0] = X1 | entry [6] = X4
entry [1] = Y1 | entry [7] = Y4
entry [2] = X2 | entry [8] = X1'
entry [3] = Y2 | entry [9] = Y1'
entry [4] = X3 | entry [10] = X3'
entry [5] = Y3 | entry [11] = Y3'

When generating LUTs for a 3x3 matrix-defined warping, InWarpParameter must be set to the identifier of a 3x3 floating-point buffer that has an M_ARRAY attribute. The first row specifies the an coefficients, the second row specifies the bn coefficients, and the third row specifies the cn coefficients.

OutXLutOrCoef

Specifies the buffer in which to place generated coefficients or x-LUT entries.

For coefficients (either those for a polynomial warping or a perspective warping), the buffer must be a 3x3 floating-point buffer with an M_ARRAY attribute.

For x-LUT entries, the buffer must be signed 16- or 32-bit integer, have the same x and y size as the destination buffer that you will eventually pass to MimWarp(), and have an M_LUT attribute.

OutYLut

Specifies the buffer in which to place y-LUT entries. This buffer must be signed 16- or 32-bit integer, have the same x and y size as the destination buffer that you will eventually pass to MimWarp(), and have an M_LUT attribute.

If you are not generating LUTs, set the OutYLut parameter to M_NULL.

OperationMode

Specifies the mode of operation. It can be set to the following:

Open Collapse Value Description
Open Collapse M_WARP_4_CORNER

 Generate coefficients for a perspective warping that maps an arbitrary quadrilateral onto a rectangle.  Generate coefficients for a perspective warping that maps an arbitrary quadrilateral onto a rectangle.

  Open   Collapse  M_WARP_4_CORNER_REVERSE

 Generate coefficients for a perspective warping that maps a rectangle onto an arbitrary quadrilateral.  Generate coefficients for a perspective warping that maps a rectangle onto an arbitrary quadrilateral.

  Open   Collapse  M_WARP_LUT

 Generate LUTs for a 3x3 matrix-defined warping.  Generate LUTs for a 3x3 matrix-defined warping.

  Open   Collapse  M_WARP_POLYNOMIAL

 Generate coefficients for a first-order polynomial warping.  Generate coefficients for a first-order polynomial warping.

      [Combination constants]

 When using LUT buffers for your output, you can add the following value to the OperationMode parameter:

  Open   Collapse  Value
Description

  Open   Collapse  M_FIXED_POINT + n

 Specifies the number of fractional bits for the source address (xs, ys). The default value is 0.  Specifies the number of fractional bits for the source address (xs,ys). The default value is 0 ...

      [Combination constants]

[Matrox Genesis]

 When using LUT buffers for your output, you can add one of the following values to the OperationMode parameter:

  Open   Collapse  Value
Description

  Open   Collapse  M_OVERSCAN_DISABLE

 Replaces addresses that fall outside of the source buffer of MimWarp() with the address (0, 0). If you use this define, the size of the source buffer is required; specify the x-size with the Val1 parameter and the y-size with the Val2 parameter. To use the same x- and/or y-size as the LUT buffers, set Val1 and/or Val2 to M_NULL or M_DEFAULT.  Replaces addresses that fall outside of the source buffer of MimWarp() with the address (0, 0) ...

This is the default value.

  Open   Collapse  M_OVERSCAN_ENABLE

 If addresses fall outside of the source buffer of MimWarp(), use them anyway. Note that, if the source buffer is not a child buffer, these addresses will point to undefined pixel values, leading to unpredictable results.  If addresses fall outside of the source buffer of MimWarp(), use them anyway ...

 Transform

 Specifies the type of first-order polynomial warping for which to generate coefficients.  It can be set to the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_ROTATE

 Generate coefficients for a counter-clockwise rotation around (0,0) by Val1 °.  Generate coefficients for a counter-clockwise rotation around (0,0) by Val1 °.

  Open   Collapse  M_SCALE

 Generate coefficients for an image scaling, by a factor of Val1 in the x direction and by a factor of Val2 in the y direction.  Generate coefficients for an image scaling, by a factor of Val1 in the x direction and by a factor of Val2 in the y direction.

  Open   Collapse  M_SHEAR_X

 Generate coefficients for a shearing in the x direction, by a factor of Val1.  Generate coefficients for a shearing in the x direction, by a factor of Val1.

  Open   Collapse  M_SHEAR_Y

 Generate coefficients for a shearing in the y direction, by a factor of Val1.  Generate coefficients for a shearing in the y direction, by a factor of Val1.

  Open   Collapse  M_TRANSLATE

 Generate coefficients for a translation by Val1 pixels in the x direction and by Val2 pixels in the y direction.  Generate coefficients for a translation by Val1 pixels in the x direction and by Val2 pixels in the y direction.

 If you are not generating coefficients for a first-order polynomial warping, set the Transform parameter to M_DEFAULT.

 Val1

 Specifies the first transform constant.  If this parameter is not being used, set it to M_NULL.

 Val2

 Specifies the second transform constant.  If this parameter is not being used, set it to M_NULL.

WARP POLYNOMIAL WARP 4 CORNER WARP 4 CORNER REVERSE
           WARP LUT WARP LUT WARP LUT ARRAY ARRAY ARRAY LUT LUT     WARP 4 CORNER WARP 4 CORNER REVERSE WARP LUT WARP POLYNOMIAL FIXED POINT
                  n OVERSCAN DISABLE OVERSCAN ENABLE  ROTATE SCALE SHEAR X SHEAR Y TRANSLATE


gra

Mgra functions

Example | Availability
There are no examples containing gra().
Available in MIL-Lite

Available in MIL
Synopsis
The basic graphics module provides a limited set of graphic primitives that can be used to create drawings and text annotations in an image.
Functions
  • MgraAlloc
  • MgraArc
  • MgraArcFill
  • MgraBackColor
  • MgraClear
  • MgraColor
  • MgraControl
  • MgraDot
  • MgraDots
  • MgraFill
  • MgraFont
  • MgraFontScale
  • MgraFree
  • MgraInquire
  • MgraLine
  • MgraLines
  • MgraRect
  • MgraRectFill
  • MgraText


MgraAlloc

See Also | Example | Availability | MgraArc
User Guide:
Preparing for graphics

Reference:
MgraBackColor
MgraColor
MgraControl
MgraFont
MgraFontScale
MgraFree
MgraInquire
MsysAlloc
There are no examples containing MgraAlloc().
Available in MIL-Lite

Available in MIL
Synopsis
Allocate a graphics context.
Syntax
MIL_ID MgraAlloc(
MIL_ID SystemId,
MIL_ID *GraphContIdPtr
)
Description

This function allocates a graphics context, which specifies drawing and text parameters for use in subsequent MIL graphic functions.

Upon allocation of a graphics context, the drawing and text parameters are set to the following default values:

Name | Value
Foreground color | 0xFFFFFFFF
Background color | 0x00000000
Font | M_FONT_DEFAULT_SMALL
Font scale | X = 1.0, Y = 1.0

You can modify these values, using MgraColor(), MgraBackColor(), MgraFont(), and MgraFontScale(), or inquire about the current values, using MgraInquire().

You can set the attributes of the graphics context (for example, background transparency), using MgraControl().

When a graphics context is no longer required, release it, using MgraFree().

Note, upon allocation of an application, a default graphics context is automatically allocated. Rather than using MgraAlloc() to allocate a graphics context, you can use this default graphics context, by specifying M_DEFAULT wherever a graphics context identifier is required.

Parameters
SystemId

Specifies the system on which to allocate the graphics context.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 GraphContIdPtr

 Specifies the address of the variable in which the graphics context identifier is to be written.  Since the MgraAlloc() function also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the graphics context identifier. If allocation fails, M_NULL is returned.

FONT DEFAULT SMALL  DEFAULT HOST


MgraArc

See Also | Example | Availability | MgraAlloc | MgraArcFill
User Guide:
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
mimfft.c
Available in MIL-Lite

Available in MIL
Synopsis
Draw an arc.
Syntax
void MgraArc(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long XCenter,
long YCenter,
long XRad,
long YRad,
double StartAngle,
double EndAngle
)
Description

This function draws an elliptic arc based on an ellipse centered at (XCenter, YCenter) with radii XRad and YRad. The arc is defined by the start angle StartAngle and the end angle EndAngle. The arc is drawn with the foreground color of the specified graphics context.

This function uses the image coordinate system (pixel coordinates). To draw in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

If part of the arc falls outside of the specified target buffer, that part is clipped off.

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter can be set to M_DEFAULT, in which case the default graphics context of the current MIL application is used.

DestImageBufId

Specifies the identifier of the image buffer in which to draw.

XCenter

Specifies the X-coordinate of the ellipse center, relative to the top-left corner of the specified target buffer.

YCenter

Specifies the Y-coordinate of the ellipse center, relative to the top-left corner of the specified target buffer.

XRad

Specifies the radius of the ellipse along the X-axis. The radius should be given in pixels and must be greater than 0.

YRad

Specifies the radius of the ellipse along the Y-axis. The radius should be given in pixels and must be greater than 0.

StartAngle

Specifies the angle at which to start drawing the arc, moving in a counter-clockwise direction. Express the angle in degrees relative to the positive X-axis.

EndAngle

Specifies the angle at which to end drawing the arc, moving in a counter-clockwise direction. Express the angle in degrees relative to the positive X-axis.


MgraArcFill

See Also | Example | Availability | MgraArc | MgraBackColor
User Guide:
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
mdispselect.c
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Draw a filled elliptic arc.
Syntax
void MgraArcFill(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long XCenter,
long YCenter,
long XRad,
long YRad,
double StartAngle,
double EndAngle
)
Description

This function draws a filled elliptic arc based on an ellipse centered at (XCenter, YCenter) with radii XRad and YRad. The arc is defined by the start angle StartAngle and end angle EndAngle. The arc is drawn and filled with the foreground color of the specified graphics context.

This function uses the image coordinate system (pixel coordinates). To draw in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

If part of the arc falls outside of the specified target buffer, that part is clipped off.

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter can be set to M_DEFAULT, in which case the default graphics context of the current MIL application will be used.

DestImageBufId

Specifies the identifier of the image buffer in which to draw.

XCenter

Specifies the X-coordinate of the ellipse center, relative to the top-left corner of the specified target buffer.

YCenter

Specifies the Y-coordinate of the ellipse center, relative to the top-left corner of the specified target buffer.

XRad

Specifies the radius of the ellipse along the X-axis. The radius should be given in pixels and must be greater than 0.

YRad

Specifies the radius of the ellipse along the Y-axis. The radius should be given in pixels and must be greater than 0.

StartAngle

Specifies the angle at which to start drawing the arc, moving in a counter-clockwise direction. Express the angle in degrees relative to the positive X-axis.

EndAngle

Specifies the angle at which to end drawing the arc, moving in a counter-clockwise direction. Express the angle in degrees relative to the positive X-axis.


MgraBackColor

See Also | Example | Availability | MgraArcFill | MgraClear
User Guide:
Preparing for graphics

Reference:
MgraAlloc
MgraControl
mcal.c
mcode.c
Available in MIL-Lite

Available in MIL
Synopsis
Sets the background color of a graphics context.
Syntax
void MgraBackColor(
MIL_ID GraphContId,
double BackgroundColor
)
Description

This function sets the background color of a specified graphics context.

Parameters
GraphContId

Specifies the graphics context with which to associate the background color. This parameter must be set to one of the following values:

Value | Description
M_DEFAULT | Specifies that the default graphics context of the current MIL application is used.
MIL graphics context identifier | Specifies a graphics context identifier, which you have allocated using the MgraAlloc() function.
BackgroundColor

Sets the background color of a specified graphics context. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_RGB888(
long Red,
long Green,
long Blue
)

Specifies an RGB value when using the graphics context to draw in an 8-bit, 3-band buffer. The red, green, and blue values must be values between 0 and 255, inclusive. Specifies an RGB value when using the graphics context to draw in an 8-bit, 3-band buffer ...

When drawing in a 16-bit or 32-bit multi-band buffer, the components of the RGB value are cast to the type of the destination buffer's bands.

To specify a 16-bit or 32-bit color compenent, use MgraControl() with M_BACKCOLOR combined with the appropriate constant (M_RED, M_GREEN, or M_BLUE).

Parameters
Red

Specifies the red value of an RGB value.

Green

Specifies the green value of an RGB value.

Blue

Specifies the blue value of an RGB value.

Open Collapse Value

 Specifies a grayscale value.  Specifies a grayscale value ...

 When drawing in a 1-band buffer, the grayscale value is cast to the type of the destination buffer.

 When drawing in a multi-band buffer, the grayscale value is cast to the type of the destination buffer's bands. This value will be replicated in each band.

BACKCOLOR RED GREEN BLUE


MgraClear

Example | Availability | MgraBackColor | MgraColor
There are no examples containing MgraClear().
Available in MIL-Lite

Available in MIL
Synopsis
Clear an image buffer to a specified foreground color.
Syntax
void MgraClear(
MIL_ID GraphContId,
MIL_ID DestImageBufId
)
Description

This function clears the entire specified buffer to the foreground color of the specified graphics context.

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter can be set to M_DEFAULT, in which case the default graphics context of the current MIL application is used.

DestImageBufId

Specifies the identifier of the buffer to clear. This parameter must be given a valid image buffer identifier.


MgraColor

See Also | Example | Availability | MgraClear | MgraControl
User Guide:
Preparing for graphics

Reference:
MgraAlloc
MgraControl
mappstart.c
mblob.c
mbufcolor.c
mcal.c
mcode.c
mdigautofocus.c
mdispoverlay.c
mdispselect.c
mdispwindowleveling.c
medge.c
mgrabbayer.c
mimfft.c
mimhistogram.c
mmeas.c
mmod.c
mmodeltracking.c
mocr.c
mpat.c
mstr.c
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Sets the foreground color of a graphics context.
Syntax
void MgraColor(
MIL_ID GraphContId,
double ForegroundColor
)
Description

This function sets the foreground color of a specified graphics context.

Parameters
GraphContId

Specifies the graphics context with which to associate the foreground color. This parameter must be set to one of the following values:

Value | Description
M_DEFAULT | Specifies that the default graphics context of the current MIL application is used.
MIL graphics context identifier | Specifies a graphics context identifier, which you have allocated using the MgraAlloc() function.
ForegroundColor

Sets the foreground color of a specified graphics context. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_RGB888(
long Red,
long Green,
long Blue
)

Specifies an RGB value when using the graphics context to draw in an 8-bit, 3-band buffer. The red, green, and blue values must be values between 0 and 255, inclusive. Specifies an RGB value when using the graphics context to draw in an 8-bit, 3-band buffer ...

When drawing in a 16-bit or 32-bit multi-band buffer, the components of the RGB value are cast to the type of the destination buffer's bands.

To specify a 16-bit or 32-bit color compenent, use MgraControl() with M_BACKCOLOR combined with the appropriate constant (M_RED, M_GREEN, or M_BLUE).

Parameters
Red

Specifies the red value of an RGB value.

Green

Specifies the green value of an RGB value.

Blue

Specifies the blue value of an RGB value.

Open Collapse Value

 Specifies a grayscale value.  Specifies a grayscale value ...

 When drawing in a 1-band buffer, the grayscale value is cast to the type of the destination buffer.

 When drawing in a multi-band buffer, the grayscale value is cast to the type of the destination buffer's bands. This value will be replicated in each band.

BACKCOLOR RED GREEN BLUE


MgraControl

See Also | Example | Availability | MgraColor | MgraDot
Reference:
MgraAlloc
mdispoverlay.c
mgrabbayer.c
Available in MIL-Lite

Available in MIL
Synopsis
Control a specified graphics context setting.
Syntax
void MgraControl(
MIL_ID GraphContId,
long ControlType,
double ControlValue
)
Description

This function allows you to set the attributes of a graphics context.

Parameters
GraphContId

Specifies the graphics context to control. This parameter must be set to one of the following:

Value | Description
M_DEFAULT | Specifies that the default graphics context of the current MIL application is used.
MIL graphics context identifier | Specifies a graphics context identifier, which you have allocated using the MgraAlloc() function.

Note that there is a different default graphics context for each thread.

ControlType

Specifies the graphic setting to control.

See the Parameter associations section for possible values.

ControlValue

Specifies the values needed for the control.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

Open Collapse ControlType Description
ControlValue
Open Collapse M_BACKCOLOR

Sets the background color of a specified graphics context. Sets the background color of a specified graphics context ...

M_RGB888(
long Red,
long Green,
long Blue
)

Specifies an RGB value when using the graphics context to draw in an 8-bit, 3-band buffer. The red, green, and blue values must be values between 0 and 255, inclusive.

When drawing in a 16-bit or 32-bit multi-band buffer, the components of the RGB value are cast to the type of the destination buffer's bands.

To specify a 16-bit or 32-bit color compenent, use MgraControl() with M_BACKCOLOR combined with the appropriate constant (M_RED, M_GREEN, or M_BLUE).

Parameters
Red

Specifies the red value of an RGB value.

Green

Specifies the green value of an RGB value.

Blue

Specifies the blue value of an RGB value.

Value

Specifies a grayscale value.

When drawing in a 1-band buffer, the grayscale value is cast to the type of the destination buffer.

When drawing in a multi-band buffer, the grayscale value is cast to the type of the destination buffer's bands. This value will be replicated in each band.

The default value is 0.

Open Collapse M_BACKGROUND_MODE

Controls the setting of the background color on the drawing surface. Controls the setting of the background color on the drawing surface ...

M_OPAQUE

Fills background with the current background color before drawing text.

This is the default value.
M_TRANSPARENT

Does not change background before drawing text. This creates a transparent background for printed characters.

Open Collapse M_COLOR

Sets the foreground color of a specified graphics context. Sets the foreground color of a specified graphics context ...

M_RGB888(
long Red,
long Green,
long Blue
)

Specifies an RGB value when using the graphics context to draw in an 8-bit, 3-band buffer. The red, green, and blue values must be values between 0 and 255, inclusive.

When drawing in a 16-bit or 32-bit multi-band buffer, the components of the RGB value are cast to the type of the destination buffer's bands.

To specify a 16-bit or 32-bit color compenent, use MgraControl() with M_COLOR combined with the appropriate constant (M_RED, M_GREEN, or M_BLUE).

Parameters
Red

Specifies the red value of an RGB value.

Green

Specifies the green value of an RGB value.

Blue

Specifies the blue value of an RGB value.

Value

Specifies a grayscale value.

When drawing in a 1-band buffer, the grayscale value is cast to the type of the destination buffer.

When drawing in a multi-band buffer, the grayscale value is cast to the type of the destination buffer's bands. This value will be replicated in each band.

The default value is -1. For example, this value is equivalent to 0xFF for an 8-bit buffer.

[Combination constants]

The values below can be added to M_COLOR or M_BACKCOLOR. Adding the values will specify the color component.

Open Collapse Value Description
Open Collapse M_BLUE

 Specifies the blue color component.  Specifies the blue color component.

  Open   Collapse  M_GREEN

 Specifies the green color component.  Specifies the green color component.

  Open   Collapse  M_RED

 Specifies the red color component.  Specifies the red color component.

BACKCOLOR RED GREEN BLUE COLOR RED GREEN BLUE COLOR BACKCOLOR    BACKCOLOR     BACKGROUND MODE OPAQUE TRANSPARENT COLOR     BLUE GREEN RED


MgraDot

See Also | Example | Availability | MgraControl | MgraDots
User Guide:
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
There are no examples containing MgraDot().
Available in MIL-Lite

Available in MIL
Synopsis
Draw a dot.
Syntax
void MgraDot(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long XPos,
long YPos
)
Description

This function draws a dot at the specified drawing position, using the foreground color of the specified graphics context.

This function uses the image coordinate system (pixel coordinates). To draw in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter can be set to M_DEFAULT, in which case the default graphics context of the current MIL application is used.

DestImageBufId

Specifies the identifier of the buffer in which to draw. This parameter must be given a valid image buffer identifier.

XPos

Specifies the X-coordinate of the drawing position. The given coordinate is relative to the top-left corner of the specified target buffer. It should be valid in the specified image buffer; otherwise, nothing will be drawn.

YPos

Specifies the Y-coordinate of the drawing position. The given coordinate is relative to the top-left corner of the specified target buffer. It should be valid in the specified image buffer; otherwise, nothing will be drawn.


MgraDots

See Also | Example | Availability | MgraDot | MgraFill
User Guide:
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
MgraAlloc
There are no examples containing MgraDots().
Available in MIL-Lite

Available in MIL
Synopsis
Draw one or more dots.
Syntax
void MgraDots(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long NumberOfDots,
long *XPosArray,
long *YPosArray,
long ControlFlag
)
Description

This function draws dots at the specified drawing positions, using the foreground color of the specified graphics context.

This function uses the image coordinate system (pixel coordinates). To draw in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that the default graphics context of the current MIL application is used.  Specifies that the default graphics context of the current MIL application is used.

  Open   Collapse  MIL graphics context identifier

 Specifies the identifier of the graphics context, which you have allocated using the MgraAlloc() function.  Specifies the identifier of the graphics context, which you have allocated using the MgraAlloc() function.

 DestImageBufId

 Specifies the identifier of the buffer in which to draw.  This parameter must be given a valid image buffer identifier.

 NumberOfDots

 Specifies the number of dots to draw.

 XPosArray

 Specifies the address of the array containing the X-coordinate(s) of the dots to be drawn.

 Each given coordinate is relative to the top-left corner of the specified target buffer. It should be valid in the specified image buffer; otherwise, nothing will be drawn.

 YPosArray

 Specifies the address of the array containing the Y-coordinate(s) of the dots to be drawn.

 Each given coordinate is relative to the top-left corner of the specified target buffer. It should be valid in the specified image buffer; otherwise, nothing will be drawn.

 ControlFlag

 Specifies the function's control flag and must be set to M_DEFAULT.

 DEFAULT


MgraFill

See Also | Example | Availability | MgraDots | MgraFont
User Guide:
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
There are no examples containing MgraFill().
Available in MIL-Lite

Available in MIL
Synopsis
Perform a boundary-type seed fill.
Syntax
void MgraFill(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long XStart,
long YStart
)
Description

This function performs a boundary-type seed fill. It fills in an area of the target buffer, with the foreground color of the specified graphics context, starting from the specified seed position. Filling occurs on adjacent pixels (vertically and horizontally to original seed pixel) that have the same value as the original seed pixel.

If the source buffer is a multi-band buffer, this function will process each band separately. This means that each band of the adjacent pixels will be compared with the corresponding band of the seed pixel. This can produce strange results if, for example, you try to fill the inside of a red circle with blue. The blue will spread to the whole image since the red circle does not exist in the blue band.

This function accepts only pixel coordinates. If you want to fill an area of a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter can be set to M_DEFAULT, in which case the default graphics context of the current MIL application is used.

DestImageBufId

Specifies the identifier of the buffer in which to draw. This parameter must be given a valid image buffer identifier.

XStart

Specifies the X-coordinate of the seed position. If the specified point is not within an enclosed area, filling occurs until the boundaries of the buffer are encountered. The given coordinate is relative to the top-left corner of the specified target buffer. It should be valid in the specified image buffer; otherwise, the operation is not performed.

YStart

Specifies the Y-coordinate of the seed position. If the specified point is not within an enclosed area, filling occurs until the boundaries of the buffer are encountered. The given coordinate is relative to the top-left corner of the specified target buffer. It should be valid in the specified image buffer; otherwise, the operation is not performed.


MgraFont

See Also | Example | Availability | MgraFill | MgraFontScale
User Guide:
Writing text

Reference:
MgraText
mappstart.c
mdispwindow.c
mocr.c
Available in MIL-Lite

Available in MIL
Synopsis
Associate a text font with a graphics context.
Syntax
void MgraFont(
MIL_ID GraphContId,
long FontName
)
Description

This function associates a character font with the specified graphics context for use with subsequent MgraText() function calls.

Parameters
GraphContId

Specifies the identifier of the graphics context with which to associate the character font. This parameter can be set to M_DEFAULT, in which case, the default graphics context of the current MIL application is used.

FontName

Specifies the font with which to write text. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_FONT_DEFAULT

 Same as M_FONT_DEFAULT_SMALL.  Same as M_FONT_DEFAULT_SMALL.

  Open   Collapse  M_FONT_DEFAULT_LARGE

 Sets the parameter to the default font with 16x32 pixel wide characters.  Sets the parameter to the default font with 16x32 pixel wide characters.

  Open   Collapse  M_FONT_DEFAULT_MEDIUM

 Sets the parameter to the default font with 12x24 pixel wide characters.  Sets the parameter to the default font with 12x24 pixel wide characters.

  Open   Collapse  M_FONT_DEFAULT_SMALL

 Sets the parameter to the default font with 8x16 pixel wide characters.  Sets the parameter to the default font with 8x16 pixel wide characters.

FONT DEFAULT SMALL   FONT DEFAULT FONT DEFAULT LARGE FONT DEFAULT MEDIUM FONT DEFAULT SMALL


MgraFontScale

See Also | Example | Availability | MgraFont | MgraFree
User Guide:
Writing text

Reference:
MgraText
There are no examples containing MgraFontScale().
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Genesis

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Set the font scale of a graphics context.
Syntax
void MgraFontScale(
MIL_ID GraphContId,
double XFontScale,
double YFontScale
)
Description

This function sets the font scale of the specified graphics context for use with subsequent MgraText() function calls.

[Matrox Genesis]

MIL uses the Host to scale a font by a non-integer factor; integer factors are scaled by the on-board Matrox Genesis processor.

Parameters
GraphContId

Specifies the identifier of the graphics context for which to set the font scale. This parameter can be set to M_DEFAULT, in which case the default graphics context of the current MIL application is used.

XFontScale

Specifies the X-scale-factor by which to multiply the width of the font characters. This parameter can be independently set to any positive floating point value. The default scale factor is1.0.

Note, using a font with a scale of 1.0 accelerates text drawing.

YFontScale

Specifies the Y-scale-factor by which to multiply the height of the font characters. This parameter can be independently set to any positive floating point value. The default scale factor is1.0.

Note, using a font with a scale of 1.0 accelerates text drawing.


MgraFree

See Also | Example | Availability | MgraFontScale | MgraInquire
User Guide:
Preparing for graphics

Reference:
MgraAlloc
There are no examples containing MgraFree().
Available in MIL-Lite

Available in MIL
Synopsis
Free a graphics context.
Syntax
void MgraFree(
MIL_ID GraphContId
)
Description

This function deallocates a graphics context previously allocated with MgraAlloc().

Parameter
GraphContId

Specifies the identifier of the graphics context to deallocate. If M_DEFAULT is specified, an error will occur.


MgraInquire

Example | Availability | MgraFree | MgraLine
There are no examples containing MgraInquire().
Available in MIL-Lite

Available in MIL
Synopsis
Inquire about the graphics parameters.
Syntax
long MgraInquire(
MIL_ID GraphContId,
long InquireType,
void *UserVarPtr
)
Description

This function inquires about a graphic parameter in the specified graphics context.

Parameters
GraphContId

Specifies the identifier of the graphics context on which to perform the inquiry. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that the default graphics context of the current MIL application is used. Note that there is a different default graphics context for each thread.  Specifies that the default graphics context of the current MIL application is used ...

  Open   Collapse  Value

 Specifies the identifier of the graphics context.  Specifies the identifier of the graphics context.

 InquireType

 Specifies the graphic parameter about which to inquire.  This parameter can be set to one of the following values:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

Open Collapse Value | Description
Open Collapse M_BACKCOLOR | Returns the background color. Returns the background color ...
 |  | UserVarPtr info Return values: Value (details)
Open Collapse M_BACKGROUND_MODE | Returns the background mode. Returns the background mode ...
 |  | UserVarPtr info Data type: long Return values: M_OPAQUE, M_TRANSPARENT (details)
Open Collapse M_COLOR | Returns the foreground color. Returns the foreground color ...
 |  | UserVarPtr info Return values: Value (details)
Open Collapse M_FONT | Returns the character font. Returns the character font ...
 |  | UserVarPtr info Data type: long Return values: M_FONT_DEFAULT, M_FONT_DEFAULT_LARGE, M_FONT_DEFAULT_MEDIUM, M_FONT_DEFAULT_SMALL (details)
Open Collapse M_FONT_X_SCALE | Returns the font scaling factor in X. Returns the font scaling factor in X ...
 |  | UserVarPtr info Return values: Please see the XFontScale parameter of MgraFontScale().
Open Collapse M_FONT_Y_SCALE | Returns the font scaling factor in Y. Returns the font scaling factor in Y ...
 |  | UserVarPtr info Return values: Please see the YFontScale parameter of MgraFontScale().
Open Collapse M_OWNER_SYSTEM | Returns the MIL identifier (MIL_ID) of the system on which the graphics context has been allocated. Returns the MIL identifier (MIL_ID) of the system on which the graphics context has been allocated ...
 |  | UserVarPtr info Data type: MIL_ID Return values: M_DEFAULT_HOST, MIL system identifier (details)

      [Combination constants]

 To inquire the color value used in the graphics context for a 16-bit or 32-bit multi-band buffer, you must inquire each color component (R,G, and B) separately. Add one of the following values to M_COLOR or M_BACKCOLOR to specify the color component:

Open Collapse Value | Description
Open Collapse M_BLUE | Returns the blue component. Returns the blue component.
Open Collapse M_GREEN | Returns the green component. Returns the green component.
Open Collapse M_RED | Returns the red component. Returns the red component.

 For example, you would make the following call to inquire the red color component:

 MgraInquire(M_DEFAULT, M_COLOR + M_RED, &red color component)

 UserVarPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • double
    •

  • long
    •

  • MIL_ID
    •

 Specifies the address in which the requested information is to be written.  Since this function also returns the requested information, you can set this parameter to M_NULL.

Return value

 The returned value is the requested system information cast to long.

COLOR BACKCOLOR DEFAULT COLOR RED  DEFAULT   BACKCOLOR BACKGROUND MODE COLOR FONT FONT X SCALE FONT Y SCALE OWNER SYSTEM BLUE GREEN RED


MgraLine

See Also | Example | Availability | MgraInquire | MgraLines
User Guide:
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
mdigautofocus.c
mdispwindowleveling.c
Available in MIL-Lite

Available in MIL
Synopsis
Draw a line.
Syntax
void MgraLine(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long XStart,
long YStart,
long XEnd,
long YEnd
)
Description

This function draws a line starting and ending at the specified coordinates, using the foreground color of the specified graphics context.

Note that the given coordinates (XStart, YStart, XEnd, YEnd) are relative to the top-left corner of the specified target buffer. They should be valid in the specified buffer; otherwise, the line is clipped outside the buffer boundaries.

This function uses the image coordinate system (pixel coordinates). To draw in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that the default graphics context of the current MIL application is used.  Specifies that the default graphics context of the current MIL application is used.

  Open   Collapse  Value

 Specifies the identifier of the graphics context.  Specifies the identifier of the graphics context.

 DestImageBufId

 Specifies the identifier of the buffer in which to draw.  This parameter must be given a valid image buffer identifier.

 XStart

 Specifies the X-coordinate for the start of the line position.

 YStart

 Specifies the Y-coordinate for the start of the line position.

 XEnd

 Specifies the X-coordinate for the end of the line position.

 YEnd

 Specifies the Y-coordinate for the end of the line position.

 DEFAULT


MgraLines

See Also | Example | Availability | MgraLine | MgraRect
User Guide:
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
MgraAlloc
mimhistogram.c
Available in MIL-Lite

Available in MIL
Synopsis
Draw one or more lines.
Syntax
void MgraLines(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long NumberOfLines,
long *XStartArray,
long *YStartArray,
long *XEndArray,
long *YEndArray,
long ControlFlag
)
Description

This function draws lines starting and ending at the specified coordinates, using the foreground color of the specified graphics context.

Note that the given coordinates (XStartArray, YStartArray, XEndArray, YEndArray) are relative to the top-left corner of the specified target buffer. They should be valid in the specified buffer; otherwise, the line is clipped outside the buffer boundaries.

This function uses the image coordinate system (pixel coordinates). To draw in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that the default graphics context of the current MIL application is used.  Specifies that the default graphics context of the current MIL application is used.

  Open   Collapse  MIL graphics context identifier

 Specifies the identifier of the graphics context, which you have allocated using the MgraAlloc() function.  Specifies the identifier of the graphics context, which you have allocated using the MgraAlloc() function.

 DestImageBufId

 Specifies the identifier of the buffer in which to draw.  This parameter must be given a valid image buffer identifier.

 NumberOfLines

 Specifies the number of lines to draw.

 XStartArray

 Specifies the address of the array containing the X-coordinate(s) of the start of the lines to be drawn.

 YStartArray

 Specifies the address of the array containing the Y-coordinate(s) of the start of the lines to be drawn.

 XEndArray

 Specifies the address of the array containing the X-coordinate(s) of the end of the lines to be drawn.

 YEndArray

 Specifies the address of the array containing the Y-coordinate(s) of the end of the lines to be drawn.

 ControlFlag

 Specifies the function's control flag and must be set to M_DEFAULT.

 DEFAULT


MgraRect

See Also | Example | Availability | MgraLines | MgraRectFill
User Guide:
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
dtkobjecttracking.c
mappstart.c
mcode.c
mdispwindow.c
mgrabbayer.c
mmodeltracking.c
Available in MIL-Lite

Available in MIL
Synopsis
Draw a rectangle.
Syntax
void MgraRect(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long XStart,
long YStart,
long XEnd,
long YEnd
)
Description

This function draws a rectangle starting from the specified top-left coordinate to the specified bottom-right corner. The rectangle is drawn in the foreground color of the specified graphics context.

Note that the given coordinates (XStart, YStart, XEnd, YEnd) are relative to the top-left corner of the specified target buffer. They should be valid in the specified buffer; otherwise, the line is clipped outside the buffer boundaries.

This function uses the image coordinate system (pixel coordinates). To draw in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that the default graphics context of the current MIL application is used.  Specifies that the default graphics context of the current MIL application is used.

  Open   Collapse  Value

 Specifies the identifier of the graphics context.  Specifies the identifier of the graphics context.

 DestImageBufId

 Specifies the identifier of the buffer in which to draw.  This parameter must be given a valid image buffer identifier.

 XStart

 Specifies the X-coordinate of the top-left corner of the rectangle.

 YStart

 Specifies the Y-coordinate of the top-left corner of the rectangle.

 XEnd

 Specifies the X-coordinate of the bottom-right corner of the rectangle.

 YEnd

 Specifies the Y-coordinate of the bottom-right corner of the rectangle.

 DEFAULT


MgraRectFill

See Also | Example | Availability | MgraRect | MgraText
User Guide:
Supported code types and noteworthy characteristics
Drawing graphics

Reference:
McalTransformCoordinate
McalTransformCoordinateList
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Draw a filled rectangle.
Syntax
void MgraRectFill(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long XStart,
long YStart,
long XEnd,
long YEnd
)
Description

This function draws a filled rectangle starting from the specified top-left coordinate to the specified bottom-right corner. The rectangle is drawn and filled in the foreground color of the specified graphics context.

Note that the given coordinates (XStart, YStart, XEnd, YEnd) are relative to the top-left corner of the specified target buffer. They should be valid in the specified buffer; otherwise, the line is clipped outside the buffer boundaries.

This function uses the image coordinate system (pixel coordinates). To draw in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that the default graphics context of the current MIL application is used.  Specifies that the default graphics context of the current MIL application is used.

  Open   Collapse  Value

 Specifies the identifier of the graphics context.  Specifies the identifier of the graphics context.

 DestImageBufId

 Specifies the identifier of the buffer in which to draw.  This parameter must be given a valid image buffer identifier.

 XStart

 Specifies the X-coordinate of the top-left corner of the rectangle.

 YStart

 Specifies the Y-coordinate of the top-left corner of the rectangle.

 XEnd

 Specifies the X-coordinate of the bottom-right corner of the rectangle.

 YEnd

 Specifies the Y-coordinate of the bottom-right corner of the rectangle.

 DEFAULT


MgraText

See Also | Example | Availability | MgraRectFill
User Guide:
Annotating the displayed image non-destructively
Writing text

Reference:
McalTransformCoordinate
McalTransformCoordinateList
MgraControl
MgraFont
MgraFontScale
dtkobjecttracking.c
mappstart.c
mbufcolor.c
mcal.c
mcode.c
mdigdoublebuffering.c
mdiggrabsequence.c
mdighook.c
mdigprocess.c
mdigprocessmultiple.c
mdispoverlay.c
mdispselect.c
mdispwindow.c
mdispwindowleveling.c
mocr.c
mthread.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Write text.
Syntax
void MgraText(
MIL_ID GraphContId,
MIL_ID DestImageBufId,
long XStart,
long YStart,
MIL_TEXT_PTR String
)
Description

This function writes the specified string to the specified buffer starting at the specified writing position, using the parameters (colors, font, and size) defined in the graphics context. Use MgraFont() and MgraFontScale() to modify the font and size. Use MgraControl() to obtain a transparent background for printed characters.

Note that the coordinates at which to start writing the string (XStart, YStart) are relative to the top-left corner of the specified target buffer. They should be valid in the specified buffer; otherwise, the line is clipped outside the buffer boundaries.

This function uses the image coordinate system (pixel coordinates). To write in a calibrated image using real-world coordinates, you must first convert the coordinates from their real-world value to their pixel value using McalTransformCoordinate() or McalTransformCoordinateList().

Parameters
GraphContId

Specifies the identifier of the graphics context. This parameter must be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies that the default graphics context of the current MIL application is used.  Specifies that the default graphics context of the current MIL application is used.

  Open   Collapse  Value

 Specifies the identifier of the graphics context.  Specifies the identifier of the graphics context.

 DestImageBufId

 Specifies the identifier of the buffer in which to write.  This parameter must be given a valid image buffer identifier.

 XStart

 Specifies the X-coordinate of the position at which to start writing the top-left corner of the first character.

 YStart

 Specifies the Y-coordinate of the position at which to start writing the top-left corner of the first character.

 String

 Specifies the address of the string that must be written in the destination buffer.  There is no restriction on the length of the string, except that the string must be null (\0) terminated.

 DEFAULT


im

Mim functions

Example | Availability
There are no examples containing im().
Not available in MIL-Lite

Available in MIL
Synopsis
The basic image processing module gives the user the possiblity to do point-to-point, statistical, spatial filtering, morphological, and geometric transformation operations. These operations allow you to perform image enhancements, distortion corrections, and analyses.
Functions
  • MimAllocResult
  • MimArith
  • MimArithMultiple
  • MimBinarize
  • MimClip
  • MimClose
  • MimConnectMap
  • MimConvert
  • MimConvolve
  • MimCountDifference
  • MimDilate
  • MimDistance
  • MimEdgeDetect
  • MimErode
  • MimFindExtreme
  • MimFlip
  • MimFree
  • MimGetResult
  • MimGetResult1d
  • MimHistogram
  • MimHistogramEqualize
  • MimInquire
  • MimLabel
  • MimLocateEvent
  • MimLutMap
  • MimMorphic
  • MimOpen
  • MimPolarTransform
  • MimProject
  • MimRank
  • MimResize
  • MimRotate
  • MimShift
  • MimStat
  • MimThick
  • MimThin
  • MimTransform
  • MimTranslate
  • MimWarp
  • MimWatershed
  • MimZoneOfInfluence


MimAllocResult

See Also | Example | Availability | MimArith
User Guide:
Image statistics

Reference:
MimCountDifference
MimFindExtreme
MimFree
MimHistogram
MimLocateEvent
MimProject
MimStat
MsysAlloc
dtkremap.c
mdispwindowleveling.c
mimhistogram.c
mimprocessing.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate an image processing result buffer.
Syntax
MIL_ID MimAllocResult(
MIL_ID SystemId,
long NbEntries,
long ResultType,
MIL_ID *ImResultIdPtr
)
Description

This function allocates a result buffer with the specified number of entries, for use with the image processing module's statistical functions.

When the result buffer is no longer required, you should release its memory, using MimFree().

Parameters
SystemId

Specifies the system on which to allocate the result buffer. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  Value

 Specifies a valid system identifier, previously allocated using MsysAlloc().  Specifies a valid system identifier, previously allocated using MsysAlloc().

 NbEntries

 Specifies the number of buffer entries of the specified result buffer type (ResultType).  This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 MIL automatically decides the size of the result buffer.  MIL automatically decides the size of the result buffer.

  Open   Collapse  Value

 Specifies a valid number of buffer entries.  Specifies a valid number of buffer entries.

 ResultType

 Specifies the type of data that will be stored in this result buffer.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_COUNT_LIST

 Specifies MimCountDifference() results.  Specifies MimCountDifference() results.

  Open   Collapse  M_EVENT_LIST

 Specifies MimLocateEvent() results.  Specifies MimLocateEvent() results.

  Open   Collapse  M_EXTREME_LIST

 Specifies MimFindExtreme() results.  Specifies MimFindExtreme() results.

  Open   Collapse  M_HIST_LIST

 Specifies MimHistogram() results.  Specifies MimHistogram() results.

  Open   Collapse  M_PROJ_LIST

 Specifies MimProject() results.  Specifies MimProject() results.

  Open   Collapse  M_STAT_LIST

 Specifies MimStat() results.  Specifies MimStat() results.

      [Combination constants]

 The value below can be added to M_PROJ_LIST, M_EXTREME_LIST or M_EVENT_LIST result types to change the type of data stored in the result buffer.

  Open   Collapse  Value
Description

  Open   Collapse  M_FLOAT

 Allocates a result buffer of type float. You should allocate a float result type buffer when the source buffer specified by MimProject(), MimFindExtreme(), or MimLocateEvent() is of type float. If the specified source buffer is of type float and the result buffer is not, the functions can produce inaccurate results.  Allocates a result buffer of type float ...

 Note that allocating a result buffer of type float when the source buffer is not, will slow down the operations performed by the MimProject(), MimFindExtreme(), or MimLocateEvent() function.

 ImResultIdPtr

 Specifies the address of the variable in which to write the image processing result buffer identifier.  Since MimAllocResult() also returns the image processing result buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the image processing result buffer identifier. If allocation fails, M_NULL is returned.

PROJ LIST EXTREME LIST EVENT LIST  DEFAULT HOST    DEFAULT  COUNT LIST EVENT LIST EXTREME LIST HIST LIST PROJ LIST STAT LIST FLOAT


MimArith

Example | Availability | MimAllocResult | MimArithMultiple
dtkaddconstantmain.c
mbufcolor.c
mdigdoublebuffering.c
mdigmultdestination.c
mdigprocess.c
mdigprocessmultiple.c
mdigsubtract.c
mimperimeter.c
mimprocessing.c
mimsegment.c
mthread.c
odysseymultiboard.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a point-to-point arithmetic operation.
Syntax
void MimArith(
double Src1ImageBufId,
double Src2ImageBufId,
MIL_ID DestImageBufId,
long Operation
)
Description

This function performs the specified point-to-point operation on two images, an image and a constant, an image, or a constant, storing results in the specified destination image buffer.

Parameters
Src1ImageBufId

Specifies the data source of the first operand. This parameter can be given an image buffer identifier or a constant. When using a constant, it will be considered to have the same type as the destination buffer.

Src2ImageBufId

Specifies the data source of the second operand. This parameter can be given an image buffer identifier or a constant. If the selected operation uses only one operand, set this parameter to M_NULL. When using a constant, it will be considered to have the same type as the destination buffer.

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer identifier.

Operation

Specifies the operation to perform. This parameter should be set in accordance to the operands. Operations using two image buffer operands are the following:

Open Collapse Value Description
Open Collapse M_ADD

 Adds the values of the first image to the values of the second image.  Adds the values of the first image to the values of the second image.

  Open   Collapse  M_AND

 Performs a bitwise AND operation on the two operands.  Performs a bitwise AND operation on the two operands.

  Open   Collapse  M_DIV

 Divides the values of the first image by the values of the second image.  Divides the values of the first image by the values of the second image ...

 Note that dividing a value by 0 will generate a destination pixel with an unpredictable value. This will not generate an error.

  Open   Collapse  M_MAX

 Compares the values of the first image with the values of the second image, and takes the maximum of the two.  Compares the values of the first image with the values of the second image, and takes the maximum of the two.

  Open   Collapse  M_MIN

 Compares the values of the first image with the values of the second image, and takes the minimum of the two.  Compares the values of the first image with the values of the second image, and takes the minimum of the two.

  Open   Collapse  M_MULT

 Multiplies the values of the first image with the values of the second image.  Multiplies the values of the first image with the values of the second image.

  Open   Collapse  M_NAND

 Performs a bitwise 'AND-NOT' operation on the two operands.  Performs a bitwise 'AND-NOT' operation on the two operands.

  Open   Collapse  M_NOR

 Performs a bitwise NOR operation on the two operands.  Performs a bitwise NOR operation on the two operands.

  Open   Collapse  M_OR

 Performs a bitwise OR operation on the two operands.  Performs a bitwise OR operation on the two operands.

  Open   Collapse  M_SUB

 Subtracts the values of the second image from the first image (for example, image 1 - image 2).  Subtracts the values of the second image from the first image (for example, image 1 - image 2).

  Open   Collapse  M_SUB_ABS

 Takes the absolute value of the result of subtracting the two operands.  Takes the absolute value of the result of subtracting the two operands.

  Open   Collapse  M_XNOR

 Performs a bitwise exclusive NOR operation on the operands.  Performs a bitwise exclusive NOR operation on the operands.

  Open   Collapse  M_XOR

 Performs a bitwise exclusive OR operation on the operands.  Performs a bitwise exclusive OR operation on the operands.

 The following are operations that use an image buffer operand and a constant. If the operation is not commutative, you must give the constant as either the first or second operand, as can be determined from the predefined operation name.

  Open   Collapse  Value
Description

  Open   Collapse  M_ADD_CONST

 Adds a constant to the values of an image.  Adds a constant to the values of an image.

  Open   Collapse  M_AND_CONST

 Performs a bitwise AND operation on the image and a constant.  Performs a bitwise AND operation on the image and a constant.

  Open   Collapse  M_CONST_DIV

 Divides a constant by the values of an image (for example, constant / image).  Divides a constant by the values of an image (for example, constant / image).

  Open   Collapse  M_CONST_PASS

 Copies the constant to each destination pixel.  Copies the constant to each destination pixel.

  Open   Collapse  M_CONST_SUB

 Subtracts the image from the constant (for example, constant - image).  Subtracts the image from the constant (for example, constant - image).

  Open   Collapse  M_DIV_CONST

 Divides the values of an image by a constant (for example, image / constant).  Divides the values of an image by a constant (for example, image / constant).

  Open   Collapse  M_MAX_CONST

 Compares the values of one image with a constant, and takes the maximum of the two.  Compares the values of one image with a constant, and takes the maximum of the two.

  Open   Collapse  M_MIN_CONST

 Compares the values of one image with a constant, and takes the minimum of the two.  Compares the values of one image with a constant, and takes the minimum of the two.

  Open   Collapse  M_MULT_CONST

 Multiplies the values of the image by the constant.  Multiplies the values of the image by the constant.

  Open   Collapse  M_NAND_CONST

 Performs a bitwise AND-NOT operation with an image and a constant.  Performs a bitwise AND-NOT operation with an image and a constant.

  Open   Collapse  M_NOR_CONST

 Performs a bitwise NOR operation with an image and a constant.  Performs a bitwise NOR operation with an image and a constant.

  Open   Collapse  M_OR_CONST

 Performs a bitwise OR operation with an image and a constant.  Performs a bitwise OR operation with an image and a constant.

  Open   Collapse  M_SUB_CONST

 Subtracts an constant from the values of an image (for example, image - constant).  Subtracts an constant from the values of an image (for example, image - constant).

  Open   Collapse  M_XNOR_CONST

 Performs a bitwise exclusive NOR operation with an image and a constant.  Performs a bitwise exclusive NOR operation with an image and a constant.

  Open   Collapse  M_XOR_CONST

 Performs a bitwise exclusive OR operation with an image and a constant.  Performs a bitwise exclusive OR operation with an image and a constant.

 Operations using only one image buffer operand are the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_ABS

 Takes the absolute value of the image values.  Takes the absolute value of the image values.

  Open   Collapse  M_NEG

 Performs a negation operation on an image.  Performs a negation operation on an image.

  Open   Collapse  M_NOT

 Performs a bitwise NOT operation on an image.  Performs a bitwise NOT operation on an image.

  Open   Collapse  M_PASS

 Copies the source buffer to the destination image buffer.  Copies the source buffer to the destination image buffer.

      [Combination constants]

 The value below can be added to M_DIV, M_CONST_DIV, and M_DIV_CONST to alter the result of the operation.

  Open   Collapse  Value
Description

  Open   Collapse  M_FIXED_POINT

 Forces the operation to result in a fixed point format.  Forces the operation to result in a fixed point format ...

 Note that operations using this attribute result in an 0.8 fixed-point format for an 8-bit destination. That is, the 8 bits comprise only the fractional portion of the value, and no integer portion. When the destination image buffer is 16-bit, operations that use the M_FIXED_POINT attribute result in an 8.8 fixed-point format (where the eight most-significant bits are the integer portion and the eight least-significant bits are the fractional portion). For a 32-bit destination, the result is in a 16.16 fixed-point format.

 Note that this attribute cannot be used when using a floating-point destination buffer.

      [Combination constants]

 The value below can be added to M_ADD, M_ADD_CONST, M_SUB, M_SUB_ABS, M_SUB_CONST, M_CONST_SUB, M_MULT, and M_MULT_CONST.

  Open   Collapse  Value
Description

  Open   Collapse  M_SATURATION

 Forces the operation to result in the maximum value possible for the destination image buffer whenever the calculation results in a value that would otherwise overflow or underflow.  Forces the operation to result in the maximum value possible for the destination image buffer whenever the calculation results in a value that would otherwise overflow or underflow.

Remarks

  •  This function is optimized for packed binary buffers.
    •

  •  When performing a division operation (for example, using M_DIV or M_DIV + M_FIXED_POINT), dividing a value by 0 will generate a destination pixel with an unpredictable value. However, an error is not generated.
    •

  •  Logical operations (M_OR, M_NOR, M_OR_CONST, M_NOR_CONST, M_NOT, M_AND, M_NAND, M_AND_CONST, M_NAND_CONST, M_XOR, M_NOR, M_XOR_CONST, M_XNOR_CONST) cannot be performed on a floating-point buffer.
    •

  •  In-place processing is supported (source equals destination), but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

DIV CONST DIV DIV CONST FIXED POINT ADD ADD CONST SUB SUB ABS SUB CONST CONST SUB MULT MULT CONST DIV DIV FIXED POINT OR NOR OR CONST NOR CONST NOT AND NAND AND CONST NAND CONST XOR NOR XOR CONST XNOR CONST     ADD AND DIV MAX MIN MULT NAND NOR OR SUB SUB ABS XNOR  XOR ADD CONST AND CONST CONST DIV CONST PASS CONST SUB DIV CONST MAX CONST MIN CONST MULT CONST NAND CONST NOR CONST  OR CONST SUB CONST XNOR CONST XOR CONST ABS NEG NOT PASS FIXED POINT  SATURATION


MimArithMultiple

Example | Availability | MimArith | MimBinarize
There are no examples containing MimArithMultiple().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a point-to-point arithmetic operation using multiple source images.
Syntax
void MimArithMultiple(
double Src1ImageBufId,
double Src2ImageBufId,
double Src3ImageBufId,
double Src4ImageBufId,
double Src5ImageBufId,
MIL_ID DestImageBufId,
long Operation,
long OperationFlag
)
Description

This function performs the specified point-to-point operation requiring multiple images, images and constants, or constants, storing results in the specified destination image buffer. Note that this function does not take 1-bit buffers in any of its parameters.

Also note that if the selected operation does not require all of the possible operands, set the excess source buffer parameters to M_NULL.

Parameters
Src1ImageBufId

Specifies the data source of the first operand; this parameter can be given an image buffer identifier or a constant.

See the Parameter associations section for possible values.

Src2ImageBufId

Specifies the data source of the second operand; this parameter can be given an image buffer identifier or a constant.

See the Parameter associations section for possible values.

Src3ImageBufId

Specifies the data source of the third operand; this parameter can be given an image buffer identifier or a constant.

See the Parameter associations section for possible values.

Src4ImageBufId

Specifies the data source of the fourth operand; this parameter can be given an image buffer identifier or a constant.

See the Parameter associations section for possible values.

Src5ImageBufId

Specifies the data source of the fifth operand; this parameter can be given an image buffer identifier or a constant.

See the Parameter associations section for possible values.

DestImageBufId

Specifies the identifier of the destination of the results; this parameter must be given an image buffer identifier.

Operation

Specifies the operation to perform. The following table lists the valid multiple operation names, their equations, and their descriptions, as well as their requirements for the sources of the operands:

See the Parameter associations section for possible values.

OperationFlag

Must be set to M_DEFAULT.

Parameter associations

Possible values for the Operation, Src1ImageBufId, Src2ImageBufId, Src3ImageBufId, Src4ImageBufId, and Src5ImageBufId parameters are described below.

Open Collapse Operation |  |  | Description
 | Src1ImageBufId
 | Src2ImageBufId
 | Src3ImageBufId
 | Src4ImageBufId
 | Src5ImageBufId
Open Collapse M_MULTIPLY_ACCUMULATE_1 |  |  | Applies the following equation to the specified image: ((Src1 * Src2) + Src3) / Src4
 | Src1ImageBufId |  |
 |  | MIL Image buffer identifier | Specifies the image buffer identifier required for the first operand.
 | Src2ImageBufId |  |
 |  | Constant value | Specifies the buffer requires a constant. Note that the constant is cast to the same type as the buffer specified for first operand.
 | Src3ImageBufId |  |
 |  | Constant value | Specifies the buffer requires a constant. Note that the constant is cast to the same type as the buffer specified for first operand.
 | Src4ImageBufId |  |
 |  | Value | Specifies the constant required for the fourth operand. This constant must be a power of 2. Note that the constant is cast to the same type as the buffer specified for first operand.
 | Src5ImageBufId |  |
 |  | M_NULL | Must be set to this value.
Open Collapse M_MULTIPLY_ACCUMULATE_2 |  |  | Applies the following equation to the specified image: ((Src1 * Src2) + (Src3 * Src4)) / Src5
 | Src1ImageBufId |  |
 |  | MIL Image buffer identifier | Specifies that an image buffer identifier is required.
 | Src2ImageBufId |  |
 |  | Constant value | Specifies the buffer requires a constant. This constant is cast to the same type as the buffer specified for the first operand.
 | Src3ImageBufId |  |
 |  | MIL Image buffer identifier | Specifies that an image buffer identifier is required. This constant is cast to the same type as the buffer specified for the first operand.
 | Src4ImageBufId |  |
 |  | Constant value | Specifies the buffer requires a constant. This constant is cast to the same type as the buffer specified for the fourth operand.
 | Src5ImageBufId |  |
 |  | Value | Specifies the buffer requires a constant and power of 2.
Open Collapse M_OFFSET_GAIN |  |  | Applies per-pixel gain and offset correction to an image using the following equation: ((Src1 - Src2) * Src3) / Src4
 | Src1ImageBufId |  |
 |  | MIL Image buffer identifier | Specifies that an image buffer identifier is required.
 | Src2ImageBufId |  |
 |  | MIL Image buffer identifier | Specifies that an image buffer identifier is required. Note that the image buffer must be of the same type as the first operand.
 | Src3ImageBufId |  |
 |  | MIL Image buffer identifier | Specifies that an image buffer identifier is required. Note that the image buffer must be of the same type as the first operand.
 | Src4ImageBufId |  |
 |  | Value | Specifies the buffer requires a constant and power of 2.
 | Src5ImageBufId |  |
 |  | M_NULL | Must be set to this value.
Open Collapse M_WEIGHTED_AVERAGE |  |  | Applies a weighted average to an image using the following equation and places the result in an accumulator: ((Src1 - Src3) / Src2) + Src3
 | Src1ImageBufId |  |
 |  | MIL Image buffer identifier | Specifies that an image buffer identifier is required.
 | Src2ImageBufId |  |
 |  | Value | Specifies the buffer requires a constant and power of 2.
 | Src3ImageBufId |  |
 |  | MIL Image buffer identifier | Specifies that an image buffer identifier is required. Note that the image buffer must be of the same type as the first operand.
 | Src4ImageBufId |  |
 |  | M_NULL | Must be set to this value.
 | Src5ImageBufId |  |
 |  | M_NULL | Must be set to this value.

Remark
  • In-place processing is supported (source equals destination), but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
MULTIPLY ACCUMULATE 1 NULL MULTIPLY ACCUMULATE 2 OFFSET GAIN NULL WEIGHTED AVERAGE NULL NULL


MimBinarize

Example | Availability | MimArithMultiple | MimClip
mblob.c
mimmorphic.c
mimperimeter.c
mimprocessing.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a point-to-point binary thresholding operation.
Syntax
long MimBinarize(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long Condition,
double CondLow,
double CondHigh
)
Description

This function performs binary thresholding on the specified image. Each pixel that meets the specified condition is set to the highest unsigned destination buffer value, while other pixels are set to 0. If a floating point destination buffer is specified, pixels that meet the condition are set to 1. For example, the highest buffer value for an 8-bit buffer is 0xff (regardless if the source buffer is signed).

MIL can automatically determine one threshold value (CondLow or CondHigh) from the source image's histogram. In this case, if the histogram contains only two peaks, the threshold value is set to the minimum value between these peaks. If the histogram contains more than two peaks, then the threshold value will typically be set between the two principal peaks, though exceptions exist for pure black and full saturation (0, 255).

If the automatically calculated threshold value causes CondHigh to be less than CondLow, then the calculated value is not used, and both CondLow and CondHigh are set to the same value. If the CondLow and CondHigh parameters are both set to M_DEFAULT, they will have the same automatically calculated threshold value.

If you want this function to return the automatically calculated threshold value, without binarizing the source image, set the DestImageBufId parameter to M_NULL and set the CondLow or CondHigh parameters to M_DEFAULT.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the results. In general, this parameter must be given an image buffer identifier.

Condition

Specifies the thresholding condition. This parameter must be set to one of the values below.

The following are conditions that use two limits (CondLow and CondHigh):

Open Collapse Value Description
Open Collapse M_IN_RANGE

 Sets pixels with values between CondLow and CondHigh, inclusive, to the highest buffer value. Other pixels are set to 0.  Sets pixels with values between CondLow and CondHigh, inclusive, to the highest buffer value ...

 If a floating point destination buffer is specified, pixels that meet the condition are set to 1.

  Open   Collapse  M_OUT_RANGE

 Sets pixels with values less than CondLow, or greater than CondHigh, to the highest buffer value. Other pixels are set to 0.  Sets pixels with values less than CondLow, or greater than CondHigh, to the highest buffer value ...

 If a floating point destination buffer is specified, pixels that meet the condition are set to 1.

 The following are conditions that use one limit (CondLow):

  Open   Collapse  Value
Description

  Open   Collapse  M_EQUAL

 Sets pixel values equal to CondLow to the highest buffer value possible, while other pixels are set to zero.  Sets pixel values equal to CondLow to the highest buffer value possible, while other pixels are set to zero ...

 If a floating point destination buffer is specified, pixels that meet the condition are set to 1.

  Open   Collapse  M_GREATER

 Sets pixel values greater than CondLow to the highest buffer value possible, while other pixels are set to zero.  Sets pixel values greater than CondLow to the highest buffer value possible, while other pixels are set to zero ...

 If a floating point destination buffer is specified, pixels that meet the condition are set to 1.

  Open   Collapse  M_GREATER_OR_EQUAL

 Sets pixel values greater than or equal to CondLow to the highest buffer value possible, while other pixels are set to zero.  Sets pixel values greater than or equal to CondLow to the highest buffer value possible, while other pixels are set to zero ...

 If a floating point destination buffer is specified, pixels that meet the condition are set to 1.

  Open   Collapse  M_LESS

 Sets pixel values less than CondLow to the highest buffer value possible, while other pixels are set to zero.  Sets pixel values less than CondLow to the highest buffer value possible, while other pixels are set to zero ...

 If a floating point destination buffer is specified, pixels that meet the condition are set to 1.

  Open   Collapse  M_LESS_OR_EQUAL

 Sets pixel values less than or equal to CondLow to the highest buffer value possible, while other pixels are set to zero.  Sets pixel values less than or equal to CondLow to the highest buffer value possible, while other pixels are set to zero ...

 If a floating point destination buffer is specified, pixels that meet the condition are set to 1.

  Open   Collapse  M_NOT_EQUAL

 Sets pixel values not equal to CondLow to the highest buffer value possible, while other pixels are set to zero.  Sets pixel values not equal to CondLow to the highest buffer value possible, while other pixels are set to zero ...

 If a floating point destination buffer is specified, pixels that meet the condition are set to 1.

 CondLow

 Specifies the lower limit of the selected condition.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the parameter will be determined from the image's histogram.  Specifies that the parameter will be determined from the image's histogram.

  Open   Collapse  Value

 Specifies the lower limit.  Specifies the lower limit ...

 Note that the value for CondLow is cast to the source buffer's data type and depth. If the source buffer is binary, the value must be equal to 0 or 1.

 CondHigh

 Specifies the upper limit of the selected condition.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the parameter will be determined from the image's histogram.  Specifies that the parameter will be determined from the image's histogram.

  Open   Collapse  M_NULL

 Specifies that this setting does not apply.  Specifies that this setting does not apply ...

 This setting must be used when the condition uses only one limit.

  Open   Collapse  Value

 Specifies the upper limit.  Specifies the upper limit ...

 Note that the value for CondHigh is cast to the source buffer's data type and depth. If the source buffer is binary, the value must be equal to 0 or 1.

Return value

 When DestImageBufId is given an image buffer identifier, this function returns the parameter setting of CondLow (M_DEFAULT or the specified value). When DestImageBufId is set to M_NULL, this function returns the low threshold value (automatically calculated or specified).

Remarks

  •  This function is optimized for packed binary buffers.
    •

  •  In-place processing is supported (source equals destination), but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

   IN RANGE OUT RANGE EQUAL GREATER GREATER OR EQUAL LESS LESS OR EQUAL NOT EQUAL  DEFAULT   DEFAULT NULL


MimClip

Example | Availability | MimBinarize | MimClose
mimsegment.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a point-to-point clipping operation.
Syntax
void MimClip(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long Condition,
double CondLow,
double CondHigh,
double WriteLow,
double WriteHigh
)
Description

This function clips each image pixel that meets the specified condition. If the condition has one clipping point, each pixel that satisfies this condition is replaced with the specified WriteLow value. If it has two clipping points, they are either replaced with the WriteLow or WriteHigh value depending on the condition. Pixels that do not satisfy the condition are not affected.

Parameters
SrcImageBufId

Specifies the identifier of the image data source.

DestImageBufId

Specifies the identifier of the destination image buffer.

Condition

Specifies the clipping condition. This parameter must be set to one of the values below.

The following are conditions that use two clipping points:

Open Collapse Value Description
Open Collapse M_IN_RANGE

 Replaces pixel values in the range of CondLow and CondHigh, inclusive, with WriteLow.  Replaces pixel values in the range of CondLow and CondHigh, inclusive, with WriteLow.

  Open   Collapse  M_OUT_RANGE

 Replaces pixel values less than CondLow with WriteLow and those greater than CondHigh with WriteHigh.  Replaces pixel values less than CondLow with WriteLow and those greater than CondHigh with WriteHigh.

 The following are conditions that use one clipping point:

  Open   Collapse  Value
Description

  Open   Collapse  M_EQUAL

 Replaces pixel values equal to CondLow with WriteLow.  Replaces pixel values equal to CondLow with WriteLow.

  Open   Collapse  M_GREATER

 Replaces pixel values greater than CondLow with WriteLow.  Replaces pixel values greater than CondLow with WriteLow.

  Open   Collapse  M_GREATER_OR_EQUAL

 Replaces pixel values greater than or equal to CondLow with WriteLow.  Replaces pixel values greater than or equal to CondLow with WriteLow.

  Open   Collapse  M_LESS

 Replaces pixel values less than CondLow with WriteLow.  Replaces pixel values less than CondLow with WriteLow.

  Open   Collapse  M_LESS_OR_EQUAL

 Replaces pixel values less than or equal to CondLow with WriteLow.  Replaces pixel values less than or equal to CondLow with WriteLow.

  Open   Collapse  M_NOT_EQUAL

 Replaces pixel values not equal to CondLow with WriteLow.  Replaces pixel values not equal to CondLow with WriteLow.

 CondLow

 Specifies the lower clipping point of the selected condition.  If the condition uses only one limit, set the CondLow parameter to the required limit and set CondHigh to M_NULL.

 This parameter is cast to the source buffer's data type and interpreted accordingly.

  Open   Collapse  Value
Description

  Open   Collapse  Value

 Specifies the lower limit.  Specifies the lower limit ...

 Note, if the source buffer is binary, CondLow must be equal to 0 or 1.

 CondHigh

 Specifies the upper clipping point of the selected condition.

 This parameter is cast to the source buffer's data type and interpreted accordingly.

  Open   Collapse  Value
Description

  Open   Collapse  Value

 Specifies the upper limit.  Specifies the upper limit ...

 Note, if the source buffer is binary, CondLow and CondHigh must be equal to 0 or 1.

 WriteLow

 Specifies the values to write to the destination buffer when a pixel satisfies the specified low clipping condition.  The condition determines whether WriteLow is written. This parameter is cast to the destination buffer's data type.

  Open   Collapse  Value
Description

  Open   Collapse  Value

 Specifies the values to write when the pixel satisfies the low clipping condition.  Specifies the values to write when the pixel satisfies the low clipping condition ...

 Note, if the destination buffer is binary, WriteLow must be equal to 0 or 1.

 WriteHigh

 Specifies the values to write to the destination buffer when a pixel satisfies the specified high clipping condition.  The condition determines whether WriteHigh is written. This parameter is cast to the destination buffer's data type.

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Must be set to this value when the condition uses only one limit.  Must be set to this value when the condition uses only one limit.

  Open   Collapse  Value

 Specifies the values to write when the pixel satisfies the high clipping condition.  Specifies the values to write when the pixel satisfies the high clipping condition ...

 Note, if the destination buffer is binary, WriteHigh must be equal to 0 or 1.

Remarks

  •  This function is optimized for packed binary buffers.
    •

  •  In-place processing is supported (source equals destination), but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

   IN RANGE OUT RANGE EQUAL GREATER GREATER OR EQUAL LESS LESS OR EQUAL NOT EQUAL        NULL


MimClose

Example | Availability | MimClip | MimConnectMap
mblob.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a binary or grayscale closing-type morphological operation.
Syntax
void MimClose(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long NbIteration,
long ProcMode
)
Description

This function performs a binary or grayscale closing operation on the given source image for the specified number of iterations. A closing is a dilation followed by an erosion.

In binary mode, this function uses a 3 x 3 full rectangular structuring element; in grayscale mode, a 3 x 3 empty one.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

NbIteration

Specifies the number of times to iterate the operation.

ProcMode

Specifies the processing mode to use. This parameter can be set to the following:

Open Collapse Value Description
Open Collapse M_BINARY

 Treats non-zero pixels as ones (1) during processing. The resulting non-zero pixels will have all bits set to one.  Treats non-zero pixels as ones (1) during processing ...

  Open   Collapse  M_GRAYSCALE

 Uses the source image's gray values for processing. The resulting buffer will also contain gray values.  Uses the source image's gray values for processing ...

Remarks

  •  This function is optimized for packed binary buffers.
    •

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

    BINARY GRAYSCALE


MimConnectMap

Example | Availability | MimClose | MimConvert
There are no examples containing MimConnectMap().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a 3 by 3 binary connectivity mapping.
Syntax
void MimConnectMap(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
MIL_ID LutBufId
)
Description

This function performs a 3 x 3 binary connectivity mapping. It calculates a connectivity code for each pixel in the source image, then maps the codes through the specified LUT buffer.

Parameters
SrcImageBufId

Specifies the identifier of the source of the operation. This parameter must be given an image buffer identifier. The source pixels are treated as binary (that is, all non-zero pixels are treated as 1). Pixel connectivity codes are determined in the following order:

where ni is either 0 or 1.

Connectivity code =

Result = LUTMAP (connectivity code).

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer identifier.

LutBufId

Specifies the identifier of the LUT buffer. As each connectivity code has 9 bits, you should supply a LUT buffer with at least 512 (2 9) entries; otherwise unpredictable results can occur.

Remarks
  • This function is optimized for packed binary buffers.
  • In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).


MimConvert

See Also | Example | Availability | MimConnectMap | MimConvolve
User Guide:
Processing
Performing color conversions
mbufcolor.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a color conversion.
Syntax
void MimConvert(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long ConversionType
)
Description

This function performs a color conversion on the source image and places the result in the destination buffer.

The values generated will be normalized to the possible range of values in the destination buffer. For example, the hue values from 0 to 360° will generate the values from 0 to 255 in an 8-bit destination buffer.

Note that the values in a signed source buffer must be positive. For a floating-point destination buffer, the values generated will be normalized between 0 and 1.

See the Performing color conversions section in Chapter 19: Color.

Parameters
SrcImageBufId

Specifies the identifier of the source image buffer. Source buffer values must be positive. If specifying a floating-point buffer, the values of the buffer must be normalized between 0 and 1 before calling this function.

DestImageBufId

Specifies the identifier of the destination image buffer. If specifying a floating-point buffer, the values generated will be normalized between 0 and 1.

ConversionType

Specifies the type of conversion to perform. This parameter can be set to one of the following values.

Open Collapse Value Description
Open Collapse M_HLS_TO_RGB

 Specifies a HLS to RGB conversion. Both the source and destination image buffers must be 3-band image buffers.  Specifies a HLS to RGB conversion ...

  Open   Collapse  M_L_TO_RGB

 Specifies an L (luminance) to RGB conversion. The luminance (intensity) is repeated in each color band of the destination buffer, creating a monochromatic (gray) RGB buffer. The source buffer must be a 1-band image buffer and the destination buffer must be a 3-band image buffer.  Specifies an L (luminance) to RGB conversion ...

  Open   Collapse  M_RGB_TO_H

 Specifies an RGB to H conversion, where H represents the hue of the HLS color space. The source image must be a 3-band image buffer and the destination buffer must be a 1-band image buffer.  Specifies an RGB to H conversion, where H represents the hue of the HLS color space ...

  Open   Collapse  M_RGB_TO_HLS

 Specifies an RGB to HLS (hue, luminance (intensity), and saturation) conversion. Both the source and destination image buffers must be 3-band image buffers. The hue component (H) is stored in band 0, the luminance component (L) is stored in band 2, and the saturation component (S) is stored in band 1.  Specifies an RGB to HLS (hue, luminance (intensity), and saturation) conversion ...

  Open   Collapse  M_RGB_TO_L

 Specifies an RGB to L conversion, where L represents the luminance (intensity) of the HLS color space. The source image must be a 3-band image buffer and the destination buffer must be a 1-band image buffer.  Specifies an RGB to L conversion, where L represents the luminance (intensity) of the HLS color space ...

 Note that M_RGB_TO_L and M_RGB_TO_Y produce similar results but not identical results because they are calculated to different color spaces.

  Open   Collapse  M_RGB_TO_Y

 Specifies an RGB to Y conversion, where Y represents the luminance of the YUV color space. The source buffer must have 3 bands. The destination buffer can have 1 or 3 bands. If it has 3 bands, only the first band is overwritten.  Specifies an RGB to Y conversion, where Y represents the luminance of the YUV color space ...

 Note that M_RGB_TO_L and M_RGB_TO_Y produce similar results but not identical results because they are calculated to different color spaces.

RGB TO L RGB TO Y     HLS TO RGB L TO RGB RGB TO H RGB TO HLS RGB TO L RGB TO Y


MimConvolve

See Also | Example | Availability | MimConvert | MimCountDifference
User Guide:
Denoising
Enhancing and detecting edges
Custom spatial filters
Buffer overscan region

Reference:
MbufAlloc1d
MbufAlloc2d
MbufControlNeighborhood
MbufPut
mdigautofocus.c
mdigmultdestination.c
mheliosconcurent.c
mimconvolve.c
mimmorphic.c
mimprocessing.c
mthread.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Genesis

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Perform a general convolution operation.
Syntax
void MimConvolve(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
MIL_ID KernelBufId
)
Description

This function performs a general convolution operation on the source buffer using the specified filter, storing results in the specified destination buffer. This function supports two types of filters: Finite Impulse Response (FIR) filters and Infinite Impulse Response (IIR) filters. FIR filters operate on a finite neighborhood, while IIR filters take in account all values in an image. You can specify either a predefined or a custom FIR or IIR filter.

This function provides a number of predefined FIR. For predefined FIR filters, the overscan is set to transparent overscan pixel values, saturation is enabled for results, and the kernel's default center pixel is set as the top-left pixel of the central elements in a neighborhood. When using predefined FIR filters, you cannot change operation control settings except for the overscan.

This function provides two types of predefined IIR filters. Predefined IIR filters, M_SHEN_FILTER() and M_DERICHE_FILTER(), use a recursive implementation, and the overscan pixel values are ignored. The normalization factor is automatically set so that it is possible to use the full data range of the destination buffer without overflows, and the result is given in the number of bits of the destination buffer. When using predefined IIR filters, you cannot change operation control settings except for the smoothness value. To use an IIR filter in kernel mode, you must use a custom IIR filter.

This function also accepts a custom FIR or IIR filter with which you can customize operation control settings. To define a custom filter, you must allocate a kernel buffer using MbufAlloc1d() or MbufAlloc2d(). Note that the kernel buffer size can be constrained by the available resources.

To define a custom FIR filter, you must load the kernel buffer with values, using MbufPut(). To define a custom IIR filter, use MbufControlNeighborhood() with M_FILTER_TYPE, M_FILTER_OPERATION, and M_FILTER_MODE; the kernel values are automatically calculated based on these settings.

When using custom FIR or IIR filters, you can change default operation control settings using MbufControlNeighborhood().

For predefined and custom FIR filters, when using 32-bit integer buffers and saturation is disabled, the accumulator buffer is a 32-bit integer buffer (long); whereas, when saturation is enabled, the accumulator buffer is a 64-bit floating point internal buffer (double). For predefined and custom IIR filters, when using 32-bit floating point source buffers, operations are performed using floating precision regardless of the destination buffer; whereas, when using non 32-bit floating point source buffers, operations are performed using fixed-point precisio n.

If the source and destination are multi-band buffers, the same filter is applied to every band of the source buffer.

[Matrox Genesis]

All 16-bit buffers are processed as signed buffers for FIR filters.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer identifier.

Note that for a FIR filter or custom IIR filter which uses a kernel mode implementation, the size of the source and destination must be greater or equal to the size of the kernel.

KernelBufId

Specifies the filter to use. Set this parameter to a predefined filter or the identifier of the kernel buffer which defines the custom filter.

To specify a predefined FIR filter, set this parameter to one of the following:

Open Collapse Value Description
Open Collapse M_EDGE_DETECT

 Computes the gradient of the image using the following operation, which is based on a Sobel filter.  Computes the gradient of the image using the following operation, which is based on a Sobel filter ...

  Open   Collapse  M_EDGE_DETECT2

 Computes the gradient of the image using the following operation, which is based on a Prewitt filter.  Computes the gradient of the image using the following operation, which is based on a Prewitt filter ...

  Open   Collapse  M_HORIZ_EDGE

 Computes the absolute value of the horizontal derivative of the image using the following horizontal edge detection filter.  Computes the absolute value of the horizontal derivative of the image using the following horizontal edge detection filter ...

  Open   Collapse  M_LAPLACIAN_EDGE

 Computes the Laplacian values of the image using the following 4-connected Laplacian edge detection filter.  Computes the Laplacian values of the image using the following 4-connected Laplacian edge detection filter ...

  Open   Collapse  M_LAPLACIAN_EDGE2

 Computes the Laplacian values of the image using the following 8-connected Laplcian edge detection filter.  Computes the Laplacian values of the image using the following 8-connected Laplcian edge detection filter ...

  Open   Collapse  M_SHARPEN

 Performs a sharpening operation on the image using the following 8-connected Laplacian filter combined with the original image.  Performs a sharpening operation on the image using the following 8-connected Laplacian filter combined with the original image ...

 Note that this operation results in a stronger sharpening effect than M_SHARPEN2.

  Open   Collapse  M_SHARPEN2

 Performs a sharpening operation on the image using the following 4-connected Laplacian filter combined with the original image.  Performs a sharpening operation on the image using the following 4-connected Laplacian filter combined with the original image ...

 Note that this operation results in a sharpening effect that is not as strong as the one achieved with M_SHARPEN.

  Open   Collapse  M_SMOOTH

 Performs a smoothing operation on the image using the following smoothing filter.  Performs a smoothing operation on the image using the following smoothing filter ...

  Open   Collapse  M_VERT_EDGE

 Computes the absolute value of the vertical derivative of the image using the following vertical edge detection filter.  Computes the absolute value of the vertical derivative of the image using the following vertical edge detection filter ...

      [Combination constants]

 To temporarily disable overscanning, the value below can be added to a predefined FIR filter.

  Open   Collapse  Value
Description

  Open   Collapse  M_OVERSCAN_DISABLE

 Disables overscanning temporarily. You should disable overscanning to accelerate the convolution for applications in which the overscan data is not important in the resulting buffer.  Disables overscanning temporarily ...

 To specify a predefined IIR filter, set this parameter to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DERICHE_FILTER(
MIL_ID FilterOperation,

long FilterSmoothness

          )

 Specifies a Canny-Deriche Infinite Support Exponential filter. This is an exponential weighting function, of the general form:  Specifies a Canny-Deriche Infinite Support Exponential filter ...

 For the Canny-Deriche filter, the neighborhoods' influence decreases much slower as the distance from the central pixel increases, compared to the Shen-Castan filter (see M_SHEN_FILTER() macro).

 Possible values for the OperationType and SmoothFactor parameters of M_DERICHE_FILTER() macro are described below.

Parameters

FilterOperation

 This parameter specifies the type of operation to perform. You can set this parameter to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default filter operation. The default is M_SMOOTH.  Specifies the default filter operation ...

  Open   Collapse  M_EDGE_DETECT

 Computes the gradient of the image using the Canny-Deriche filter.  Computes the gradient of the image using the Canny-Deriche filter ...

  Open   Collapse  M_EDGE_DETECT_SQR

 Computes the square of the gradient of the image using the Canny-Deriche filter.  Computes the square of the gradient of the image using the Canny-Deriche filter ...

  Open   Collapse  M_FIRST_DERIVATIVE_X

 Computes the first derivative of the image, with respect to X, using the Canny-Deriche filter.  Computes the first derivative of the image, with respect to X, using the Canny-Deriche filter ...

  Open   Collapse  M_FIRST_DERIVATIVE_Y

 Computes the first derivative of the image, with respect to Y, using the Canny-Deriche filter.  Computes the first derivative of the image, with respect to Y, using the Canny-Deriche filter ...

  Open   Collapse  M_HORIZ_EDGE

 Computes the absolute value of the horizontal derivative of the image using the Canny-Deriche filter.  Computes the absolute value of the horizontal derivative of the image using the Canny-Deriche filter ...

  Open   Collapse  M_LAPLACIAN_EDGE

 Computes the Laplacian values of the image using the Canny-Deriche filter.  Computes the Laplacian values of the image using the Canny-Deriche filter ...

  Open   Collapse  M_SECOND_DERIVATIVE_X

 Computes the second derivative of the image, with respect to X, using the Canny-Deriche filter.  Computes the second derivative of the image, with respect to X, using the Canny-Deriche filter ...

  Open   Collapse  M_SECOND_DERIVATIVE_XY

 Computes the second derivative of the image, with respect to X and Y, using the Canny-Deriche filter.  Computes the second derivative of the image, with respect to X and Y, using the Canny-Deriche filter ...

  Open   Collapse  M_SECOND_DERIVATIVE_Y

 Computes the second derivative of the image, with respect to Y, using the Canny-Deriche filter.  Computes the second derivative of the image, with respect to Y, using the Canny-Deriche filter ...

  Open   Collapse  M_SHARPEN

 Performs a sharpening operation on the image using the Canny-Deriche filter.  Performs a sharpening operation on the image using the Canny-Deriche filter ...

  Open   Collapse  M_SMOOTH

 Performs a smoothing operation on the image using the Canny-Deriche filter.  Performs a smoothing operation on the image using the Canny-Deriche filter ...

  Open   Collapse  M_VERT_EDGE

 Computes the absolute value of the vertical derivative of the image using the Canny-Deriche filter.  Computes the absolute value of the vertical derivative of the image using the Canny-Deriche filter ...

FilterSmoothness

 This parameter specifies the degree of smoothness (strength of the denoising) applied by the convolution operation. You can set this parameter to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default value. The default value is 50.0.  Specifies the default value ...

  Open   Collapse  0.0 to 100.0

 Specifies the smoothness value.  Specifies the smoothness value ...

 A value of 100.0 results in a strong noise reduction effect, while a value of 0.0 has almost no noise reduction effect.

  Open   Collapse  M_SHEN_FILTER(
MIL_ID FilterOperation,

long FilterSmoothness

          )

 Specifies a Shen-Castan Infinite Support Exponential filter. This is an exponential weighting function, of the general form:  Specifies a Shen-Castan Infinite Support Exponential filter ...

 For the Shen-Castan filter, the neighborhoods' influence decreases much faster as the distance from the central pixel increases, compared to the Canny-Deriche filter (see M_DERICHE_FILTER() macro).

 Possible values for the OperationType and SmoothFactor parameters of M_SHEN_FILTER() macro are described below.

Parameters

FilterOperation

 This parameter specifies the type of operation to perform. You can set this parameter to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default filter operation. The default is M_SMOOTH.  Specifies the default filter operation ...

  Open   Collapse  M_EDGE_DETECT

 Computes the gradient of the image using the Shen-Castan filter.  Computes the gradient of the image using the Shen-Castan filter ...

  Open   Collapse  M_EDGE_DETECT_SQR

 Computes the square of the gradient of the image using the Shen-Castan filter.  Computes the square of the gradient of the image using the Shen-Castan filter ...

  Open   Collapse  M_FIRST_DERIVATIVE_X

 Computes the first derivative of the image, with respect to X, using the Shen-Castan filter.  Computes the first derivative of the image, with respect to X, using the Shen-Castan filter ...

  Open   Collapse  M_FIRST_DERIVATIVE_Y

 Computes the first derivative of the image, with respect to Y, using the Shen-Castan filter.  Computes the first derivative of the image, with respect to Y, using the Shen-Castan filter ...

  Open   Collapse  M_HORIZ_EDGE

 Computes the absolute value of the horizontal derivative of the image using the Shen-Castan filter.  Computes the absolute value of the horizontal derivative of the image using the Shen-Castan filter ...

  Open   Collapse  M_LAPLACIAN_EDGE

 Computes the Laplacian values of the image using the Shen-Castan filter.  Computes the Laplacian values of the image using the Shen-Castan filter ...

  Open   Collapse  M_SECOND_DERIVATIVE_X

 Computes the second derivative of the image, with respect to X, using the Shen-Castan filter.  Computes the second derivative of the image, with respect to X, using the Shen-Castan filter ...

  Open   Collapse  M_SECOND_DERIVATIVE_XY

 Computes the second derivative of the image, with respect to X and Y, using the Shen-Castan filter.  Computes the second derivative of the image, with respect to X and Y, using the Shen-Castan filter ...

  Open   Collapse  M_SECOND_DERIVATIVE_Y

 Computes the second derivative of the image, with respect to Y, using the Shen-Castan filter.  Computes the second derivative of the image, with respect to Y, using the Shen-Castan filter ...

  Open   Collapse  M_SHARPEN

 Performs a sharpening operation on the image using the Shen-Castan filter.  Performs a sharpening operation on the image using the Shen-Castan filter ...

  Open   Collapse  M_SMOOTH

 Performs a smoothing operation on the image using the Shen-Castan filter.  Performs a smoothing operation on the image using the Shen-Castan filter ...

  Open   Collapse  M_VERT_EDGE

 Computes the absolute value of the vertical derivative of the image using the Shen-Castan filter.  Computes the absolute value of the vertical derivative of the image using the Shen-Castan filter ...

FilterSmoothness

 This parameter specifies the degree of smoothness (strength of the denoising) applied by the convolution operation. You can set this parameter to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default value. The default value is 50.0.  Specifies the default value ...

  Open   Collapse  0.0 to 100.0

 Specifies the smoothness value.  Specifies the smoothness value ...

 A value of 100.0 results in a strong noise reduction effect, while a value of 0.0 has almost no noise reduction effect.

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

FILTER TYPE FILTER OPERATION FILTER MODE SHARPEN2 SHARPEN SMOOTH SMOOTH    EDGE DETECT EDGE DETECT2 HORIZ EDGE LAPLACIAN EDGE LAPLACIAN EDGE2 SHARPEN SHARPEN2 SMOOTH VERT EDGE OVERSCAN DISABLE  DEFAULT SMOOTH HORIZ EDGE VERT EDGE EDGE DETECT EDGE DETECT SQR LAPLACIAN EDGE SHARPEN FIRST DERIVATIVE X FIRST DERIVATIVE Y SECOND DERIVATIVE X SECOND DERIVATIVE Y SECOND DERIVATIVE XY  DEFAULT   DEFAULT SMOOTH HORIZ EDGE VERT EDGE EDGE DETECT EDGE DETECT SQR LAPLACIAN EDGE SHARPEN FIRST DERIVATIVE X FIRST DERIVATIVE Y SECOND DERIVATIVE X SECOND DERIVATIVE Y SECOND DERIVATIVE XY  DEFAULT


MimCountDifference

See Also | Example | Availability | MimConvolve | MimDilate
User Guide:
Image statistics

Reference:
MimAllocResult
MimGetResult
MimGetResult1d
There are no examples containing MimCountDifference().
Not available in MIL-Lite

Available in MIL
Synopsis
Count the number of pixels that differ in each image.
Syntax
void MimCountDifference(
MIL_ID Src1ImageBufId,
MIL_ID Src2ImageBufId,
MIL_ID ImResultId
)
Description

This function finds the number of differences between the two specified source buffers and stores the resulting number in the specified result buffer.

You can read the number of differences from the result buffer, using MimGetResult1d() or MimGetResult(), specifying M_VALUE as the result type.

Parameters
Src1ImageBufId

Specifies the identifier of the first image data source. This parameter can be given an image buffer identifier. The image buffer must be one-band.

Src2ImageBufId

Specifies the identifier of the second image data source. This parameter can only be given an image buffer identifier. The image buffer must be one-band.

ImResultId

Specifies the identifier of the buffer in which to store the differences. This parameter must be given the identifier of an image processing result buffer that was allocated with MimAllocResult() and has an M_COUNT_LIST type. The buffer needs only one entry.

Remark
  • This function is optimized for packed binary buffers.
VALUE COUNT LIST


MimDilate

Example | Availability | MimCountDifference | MimDistance
mimperimeter.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a binary or grayscale dilation-type morphological operation.
Syntax
void MimDilate(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long NbIteration,
long ProcMode
)
Description

This function performs a binary or grayscale dilation on the given source image for the specified number of iterations.

This function is optimized for packed binary buffers.

In binary mode, this function uses a 3 x 3 full rectangular structuring element; in grayscale mode, a 3 x 3 empty one.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

NbIteration

Specifies the number of times to iterate the operation.

ProcMode

Specifies the processing mode to use. This parameter can be set to the following:

Open Collapse Value Description
Open Collapse M_BINARY

 Treats non-zero pixels as ones (1) during processing. The resulting non-zero pixels will have all bits set to one.  Treats non-zero pixels as ones (1) during processing ...

  Open   Collapse  M_GRAYSCALE

 Uses the source image's gray values for processing. The resulting buffer will also contain gray values.  Uses the source image's gray values for processing ...

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

    BINARY GRAYSCALE


MimDistance

Example | Availability | MimDilate | MimEdgeDetect
mimsegment.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a distance transformation.
Syntax
void MimDistance(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long DistanceTransform
)
Description

This function determines the shortest distance between each blob pixel and the blob's background, and assigns this distance to the pixel. It produces a type of contour mapping of a blob.

This function is optimized for packed binary buffers.

Parameters
SrcImageBufId

Specifies the identifier of the source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

DistanceTransform

Specifies the way in which the minimum distance from blob pixel to background pixel is calculated. This parameter approximates the true distance from blob pixel to background pixel using a 3 x 3 distance matrix and can be set to one of the following:

Open Collapse Value Description
Open Collapse M_CHAMFER_3_4

 Determines the minimum distance using horizontal, vertical or diagonal pixel steps. Horizontal and vertical steps are counted as 3; diagonal steps are counted as 4. This transform provides the best approximation to Euclidean distance. However, when using this transform, the destination buffer must meet certain requirements. The requirements are detailed below this table.  Determines the minimum distance using horizontal, vertical or diagonal pixel steps ...

 3x3 Distance Matrix:

  Open   Collapse  M_CHESSBOARD

 Determines the minimum distance using horizontal, vertical, or diagonal pixel steps. All steps count as 1.  Determines the minimum distance using horizontal, vertical, or diagonal pixel steps ...

 3x3 Distance Matrix:

  Open   Collapse  M_CITY_BLOCK

 Determines the minimum distance using only horizontal or vertical pixel steps. Horizontal and vertical steps count as 1.  Determines the minimum distance using only horizontal or vertical pixel steps ...

 3x3 Distance Matrix:

 The M_CHAMFER_3_4 transform requires that the destination buffer be deep enough to hold a number at least three times the maximum distance from a blob pixel to its edge. For example, an 8-bit buffer (255 max) can be used for a maximum distance of 85 pixels and a 16-bit buffer (65535 max) for a maximum distance of 21845 pixels.

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

CHAMFER 3 4    CHAMFER 3 4 CHESSBOARD CITY BLOCK


MimEdgeDetect

Example | Availability | MimDistance | MimErode
mimsegment.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a specific edge detection operation and produce a gradient intensity and/or gradient angle image.
Syntax
void MimEdgeDetect (
MIL_ID SrcImageBufId,
MIL_ID DestIntensityImageBufId,
MIL_ID DestAngleImageBufId,
MIL_ID KernelId,
long ControlFlag,
long Threshold
)
Description

This function performs an edge detection operation on the specified source image, using the specified filter. It produces a gradient intensity image and/or a gradient angle image in the specified image buffer(s). If one of the destination images is not required, specify M_NULL as its image buffer identifier.

For an unsigned destination buffer, the angle is returned from 0° to 360° (counter-clockwise) and mapped to the entire range of the destination buffer. For example, for an unsigned 8-bit buffer, the angles of 0°, 90°, 180°, and 270° map to 0, 64, 128, and 192, respectively. For a signed destination buffer, mapping is done in both the positive and negative range of the buffer and represents angle values from -180° to 180°. For example, for a signed 8-bit buffer, the angles of -180°, -90°, 0°, and 90° map to -128, -64, 0 and 64, respectively.

This function can also be performed on a floating point buffer. However, the results are not mapped and are returned in the range of 0° to 360°. The degree of precision is equal to the precision of the floating point buffer for regular computation or to +/- 0.4° for fast computation. The value for undefined results is the maximum positive value of the floating-point buffer.

For a gradient value lower than the threshold value, the angle is not computed (not considered a significant edge) and the resulting angle pixel is undetermined.

You can perform the operation using a combination of fast and full gradient and angle computations.

Type of computation | Description of computation
Full gradient computation | Gradient = sqrt(GradientX*GradientX + GradientY*GradientY)
Fast gradient computation | Gradient = ( abs(GradientX) + abs(GradientY) )/2
Full angle computation | Angle = arctan(GradientY/GradientX)

The fast angle approximation is based on the same equation as the full angle computation, however the value is determined from a LUT mapping. Note that the fast angle approximation introduces a maximum error of +/- 0.4°.

Parameters
SrcImageBufId

Specifies the identifier of the source of the operation. This parameter must be given an image buffer identifier.

DestIntensityImageBufId

Specifies the identifier of the destination buffer for the resulting gradient intensity image. This parameter must be given an image buffer identifier or M_NULL. Saturation is performed on this buffer.

DestAngleImageBufId

Specifies the identifier of the destination buffer for the resulting gradient angle image. This parameter must be given an image buffer identifier or M_NULL.

KernelId

Specifies the filter to use. This parameter must be set to the value below.

Open Collapse Value Description
Open Collapse M_SOBEL

 Sets the parameter to the predefined 3x3 edge detection filter. This filter is as follows:  Sets the parameter to the predefined 3x3 edge detection filter ...

 X gradient,

 Y gradient,

      [Combination constants]

 The value below can be added to M_SOBEL.

  Open   Collapse  Value
Description

  Open   Collapse  M_OVERSCAN_DISABLE

 Disables overscan processing.  Disables overscan processing.

 ControlFlag

 Specifies how to perform the operations.

 The ControlFlag parameter can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_FAST_EDGE_DETECT.  Same as M_FAST_EDGE_DETECT.

  Open   Collapse  M_FAST_ANGLE + M_REGULAR_GRADIENT

 Specifies a full gradient computation and a fast angle approximation.  Specifies a full gradient computation and a fast angle approximation.

  Open   Collapse  M_FAST_EDGE_DETECT

 Specifies a fast gradient computation and a fast angle approximation. The gradient is computed as an approximation, using the average of the absolute value of the two directional components (X and Y).  Specifies a fast gradient computation and a fast angle approximation ...

  Open   Collapse  M_REGULAR_ANGLE + M_FAST_GRADIENT

 Specifies a fast gradient computation and a full angle computation.  Specifies a fast gradient computation and a full angle computation.

  Open   Collapse  M_REGULAR_EDGE_DETECT

 Specifies a full gradient computation and a full angle computation. The gradient is computed as the square root of the sum of the square of each directional component (X and Y). This method of calculation is slower but more precise.  Specifies a full gradient computation and a full angle computation. The gradient is computed as the square root of the sum of the square of each directional component (X and Y) ...

 Threshold

 Specifies the threshold value for calculating gradient intensity.  To perform the full operation, set this parameter to zero or M_NULL.

SOBEL FAST EDGE DETECT     SOBEL OVERSCAN DISABLE  DEFAULT FAST EDGE DETECT FAST ANGLE  M REGULAR GRADIENT
                 REGULAR ANGLE  M FAST GRADIENT
                 REGULAR EDGE DETECT


MimErode

Example | Availability | MimEdgeDetect | MimFindExtreme
There are no examples containing MimErode().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a binary or grayscale erosion-type morphological operation.
Syntax
void MimErode(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long NbIteration,
long ProcMode
)
Description

This function performs a binary or grayscale erosion on the given source image for the specified number of iterations.

In binary mode, this function uses a 3 x 3 full rectangular structuring element; in grayscale mode, a 3 x 3 empty one.

The overscan pixels are automatically set to the highest possible buffer value, which will produce the most accurate possible results for the image border pixels.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

NbIteration

Specifies the number of times to iterate the operation.

ProcMode

Specifies the processing mode to use. This parameter can be set to the following:

Open Collapse Value Description
Open Collapse M_BINARY

 Treats non-zero pixels as ones (1) during processing. The resulting non-zero pixels will have all bits set to one.  Treats non-zero pixels as ones (1) during processing ...

  Open   Collapse  M_GRAYSCALE

 Uses the source image's gray values for processing. The resulting buffer will also contain gray values.  Uses the source image's gray values for processing ...

Remarks

  •  This function is optimized for packed binary buffers.
    •

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

    BINARY GRAYSCALE


MimFindExtreme

See Also | Example | Availability | MimErode | MimFlip
User Guide:
Image statistics

Reference:
MimAllocResult
MimGetResult
MimGetResult1d
dtkremap.c
mdispwindowleveling.c
mimprocessing.c
Not available in MIL-Lite

Available in MIL
Synopsis
Find an image buffer's extremes (minimum and/or maximum pixel values).
Syntax
void MimFindExtreme(
MIL_ID SrcImageBufId,
MIL_ID ExtremeImResultId,
long ExtremeType
)
Description

This function finds the maximum and/or minimum value of the specified source image and stores results in the specified extreme result buffer.

You can read the minimum/or maximum from the result buffer, using MimGetResult1d() or MimGetResult(), specifying M_VALUE as the result type.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier. The buffer must be one-band.

ExtremeImResultId

Specifies the identifier of the buffer in which to store the extreme values. This parameter must be given the identifier of an image processing result buffer that was allocated with MimAllocResult() and that has an M_EXTREME_LIST type. If just the maximum or minimum is calculated, only one entry is needed. If both the minimum and maximum are calculated, the result buffer must have two entries. The minimum value is stored in the first entry and the maximum value is stored in the second.

ExtremeType

Specifies whether to find the minimum value, maximum value, or both. This parameter can be set to one of the values in the table below.

Open Collapse Value Description
Open Collapse M_MAX_ABS_VALUE

 Finds the maximum value, as an absolute value.  Finds the maximum value, as an absolute value.

  Open   Collapse  M_MAX_VALUE

 Finds the maximum value.  Finds the maximum value.

  Open   Collapse  M_MIN_ABS_VALUE

 Finds the minimum value, as an absolute value.  Finds the minimum value, as an absolute value.

  Open   Collapse  M_MIN_ABS_VALUE + M_MAX_ABS_VALUE

 Finds the minimum and maximum values, as absolute values.  Finds the minimum and maximum values, as absolute values.

  Open   Collapse  M_MIN_VALUE

 Finds the minimum value.  Finds the minimum value.

  Open   Collapse  M_MIN_VALUE + M_MAX_VALUE

 Finds the minimum and maximum values.  Finds the minimum and maximum values.

VALUE EXTREME LIST    MAX ABS VALUE MAX VALUE MIN ABS VALUE MIN ABS VALUE  M MAX ABS VALUE
                 MIN VALUE MIN VALUE  M MAX VALUE


MimFlip

Example | Availability | MimFindExtreme | MimFree
There are no examples containing MimFlip().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a horizontal or vertical image-flipping operation.
Syntax
void MimFlip(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long Operation,
long OpFlag
)
Description

This function flips the source image to the destination image according to the specified operation.

Parameters
SrcImageBufId

Specifies the identifier of the source image buffer.

DestImageBufId

Specifies the identifier of the destination image buffer.

Operation

Specifies the operation to perform. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_FLIP_HORIZONTAL

 Flips the image in a horizontal direction (left to right, along a vertical axis).  Flips the image in a horizontal direction (left to right, along a vertical axis).

  Open   Collapse  M_FLIP_VERTICAL

 Flips the image in a vertical direction (top to bottom, along a horizontal axis).  Flips the image in a vertical direction (top to bottom, along a horizontal axis).

 OpFlag

 Must be set to M_DEFAULT.

   FLIP HORIZONTAL FLIP VERTICAL


MimFree

See Also | Example | Availability | MimFlip | MimGetResult1d
User Guide:
Image statistics

Reference:
MimAllocResult
dtkremap.c
mdispwindowleveling.c
mimhistogram.c
mimprocessing.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free an image processing result buffer.
Syntax
void MimFree(
MIL_ID ImResultId
)
Description

This function deallocates a result buffer previously allocated with MimAllocResult().

Parameter
ImResultId

Specifies the identifier of the image processing result buffer to be released.


MimGetResult1d

See Also | Example | Availability | MimFree | MimGetResult
Reference:
McalControl
MimAllocResult
There are no examples containing MimGetResult1d().
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified number of result entries from an image processing result buffer.
Syntax
void MimGetResult1d(
MIL_ID ImResultId,
long OffEntry,
long NbEntries,
long ResultType,
void *UserArrayPtr
)
Description

This function retrieves the specified number of result entries from the specified result buffer and stores them in the specified one-dimensional destination user array.

Note that if your target image has been associated with a calibration object, positional results are by default returned in real-world units. To have results returned in pixel units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to M_PIXEL. If the target image is not calibrated, positional results are returned in pixels, relative to the top-left pixel in the target image.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set UserArrayPtr to M_NULL. When this parameter is set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when you pass the parameter an array instead. You must ensure that the array is sufficiently large to hold the current and previously queued results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
ImResultId

Specifies the identifier of the image processing result buffer from which to get results.

OffEntry

Specifies the offset of the first result to read. The given value must be within the number of allocated result entries.

NbEntries

Specifies the number of result entries to get, starting from the entry specified by the OffEntry parameter.

ResultType

Specifies the type of result(s) to retrieve. This parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the UserArrayPtr parameter the address of an array of type double (with a size of the same number of elements as the number of entries to obtain) .

Open Collapse Value Description
Open Collapse M_MAX

Retrieves the maximum pixel value from an M_STAT_LIST result buffer. Retrieves the maximum pixel value from an M_STAT_LIST result buffer.

Open Collapse M_MAX_ABS

Retrieves the maximum absolute pixel value from an M_STAT_LIST result buffer. Retrieves the maximum absolute pixel value from an M_STAT_LIST result buffer.

Open Collapse M_MEAN

Retrieves the mean pixel value from an M_STAT_LIST result buffer. Retrieves the mean pixel value from an M_STAT_LIST result buffer.

Open Collapse M_MIN

Retrieves the minimum pixel value from an M_STAT_LIST result buffer. Retrieves the minimum pixel value from an M_STAT_LIST result buffer.

Open Collapse M_MIN_ABS

Retrieves the minimum absolute pixel value from an M_STAT_LIST result buffer. Retrieves the minimum absolute pixel value from an M_STAT_LIST result buffer.

Open Collapse M_NB_EVENT

Retrieves the number of events from an M_EVENT_LIST result buffer. Retrieves the number of events from an M_EVENT_LIST result buffer ...

UserArrayPtr info

Data type:

  • array of type long
    Array size: only one element is required.
  • array of type float
    Array size: only one element is required.
    note: use if M_FLOAT was added to the ResultType parameter of MimAllocResult() during result buffer allocation.
Open Collapse M_NUMBER

Retrieves the number of pixels from an M_STAT_LIST result buffer. Retrieves the number of pixels from an M_STAT_LIST result buffer.

Open Collapse M_POSITION_X

Retrieves the image X-coordinate of each event from an M_EVENT_LIST result buffer. Retrieves the image X-coordinate of each event from anM_EVENT_LIST result buffer ...

UserArrayPtr info

Data type:

  • array of type long
    Array size: the same number of elements as number of entries to obtain.
  • array of type float
    Array size: the same number of elements as number of entries to obtain.
    note: use if M_FLOAT was added to the ResultType parameter of MimAllocResult() during result buffer allocation.
Open Collapse M_POSITION_Y

Retrieves the image Y-coordinate of each event from an M_EVENT_LIST result buffer. Retrieves the image Y-coordinate of each event from anM_EVENT_LIST result buffer ...

UserArrayPtr info

Data type:

  • array of type long
    Array size: the same number of elements as number of entries to obtain.
  • array of type float
    Array size: the same number of elements as number of entries to obtain.
    note: use if M_FLOAT was added to the ResultType parameter of MimAllocResult() during result buffer allocation.
Open Collapse M_STANDARD_DEVIATION

Retrieves the pixel standard deviation value from an M_STAT_LIST result buffer. Retrieves the pixel standard deviation value from an M_STAT_LIST result buffer.

Open Collapse M_SUM

Retrieves the sum of the pixel values from an M_STAT_LIST result buffer. Retrieves the sum of the pixel values from an M_STAT_LIST result buffer.

Open Collapse M_SUM_ABS

Retrieves the sum of the absolute pixel values from an M_STAT_LIST result buffer. Retrieves the sum of the absolute pixel values from an M_STAT_LIST result buffer.

Open Collapse M_SUM_SQUARED

Retrieves the sum of the squared pixel values from an M_STAT_LIST result buffer. Retrieves the sum of the squared pixel values from an M_STAT_LIST result buffer.

Open Collapse M_VALUE

Retrieves values from an M_HIST_LIST, M_PROJ_LIST, M_EXTREME_LIST, M_EVENT_LIST, M_COUNT_LIST, or M_STAT_LIST result buffer. Retrieves values from an M_HIST_LIST, M_PROJ_LIST, M_EXTREME_LIST, M_EVENT_LIST, M_COUNT_LIST, or M_STAT_LIST result buffer ...

If an M_EXTREME_LIST type result buffer contains both the minimum and maximum value of an image, the minimum is written first, followed by the maximum.

UserArrayPtr info

Data type:

  • array of type long
    Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
  • array of type float
    Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
    note: use when retrieving results from a M_PROJ_LIST, M_EXTREME_LIST, or M_EVENT_LIST result buffer if M_FLOAT was added to the ResultType parameter of MimAllocResult() during result buffer allocation.

[Combination constants]

The values below can be added to the ResultType parameter to cast the requested results to a required data type. For example M_MAX + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_DOUBLE | Casts the requested results to a double. Casts the requested results to a double ...
 |  | UserArrayPtr info Data type: array of type double Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
Open Collapse M_TYPE_FLOAT | Casts the requested results to a float. Casts the requested results to a float ...
 |  | UserArrayPtr info Data type: array of type float Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
Open Collapse M_TYPE_LONG | Casts the requested results to a long. Casts the requested results to a long ...
 |  | UserArrayPtr info Data type: array of type long Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type double
  • array of type float
  • array of type long

Specifies the address of the one-dimensional array in which to write the results read from the MIL result buffer.

You can set this parameter to M_NULL to put the result request on the local queue of the result buffer.

OUTPUT COORDINATE SYSTEM PIXEL STAT LIST STAT LIST STAT LIST STAT LIST STAT LIST EVENT LIST STAT LIST EVENT LIST EVENT LIST STAT LIST STAT LIST STAT LIST STAT LIST HIST LIST PROJ LIST EXTREME LIST EVENT LIST COUNT LIST STAT LIST EXTREME LIST PROJ LIST EXTREME LIST EVENT LIST MAX MAX ABS MEAN MIN MIN ABS NB EVENT NUMBER POSITION X POSITION Y STANDARD DEVIATION SUM SUM ABS SUM SQUARED VALUE TYPE DOUBLE TYPE FLOAT TYPE LONG


MimGetResult

See Also | Example | Availability | MimGetResult1d | MimHistogram
User Guide:
Image statistics

Reference:
McalControl
MimAllocResult
MimCountDifference
MimFindExtreme
MimHistogram
MimLocateEvent
MimProject
MimStat
dtkremap.c
mdispwindowleveling.c
mimhistogram.c
mimprocessing.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified type of result(s) from an image processing result buffer.
Syntax
void MimGetResult(
MIL_ID ImResultId,
long ResultType,
void *UserArrayPtr
)
Description

This function retrieves all the results of the specified type from the specified result buffer and stores them in the specified one-dimensional destination user array. Results are only available after calling MimHistogram(), MimFindExtreme(), MimLocateEvent(), MimCountDifference(), MimProject(), or MimStat().

Note that if your target image has been associated with a calibration object, positional results are by default returned in real-world units. To have results returned in pixel units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to M_PIXEL. If the target image is not calibrated, positional results are returned in pixels, relative to the top-left pixel in the target image.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set UserArrayPtr to M_NULL. When this parameter is set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when you pass the parameter an array instead. You must ensure that the array is sufficiently large to hold the current and previously queued results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
ImResultId

Specifies the identifier of the image processing result buffer from which to retrieve results.

ResultType

Specifies the type of result(s) to retrieve. This parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the UserArrayPtr parameter the address of an array of type double (with a size of the same number of elements as the number of entries to obtain (MimAllocResult()) .

Open Collapse Value Description
Open Collapse M_MAX

Retrieves the maximum pixel value from an M_STAT_LIST result buffer. Retrieves the maximum pixel value from an M_STAT_LIST result buffer.

Open Collapse M_MAX_ABS

Retrieves the maximum absolute pixel value from an M_STAT_LIST result buffer. Retrieves the maximum absolute pixel value from an M_STAT_LIST result buffer.

Open Collapse M_MEAN

Retrieves the mean pixel value from an M_STAT_LIST result buffer. Retrieves the mean pixel value from an M_STAT_LIST result buffer.

Open Collapse M_MIN

Retrieves the minimum pixel value from an M_STAT_LIST result buffer. Retrieves the minimum pixel value from an M_STAT_LIST result buffer.

Open Collapse M_MIN_ABS

Retrieves the minimum absolute pixel value from an M_STAT_LIST result buffer. Retrieves the minimum absolute pixel value from an M_STAT_LIST result buffer.

Open Collapse M_NB_EVENT

Retrieves the number of events from an M_EVENT_LIST result buffer. Retrieves the number of events from an M_EVENT_LIST result buffer ...

UserArrayPtr info

Data type:

  • array of type long
    Array size: only one element is required.
  • array of type float
    Array size: only one element is required.
    note: use if M_FLOAT was added to the ResultType parameter of MimAllocResult() during result buffer allocation.
Open Collapse M_NUMBER

Retrieves the number of pixels from an M_STAT_LIST result buffer. Retrieves the number of pixels from an M_STAT_LIST result buffer.

Open Collapse M_POSITION_X

Retrieves the image X-coordinate of each event from an M_EVENT_LIST result buffer. Retrieves the image X-coordinate of each event from anM_EVENT_LIST result buffer ...

UserArrayPtr info

Data type:

  • array of type long
    Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
  • array of type float
    Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
    note: use if M_FLOAT was added to the ResultType parameter of MimAllocResult() during result buffer allocation.
Open Collapse M_POSITION_Y

Retrieves the image Y-coordinate of each event from an M_EVENT_LIST result buffer. Retrieves the image Y-coordinate of each event from anM_EVENT_LIST result buffer ...

UserArrayPtr info

Data type:

  • array of type long
    Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
  • array of type float
    Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
    note: use if M_FLOAT was added to the ResultType parameter of MimAllocResult() during result buffer allocation.
Open Collapse M_STANDARD_DEVIATION

Retrieves the pixel standard deviation value from an M_STAT_LIST result buffer. Retrieves the pixel standard deviation value from an M_STAT_LIST result buffer.

Open Collapse M_SUM

Retrieves the sum of the pixel values from an M_STAT_LIST result buffer. Retrieves the sum of the pixel values from an M_STAT_LIST result buffer.

Open Collapse M_SUM_ABS

Retrieves the sum of the absolute pixel values from an M_STAT_LIST result buffer. Retrieves the sum of the absolute pixel values from an M_STAT_LIST result buffer.

Open Collapse M_SUM_SQUARED

Retrieves the sum of the squared pixel values from an M_STAT_LIST result buffer. Retrieves the sum of the squared pixel values from an M_STAT_LIST result buffer.

Open Collapse M_VALUE

Retrieves values from an M_HIST_LIST, M_PROJ_LIST, M_EXTREME_LIST, M_EVENT_LIST, M_STAT_LIST, or M_COUNT_LIST result buffer. Retrieves values from an M_HIST_LIST, M_PROJ_LIST, M_EXTREME_LIST, M_EVENT_LIST, M_STAT_LIST, or M_COUNT_LIST result buffer ...

If an M_EXTREME_LIST type result buffer contains both the minimum and maximum value of an image, the minimum is written first, followed by the maximum.

UserArrayPtr info

Data type:

  • array of type long
    Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
  • array of type float
    Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
    note: use when retrieving results from a M_PROJ_LIST, M_EXTREME_LIST, or M_EVENT_LIST result buffer if M_FLOAT was added to the ResultType parameter of MimAllocResult() during result buffer allocation.

[Combination constants]

The values below can be added to the ResultType parameter to cast the requested results to a required data type. For example M_MAX + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_DOUBLE | Casts the requested results to a double. Casts the requested results to a double ...
 |  | UserArrayPtr info Data type: array of type double Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
Open Collapse M_TYPE_FLOAT | Casts the requested results to a float. Casts the requested results to a float ...
 |  | UserArrayPtr info Data type: array of type float Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
Open Collapse M_TYPE_LONG | Casts the requested results to a long. Casts the requested results to a long ...
 |  | UserArrayPtr info Data type: array of type long Array size: the same number of elements as number of entries to obtain (MimAllocResult()).
UserArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type double
  • array of type float
  • array of type long

Specifies the address of the one-dimensional array in which to write the results read from the MIL result buffer.

You can set this parameter to M_NULL to put the result request on the local queue of the result buffer.

OUTPUT COORDINATE SYSTEM PIXEL STAT LIST STAT LIST STAT LIST STAT LIST STAT LIST EVENT LIST STAT LIST EVENT LIST EVENT LIST STAT LIST STAT LIST STAT LIST STAT LIST HIST LIST PROJ LIST EXTREME LIST EVENT LIST STAT LIST COUNT LIST EXTREME LIST PROJ LIST EXTREME LIST EVENT LIST MAX MAX MAX ABS MEAN MIN MIN ABS NB EVENT NUMBER POSITION X POSITION Y STANDARD DEVIATION SUM SUM ABS SUM SQUARED VALUE TYPE DOUBLE TYPE FLOAT TYPE LONG


MimHistogram

See Also | Example | Availability | MimGetResult | MimHistogramEqualize
User Guide:
Image statistics

Reference:
MimAllocResult
MimGetResult
MimGetResult1d
mimhistogram.c
Not available in MIL-Lite

Available in MIL
Synopsis
Generate the intensity histogram of an image buffer.
Syntax
void MimHistogram(
MIL_ID SrcImageBufId,
MIL_ID HistImResultId
)
Description

This function calculates the histogram (or pixel intensity distribution) of the specified source buffer and stores results in the specified histogram result buffer.

You can read the histogram values from the result buffer, using MimGetResult1d() or MimGetResult(), specifying M_VALUE as the result type.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This buffer must be one-band. The buffer data will be treated as unsigned.

HistImResultId

Specifies the identifier of the destination for the histogram results. This parameter must be given the identifier of an image processing result buffer that was allocated with MimAllocResult() and has an M_HIST_LIST type. If the result buffer has fewer entries than the full range of source values, the pixels that are out of range will not be written into the histogram.

Remark
  • Floating point values will be cast to unsigned long values before performing the histogram. Therefore, unexpected results can occur if a floating point value is larger than the unsigned long range.
VALUE HIST LIST


MimHistogramEqualize

See Also | Example | Availability | MimHistogram | MimInquire
User Guide:
Histogram equalization
Loading and generating data into LUTs

Reference:
MimLutMap
There are no examples containing MimHistogramEqualize().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a histogram equalization of an image.
Syntax
void MimHistogramEqualize(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long Method,
double Alpha,
double Min,
double Max
)
Description

This function performs a histogram equalization of the specified source image. Results are written to a destination buffer, which can be either an image buffer or a LUT buffer.

This function first performs a histogram of the source image buffer. The histogram is then used to calculate a transformation LUT that can be used to enhance the source image (with MimLutMap()). If the destination buffer is a LUT, the transformation LUT is copied into the destination LUT. If the destination buffer is an image, the source buffer is remapped through the transformation LUT to produce the destination image.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter will be treated as an unsigned image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer or LUT buffer identifier.

Method

Specifies the type of equalization to perform. The following values and their associated density functions are available:

Open Collapse Value Description
Open Collapse M_EXPONENTIAL

 Specifies an equalization density function which generates an Exponential distribution.  Specifies an equalization density function which generates an Exponential distribution ...

 Output probability density model:

 Transfer function:

  Open   Collapse  M_HYPER_CUBE_ROOT

 Specifies an equalization density function which generates a Hyperbolic Cube Root distribution.  Specifies an equalization density function which generates a Hyperbolic Cube Root distribution ...

 Output probability density model:

 Transfer function:

  Open   Collapse  M_HYPER_LOG

 Specifies an equalization density function which generates a Hyperbolic Logarithmic distribution.  Specifies an equalization density function which generates a Hyperbolic Logarithmic distribution ...

 Output probability density model:

 Transfer function:

  Open   Collapse  M_RAYLEIGH

 Specifies an equalization density function which generates a Rayleigh distribution.  Specifies an equalization density function which generates a Rayleigh distribution ...

 Output probability density model:

 Transfer function:

  Open   Collapse  M_UNIFORM

 Specifies an equalization density function which generates a Uniform distribution.  Specifies an equalization density function which generates a Uniform distribution ...

 Output probability density model:

 Transfer function:

 The cumulative probability distribution, Pf(f), of the input image is approximated by its cumulative histogram:

 Refer to "Digital Image Processing," William K. Pratt, United States, John Wiley & Sons, 1978, p.318.

 Alpha

 Specifies the adjustment parameter. Alpha is used with the Method parameter values M_EXPONENTIAL and M_RAYLEIGH.

 In the case of the M_EXPONENTIAL method, a greater Alpha yields a lower occurrence of the most frequent pixels of the histogram in the resulting image buffer.

 In the case of the M_RAYLEIGH method, the greater the alpha is, the greater the occurrence of the most frequent pixels of the histogram in the resulting image buffer.

 Min

 Specifies the lowest pixel value to equalize

 Max

 Specifies the highest pixel value to equalize

Remark

  •  Floating point values will be cast to unsigned long values before performing the histogram. Therefore, unexpected results can occur if a floating point value is larger than the unsigned long range.
    •

EXPONENTIAL RAYLEIGH EXPONENTIAL RAYLEIGH    EXPONENTIAL HYPER CUBE ROOT HYPER LOG RAYLEIGH UNIFORM


MimInquire

See Also | Example | Availability | MimHistogramEqualize | MimLabel
Reference:
MimAllocResult
There are no examples containing MimInquire().
Not available in MIL-Lite

Available in MIL
Synopsis
Inquire about an image processing result buffer parameter setting.
Syntax
long MimInquire(
long BufId,
long InquireType,
void *UserVarPtr
)
Description

This function inquires about a specified MIL image processing result buffer setting. The result buffer must have been allocated with MimAllocResult().

Parameters
BufId

Specifies the identifier of the image processing result buffer.

InquireType

Specifies the type of information about which to inquire. This parameter can be set to one of the following values:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value | Description
Open Collapse M_HOST_ADDRESS | Returns the RAM address of the Host buffer (huge). Returns the RAM address of the Host buffer (huge).
Open Collapse M_MODIFICATION_COUNT | Returns the number of modifications made to the buffer since it was allocated. Returns the number of modifications made to the buffer since it was allocated.
Open Collapse M_OWNER_SYSTEM | Returns the identifier of the system on which the buffer is allocated. Returns the identifier of the system on which the buffer is allocated ...
 |  | UserVarPtr info Data type: MIL_ID
Open Collapse M_RESULT_SIZE | Returns the number of entries in the buffer. Returns the number of entries in the buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_RESULT_TYPE | Returns the attribute or nature of the buffer. Returns the attribute or nature of the buffer ...
 |  | UserVarPtr info Return values: M_COUNT_LIST, M_EVENT_LIST, M_EXTREME_LIST, M_HIST_LIST, M_PROJ_LIST, M_STAT_LIST (details)
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • long
  • MIL_ID

Specifies the address of the variable in which the requested information is to be written. Since the MimInquire() function also returns the requested information, you can set this parameter to M_NULL.

Return value
The returned value is the requested MIL buffer information, cast to long.
HOST ADDRESS MODIFICATION COUNT OWNER SYSTEM RESULT SIZE RESULT TYPE


MimLabel

See Also | Example | Availability | MimInquire | MimLocateEvent
User Guide:
Image statistics
Labeling

Reference:
MimBinarize
mimprocessing.c
Not available in MIL-Lite

Available in MIL
Synopsis
Label objects in an image buffer.
Syntax
void MimLabel(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long ProcMode
)
Description

This function labels all objects (or blobs) in the specified source image, starting from the top-left corner, with unique consecutive values beginning with the value 1. Each pixel in the same blob is given the same numerical value.

If you want to distinguish between touching blobs, you should separate the blobs. For example, you can use an erosion operation before performing the labeling operation.

Parameters
SrcImageBufId

Specifies identifier of the data source of the operation. This parameter must be given an image buffer identifier. If the source buffer is not binary, all non-zero pixels are considered as part of an object or blob.

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer identifier. The destination buffer should be large enough to hold the maximum number of objects (blobs). For example, an 8-bit buffer can be used for a maximum of 254 blobs and a 16-bit buffer can be used for a maximum of 65534 blobs). If the destination buffer depth is too small, several blobs might be given the same value.

ProcMode

Specifies the type of connectivity (lattice) to use for processing. This parameter can be set to one of the following values:

Open Collapse Value Description
Open Collapse M_4_CONNECTED

 Specifies that each pixel has 4 neighbors. If two blobs touch on the vertical and horizontal axis, they are considered one blob.  Specifies that each pixel has 4 neighbors ...

  Open   Collapse  M_8_CONNECTED

 Specifies that each pixel has 8 neighbors. If two blobs touch on the vertical, horizontal, or diagonal, they are considered one blob.  Specifies that each pixel has 8 neighbors ...

      [Combination constants]

 One of the values below can be added to the ProcMode parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Specifies the binary processing mode.  Specifies the binary processing mode ...

 If the source image is a binarized image (containing 0 or the maximum value of the buffer, achieved for example with MimBinarize()), you can add M_BINARY to the connectivity mode to accelerate processing, particularly if the labeling is done by the Host.

  Open   Collapse  M_GRAYSCALE

 Specifies the grayscale processing mode.  Specifies the grayscale processing mode ...

This is the default value.

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

BINARY    4 CONNECTED 8 CONNECTED BINARY GRAYSCALE


MimLocateEvent

See Also | Example | Availability | MimLabel | MimLutMap
User Guide:
Image statistics

Reference:
MimAllocResult
MimGetResult
MimGetResult1d
There are no examples containing MimLocateEvent().
Not available in MIL-Lite

Available in MIL
Synopsis
Find pixel coordinates or values that satisfies a specified condition.
Syntax
void MimLocateEvent(
MIL_ID SrcImageBufId,
MIL_ID EventImResultId,
long Condition,
double CondLow,
double CondHigh
)
Description

This function finds the coordinates and value of the pixels that satisfy the specified condition in the specified source image. Results are stored in the specified event result buffer.

You can retrieve the values, X- or Y-coordinates, and the total number of pixels that satisfy the condition, using MimGetResult() or MimGetResult1d().

Parameters
SrcImageBufId

Specifies the identifier of the source image for the operation. This parameter must be given the identifier of a 1-band buffer.

EventImResultId

Specifies the identifier of the buffer in which to store the event results. This parameter must be given the identifier of an image processing result buffer, allocated using MimAllocResult() with an M_EVENT_LIST type. The buffer must have enough entries to hold the expected number of events.

If the number of pixels found is less than the number of event result buffer entries, the remaining result buffer entries are set to M_INVALID. If the number of events is greater than the number of allocated result buffer entries, the extra entries are discarded.

Condition

Specifies the condition under which pixel values are considered an event. This parameter must be set to one of the values below.

For conditions that use two limits, set the Condition parameter to one of the values below.

Open Collapse Value Description
Open Collapse M_IN_RANGE

 Specifies that pixels with values between CondLow and CondHigh, inclusive, are considered events.  Specifies that pixels with values between CondLow and CondHigh, inclusive, are considered events.

  Open   Collapse  M_OUT_RANGE

 Specifies that pixels with values less than CondLow, or greater than CondHigh, are considered events.  Specifies that pixels with values less than CondLow, or greater than CondHigh, are considered events.

 For conditions that use one limit, set the Condition parameter to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_EQUAL

 Specifies that only pixels with values equal to CondLow will be considered an event.  Specifies that only pixels with values equal to CondLow will be considered an event.

  Open   Collapse  M_GREATER

 Specifies that only pixels with values greater than CondLow will be considered an event.  Specifies that only pixels with values greater than CondLow will be considered an event.

  Open   Collapse  M_GREATER_OR_EQUAL

 Specifies that only pixels with values greater than or equal to the CondLow will be considered an event.  Specifies that only pixels with values greater than or equal to the CondLow will be considered an event.

  Open   Collapse  M_LESS

 Specifies that only pixels with values less than CondLow will be considered an event.  Specifies that only pixels with values less than CondLow will be considered an event.

  Open   Collapse  M_LESS_OR_EQUAL

 Specifies that only pixels with values less than or equal to CondLow will be considered an event.  Specifies that only pixels with values less than or equal to CondLow will be considered an event.

  Open   Collapse  M_NOT_EQUAL

 Specifies that only pixels with values not equal to CondLow will be considered an event.  Specifies that only pixels with values not equal to CondLow will be considered an event.

 CondLow

 Specifies the lower limit of the selected condition.

  Open   Collapse  Value
Description

  Open   Collapse  Value

 Specifies the lower limit.  Specifies the lower limit.

 CondHigh

 Specifies the upper limit of the selected condition.

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Specifies that no upper limit is required. This setting should be used for conditions that use one limit.  Specifies that no upper limit is required ...

  Open   Collapse  Value

 Specifies the upper limit.  Specifies the upper limit.

EVENT LIST    IN RANGE OUT RANGE EQUAL GREATER GREATER OR EQUAL LESS LESS OR EQUAL NOT EQUAL    NULL


MimLutMap

See Also | Example | Availability | MimLocateEvent | MimMorphic
User Guide:
Histogram equalization
Arithmetic with images
Lookup tables in general

Reference:
MbufPut1d
MgenLutRamp
dtkremap.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a point-to-point LUT mapping operation.
Syntax
void MimLutMap(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
MIL_ID LutBufId
)
Description

This function maps each pixel in the specified source image to values determined by the specified lookup table (LUT).

If the source image is signed, negative numbers are treated as unsigned values and address the LUT accordingly. For example, -1 is represented as 0xff for 8-bit image data and 0xffff for 16-bit image data and will therefore address LUT entry 0xff or 0xffff, respectively.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer identifier.

LutBufId

Specifies the LUT through which to map source input values. This parameter must be given a valid LUT buffer identifier.

If the LUT has fewer entries than the full range of source values, unexpected results will occur. If the LUT buffer depth is greater than that of the destination buffer, results will be truncated to fit the destination buffer. LUT entries must have been previously initialized (for example, using MgenLutRamp() or MbufPut1d()).

Remark
  • In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).


MimMorphic

See Also | Example | Availability | MimLutMap | MimOpen
User Guide:
Erosion and dilation
Custom morphological operations

Reference:
MbufAlloc1d
MbufAlloc2d
MbufControlNeighborhood
MbufPut
mimmorphic.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a morphological transformation using a user-defined kernel.
Syntax
void MimMorphic(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
MIL_ID StructElemBufId,
long Operation,
long NbIteration,
long ProcMode
)
Description

This function performs one of several morphological transformations on the specified source image, using a user-defined structuring element.

Parameters
SrcImageBufId

Specifies the identifier of the source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

StructElemBufId

Specifies the identifier of the structuring element buffer. The user-defined structuring element must have been allocated, using MbufAlloc1d() or MbufAlloc2d() with an M_STRUCT_ELEMENT Attribute, and loaded with structuring-element values, using MbufPut(). These values can be set to M_DONT_CARE to specify that the corresponding image pixels should not be taken into account during the operation. You can set the overscan type and the center of the structuring element, using MbufControlNeighborhood().

If the source and destination are multi-band buffers then the same structuring element is applied to every band of the source buffer.

Operation

Specifies the operation to perform. Supported operations are given in the table below.

Open Collapse Value Description
Open Collapse M_DILATE

 Specifies a dilation operation.  Specifies a dilation operation.

  Open   Collapse  M_ERODE

 Specifies an erosion operation.  Specifies an erosion operation.

  Open   Collapse  M_HIT_OR_MISS

 Specifies a hit or miss transformation.  Specifies a hit or miss transformation.

  Open   Collapse  M_MATCH

 specifies a matching operation.  specifies a matching operation.

  Open   Collapse  M_THICK

 Specifies a thickening operation.  Specifies a thickening operation.

  Open   Collapse  M_THIN

 Specifies a thinning operation.  Specifies a thinning operation.

 NbIteration

 Specifies the number of times to iterate the operation.  For M_HIT_OR_MISS or M_MATCH operations, this parameter must be set to 1.

 ProcMode

 Specifies the processing mode to use.  This parameter can be set to the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Treats non-zero pixels as ones (1) during processing.  Treats non-zero pixels as ones (1) during processing.

  Open   Collapse  M_GRAYSCALE

 Uses the source image's gray values for processing and the resulting buffer will also contain gray values. This is the default value.  Uses the source image's gray values for processing and the resulting buffer will also contain gray values ...

Remarks

  •  This function is optimized for packed binary buffers.
    •

  •  In-place processing is supported, but the source and destination image buffers cannot overlap (a situation that can only occur when using child buffers).
    •

STRUCT ELEMENT HIT OR MISS MATCH     DILATE ERODE HIT OR MISS MATCH THICK THIN   BINARY GRAYSCALE


MimOpen

Example | Availability | MimMorphic | MimPolarTransform
mblob.c
mimmorphic.c
mimperimeter.c
mimprocessing.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a binary or grayscale opening-type morphological operation.
Syntax
void MimOpen(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long NbIteration,
long ProcMode
)
Description

This function performs a binary or grayscale opening operation on the given source image for the specified number of iterations. An opening is an erosion followed by a dilation.

This function is optimized for packed binary buffers.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

NbIteration

Specifies the number of times to iterate the operation.

ProcMode

Specifies the processing mode to use. This parameter can be set to the following:

Open Collapse Value Description
Open Collapse M_BINARY

 Treats non-zero pixels as ones (1) during processing. The resulting non-zero pixels will have all bits set to one.  Treats non-zero pixels as ones (1) during processing ...

  Open   Collapse  M_GRAYSCALE

 Uses the source image's gray values for processing. The resulting buffer also contains gray values.  Uses the source image's gray values for processing ...

 In binary mode, this function uses a 3 x 3 full structuring element; in grayscale mode, a 3 x 3 empty one.

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

    BINARY GRAYSCALE


MimPolarTransform

Example | Availability | MimOpen | MimProject
mimpolar.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a polar-to-rectangular or rectangular-to-polar transform.
Syntax
void MimPolarTransform(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
double CenterPosX,
double CenterPosY,
double StartRadius,
double EndRadius,
double StartAngle,
double EndAngle,
long OperationMode,
long InterpolationMode,
double *DestSizeXPtr,
double *DestSizeYPtr
)
Description

This function performs a rectangular-to-polar or polar-to-rectangular transformation.

For a rectangular-to-polar transformation set the zone to convert by specifying the center coordinates (CenterPosX and CenterPosY), the start and end radius (StartRadius and EndRadius), and the start and end angle (StartAngle and EndAngle) as follows:

The result will be mapped to the destination buffer as follows:

The increment in angle is determined by the length (in pixels) of the outside arc, calculated as follows:

(endangle - startangle) / arclength.

A polar-to-rectangular transform performs the reverse of the transform described above. It takes a polar buffer and maps it to a rectangular buffer. Use CenterPosX, CenterPosY, StartAngle, EndAngle, StartRadius, EndRadius parameters to specify where in the destination buffer the contents of the polar buffer will be mapped.

Parameters
SrcImageBufId

Specifies the identifier of the source buffer.

DestImageBufId

Specifies the identifier of the destination buffer. To determine the required size of the destination buffer, call the function with DestImageBufId set to M_NULL and obtain the size in DestSizeXPtr and DestSizeYPtr.

CenterPosX

Specifies the X-coordinate of the center in the rectangular image.

CenterPosY

Specifies the Y-coordinate of the center in the rectangular image.

StartRadius

Specifies the start radius of the zone of interest (in pixels).

EndRadius

Specifies the end radius of the zone of interest (in pixels).

StartAngle

Specifies the start of scan in the zone of interest. If the start angle (StartAngle) is less than the end angle (EndAngle), the direction of the scan will be counter clockwise. If the start angle is greater than the end angle, the direction of the scan will be clockwise.

The valid range for StartAngle is between -360.0 to 360.0° and the maximum span between StartAngle and EndAngle must not exceed 360.0°.

EndAngle

Specifies the end of scan in the zone of interest.

The valid range for EndAngle is between -360.0 to 360.0° and the maximum span between StartAngle and EndAngle must not exceed 360.0°.

OperationMode

Specifies the transform to perform. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_POLAR_TO_RECTANGULAR

 Performs polar-to-rectangular transform.  Performs polar-to-rectangular transform.

  Open   Collapse  M_RECTANGULAR_TO_POLAR

 Performs rectangular-to-polar transform. This is the default.  Performs rectangular-to-polar transform ...

 InterpolationMode

 Specifies the interpolation used in the conversion.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Default for interpolation mode and type. Same as M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE.  Default for interpolation mode and type ...

  Open   Collapse  M_BICUBIC

 Performs bicubic interpolation.  Performs bicubic interpolation.

  Open   Collapse  M_BILINEAR

 Performs bilinear interpolation.  Performs bilinear interpolation.

  Open   Collapse  M_NEAREST_NEIGHBOR

 Performs nearest neighbor interpolation.  Performs nearest neighbor interpolation.

      [Combination constants]

 To specify how to determine the value of a destination pixel when its associated point falls outside the source buffer, you can add one of the values below to the InterpolationMode parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_OVERSCAN_CLEAR

 Sets the destination pixel to 0.  Sets the destination pixel to 0.

  Open   Collapse  M_OVERSCAN_DISABLE

 Leaves the destination pixel as is.  Leaves the destination pixel as is.

  Open   Collapse  M_OVERSCAN_ENABLE

 Uses pixels from the source buffer's ancestor buffer. If the source buffer is not a child buffer or if the point falls outside the ancestor buffer, leave the destination pixel as is.  Uses pixels from the source buffer's ancestor buffer ...

 Note that when using bicubic interpolation, saturation is performed according to the type of the destination buffer. For the other interpolation modes, no saturation is performed.

 DestSizeXPtr

 Specifies the required width of the destination buffer.  If this parameter is not set to M_NULL, the width will be returned.

 DestSizeYPtr

 Specifies the required height of the destination buffer.  If this parameter is not set to M_NULL, the height will be returned.

NEAREST NEIGHBOR OVERSCAN ENABLE          POLAR TO RECTANGULAR RECTANGULAR TO POLAR  DEFAULT BICUBIC BILINEAR NEAREST NEIGHBOR OVERSCAN CLEAR OVERSCAN DISABLE OVERSCAN ENABLE


MimProject

See Also | Example | Availability | MimPolarTransform | MimRank
User Guide:
Image statistics

Reference:
MimAllocResult
MimGetResult
MimGetResult1d
There are no examples containing MimProject().
Not available in MIL-Lite

Available in MIL
Synopsis
Project a 2D image into 1D.
Syntax
void MimProject(
MIL_ID SrcImageBufId,
MIL_ID ProjImResultId,
double ProjAngle
)
Description

This function projects a two-dimensional buffer into a one-dimensional buffer from the specified angle, and writes results to the specified projection result buffer. The results are generated by adding all pixel values along each diagonal in the image at the specified projection angle. The 90° projection of the image is known as the row profile; the 0° projection as the column profile.

Note that, if the sum of any diagonal is larger than the depth of the result buffer, the result will be undefined.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the image. This parameter must be given an image buffer identifier. The buffer must be one-band.

ProjImResultId

Specifies the identifier of the destination of the projection results. This parameter must be given the identifier of an image processing result buffer allocated with MimAllocResult() and an M_PROJ_LIST type. The buffer should have as many locations as there are lines to project in the image at the specified angle.

You can read the projection values from the result buffer, using MimGetResult1d() or MimGetResult(), specifying M_VALUE as the result type.

ProjAngle

Specifies the angle of projection, in degrees. Predefined projection angles are the following:

Open Collapse Value Description
Open Collapse M_0_DEGREE

 Specifies a 0° projection (column profile).  Specifies a 0° projection (column profile).

  Open   Collapse  M_90_DEGREE

 Specifies a 90° projection (row profile).  Specifies a 90° projection (row profile).

Remark

  •  Only 0° and 90° projection angles are supported.
    •

PROJ LIST VALUE    0 DEGREE 90 DEGREE


MimRank

See Also | Example | Availability | MimProject | MimResize
User Guide:
Denoising

Reference:
MbufAlloc1d
MbufAlloc2d
MbufPut
There are no examples containing MimRank().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox CronosPlus
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Perform a rank filter on the pixels in an image.
Syntax
void MimRank(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
MIL_ID StructElemBufId,
long Rank,
long ProcMode
)
Description

This function performs a rank filter operation on the specified source buffer. It replaces each pixel with the pixel in its neighborhood whose value is the specified rankth value relative to others. It uses the specified structuring element as a mask. This mask determines the neighborhood size and which pixels in the neighborhood to ignore.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

StructElemBufId

Specifies the identifier of the structuring element buffer to use as a mask. You can either define a custom structuring element as a mask or use a predefined mask buffer.

To use a custom structuring element, you must have previously allocated it with MbufAlloc1d() or MbufAlloc2d() (specifying M_STRUCT_ELEMENT as the attribute) and loaded it with values, using MbufPut(). The structuring element buffer dimensions are used as the neighborhood size. Values in the structuring element set to M_DONT_CARE represent neighborhood pixels not to be considered in the ranking operation. All other values in the structuring element must be set to 1, representing neighborhood pixels to be considered in the ranking operation.

The following are predefined mask buffers:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_3X3_CROSS

 Applies a cross (+) mask and sets the neighborhood size to 3 x 3 pixels. In this case, there are 5 valid neighborhood pixels; the cross mask makes the function ignore the pixels located at the four corners of the neighborhood.  Applies a cross (+) mask and sets the neighborhood size to 3 x 3 pixels ...

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_3X3_RECT

 Applies no mask and sets the neighborhood size to 3 x 3 pixels. In this case, there are 9 valid neighborhood pixels.  Applies no mask and sets the neighborhood size to 3 x 3 pixels ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_5X5_RECT

 Applies no mask and sets the neighborhood size to 5 x 5 pixels. In this case, there are 25 valid neighborhood pixels.  Applies no mask and sets the neighborhood size to 5 x 5 pixels ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

 To temporarily disable overscanning, the value below can be added to a predefined mask buffer.

  Open   Collapse  Value
Description

  Open   Collapse  M_OVERSCAN_DISABLE

 Disables overscanning temporarily. You should disable overscanning to accelerate the operation for applications in which the overscan data is not important in the resulting buffer.  Disables overscanning temporarily ...

 Rank

 Specifies which of the pixel values to select after valid neighborhood values are sorted in increasing order; valid neighborhood pixel values are those that are not masked-out.

  Open   Collapse  Value
Description

  Open   Collapse  1 <= Value <= number of valid neighborhood pixels

 Specifies the rank of the pixel value to select. If the number of valid pixels is less than the given rank, the number of valid pixels is used as the rank.  Specifies the rank of the pixel value to select ...

  Open   Collapse  M_MEDIAN

 Specifies that MimRank() performs a median filter (that is, each pixel is replaced with the median neighborhood value).  Specifies that MimRank() performs a median filter (that is, each pixel is replaced with the median neighborhood value).

 ProcMode

 Specifies the processing mode to use.  This parameter can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Treats non-zero pixels as ones (1) during processing. The resulting non-zero pixels will have all bits set to one.  Treats non-zero pixels as ones (1) during processing ...

  Open   Collapse  M_GRAYSCALE

 Uses the source image's gray values for processing. The resulting buffer will also contain gray values.  Uses the source image's gray values for processing ...

This is the default value.

Remarks

  •  This function is optimized for packed binary buffers.
    •

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

STRUCT ELEMENT DONT CARE    3X3 CROSS 3X3 RECT 5X5 RECT OVERSCAN DISABLE  MEDIAN   BINARY  GRAYSCALE


MimResize

Example | Availability | MimRank | MimRotate
There are no examples containing MimResize().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox CronosPlus
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Resize an image.
Syntax
void MimResize(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
double ScaleFactorX,
double ScaleFactorY,
long InterpolationMode
)
Description

This function resizes the source image by the specified factors. Results are stored in the destination buffer starting from the top-left corner.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer identifier.

ScaleFactorX

Specifies the scaling factor for the width of the source image. This parameter can be set to one of the values below.

Open Collapse Value Description
Open Collapse M_FILL_DESTINATION

 Resizes the source image to fill the entire width of the destination buffer. When set to M_FILL_DESTINATION, the source image is resized to fill the entire width of the destination buffer.  Resizes the source image to fill the entire width of the destination buffer ...

  Open   Collapse  Value

 Uses a non-null positive value to multiply the width of the source image. A value greater than 1.0 enlarges the source image, while a factor less than 1.0 reduces it.  Uses a non-null positive value to multiply the width of the source image ...

 ScaleFactorY

 Specifies the scaling factor for the height of the source image.  This parameter can be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_FILL_DESTINATION

 Resizes the source image to fill the entire height of the destination buffer. When set to M_FILL_DESTINATION, the source image is resized to fill the entire height of the destination buffer.  Resizes the source image to fill the entire height of the destination buffer ...

  Open   Collapse  Value

 Uses a non-null positive value to multiply the height of the source image. A value greater than 1.0 enlarges the source image, while a factor less than 1.0 reduces it.  Uses a non-null positive value to multiply the height of the source image ...

 InterpolationMode

 Specifies the mode of interpolation.  This parameter can be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE + M_FAST.  Same as M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE + M_FAST.

  Open   Collapse  M_AVERAGE

 Specifies averaging interpolation.  Specifies averaging interpolation.

  Open   Collapse  M_BICUBIC

 Specifies bicubic interpolation.  Specifies bicubic interpolation.

  Open   Collapse  M_BILINEAR

 Specifies bilinear interpolation.  Specifies bilinear interpolation.

  Open   Collapse  M_INTERPOLATE

 Specifies interpolated resizing: for zooming = bilinear, for dezooming = averaging. Gives the best speed/result compromise for interpolated resizing.  Specifies interpolated resizing: for zooming = bilinear, for dezooming = averaging ...

  Open   Collapse  M_NEAREST_NEIGHBOR

 Specifies the nearest neighbor interpolation.  Specifies the nearest neighbor interpolation.

      [Combination constants]

 To specify how to determine the value of a destination pixel when its associated point falls outside the source buffer, you can add one of the values below to the InterpolationMode parameter.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_OVERSCAN_CLEAR

 Sets the destination pixel to 0.  Sets the destination pixel to 0.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OVERSCAN_DISABLE

 Leaves the destination pixel as is.  Leaves the destination pixel as is.

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OVERSCAN_ENABLE

 Uses pixels from the source buffer's ancestor buffer. If the source buffer is not a child buffer or if the point falls outside the ancestor buffer, leave the destination pixel as is.  Uses pixels from the source buffer's ancestor buffer ...

This is the default value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

      [Combination constants]

 In addition, one of the following can be added to the interpolation mode to control the speed and precision of the interpolation.

  Open   Collapse  Value
Description

  Open   Collapse  M_FAST

 Uses the fast interpolation method. This method is less precise. The default setting is M_FAST.  Uses the fast interpolation method ...

  Open   Collapse  M_REGULAR

 Uses the slow interpolation method. This method is more precise.  Uses the slow interpolation method ...

 Note that when using bicubic interpolation, saturation is performed according to the type of the destination buffer. For the other interpolation modes, no saturation is performed.

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

FILL DESTINATION FILL DESTINATION NEAREST NEIGHBOR OVERSCAN ENABLE FAST FAST    FILL DESTINATION   FILL DESTINATION   DEFAULT AVERAGE BICUBIC BILINEAR INTERPOLATE NEAREST NEIGHBOR OVERSCAN CLEAR OVERSCAN DISABLE OVERSCAN ENABLE FAST REGULAR


MimRotate

Example | Availability | MimResize | MimShift
mpat.c
mthread.c
odysseymultiboard.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Partially supported on Matrox CronosPlus
Synopsis
Rotate an image.
Syntax
void MimRotate(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
double Angle,
double SrcCenX,
double SrcCenY,
double DstCenX,
double DstCenY,
long InterpolationMode
)
Description

This function rotates an image by the specified angle of rotation, using the specified interpolation mode. The center of rotation in the source image is determined by the specified X and Ysource rotation-center coordinates. The rotated image will then be clipped to fit the destination buffer. It will be placed in the destination buffer with its center positioned at the specified X and Y destination center coordinates.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer identifier.

Angle

Specifies the angle of rotation, in degrees. When a positive angle is specified, the function rotates the image in a counter-clockwise direction.

SrcCenX

Specifies the X-coordinate to use as the center of rotation in the source image. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Causes the image to rotate about its true center.  Causes the image to rotate about its true center.

  Open   Collapse  Value

 Specifies the X-coordinate.  Specifies the X-coordinate.

 SrcCenY

 Specifies the Y-coordinate to use as the center of rotation in the source image.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Causes the image to rotate about its true center.  Causes the image to rotate about its true center.

  Open   Collapse  Value

 Specifies the Y-coordinate.  Specifies the Y-coordinate.

 DstCenX

 Specifies the X-coordinate in the destination buffer to which the specified center of the rotated source image will be mapped.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Causes the true center of the destination buffer to be used.  Causes the true center of the destination buffer to be used.

  Open   Collapse  Value

 Specifies the X-coordinate.  Specifies the X-coordinate.

 DstCenY

 Specifies the Y-coordinate in the destination buffer to which the specified center of the rotated source image will be mapped.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Causes the true center of the destination buffer to be used.  Causes the true center of the destination buffer to be used.

  Open   Collapse  Value

 Specifies the Y-coordinate.  Specifies the Y-coordinate.

 InterpolationMode

 Specifies the interpolation mode.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies nearest neighbor interpolation while using pixels from the source buffer's ancestor buffer. This is the same as M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE.  Specifies nearest neighbor interpolation while using pixels from the source buffer's ancestor buffer ...

  Open   Collapse  M_BICUBIC

 Specifies bicubic interpolation.  Specifies bicubic interpolation.

  Open   Collapse  M_BILINEAR

 Specifies bilinear interpolation.  Specifies bilinear interpolation.

  Open   Collapse  M_NEAREST_NEIGHBOR

 Specifies nearest neighbor interpolation.  Specifies nearest neighbor interpolation.

      [Combination constants]

 To specify how to determine the value of a destination pixel when its associated point falls outside the source buffer, you can add one of the values below to the InterpolationMode parameter.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_OVERSCAN_CLEAR

 Sets the destination pixel to 0.  Sets the destination pixel to 0.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OVERSCAN_DISABLE

 Leaves the destination pixel as is.  Leaves the destination pixel as is.

a

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OVERSCAN_ENABLE

 Uses pixels from the source buffer's ancestor buffer. If the source buffer is not a child buffer or if the point falls outside the ancestor buffer, leave the destination pixel as is.  Uses pixels from the source buffer's ancestor buffer ...

This is the default value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 Note that when using bicubic interpolation, saturation is performed according to the type of the destination buffer. For the other interpolation modes, no saturation is performed.

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

NEAREST NEIGHBOR OVERSCAN ENABLE     DEFAULT   DEFAULT   DEFAULT   DEFAULT   DEFAULT BICUBIC BILINEAR NEAREST NEIGHBOR OVERSCAN CLEAR OVERSCAN DISABLE OVERSCAN ENABLE


MimShift

Example | Availability | MimRotate | MimStat
There are no examples containing MimShift().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a point-to-point bit shift.
Syntax
void MimShift(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long BitsToShift
)
Description

This function performs left or right bit-shifting on each pixel in the specified image. The shift operation is signed or unsigned depending on the source image buffer's data type.

Note that, if you shift by 0, only a copy operation will be performed.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the results. This parameter must be given an image buffer identifier.

BitsToShift

Specifies the number of bits to shift. If the given value is negative, each pixel in the specified image is right bit-shifted by the specified number of bits; otherwise, it is left bit-shifted.

Remarks
  • Floating point values will be cast to unsigned long values before performing the shift operation (except when shifting by 0). Therefore, unexpected results can occur if a floating point value is larger than the unsigned long range.
  • In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).


MimStat

See Also | Example | Availability | MimShift | MimThick
User Guide:
Image statistics

Reference:
MimAllocResult
MimGetResult
MimGetResult1d
There are no examples containing MimStat().
Not available in MIL-Lite

Available in MIL
Synopsis
Calculate a variety of statistics on the source image.
Syntax
void MimStat(
MIL_ID SrcImageId,
MIL_ID StatResultId,
long StatType,
long Condition,
double CondLow,
double CondHigh
)
Description

This function calculates a variety of statistics for the pixels that satisfy the specified condition in the source image. Results are stored in the specified statistic result buffer.

You can retrieve statistical results using MimGetResult1d() or MimGetResult().

Parameters
SrcImageId

Specifies the identifier of the source image for the operation. This parameter must be given a 1-band image buffer identifier.

StatResultId

Specifies the identifier of the destination result buffer for the operation.

This parameter must be given the identifier of an image processing result buffer, allocated using MimAllocResult() function with M_STAT_LIST as the result type.

StatType

Specifies the type of statistic to compute.

You can set the StatType parameter to one or more of the following values.

Open Collapse Value Description
Open Collapse M_MAX

 Specifies the maximum pixel value that respects the setting of the Condition parameter.  Specifies the maximum pixel value that respects the setting of the Condition parameter.

  Open   Collapse  M_MAX_ABS

 Specifies the maximum absolute pixel value that respects the setting of the Condition parameter.  Specifies the maximum absolute pixel value that respects the setting of the Condition parameter.

  Open   Collapse  M_MEAN

 Specifies the mean value of the pixels that respect the setting of the Condition parameter.  Specifies the mean value of the pixels that respect the setting of the Condition parameter.

  Open   Collapse  M_MIN

 Specifies the minimum pixel value that respects the setting of the Condition parameter.  Specifies the minimum pixel value that respects the setting of the Condition parameter.

  Open   Collapse  M_MIN_ABS

 Specifies the minimum absolute pixel value that respects the setting of the Condition parameter.  Specifies the minimum absolute pixel value that respects the setting of the Condition parameter.

  Open   Collapse  M_NUMBER

 Specifies the number of pixels that respect the setting of the Condition parameter.  Specifies the number of pixels that respect the setting of the Condition parameter.

  Open   Collapse  M_STANDARD_DEVIATION

 Specifies the standard deviation value of the pixels that respect the setting of the Condition parameter.  Specifies the standard deviation value of the pixels that respect the setting of the Condition parameter.

  Open   Collapse  M_SUM

 Specifies the sum of the pixel values that respect the setting of the Condition parameter.  Specifies the sum of the pixel values that respect the setting of the Condition parameter.

  Open   Collapse  M_SUM__ABS

 Specifies the sum of the absolute pixel values that respect the setting of the Condition parameter.  Specifies the sum of the absolute pixel values that respect the setting of the Condition parameter.

  Open   Collapse  M_SUM_SQUARED

 Specifies the sum of the squared pixel values that respect the setting of the Condition parameter.  Specifies the sum of the squared pixel values that respect the setting of the Condition parameter.

 To compute all of the different statistics listed above, set StatType to the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL

 Specifies that all statistics are computed.  Specifies that all statistics are computed.

 Condition

 Specifies the condition for the statistical computation.

 If no condition is required, set the Condition parameter to the value below.

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Specifies that no condition is set. Set CondLow and CondHigh parameters to M_NULL.  Specifies that no condition is set ...

 For conditions that use two limits, set the Condition parameter to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_IN_RANGE

 Specifies that pixels with values between CondLow and CondHigh, inclusive, will be used for statistical calculations.  Specifies that pixels with values between CondLow and CondHigh, inclusive, will be used for statistical calculations.

  Open   Collapse  M_OUT_RANGE

 Specifies that pixels with values less than CondLow, or greater than CondHigh, will be used for statistical calculations.  Specifies that pixels with values less than CondLow, or greater than CondHigh, will be used for statistical calculations.

 For conditions that use one limit, set the Condition parameter to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_EQUAL

 Specifies that only pixels with values equal to CondLow will be used for statistical calculations.  Specifies that only pixels with values equal to CondLow will be used for statistical calculations.

  Open   Collapse  M_GREATER

 Specifies that only pixels with values greater than CondLow will be used for statistical calculations.  Specifies that only pixels with values greater than CondLow will be used for statistical calculations.

  Open   Collapse  M_GREATER_OR_EQUAL

 Specifies that only pixels with values greater than or equal to CondLow will be used for statistical calculations.  Specifies that only pixels with values greater than or equal to CondLow will be used for statistical calculations.

  Open   Collapse  M_LESS

 Specifies that only pixels with values less than CondLow will be used for statistical calculations.  Specifies that only pixels with values less than CondLow will be used for statistical calculations.

  Open   Collapse  M_LESS_OR_EQUAL

 Specifies that only pixels with values less than or equal to CondLow will be used for statistical calculations.  Specifies that only pixels with values less than or equal to CondLow will be used for statistical calculations.

  Open   Collapse  M_MASK

 Specifies that only pixels corresponding to the non-zero pixels in the mask buffer will be used for statistical calculations. Specify the mask using the CondLow parameter.  Specifies that only pixels corresponding to the non-zero pixels in the mask buffer will be used for statistical calculations ...

  Open   Collapse  M_NOT_EQUAL

 Specifies that only pixels with values not equal to CondLow will be used for statistical calculations.  Specifies that only pixels with values not equal to CondLow will be used for statistical calculations.

 CondLow

 Specifies the lower limit of the selected condition.

 This parameter must be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Specifies that no lower limit is required. This setting should only be used when the Condition parameter is also set to M_NULL.  Specifies that no lower limit is required ...

  Open   Collapse  MIL image buffer identifier

 Specifies a 1-band image buffer used as the mask. The buffer must be of the same size as the source image. This setting can only be used when the Condition parameter is set to M_MASK.  Specifies a 1-band image buffer used as the mask ...

  Open   Collapse  Value

 Specifies the lower limit.  Specifies the lower limit.

 CondHigh

 Specifies the upper limit of the selected condition.

 This parameter must be set to one of the following values.

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Specifies that no upper limit is required. This setting should be used unless the Condition parameter is set to M_IN_RANGE or M_OUT_RANGE.  Specifies that no upper limit is required ...

  Open   Collapse  Value

 Specifies the upper limit.  Specifies the upper limit.

STAT LIST MASK IN RANGE OUT RANGE    MAX MAX ABS MEAN MIN MIN ABS NUMBER STANDARD DEVIATION SUM SUM  ABS SUM SQUARED ALL  NULL IN RANGE OUT RANGE EQUAL GREATER GREATER OR EQUAL LESS LESS OR EQUAL MASK NOT EQUAL  NULL    NULL


MimThick

See Also | Example | Availability | MimStat | MimThin
User Guide:
Custom morphological operations

Reference:
There are no examples containing MimThick().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a binary or grayscale thickening operation on an image.
Syntax
void MimThick(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long NbIteration,
long ProcMode
)
Description

This function performs a binary or grayscale thickening on the specified source image for the specified number of iterations. MimThick() is optimized for packed binary buffers.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

NbIteration

Specifies the number of times to iterate the operation. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_TO_IDEMPOTENCE

 Specifies the operation will iterate until idempotence is reached.  Specifies the operation will iterate until idempotence is reached.

  Open   Collapse  Value

 Sets the number of iterations.  Sets the number of iterations.

 ProcMode

 Specifies the processing mode to use.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Treats non-zero pixels as ones (1) during processing. The resulting non-zero pixels will have all bits set to one.  Treats non-zero pixels as ones (1) during processing ...

  Open   Collapse  M_GRAYSCALE

 Uses the source image's gray values for processing. The resulting buffer will also contain gray values.  Uses the source image's gray values for processing ...

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

   TO IDEMPOTENCE   BINARY GRAYSCALE


MimThin

See Also | Example | Availability | MimThick | MimTransform
User Guide:
Custom morphological operations

Reference:
There are no examples containing MimThin().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a binary or grayscale thinning operation on an image.
Syntax
void MimThin(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long NbIteration,
long ProcMode
)
Description

This function performs a binary or grayscale thinning on the specified source image for the specified number of iterations. MimThin() is optimized for packed binary buffers.

Parameters
SrcImageBufId

Specifies the identifier of the data source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

NbIteration

Specifies the number of times to iterate the operation. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_TO_SKELETON

 Specifies that every object will be reduced to its skeleton.  Specifies that every object will be reduced to its skeleton.

  Open   Collapse  Value

 Sets the number of iterations.  Sets the number of iterations.

 ProcMode

 Specifies the processing mode to use.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_BINARY

 Treats non-zero pixels as ones (1) during processing. The resulting non-zero pixels will have all bits set to one.  Treats non-zero pixels as ones (1) during processing ...

  Open   Collapse  M_GRAYSCALE

 Uses the source image's gray values for processing. The resulting buffer will also contain gray values.  Uses the source image's gray values for processing ...

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

   TO SKELETON   BINARY GRAYSCALE


MimTransform

Example | Availability | MimThin | MimTranslate
mimfft.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a Fast Fourier transform (FFT) or a Discrete Cosine transform (DCT).
Syntax
void MimTransform(
MIL_ID SrcImageRBufID,
MIL_ID SrcImageIBufID,
MIL_ID DestImageRBufID,
MIL_ID DestImageIBufID,
long TransformType,
long ControlFlag
)
Description

This function performs a forward or reverse FFT or DCT on an image.

Parameters
SrcImageRBufID

Specifies the identifier of the source buffer for the real component of the image.

For a reverse transform, the source buffer must be a 32-bit signed integer or a floating point buffer. For an FFT, the width and height of the source buffer must be a power of 2. For a DCT, the width and height of the source buffer should be a multiple of 8.

SrcImageIBufID

Specifies the identifier of the source buffer for the imaginary component of the image.

The buffer has the same restrictions as SrcImageRBufID. SrcImageIBufID can be set to M_NULL. In addition, for an FFT, the buffer must be of the same type and have the same pixel depth as the buffer specified for SrcImageRBufID.

DestImageRBufID

Specifies the identifier of the destination buffer for the real component of the image.

For a forward transform, the destination buffer must be a 32-bit signed integer or a floating point buffer. For an FFT, the width and height of the destination buffer must be a power of 2. For a DCT, the width and height of the destination buffer should be a multiple of 8.

DestImageIBufID

Specifies the identifier of the destination buffer for the imaginary component of the image.

The buffer has the same restrictions as DestImageRBufID. DestImageIBufID can be set to M_NULL. In addition, for an FFT, the buffer must be of the same type and have the same depth as the buffer specified for DestImageRBufID.

TransformType

Specifies the type of transform to be performed on the image. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Same as M_FFT.  Same as M_FFT.

  Open   Collapse  M_DCT8X8

 Performs a Discrete Cosine transform on each 8x8 pixel block in the image.  Performs a Discrete Cosine transform on each 8x8 pixel block in the image.

  Open   Collapse  M_FFT

 Performs a Fast Fourier transform.  Performs a Fast Fourier transform.

 ControlFlag

 Specifies if the transform is a forward transform or a reverse transform.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_FORWARD.  Same as M_FORWARD.

  Open   Collapse  M_FORWARD

 Performs a forward transform on the image. Calculations for integer source buffers are performed in fixed-point format and returned to the destinations in 23.9 fixed point format for 8-bit sources or in 25.7 fixed point format for 16-bit sources. For 32-bit source buffers, the fixed point format of the destination buffer will be the same as that of the source. In this case, you must left-shift the image prior to a forward transform. If the destination buffer is float, the processing will be performed in floating-point arithmetic. In an FFT, if SrcImageIBufID is set to M_NULL, a faster version of the forward transform will be performed.  Performs a forward transform on the image ...

  Open   Collapse  M_REVERSE

 Performs a reverse transform on the image. When performing a reverse transform into 8-bit or 16-bit destination buffers, the format of the source buffers is assumed to be in 23.9 and 25.7 fixed point format, respectively. For 32-bit integer destination buffers, the format of the source buffer will be same as that of the destination. In this case, you must right-shift the image after processing. If the source buffer is float, the processing will be performed in floating-point arithmetic. In an FFT, if DestImageIBufID is set to M_NULL, a faster version of the reverse transform will be performed.  Performs a reverse transform on the image ...

      [Combination constants]

 The values below can be added to the ControlFlag parameter. Note that only M_NORMALIZE is supported with both FFT and DCT. All other values are supported only with the FFT.

  Open   Collapse  Value
Description

  Open   Collapse  M_CENTER

 Centers the real part and the imaginary part of the spectrum. The center of the spectrum is put at the (SizeX/2-1, SizeY/2-1).  Centers the real part and the imaginary part of the spectrum ...

 If M_CENTER has been specified with the forward transform, then it must be specified for the reverse transform as well.

  Open   Collapse  M_1D_COLUMNS

 Performs a 1-D transform on all columns of the image.  Performs a 1-D transform on all columns of the image ...

 If M_1D_COLUMNS has been specified with the forward transform, then it must be specified for the reverse transform as well.

  Open   Collapse  M_1D_ROWS

 Performs a 1-D transform on all rows of the image.  Performs a 1-D transform on all rows of the image ...

 If M_1D_ROWS has been specified with the forward transform, then it must be specified for the reverse transform as well.

  Open   Collapse  M_MAGNITUDE

 Computes the magnitude of the forward transform (the square root of R2+I2) and returns its value in the real destination buffer.  Computes the magnitude of the forward transform (the square root of R2+I2) and returns its value in the real destination buffer ...

M_MAGNITUDE can only be used in forward transforms processed with floating point buffers.

  Open   Collapse  M_NORMALIZE

 Normalizes results (divide the final result by 8 for DCT and by (m x n) for FFT where m x n is the size of the image). M_NORMALIZE must be used with fixed-point arithmetic (all integer buffers) to avoid overflows.  Normalizes results (divide the final result by 8 for DCT and by (m x n) for FFT where m x n is the size of the image) ...

 If M_NORMALIZE has been specified with the forward transform, then it must be specified for the reverse transform as well.

  Open   Collapse  M_PHASE

 Computes the phase of the forward transform atan(I/R) and return its value in the imaginary destination buffer. The phase is returned in the range of -180 to 180°.  Computes the phase of the forward transform atan(I/R) and return its value in the imaginary destination buffer ...

M_PHASE can only be used in forward transforms processed with floating point buffers.

      [Combination constants]

 The value below can be added to M_MAGNITUDE.

  Open   Collapse  Value
Description

  Open   Collapse  M_LOG_SCALE

 Scales logarithmically the magnitude of the forward FFT to be in the range of 0-255. This value is used to scale the spectrum into a displayable range.  Scales logarithmically the magnitude of the forward FFT to be in the range of 0-255 ...

M_LOG_SCALE can only be used in forward transforms processed with floating point buffers.

 Note that when the values M_MAGNITUDE and M_PHASE are used, their results are returned in the real and imaginary buffers respectively, thereby overwriting the real and imaginary components of the image in the destination buffers. A reverse transform of these buffers will not yield a desirable result.

FFT FORWARD NORMALIZE CENTER 1D COLUMNS 1D ROWS MAGNITUDE NORMALIZE NORMALIZE PHASE MAGNITUDE LOG SCALE MAGNITUDE PHASE      DEFAULT DCT8X8 FFT  DEFAULT FORWARD  REVERSE CENTER 1D COLUMNS 1D ROWS MAGNITUDE NORMALIZE PHASE LOG SCALE


MimTranslate

Example | Availability | MimTransform | MimWarp
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Translate an image in X and/or Y displacement.
Syntax
void MimTranslate(
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
double XDisplacement,
double YDisplacement,
long InterpolationMode
)
Description

This function translates the source image position by the specified amount, writing results to the destination buffer. This function can be used to align images to subpixel accuracy before, for example, subtracting them.

Parameters
SrcImageBufId

Specifies the source image buffer identifier.

DestImageBufId

Specifies the destination image buffer identifier.

XDisplacement

Specifies the amount by which to displace the source image in the X-direction. This parameter can be set to any positive or negative value.

YDisplacement

Specifies the amount by which to displace the source image in the Y-direction. This parameter can be set to any positive or negative value.

InterpolationMode

Specifies the interpolation mode. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Same as M_BILINEAR + M_OVERSCAN_ENABLE.  Same as M_BILINEAR + M_OVERSCAN_ENABLE.

  Open   Collapse  M_BILINEAR

 Specifies bilinear interpolation.  Specifies bilinear interpolation.

      [Combination constants]

 To specify how to determine the value of a destination pixel when its associated point falls outside the source buffer, you can add one of the values below to the InterpolationMode parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_OVERSCAN_CLEAR

 Sets the destination pixel to 0.  Sets the destination pixel to 0.

  Open   Collapse  M_OVERSCAN_DISABLE

 Leaves the destination pixel as is.  Leaves the destination pixel as is.

  Open   Collapse  M_OVERSCAN_ENABLE

 Uses pixels from the source buffer's ancestor buffer. If the source buffer is not a child buffer or if the point falls outside the ancestor buffer, leave the destination pixel as is.  Uses pixels from the source buffer's ancestor buffer ...

This is the default value.

BILINEAR OVERSCAN ENABLE      DEFAULT BILINEAR OVERSCAN CLEAR OVERSCAN DISABLE OVERSCAN ENABLE


MimWarp

See Also | Example | Availability | MimTranslate | MimWatershed
User Guide:
Basic geometric transform
Warping
Processing calibrated images
Adjusting blob analysis processing controls

Reference:
MgenWarpParameter
mimwarp.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox CronosPlus
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Perform a warping.
Syntax
void MimWarp(
MIL_ID SrcImageId,
MIL_ID DestImageId,
MIL_ID WarpParam1Id,
MIL_ID WarpParam2Id,
long OperationMode,
long InterpolationMode
)
Description

This function warps an image through either a first-order polynomial mapping or through lookup tables (LUTs).

A warping associates each pixel position of the destination buffer, (xd, yd), with a specific point in the source buffer, (xs, ys), and then determines the pixel value of (xd, yd) from its associated point and from a specified interpolation mode.

When using a first-order polynomial mapping, (xd, yd) gets associated with (xs, ys) through the following equations:

xs= a0xd+ a1yd+ a2

ys= b0xd+ b1yd+ b2

In this case, WarpParam1Id specifies the required coefficients (a0...a2, b0...b2) and WarpParam2Id must be set to M_NULL. The coefficients can be automatically generated using MgenWarpParameter() or can be user-supplied.

When using LUTs, xs is determined from (xd, yd) through one LUT and ys is determined from (xd, yd) through another LUT. In this case, WarpParam1Id specifies the LUT for xs and WarpParam2Id specifies the LUT for ys. The LUTs can be user-supplied or, for 3x3 matrix-defined warpings, can be automatically generated using MgenWarpParameter().

Parameters
SrcImageId

Specifies the buffer on which to perform the warping. This buffer can be of any type.

DestImageId

Specifies the buffer in which to place the results of the warping. This buffer can be of any type.

WarpParam1Id

Specifies the buffer containing the (a0...a2, b0...b2) coefficients or the LUT buffer from which xs is determined. When WarpParam1Id specifies the (a0...a2, b0...b2) coefficients, the coefficients must be in a single-band 32-bit floating-point buffer that has an M_ARRAY attribute and that has dimensions 3x2 or 3x3. The first row specifies the an coefficients and the second row specifies the bn coefficients. If the buffer is 3x3, the third row is ignored (it is assumed to be (0, 0, 1)) since MimWarp() does not directly perform polynomial warpings of second-order or higher.

When WarpParam1Id specifies the LUT buffer from which xs is determined, the buffer must be signed 16- or 32-bit integer, have the same x and y size as the destination buffer, and have an M_LUT attribute.

WarpParam2Id

Specifies the LUT buffer from which ys is determined. This buffer must be signed 16- or 32-bit integer, have the same x and y size as the destination buffer, and have an M_LUT attribute.

If you are not using LUTs to perform the warping, set WarpParam2Id to M_NULL.

OperationMode

Specifies the mode of operation. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_WARP_LUT

 Performs the warping through LUTs.  Performs the warping through LUTs.

  Open   Collapse  M_WARP_POLYNOMIAL

 Performs the warping through a first-order polynomial mapping.  Performs the warping through a first-order polynomial mapping.

      [Combination constants]

 The value below can be added to M_WARP_LUT.

  Open   Collapse  Value
Description

  Open   Collapse  M_FIXED_POINT + n

 Specifies the number of fractional bits for the source point (xs, ys). To do so, add the define M_FIXED_POINT + n to M_WARP_LUT where n >=
                        0.  Specifies the number of fractional bits for the source point (xs, ys) ...

 If nothing is added to M_WARP_LUT, it is assumed that there are no fractional bits in the coordinates of the source point (and therefore interpolation is not required).

 Note that this can be done only when performing the warping through LUTs.

 InterpolationMode

 Specifies the interpolation mode.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE.  Same as M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE.

  Open   Collapse  M_BICUBIC

 Specifies bicubic interpolation.  Specifies bicubic interpolation.

  Open   Collapse  M_BILINEAR

 Specifies bilinear interpolation.  Specifies bilinear interpolation.

  Open   Collapse  M_NEAREST_NEIGHBOR

 Specifies nearest neighbor interpolation.  Specifies nearest neighbor interpolation.

      [Combination constants]

 To specify how to determine the value of a destination pixel when its associated point falls outside the source buffer, you can add one of the values below to the InterpolationMode parameter.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_OVERSCAN_CLEAR

 Sets the destination pixel to 0.  Sets the destination pixel to 0.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OVERSCAN_DISABLE

 Leaves the destination pixel as is.  Leaves the destination pixel as is.

a
b

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_OVERSCAN_ENABLE

 Uses pixels from the source buffer's ancestor buffer. If the source buffer is not a child buffer or if the point falls outside the ancestor buffer, leave the destination pixel as is.  Uses pixels from the source buffer's ancestor buffer ...

This is the default value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 Note that when using bicubic interpolation, saturation is performed according to the type of the destination buffer. For the other interpolation modes, no saturation is performed.

ARRAY LUT LUT WARP LUT FIXED POINT +
                     n WARP LUT WARP LUT NEAREST NEIGHBOR OVERSCAN ENABLE      WARP LUT WARP POLYNOMIAL FIXED POINT
                  n  DEFAULT BICUBIC BILINEAR NEAREST NEIGHBOR OVERSCAN CLEAR OVERSCAN DISABLE OVERSCAN ENABLE


MimWatershed

See Also | Example | Availability | MimWarp | MimZoneOfInfluence
User Guide:
Watershed transformations
mimsegment.c
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a watershed transformation.
Syntax
void MimWatershed(
MIL_ID SrcImageId,
MIL_ID MarkerImageId,
MIL_ID DestImageId,
long MinimumVariation,
long ControlFlag
)
Description

This function performs a watershed transformation on the specified source buffer. The catchment basins of the source buffer can be determined from extrema (minima or maxima) in the source buffer and/or from a specified marker image. In the case when no marker image is specified, a valid catchment basin is determined from an extrema when the minimum variation in gray levels of an extremum's catchment basin is equal to or greater than the value specified by the MinimumVariation parameter. In the case when a marker image is specified, each marker of a marker image produces catchment basin(s) by forcing an extremum in the corresponding area(s) of the source buffer.

There are two types of marker images: non-labeled and labeled. In a non-labeled marker image, each group of touching pixels with the value zero in the marker image (known as a marker) starts a catchment basin in the corresponding area of the source image. Specifically, each marker in the marker image forces a extremum in the corresponding area of the source image. Pixels in the marker image are considered touching if they are vertically, horizontally, or diagonally adjacent, that is, if they are "8-connected". Note that each catchment basin in the destination image is given a unique grayscale value, starting at 1.

In a labeled marker image, a marker is a set of pixels that do not have to necessarily touch and that have all the same label value (pixel intensity). Each marker starts a catchment basin in the corresponding area of the source image and each catchment basin of the destination image is assigned the label value of the marker that generated it. Note that, in a labeled marker image, a marker can touch other markers, allowing you to specify adjacent catchment basins. Valid marker label values are 1 to 2n- 2 (where n refers to the number of bits per pixel in the buffer). Pixels with the label value of zero are interpreted as the region of the image that is not a marker. Finally, pixels with the label value of 2n- 1 are considered to be part of a "don't care" mask and are not processed, accelerating the watershed transformation.

You can specify that the destination buffer contain one of the following:

  • Watershed lines. The watershed lines are given the value 0 and all other pixels are given the maximum value in the destination buffer.
  • Labeled catchment basins, without watershed lines. Each catchment basin is assigned a grayscale value greater or equal to 1.
  • Labeled catchment basins and watershed lines. Each catchment basin is assigned a grayscale value greater or equal to 1. Watershed lines are given the value 0.

For more information, see the Watershed transformations section in Chapter 4: Advanced image processing.

Parameters
SrcImageId

Specifies the buffer on which to perform the transform. This buffer can be 8-bit or 16-bit, signed or unsigned.

MarkerImageId

Specifies the buffer to use as a marker image. This buffer can be 8-bit or 16-bit, signed or unsigned. If you are not using a marker image, set this parameter to M_NULL.

The default marker image type is non-labeled. If you want to use a labeled marker image, you must add M_LABELED_MARKER to the ControlFlag parameter.

DestImageId

Specifies the buffer in which to place the results of the transformation. This buffer can be 8-bit or 16-bit, signed or unsigned. The destination buffer can hold 2n - 5 catchment basins, where n refers to the number of bits per pixel in the buffer. Therefore, an 8-bit destination buffer can hold 251 catchment basins and a 16-bit destination buffer can hold 65531 catchment basins.

MinimumVariation

Specifies the minimum variation of gray-level of a catchment basin. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Produces a catchment basin from each extremum in the source buffer. Setting MinimumVariation to 1 will have the same effect.  Produces a catchment basin from each extremum in the source buffer ...

  Open   Collapse  M_OFF

 Specifies that catchment basins will not be determined from extrema in the source buffer. M_NULL will do the same thing.  Specifies that catchment basins will not be determined from extrema in the source buffer ...

  Open   Collapse  Value

 Sets the minimum variation.  Sets the minimum variation.

 ControlFlag

 Specifies how to perform the transformation.  It can be set to any combination of the following seven sets of values below. It can also be set to M_DEFAULT, in which case the default value from each set is used (without M_SKIP_LAST_LEVEL, M_LABELED_MARKER and M_FILL_SOURCE). If no value from a set is specified, its default value is used.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_WATERSHED + M_MINIMA_FILL + M_REGULAR + M_4_CONNECTED.  Same as M_WATERSHED + M_MINIMA_FILL + M_REGULAR + M_4_CONNECTED.

  Open   Collapse  M_BASIN

 Labels catchment basins.  Labels catchment basins.

  Open   Collapse  M_WATERSHED

 Calculates watershed lines.  Calculates watershed lines.

  Open   Collapse  M_WATERSHED + M_BASIN

 Labels catchment basin and calculates watershed lines.  Labels catchment basin and calculates watershed lines.

      [Combination constants]

 To specify whether to use the source buffer's minima or maxima when determining catchment basins from extrema in the source buffer, you must add one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_MAXIMA_FILL

 Uses the source buffer's maxima.  Uses the source buffer's maxima.

  Open   Collapse  M_MINIMA_FILL

 Uses the source buffer's minima.  Uses the source buffer's minima ...

This is the default value.

      [Combination constants]

 To specify how the watershed lines are drawn, you must add one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_REGULAR

 Traces the watershed lines exactly.  Traces the watershed lines exactly ...

This is the default value.

  Open   Collapse  M_STRAIGHT_WATERSHED

 Forces the watershed lines to be straight. Note that selecting M_STRAIGHT_WATERSHED automatically selects the M_SKIP_LAST_LEVEL setting.  Forces the watershed lines to be straight ...

      [Combination constants]

 To specify whether 4 or 8-connected watershed lines will be used, you must add one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_4_CONNECTED

 Uses 4-connected watershed lines.  Uses 4-connected watershed lines ...

This is the default value.

  Open   Collapse  M_8_CONNECTED

 Uses 8-connected watershed lines.  Uses 8-connected watershed lines.

      [Combination constants]

 To prevent an extremum's zone of influence from extending past the minimum and maximum gray level, you can add the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_SKIP_LAST_LEVEL

 Prevents an extremum's zone of influence from extending beyond Lmax - 1 (for a minimum) or Lmin - 1 (for a maximum), where Lmax is the maximum gray level in the image and Lmin is the minimum gray level.  Prevents an extremum's zone of influence from extending beyond Lmax - 1 (for a minimum) or Lmin - 1 (for a maximum), where Lmax is the maximum gray level in the image and Lmin is the minimum gray level ...

      [Combination constants]

 To denote that the marker image is labeled, you can add the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_LABELED_MARKER

 Specifies that the marker image is a labeled marker image.  Specifies that the marker image is a labeled marker image.

      [Combination constants]

 The following value can be added to remove any unwanted extrema from the source image for any subsequent watershed transformation. It removes the extrema by filling the catchment basins of unwanted extrema until they become plateaus.

  Open   Collapse  Value
Description

  Open   Collapse  M_FILL_SOURCE

 Fill all local basins of a valid catchment basin in the source image.  Fill all local basins of a valid catchment basin in the source image.

LABELED MARKER DEFAULT SKIP LAST LEVEL LABELED MARKER FILL SOURCE WATERSHED MINIMA FILL REGULAR 4 CONNECTED STRAIGHT WATERSHED SKIP LAST LEVEL     DEFAULT OFF    DEFAULT BASIN WATERSHED WATERSHED
                M BASIN MAXIMA FILL MINIMA FILL REGULAR STRAIGHT WATERSHED 4 CONNECTED
                   8 CONNECTED SKIP LAST LEVEL LABELED MARKER FILL SOURCE


MimZoneOfInfluence

Example | Availability | MimWatershed
There are no examples containing MimZoneOfInfluence().
Not available in MIL-Lite

Available in MIL
Synopsis
Perform a zone of influence detection.
Syntax
void MimZoneOfInfluence (
MIL_ID SrcImageBufId,
MIL_ID DestImageBufId,
long OperationFlag
)
Description

This function separates an image into zones, according to how much of a blob's surrounding background is within the blob's territorial boundaries, or "zone of influence". The image is considered to be binary, with background pixels equal to 0 (black), and all non-zero pixels treated as blobs. It gives every pixel in a blob's zone of influence the same value. Each zone of influence is numbered consecutively, beginning with 1. A blob's zone of influence consists of all pixels closer to that blob than to any other blob. There are as many zones as blobs.

Parameters
SrcImageBufId

Specifies the identifier of the source of the operation. This parameter must be given an image buffer identifier.

DestImageBufId

Specifies the identifier of the destination of the resulting image. This parameter must be given an image buffer identifier.

The destination buffer should be deep enough to hold the maximum number of zones (blobs). The maximum label value is 2n - 5, where n is the depth of the destination buffer in bits. For example, an 8-bit buffer can be used for a maximum of 251 blobs and a 16-bit buffer can be used for a maximum of 65531 blobs. Note that if the destination buffer depth is too small, several zones might be given the same value.

OperationFlag

Controls the type of 3x3 distance matrix used for the operation. The following table shows each value's respective 3x3 distance matrix for calculating the distance to a neighboring pixel, which is then used for the zone of influence computation.

This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Same as M_CHESSBOARD.  Same as M_CHESSBOARD.

  Open   Collapse  M_CHAMFER_3_4

 Uses a distance algorithm that makes a better approximation to actual Euclidean distance, and is therefore more accurate than M_CHESSBOARD.  Uses a distance algorithm that makes a better approximation to actual Euclidean distance, and is therefore more accurate than M_CHESSBOARD ...

 This is the 3x3 distance matrix:

  Open   Collapse  M_CHESSBOARD

 Specifies a chessboard matrix. This operation is faster than M_CHAMFER_3_4.  Specifies a chessboard matrix ...

 This is the 3x3 distance matrix:

Remark

  •  In-place processing is supported, but the source and destination image buffers cannot partially overlap (a situation that can only occur when using child buffers).
    •

CHESSBOARD CHESSBOARD CHAMFER 3 4    DEFAULT CHAMFER 3 4  CHESSBOARD


meas

Mmeas functions

Example | Availability
There are no examples containing meas().
Not available in MIL-Lite

Available in MIL
Synopsis
The basic measurement module is a set of functions that can be used to take measurements using spatial reference positions in images. The control allows you to find sets of markers in an image, based on differences in pixel intensities. Upon finding a marker, the control returns the marker's spatial reference position and measures such features as its width and angle. The measurement control can operate on 8-bit or 16-bit unsigned grayscale images. Measurements are made and results are returned with subpixel accuracy.
Functions
  • MmeasAllocContext
  • MmeasAllocMarker
  • MmeasAllocResult
  • MmeasCalculate
  • MmeasControl
  • MmeasDraw
  • MmeasFindMarker
  • MmeasFree
  • MmeasGetResult
  • MmeasGetResultSingle
  • MmeasInquire
  • MmeasRestoreMarker
  • MmeasSaveMarker
  • MmeasSetMarker
  • MmeasStream


MmeasAllocContext

See Also | Example | Availability | MmeasAllocMarker
User Guide:
Steps to finding and obtaining measurements of markers

Reference:
MmeasCalculate
MmeasControl
MmeasFindMarker
MmeasFree
MsysAlloc
There are no examples containing MmeasAllocContext().
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a measurement context.
Syntax
MIL_ID MmeasAllocContext (
MIL_ID SystemId,
long ControlFlag,
MIL_ID *ContextIdPtr
)
Description

This function allocates a measurement context on the specified system. Measurement context settings are used to control the behavior of measurement operations (MmeasFindMarker() and MmeasCalculate()). When the measurement context is no longer required, you should release its memory, using MmeasFree().

Note, upon allocation of an application, a default measurement context is automatically allocated. Rather than using MmeasAllocContext() to allocate a measurement context, you can use this default measurement context, by specifying M_DEFAULT wherever a measurement context identifier is required.

Parameters
SystemId

Specifies the system on which the to allocate the measurement context.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Specifies the allocation control flag and must be set to M_DEFAULT.

 ContextIdPtr

 Specifies the address of the variable in which the measurement context identifier is to be written.  If allocation fails, M_NULL is written as the identifier. Since the MmeasAllocContext() function also returns the marker identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the measurement context identifier. If allocation fails, M_NULL is returned.

Default values

 These measurement context control types are set to the following default values upon allocation and can be changed at any time, using MmeasControl():

Characteristic | Default Value
M_PIXEL_ASPECT_RATIO | 1.0
M_PIXEL_ASPECT_RATIO_INPUT | M_CORRECTED
M_PIXEL_ASPECT_RATIO_OUTPUT | M_CORRECTED

PIXEL ASPECT RATIO PIXEL ASPECT RATIO INPUT CORRECTED PIXEL ASPECT RATIO OUTPUT CORRECTED  DEFAULT HOST


MmeasAllocMarker

See Also | Example | Availability | MmeasAllocContext | MmeasAllocResult
User Guide:
Steps to finding and obtaining measurements of markers
Marker characteristics

Reference:
MmeasCalculate
MmeasFindMarker
MmeasFree
MmeasSetMarker
MsysAlloc
mcal.c
mmeas.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a measurement marker.
Syntax
MIL_ID MmeasAllocMarker(
MIL_ID SystemId,
long MarkerType,
long ControlFlag,
MIL_ID *MarkerIdPtr
)
Description

This function allocates a measurement marker on the specified system. Once allocated, a marker's characteristics can be specified, using MmeasSetMarker(). For an edge or stripe marker, these characteristics are used as the criteria for finding the marker in a target image. An edge or stripe marker can be located in a target image and its measurements taken, using MmeasFindMarker(). Once found, an edge or stripe can then be used as a reference position in calculations involving two markers (MmeasCalculate()). A point marker cannot be searched for, but is placed in the required location as a reference position.When the marker is no longer required, release its memory, using MmeasFree().

Parameters
SystemId

Specifies the system on which to allocate the marker.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 MarkerType

 Specifies the type of marker to allocate.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_EDGE

 An edge.  An edge.

  Open   Collapse  M_POINT

 A single point.  A single point.

  Open   Collapse  M_STRIPE

 A pair of edges.  A pair of edges.

 Any of the above types can be a multiple marker by changing the number of occurrences (M_NUMBER) with MmeasSetMarker(). A multiple marker is more than one instance of the same point, edge, or stripe characteristics.

 ControlFlag

 Specifies the allocation control flag.  This parameter must be set to M_DEFAULT.

 MarkerIdPtr

 Specifies the address of the variable in which the marker identifier is to be written.  Since the MmeasAllocMarker() function also returns the marker identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the marker identifier. If allocation fails, M_NULL is returned.

Default values

 Marker characteristics are set to the following default values upon allocation and can be changed at any time, using MmeasSetMarker(). Note, a characteristic with the value M_ANY will not be considered as a criteria for finding the marker in a target image.

Characteristic | Default Value
Number of points, edges, or stripes | 1
Spacing between edges or stripes | M_ANY
Spacing variation | M_ANY
Marker orientation | M_VERTICAL (vertical orientation)
Marker polarity | M_ANY for edge markers. M_ANY for the first (from top-left) edge of a stripe marker. M_OPPOSITE (opposite polarity from the first edge) for the second edge of a stripe marker.
Marker contrast | M_ANY
Marker contrast variation | M_ANY
Marker width | M_ANY
Marker width variation | M_ANY
Marker position | M_ANY
Marker position variation | M_ANY
Size of measurement box | M_DEFAULT (image size)
Origin of measurement box | Top-left corner of the image X-coordinate = 0.0 Y-coordinate = 0.0
Measurement box's center | M_DEFAULT (image size)
Measurement box's angle | 0.0
Marker reference | M_DEFAULT (center of the marker)
Edge strength | M_ANY
Edge strength variation | M_ANY
Edge threshold | 2.0 (2%)
Stripe inside edges | M_ANY
Stripe inside-edge variation | M_ANY
Stripe inside position | M_ANY
Box angle mode | M_DISABLE
Box angle delta negative and Box angle delta positive | M_DEFAULT (180° search for a symmetrical stripe marker; 360°, complete rotation, for non-symmetrical).
Box angle tolerance | 5.0°
Box angle accuracy | M_DISABLE
Box angle interpolation | M_BILINEAR
Box angle reference | M_BOX_CENTER
Weight factors | Weight of 50% to the strength of an edge and the remaining 50% to any other characteristics not set to M_ANY.

ANY ANY VERTICAL ANY ANY OPPOSITE ANY ANY ANY ANY ANY ANY ANY ANY ANY DISABLE DISABLE BILINEAR BOX CENTER  DEFAULT HOST   EDGE POINT STRIPE


MmeasAllocResult

See Also | Example | Availability | MmeasAllocMarker | MmeasCalculate
User Guide:
Measurements between two markers

Reference:
MmeasCalculate
MmeasFindMarker
MmeasFree
MsysAlloc
There are no examples containing MmeasAllocResult().
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a measurement result buffer.
Syntax
MIL_ID MmeasAllocResult(
MIL_ID SystemId,
long ResultType,
MIL_ID *MeasResultIdPtr
)
Description

This function allocates a buffer, on the specified system, to be used for storing measurement results obtained from a MmeasCalculate() operation. When the result buffer is no longer required, you should release its memory, using MmeasFree(). Note, a result buffer is not required for a MmeasFindMarker() operation.

Parameters
SystemId

Specifies the system on which to allocate the result buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ResultType

 Specifies the type of result buffer to allocate.

 This parameter can be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_CALCULATE.  Same as M_CALCULATE.

  Open   Collapse  M_CALCULATE

 Specifies to allocate a result buffer for a MmeasCalculate() operation.  Specifies to allocate a result buffer for a MmeasCalculate() operation.

 MeasResultIdPtr

 Specifies the address of the variable in which the measurement result identifier is to be written.  If allocation fails, M_NULL is returned as the identifier. Since the MmeasAllocResult() function also returns the measurement result identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the measurement result identifier. If allocation fails, M_NULL is returned.

CALCULATE  DEFAULT HOST   DEFAULT CALCULATE


MmeasCalculate

See Also | Example | Availability | MmeasAllocResult | MmeasControl
User Guide:
Edge markers: fundamental characteristics
Edge markers: advanced characteristics
Measurements between two markers

Reference:
MmeasControl
MmeasFindMarker
MmeasGetResult
MmeasSetMarker
There are no examples containing MmeasCalculate().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Calculate measurements between two markers.
Syntax
void MmeasCalculate(
MIL_ID ContextId,
MIL_ID Marker1Id,
MIL_ID Marker2Id,
MIL_ID MeasResultId,
long MeasurementList
)
Description

This function calculates the specified measurements between two markers. Edge and stripe markers must have been previously located in the target image with MmeasFindMarker(). The position of point markers must have been previously set, using MmeasSetMarker().

The measurement context settings will control the behavior of this function and can be set with MmeasControl().

Results are stored in the specified measurement result buffer and can be obtained using MmeasGetResult().

Parameters
ContextId

Specifies the identifier of the measurement context. This parameter must be given a valid measurement context identifier or can be set to M_DEFAULT, in which case, the default measurement context of the current MIL application will be used.

Marker1Id

Specifies the identifier of the marker to use as the first reference position for calculating measurements.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The marker (Marker1Id) must be allocated on the same system as the measurement context (ContextId). If it is not, an error will occur.

Marker2Id

Specifies the identifier of the marker to use as the second reference position for calculating measurements.

If Marker1Id and Marker2Id are multiple markers, then calculations are made using the edges or stripes of the first marker and the corresponding points, edges, or stripes in the second marker, for the entire first marker's number of points, edges, or stripes. The number of calculations performed is limited to the smallest number of points, edges, or stripes held in either marker (that is, if a marker contains only one point, edge, or stripe, then only one calculation is performed, regardless of the number of points, edges, or stripes contained in the first marker).

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The marker (Marker2Id) must be allocated on the same system as the measurement context (ContextId). If it is not, an error will occur.

MeasResultId

Specifies the identifier of the result buffer in which to place results.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The result buffer (MeasResultId) must be allocated on the same system as the measurement context (ContextId). If it is not, an error will occur.

MeasurementList

Specifies which measurement(s) to calculate. The table below lists the measurements that can be calculated. To calculate more than one measurement, add the values together (for example, M_DISTANCE + M_ANGLE):

Open Collapse Value Description
Open Collapse M_DEFAULT

 Same as M_ANGLE + M_DISTANCE + M_LINE_EQUATION.  Same as M_ANGLE + M_DISTANCE + M_LINE_EQUATION.

  Open   Collapse  M_ANGLE

 Calculates the angle of the line joining two markers, relative to the positive X-axis. The value can be any between 0° and 360°.  Calculates the angle of the line joining two markers, relative to the positive X-axis ...

  Open   Collapse  M_DISTANCE

 Calculates the distance between both markers.  Calculates the distance between both markers.

  Open   Collapse  M_LINE_EQUATION

 Calculates the equation of the line joining both markers.  Calculates the equation of the line joining both markers.

DISTANCE ANGLE ANGLE DISTANCE LINE EQUATION      DEFAULT ANGLE DISTANCE LINE EQUATION


MmeasControl

Example | Availability | MmeasCalculate | MmeasDraw
There are no examples containing MmeasControl().
Not available in MIL-Lite

Available in MIL
Synopsis
Control a measurement context setting.
Syntax
void MmeasControl(
MIL_ID ContextId,
long ControlType,
double ControlValue
)
Description

This function sets the specified measurement context processing control. Measurement context settings control the behavior of measurement operations.

Parameters
ContextId

Specifies the identifier of the measurement context.

ControlType

Specifies the processing feature to control. Note, when referring to "data relative to the corrected image", this means that the data (for example, a specified position) is given as if it were relative to an image resized by a factor equal to the aspect ratio.

See the Parameter associations section for possible values.

ControlValue

Specifies the value needed for the control. Note, when referring to "data relative to the corrected image", this means that the data (for example, a specified position) is given as if it were relative to an image resized by a factor equal to the aspect ratio.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_PIXEL_ASPECT_RATIO |  | Sets the ratio of the width of the pixel to its height. Sets the ratio of the width of the pixel to its height ...
 | Value | Specifies the pixel width to pixel height ratio. The default value is 1.0.
Open Collapse M_PIXEL_ASPECT_RATIO_INPUT |  | Sets how the measurement module interprets specified measurement characteristics relative to the pixel aspect ratio. Sets how the measurement module interprets specified measurement characteristics relative to the pixel aspect ratio ...
 | M_CORRECTED | Specifies measurement characteristics are relative to the corrected image. This is the default value.
 | M_NORMAL | Specifies that input data is relative to the given image. (ratio of 1.0)
Open Collapse M_PIXEL_ASPECT_RATIO_OUTPUT |  | Sets how the measurement module returns results relative to the pixel aspect ratio. Sets how the measurement module returns results relative to the pixel aspect ratio ...
 | M_CORRECTED | Specifies that results are relative to the corrected image. This is the default value.
 | M_NORMAL | Specifies that output data is relative to the given image. (ratio of 1.0)

PIXEL ASPECT RATIO PIXEL ASPECT RATIO INPUT CORRECTED NORMAL PIXEL ASPECT RATIO OUTPUT CORRECTED NORMAL


MmeasDraw

See Also | Example | Availability | MmeasControl | MmeasFindMarker
User Guide:
Steps to finding and obtaining measurements of markers

Reference:
MgraAlloc
MmeasCalculate
MmeasFindMarker
MmeasSetMarker
mcal.c
mmeas.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Draw specific expected marker characteristics or features of marker occurrences or measurement results in the destination image buffer.
Syntax
void MmeasDraw(
MIL_ID GraphContId,
MIL_ID MarkerOrResultId,
MIL_ID DestImageId,
long Operation,
long Index,
long ControlFlag
)
Description

This function draws specific expected marker characteristics or features of marker occurrences or measurement results in the destination buffer. This function can draw multiple features at once.

Parameters
GraphContId

Specifies the graphics context to use. This parameter should be set to one of the following:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies to use the default graphics context.  Specifies to use the default graphics context.

  Open   Collapse  MIL graphics context identifier

 Specifies a valid graphics context identifier, which you have allocated using MgraAlloc().  Specifies a valid graphics context identifier, which you have allocated using MgraAlloc().

 MarkerOrResultId

 Specifies the identifier of the measurement marker buffer or the measurement result buffer from which to retrieve the features to draw. Note that the measurement marker buffer stores both the expected marker characteristics (specified using MmeasSetMarker()), and the actual marker characteristics found in the target image (using MmeasFindMarker()). To specify which features to retrieve from this buffer, use the ControlFlag parameter.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

 The marker or result buffer must be allocated on the same system as the graphics context buffer (GraphContId). If it is not, an error will occur.

 DestImageId

 Specifies the identifier of the destination image buffer in which to draw.  The buffer can be any supported MIL image buffer. By drawing into a display's overlay buffer, you can also annotate an image non-destructively.

 Operation

 Specifies the type of operation to perform.  The possible Operation parameter values in the tables below can be added together to draw multiple features at once.

 The possible Operation parameter values for a measurement marker buffer are:

  Open   Collapse  Value
Description

  Open   Collapse  M_DRAW_POSITION

 Draws a cross at the expected or found position and angle of the marker.  Draws a cross at the expected or found position and angle of the marker ...

 Note that when drawing at the expected position, the expected marker position must have been set to a specific numeric value using MmeasSetMarker() with M_POSITION_X and M_POSITION_Y. The expected position cannot be set to M_ANY (default value); an error message is generated.

 This setting can be combined with other values to control its effect. See below.

 The possible Operation parameter values for an edge or stripe measurement marker buffer are:

  Open   Collapse  Value
Description

  Open   Collapse  M_DRAW_BOX

 Draws the measurement box, respecting the position and angle.  Draws the measurement box, respecting the position and angle.

  Open   Collapse  M_DRAW_BOX_CENTER

 Draws the measurement box center, respecting the position and angle.  Draws the measurement box center, respecting the position and angle.

  Open   Collapse  M_DRAW_EDGES

 Draws a line along the expected or found edges of the marker.  Draws a line along the expected or found edges of the marker ...

 Note that when drawing the expected edges, the expected marker position must have been set to a specific numeric value using MmeasSetMarker() with M_POSITION_X and M_POSITION_Y. The expected position cannot be set to M_ANY (default value); an error message is generated.

  Open   Collapse  M_DRAW_POSITION_VARIATION

 Draws an H-type line (|-|) indicating possible position variation of the marker.  Draws an H-type line (|-|) indicating possible position variation of the marker ...

 Note that when drawing the expected position variation, the expected position variation must have been set to a specific numeric value using MmeasSetMarker() with M_POSITION_VARIATION. The expected position variation cannot be set to M_ANY (default value); an error message is generated.

  Open   Collapse  M_DRAW_WIDTH

 Draws an H-type line (|-|) along the expected or found width of the stripe marker.  Draws an H-type line (|-|) along the expected or found width of the stripe marker ...

 Note that when drawing along the expected stripe width, the expected width must have been set to a specific numeric value using MmeasSetMarker() with M_WIDTH. The expected width cannot be set to M_ANY (default value); an error message is generated.

 This setting is not available for an edge measurement marker buffer.

  Open   Collapse  M_DRAW_WIDTH_VARIATION

 Draws an H-type line (|-|) indicating possible width variation of the marker.  Draws an H-type line (|-|) indicating possible width variation of the marker ...

 Note that when drawing the expected width variation, the expected width variation must have been set to a specific numeric value using MmeasSetMarker() with M_WIDTH_VARIATION. The expected width variation cannot be set to M_ANY (default value); an error message is generated.

 This setting is not available for an edge measurement marker buffer.

 Unless otherwise specified, the possible Operation parameter values for result occurrences in a measurement marker buffer or for results in a measurement result buffer are:

  Open   Collapse  Value
Description

  Open   Collapse  M_DRAW_EDGES_PROFILE

 Draws the results' edge profile. This setting is not available for measurement marker buffers from a MmeasCalculate() operation.  Draws the results' edge profile ...

 This setting can be combined with other values to control its effect. See below.

  Open   Collapse  M_DRAW_LINE

 Draws a line joining 2 markers.  Draws a line joining 2 markers.

  Open   Collapse  M_DRAW_SPACING

 Draws an H-type line (|-|) indicating the found spacing. This setting is not available for measurement marker buffers from a MmeasCalculate() operation.  Draws an H-type line (|-|) indicating the found spacing ...

      [Combination constants]

 Unless otherwise specified, the values below can be added to M_DRAW_POSITION and M_DRAW_EDGES_PROFILE.

  Open   Collapse  Value
Description

  Open   Collapse  M_DRAW_IN_BOX

 Draws the edge profile at the position and angle of the measurement box.  Draws the edge profile at the position and angle of the measurement box ...

 This can be only added to M_DRAW_EDGES_PROFILE.

  Open   Collapse  M_EDGE_FIRST

 Draws the specified feature for the first exterior edge of a stripe.  Draws the specified feature for the first exterior edge of a stripe ...

 Note that when drawing expected features, the expected width and orientation must have been set to a specific numeric value using MmeasSetMarker() with M_WIDTH_VARIATION and M_ORIENTATION. The expected width and orientation cannot be set to M_ANY (default value); an error message is generated.

  Open   Collapse  M_EDGE_SECOND

 Draws the specified feature for the second exterior edge of a stripe.  Draws the specified feature for the second exterior edge of a stripe ...

 Note that when drawing expected features, the expected width and orientation must have been set to a specific numeric value using MmeasSetMarker() with M_WIDTH_VARIATION and M_ORIENTATION. The expected width and orientation cannot be set to M_ANY (default value); an error message is generated.

 Index

 Specifies the index of the result to draw for a measurement marker buffer or the measurement result buffer.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_ALL.  Same as M_ALL ...

 When drawing the expected features of a marker, this parameter must be set to M_DEFAULT. Note that when drawing the expected features of a marker which is a multiple marker, only the first instance of the marker is drawn.

  Open   Collapse  M_ALL

 Draws the result for all occurrences.  Draws the result for all occurrences.

  Open   Collapse  Value

 Specifies the index of the result to draw.  Specifies the index of the result to draw.

 ControlFlag

 Specifies whether to draw the expected features of a marker or the features of a result.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_RESULT.  Same as M_RESULT.

  Open   Collapse  M_MARKER

 Draws the expected features of a marker (specified using MmeasSetMarker()).  Draws the expected features of a marker (specified using MmeasSetMarker()).

 Note that the MarkerOrResultId parameter must be set to a measurement marker buffer.

  Open   Collapse  M_RESULT

 Draws the features of a result.  Draws the features of a result.

POSITION X POSITION Y POSITION X POSITION Y POSITION VARIATION WIDTH WIDTH VARIATION  DRAW POSITION DRAW EDGES PROFILE DRAW EDGES PROFILE ALL DEFAULT RESULT WIDTH VARIATION  ORIENTATION  DEFAULT     DRAW POSITION  DRAW BOX  DRAW BOX CENTER  DRAW EDGES  DRAW POSITION VARIATION  DRAW WIDTH  DRAW WIDTH VARIATION  DRAW EDGES PROFILE  DRAW LINE  DRAW SPACING  DRAW IN BOX EDGE FIRST EDGE SECOND  DEFAULT ALL   DEFAULT  MARKER RESULT


MmeasFindMarker

See Also | Example | Availability | MmeasDraw | MmeasFree
User Guide:
Steps to finding and obtaining measurements of markers
Measurement box
Marker characteristics
Edge markers: fundamental characteristics
Edge markers: advanced characteristics
Stripe markers: fundamental characteristics
Stripe markers: advanced characteristics
Measurements between two markers

Reference:
MmeasControl
MmeasGetResult
MmeasGetResultSingle
MmeasSetMarker
mcal.c
mmeas.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Find a marker in an image and take the specified measurements.
Syntax
void MmeasFindMarker(
MIL_ID ContextId,
MIL_ID ImageBufId,
MIL_ID MarkerId,
long MeasurementList
)
Description

This function finds an edge or a stripe marker in the image and takes the measurements specified in the measurement list. The marker's characteristics are used to help locate the marker and can be set using MmeasSetMarker().

Measurement context settings will control the behavior of this function and can be set, using MmeasControl().

It is recommended that the measurement box be set to an angle close to that of the required marker (that is, within the marker's particular rotation tolerance) to ensure that the marker is found and that results are accurate: the greater the angle of the marker relative to the search region, the greater the distortion of the marker's actual characteristics and the chance that the marker might not be successfully located with MmeasFindMarker().

Results are stored with the marker (not in a result buffer), and can be obtained using MmeasGetResult().

Note, all positional results are relative to the top-left pixel in the target image, or the origin of the coordinate system if the target is a calibrated image.

Parameters
ContextId

Specifies the identifier of the measurement context. This parameter must be given a valid measurement context identifier or can be set to M_DEFAULT, in which case, the default measurement context of the current MIL application will be used.

ImageBufId

Specifies the identifier of the image buffer in which to locate the marker.

MarkerId

Specifies the identifier of the marker to be located in the image.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The marker (MarkerId) must be allocated on the same system as the measurement context (ContextId). If it is not, an error will occur.

MeasurementList

Specifies which measurement(s) to perform. To take more than one measurement, add the values together (for example, M_POSITION + M_ANGLE). Use M_DEFAULT to select all of the measurements.

The measurement list can contain the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Takes all of the measurements below.  Takes all of the measurements below.

  Open   Collapse  M_ANGLE

 Determines the angle of the marker relative to the positive X-axis of the target image. The value can be any between 0° and 360°.  Determines the angle of the marker relative to the positive X-axis of the target image ...

  Open   Collapse  M_CONTRAST

 Determines the typical difference in average grayscale values between the start and end of the intensity transition (edge width) from which an edge is established. For a stripe marker, the values should be the typical difference in average grayscale values for each of its edges.  Determines the typical difference in average grayscale values between the start and end of the intensity transition (edge width) from which an edge is established ...

  Open   Collapse  M_EDGE_INSIDE

 Determines the number of edges located between the two exterior edges of a stripe marker.  Determines the number of edges located between the two exterior edges of a stripe marker.

  Open   Collapse  M_LENGTH

 Determines the length of the marker, in pixels or real-world units. The length is limited to the dimensions of the measurement box.  Determines the length of the marker, in pixels or real-world units ...

  Open   Collapse  M_LINE_EQUATION

 Determines the equation of the mean line following an edge. When performing this calculation for a stripe marker, three line equations are calculated: the line equation of the stripe's first edge, the line equation of the stripe's second edge, and the mean of the line equations of both its edges.  Determines the equation of the mean line following an edge ...

  Open   Collapse  M_NUMBER

 Determines the number of edges or stripes found in the target image. This measurement is always selected in the measurement list.  Determines the number of edges or stripes found in the target image ...

  Open   Collapse  M_POLARITY

 Determines whether the edge (or edges of a stripe marker) are rising (positive polarity) or falling (negative polarity).  Determines whether the edge (or edges of a stripe marker) are rising (positive polarity) or falling (negative polarity).

  Open   Collapse  M_POSITION

 Determines the X and Y-coordinates of the center of the marker within the measurement box.  Determines the X and Y-coordinates of the center of the marker within the measurement box.

  Open   Collapse  M_POSITION_VARIATION

 Determines the position variation (or uncertainty) of the marker, in pixels or real-world units. If the marker is an edge, the position variation is equal to half of its edge width. If the marker is a stripe, the position variation is the sum of the position variations of both of its edges.  Determines the position variation (or uncertainty) of the marker, in pixels or real-world units ...

  Open   Collapse  M_WIDTH

 Determines the edge width of an edge marker or the width of a stripe marker in pixels or real-world units. The edge width of an edge marker is a measure of the transition in grayscale values from which it is established. The width of a stripe marker is the average distance between its edges and is calculated at the angle of the measurement box.  Determines the edge width of an edge marker or the width of a stripe marker in pixels or real-world units ...

  Open   Collapse  M_WIDTH_VARIATION

 Determines the width variation (or uncertainty) of a stripe marker, in pixels or real-world units. It is the sum of the position variations of both of its edges.  Determines the width variation (or uncertainty) of a stripe marker, in pixels or real-world units ...

      [Combination constants]

 The values below can be added to M_POSITION.

  Open   Collapse  Value
Description

  Open   Collapse  M_BOX_EDGE_VALUES

 Determines the edge value for every possible profile value of the measurement box. Therefore, for a vertical marker, the number of returned values is equal to the width of the measurement box; for a horizontal marker, the number is equal to the height. The value is represented as a normalized percentage of the image buffer's maximum possible value.  Determines the edge value for every possible profile value of the measurement box ...

  Open   Collapse  M_EDGE_STRENGTH

 Determines the minimum/maximum edge value along the edge width of an edge.  Determines the minimum/maximum edge value along the edge width of an edge.

  Open   Collapse  M_ORIENTATION

 Determines the orientation of the marker.  Determines the orientation of the marker.

  Open   Collapse  M_POSITION_MAX

 Determines the X and Y-coordinates of the maximum position of an edge in a marker.  Determines the X and Y-coordinates of the maximum position of an edge in a marker ...

 For a striper marker, this determines the average value of maximum positions unless otherwise specified (using MmeasGetResult() or MmeasGetResultSingle() with M_EDGE_FIRST or M_EDGE_SECOND).

 The X-coordinate is the maximum position within the edge width from which an edge is established. The Y-coordinate is the Y-coordinate of the measurement box center. The maximum position is always on the side of the measurement box furthest from the origin, regardless of how the measurement box is rotated. The diagram below illustrates an edge transion curve (a profile of gradual transition from dark to light) and a measurement box.

  Open   Collapse  M_POSITION_MIN

 Determines the X and Y-coordinates of the minimum position of an edge in a marker.  Determines the X and Y-coordinates of the minimum position of an edge in a marker ...

 For a striper marker, this determines the average value of minimum positions unless otherwise specified (using MmeasGetResult() or MmeasGetResultSingle() with M_EDGE_FIRST or M_EDGE_SECOND).

 The X-coordinate is the minimum position within the edge width from which an edge is established. The Y-coordinate is the Y-coordinate of the measurement box center. The minimum position is always on the side of the measurement box adjacent the origin, regardless of how the measurement box is rotated. The diagram in M_POSITION_MAX illustrates an edge transion curve and a measurement box.

  Open   Collapse  M_SPACING

 Determines the inter-edge or inter-stripe spacing of a multiple marker.  Determines the inter-edge or inter-stripe spacing of a multiple marker.

POSITION ANGLE DEFAULT POSITION     DEFAULT ANGLE CONTRAST EDGE INSIDE LENGTH LINE EQUATION NUMBER POLARITY POSITION POSITION VARIATION WIDTH WIDTH VARIATION BOX EDGE VALUES EDGE STRENGTH ORIENTATION POSITION MAX POSITION MIN SPACING


MmeasFree

See Also | Example | Availability | MmeasFindMarker | MmeasGetResult
User Guide:
Steps to finding and obtaining measurements of markers

Reference:
MmeasAllocContext
MmeasAllocMarker
MmeasAllocResult
mcal.c
mmeas.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free a measurement context, marker, or result buffer.
Syntax
void MmeasFree(
MIL_ID MeasId
)
Description

This function deletes the specified marker, result buffer, or context identifier and releases any memory associated with it.

Parameter
MeasId

Specifies the measurement identifier to free. The identifier must have been successfully allocated with MmeasAllocMarker(), MmeasAllocResult(), or MmeasAllocContext() prior to calling this function.


MmeasGetResult

See Also | Example | Availability | MmeasFree | MmeasGetResultSingle
User Guide:
Steps to finding and obtaining measurements of markers
Edge markers: fundamental characteristics
Edge markers: advanced characteristics
Stripe markers: fundamental characteristics
Stripe markers: advanced characteristics
Measurements between two markers

Reference:
McalControl
MmeasAllocMarker
MmeasAllocResult
MmeasCalculate
MmeasFindMarker
mcal.c
mmeas.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified type of result(s) for all edges, stripes, or points, from a measurement marker or result buffer.
Syntax
void MmeasGetResult(
MIL_ID MarkerOrMeasResultId,
long ResultType,
void *FirstResultArrayPtr,
void *SecondResultArrayPtr
)
Description

This function retrieves the result(s) of the specified type for all edges, stripes or points from a measurement marker or result buffer. Results should be obtained from a marker if an MmeasFindMarker() operation was performed or from a measurement result buffer if an MmeasCalculate() operation was performed.

Note that if your target image has been associated with a calibration object, positional results are by default returned in real-world units. To have results returned in pixel units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to M_PIXEL. All positional results are relative to the top-left pixel in the target image, or to the origin of the coordinate system of a calibrated image.

For certain result types, two values can be returned for a stripe marker: the value for the first edge is returned to FirstResultArrayPtr and that of the second edge to SecondResultArrayPtr. For an edge marker, all results are returned to FirstResultArrayPtr, and SecondResultArrayPtr must be set to M_NULL.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set the FirstResultArrayPtr and SecondResultArrayPtr parameters to M_NULL. When both result parameters are set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when at least one result parameter is passed an array. You must ensure that the result arrays are sufficiently large to hold all the requested results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Note, if the request queued does not return results in the second result array, the second array pointer is not padded for that particular request, when the queue is executed.

Parameters
MarkerOrMeasResultId

Specifies the identifier of the measurement marker buffer (allocated with MmeasAllocMarker()) or measurement result buffer (allocated with MmeasAllocResult()) from which to retrieve results.

ResultType

Specifies the type of result(s) to retrieve.

Note that, unless otherwise specified, marker results are returned in FirstResultArrayPtr; when this is the case, SecondResultArrayPtr must be set to M_NULL.

If retrieving a result from a marker or measurement result buffer, ResultType can be set to one of the values specified in the table below.

Unless otherwise specified, the following values require that you pass the FirstResultArrayPtr parameter the address of an array of type double (large enough to hold the results of all instances of the marker) and the SecondResultArrayPtr parameter the address of an array of type double (large enough to hold the results of all instances of the marker).

Open Collapse Value Description
Open Collapse M_ANGLE

Retrieves the angle, in degrees. Retrieves the angle, in degrees ...

If retrieved from a marker, M_ANGLE returns the angle of the marker relative to the positive X-axis. If retrieved from a measurement result buffer, M_ANGLE returns the angle of the line joining the two markers relative to the positive X-axis.

FirstResultArrayPtr info

Return values:
0.0 to 360.0 Angle, in degrees

Open Collapse M_LINE_EQUATION

Retrieves the line equation. Retrieves the line equation ...

If retrieved from a marker, M_LINE_EQUATION returns the mean line of the marker. If retrieved from a measurement result buffer, M_LINE_EQUATION returns the equation of the line joining two markers.

FirstResultArrayPtr info

Return values:
Value Slope of the equation. When the equation of the line has an infinite slope, the value returned as the slope is M_INFINITE_SLOPE (1.0E+300).

SecondResultArrayPtr info

Return values:
Value Y-intercept of the equation.

Open Collapse M_LINE_EQUATION_INTERCEPT

Retrieves the Y-intercept of the line equation. Retrieves the Y-intercept of the line equation ...

If retrieved from a marker, M_LINE_EQUATION_INTERCEPT returns the Y-intercept of the line equation of the marker. If retrieved from a measurement result buffer, M_LINE_EQUATION_INTERCEPT returns the Y-intercept of the line equation joining two markers.

Open Collapse M_LINE_EQUATION_SLOPE

Retrieves the slope of the line equation. Retrieves the slope of the line equation ...

If retrieved from a marker, M_LINE_EQUATION_SLOPE returns the slope of the marker's line equation. If retrieved from a measurement result buffer, M_LINE_EQUATION_SLOPE returns the slope of the line equation joining the two markers.

FirstResultArrayPtr info

Return values:
Value Slope of the equation. When the equation of the line has an infinite slope, the value returned as the slope is M_INFINITE_SLOPE (1.0E+300).

If retrieving a result from a marker, ResultType can be set to one of the values specified in the table below.

Unless otherwise specified, the following values require that you pass the FirstResultArrayPtr parameter the address of an array of type double (large enough to hold the results of all instances of the marker) and the SecondResultArrayPtr parameter the address of an array of type double (large enough to hold the results of all instances of the marker).

Open Collapse Value Description
Open Collapse M_BOX_CORNER_BOTTOM_LEFT

Retrieves the coordinates of the bottom-left corner of the measurement box. Retrieves the coordinates of the bottom-left corner of the measurement box ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_BOX_CORNER_BOTTOM_RIGHT

Retrieves the coordinates of the bottom-right corner of the measurement box. Retrieves the coordinates of the bottom-right corner of the measurement box ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_BOX_CORNER_TOP_LEFT

Retrieves the coordinates of the top-left corner of the measurement box. Retrieves the coordinates of the top-left corner of the measurement box ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_BOX_CORNER_TOP_RIGHT

Retrieves the coordinates of the top-right corner of the measurement box. Retrieves the coordinates of the top-right corner of the measurement box ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_BOX_EDGE_VALUES

Retrieves the edge values (as a normalized percentage of the buffer's maximum possible value for every profile value of the measurement box). Retrieves the edge values (as a normalized percentage of the buffer's maximum possible value for every profile value of the measurement box) ...

FirstResultArrayPtr info

Return values:
Value Edge value results returned as an array.

Open Collapse M_BOX_EDGE_VALUES_NUMBER

Retrieves the number of edge values to be returned by M_BOX_EDGE_VALUES. Retrieves the number of edge values to be returned by M_BOX_EDGE_VALUES ...

FirstResultArrayPtr info

Return values:
Value Number of edge values returned by M_BOX_EDGE_VALUES.

Open Collapse M_CONTRAST

Retrieves the typical difference in average grayscale values between the start and end of the intensity transition (edge width) from which an edge is established. Retrieves one value for an edge marker, and two for a stripe marker. Retrieves the typical difference in average grayscale values between the start and end of the intensity transition (edge width) from which an edge is established ...

FirstResultArrayPtr info

Return values:
Value Average grayscale difference for first edge.

SecondResultArrayPtr info

Return values:
Value Average grayscale difference for a second edge if a stripe marker.

Open Collapse M_EDGE_INSIDE

Retrieves the number of edges located between the two exterior edges of a stripe marker. Retrieves the number of edges located between the two exterior edges of a stripe marker.

Open Collapse M_EDGE_STRENGTH

Retrieves the maximum edge value variation (as a normalized percentage of the buffer's maximum possible value) of each edge of a marker. Retrieves one value for an edge marker, and two for a stripe marker. Retrieves the maximum edge value variation (as a normalized percentage of the buffer's maximum possible value) of each edge of a marker ...

Open Collapse M_LENGTH

Retrieves the length of the marker, in pixels or real-world units. Retrieves the length of the marker, in pixels or real-world units.

Open Collapse M_NUMBER

Retrieves the number of edges or stripes found in the measurement box. Retrieves the number of edges or stripes found in the measurement box ...

After a call to the MmeasFindMarker() function, the number of elements in the collection is the number of occurrences of edge or stripe marker found in the measurement box.

After a call to the MmeasCalculate() function, the number of elements in the collection is equal to the smallest number of occurrences held in either marker involved in the calculation.

Open Collapse M_ORIENTATION

Retrieves the orientation of the marker. Retrieves the orientation of the marker ...

FirstResultArrayPtr info

Return values:
M_HORIZONTAL, M_VERTICAL (details)
Open Collapse M_POLARITY

Retrieves the polarity of the marker. Retrieves one value for an edge marker, and two for a stripe marker. Retrieves the polarity of the marker ...

FirstResultArrayPtr info

Return values:

M_NEGATIVE, M_POSITIVE (details)

SecondResultArrayPtr info

Return values:

M_NEGATIVE, M_POSITIVE (details)
Open Collapse M_POSITION

Retrieves the coordinates of the marker center in the image. Retrieves the coordinates of the marker center in the image ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_POSITION_MAX

Retrieves the X and Y-coordinates of the maximum position of an edge in a marker. Retrieves the X and Y-coordinates of the maximum position of an edge in a marker ...

For a striper marker, this returns the average value of maximum positions unless otherwise specified (with M_EDGE_FIRST or M_EDGE_SECOND).

The X-coordinate is the maximum position within the edge width from which an edge is established. The Y-coordinate is the Y-coordinate of the measurement box center. The maximum position is always on the side of the measurement box furthest from the origin, regardless of how the measurement box is rotated. The diagram below illustrates an edge transion curve (a profile of gradual transition from dark to light) and a measurement box.

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_POSITION_MIN

Retrieves the X and Y-coordinates of the minimum position of an edge in a marker. Retrieves the X and Y-coordinates of the minimum position of an edge in a marker ...

For a striper marker, this returns the average value of minimum positions unless otherwise specified (with M_EDGE_FIRST or M_EDGE_SECOND).

The X-coordinate is the minimum position within the edge width from which an edge is established. The Y-coordinate is the Y-coordinate of the measurement box center. The minimum position is always on the side of the measurement box adjacent to the origin, regardless of how the measurement box is rotated. The diagram in M_POSITION_MAX illustrates an edge transion curve and a measurement box.

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_POSITION_VARIATION

Retrieves the position variation of the marker, in pixels or real-world units (postive or negative values). Retrieves the position variation of the marker, in pixels or real-world units (postive or negative values).

Open Collapse M_SCORE

Retrieves the confidence score for the MmeasFindMarker() operation, as a percentage. Retrieves the confidence score for the MmeasFindMarker() operation, as a percentage.

Open Collapse M_SPACING

Retrieves the inter-edge or inter-stripe spacing between consecutive edges or stripes. Retrieves the inter-edge or inter-stripe spacing between consecutive edges or stripes.

Open Collapse M_TOTAL_SCORE

Retrieves the average confidence score of all edges or stripes found. Retrieves the average confidence score of all edges or stripes found.

Open Collapse M_VALID_FLAG

Retrieves the flag that denotes whether or not a marker was found. Retrieves the flag that denotes whether or not a marker was found ...

FirstResultArrayPtr info

Return values:
M_FALSE | Marker not found.
M_TRUE | Marker found.

SecondResultArrayPtr info

Return values:
M_FALSE | Marker not found.
M_TRUE | Marker found.
Open Collapse M_WIDTH

Retrieves the edge width of the edge marker or the width of the stripe marker, in pixels or real-world units. Retrieves the edge width of the edge marker or the width of the stripe marker, in pixels or real-world units.

Open Collapse M_WIDTH_VARIATION

Retrieves the width variation of the stripe marker, in pixels or real-world units. Retrieves the width variation of the stripe marker, in pixels or real-world units.

[Combination constants]

One of the following values can be added to the result types listed in the table above.

Open Collapse Value | Description
Open Collapse M_EDGE_FIRST | Retrieves results for the first exterior edge of a stripe, for the requested characteristic. Retrieves results for the first exterior edge of a stripe, for the requested characteristic.
Open Collapse M_EDGE_SECOND | Retrieves results for the second exterior edge of a stripe, for the requested characteristic. Retrieves results for the second exterior edge of a stripe, for the requested characteristic.
Open Collapse M_MAX | Retrieves the maximum value for the requested characteristic in all the edges or stripes found. Only one result is returned. Retrieves the maximum value for the requested characteristic in all the edges or stripes found ...
 |  | FirstResultArrayPtr info Data type: double
Open Collapse M_MEAN | Retrieves the mean value for the requested characteristic in all the edges or stripes found. Only one result is returned. Retrieves the mean value for the requested characteristic in all the edges or stripes found ...
 |  | FirstResultArrayPtr info Data type: double
Open Collapse M_MIN | Retrieves minimum value for the requested characteristic in all the edges or stripes found. Only one result is returned. Retrieves minimum value for the requested characteristic in all the edges or stripes found ...
 |  | FirstResultArrayPtr info Data type: double
Open Collapse M_STANDARD_DEVIATION | Retrieves the standard deviation of the values for the requested characteristic in all the edges or stripes found. Only one result is returned. Retrieves the standard deviation of the values for the requested characteristic in all the edges or stripes found ...
 |  | FirstResultArrayPtr info Data type: double

If results are being obtained from a measurement result buffer (MmeasCalculate()), the ResultType parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the FirstResultArrayPtr parameter the address of an array of type double (large enough to hold the results of all instances of the marker) and the SecondResultArrayPtr parameter the address of an array of type double (large enough to hold the results of all instances of the marker).

Open Collapse Value | Description
Open Collapse M_DISTANCE | Retrieves the distance between two markers, in pixels or real-world units. Retrieves the distance between two markers, in pixels or real-world units.
Open Collapse M_DISTANCE_X | Retrieves the distance on the X-axis between two markers, in pixels or real-world units. Retrieves the distance on the X-axis between two markers, in pixels or real-world units.
Open Collapse M_DISTANCE_Y | Retrieves the distance on the Y-axis between two markers, in pixels or real-world units. Retrieves the distance on the Y-axis between two markers, in pixels or real-world units.

[Combination constants]

The values below can be added to the ResultType parameter to cast the requested information to a required data type. For example, M_DISTANCE_X + M_TYPE_LONG.

Note that M_INVALID is returned if a measurement was not calculated.

Open Collapse Value Description
Open Collapse M_TYPE_LONG

Casts the requested results to a long. Casts the requested results to along ...

FirstResultArrayPtr info

Data type:

  • long
    note: When a single result is returned to either or both FirstResultArrayPtr and SecondResultArrayPtr.
  • array of type long
    Array size: Large enough to hold results of all instances of the marker.
FirstResultArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type double
  • array of type long
  • double
  • long

Specifies the address of the first array in which to write the requested information.

With a multiple marker, results for each edge or stripe are held in an array. The results for each instance of the marker will be stored in a separate element of the specified arrays.

All positional results are relative to the top-left pixel in the target image or to the origin of the coordinate system of a calibrated image.

SecondResultArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type double
  • array of type long
  • double
  • long

Specifies the address of the second array in which to write the requested information.

For most result types, only FirstResultArrayPtr will be used, and SecondResultArrayPtr should be set to M_NULL.

With a multiple marker, results for each edge or stripe are held in an array. The results for each instance of the marker will be stored in a separate element of the specified arrays.

OUTPUT COORDINATE SYSTEM PIXEL ANGLE ANGLE LINE EQUATION LINE EQUATION LINE EQUATION INTERCEPT LINE EQUATION INTERCEPT LINE EQUATION SLOPE LINE EQUATION SLOPE BOX EDGE VALUES BOX EDGE VALUES DISTANCE X TYPE LONG ANGLE LINE EQUATION LINE EQUATION INTERCEPT LINE EQUATION SLOPE BOX CORNER BOTTOM LEFT BOX CORNER BOTTOM RIGHT BOX CORNER TOP LEFT BOX CORNER TOP RIGHT BOX EDGE VALUES BOX EDGE VALUES NUMBER CONTRAST EDGE INSIDE EDGE STRENGTH LENGTH NUMBER ORIENTATION POLARITY POSITION POSITION MAX POSITION MIN POSITION VARIATION SCORE SPACING TOTAL SCORE VALID FLAG WIDTH WIDTH VARIATION EDGE FIRST EDGE SECOND MAX MEAN MIN STANDARD DEVIATION DISTANCE DISTANCE X DISTANCE Y TYPE LONG


MmeasGetResultSingle

See Also | Example | Availability | MmeasGetResult | MmeasInquire
User Guide:
Measurements between two markers

Reference:
McalControl
MmeasAllocMarker
MmeasAllocResult
MmeasCalculate
MmeasFindMarker
There are no examples containing MmeasGetResultSingle().
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified type of result(s) for a specific edge or stripe from a measurement marker or result buffer.
Syntax
void MmeasGetResultSingle(
MIL_ID MarkerOrMeasResultId,
long ResultType,
void *FirstResultArrayPtr,
void *SecondResultArrayPtr,
long ResultIndex
)
Description

This function retrieves the result(s) of the specified type for a specified edge or stripe from a measurement marker or result buffer. You can specify to retrieve results for any one of the edges or stripes found after calling MmeasFindMarker() or for which a measurement was calculated using MmeasCalculate().

The number of edges or stripes should be determined first using MmeasGetResultSingle() with M_NUMBER to ensure that the index of the result to retrieve is valid.

For certain result types, two values can be returned for a stripe marker: the value for the first edge is returned to FirstResultArrayPtr and that of the second edge to SecondResultArrayPtr. For an edge marker, all results are returned to FirstResultArrayPtr, and SecondResultArrayPtr must be set to M_NULL.

Note that if your target image has been associated with a calibration object, positional results are by default returned in real-world units. To have results returned in pixel units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to M_PIXEL. All positional results are relative to the top-left pixel in the target image or to the origin of the coordinate system of a calibrated image.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set the FirstResultArrayPtr and SecondResultArrayPtr parameters to M_NULL. When both result parameters are set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when at least one result parameter is passed an array. You must ensure that the result arrays are sufficiently large to hold all requested results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Note, if the request queued does not return results in the second result array, the second array pointer is not padded for that particular request, when the queue is executed.

Parameters
MarkerOrMeasResultId

Specifies the identifier of the measurement marker (allocated with MmeasAllocMarker()) or measurement result buffer (allocated with MmeasAllocResult()) from which to retrieve results.

ResultType

Specifies the type of result(s) to retrieve.

Note that, unless otherwise specified, marker results are returned in FirstResultArrayPtr; when this is the case, SecondResultArrayPtr must be set to M_NULL.

If retrieving a result from a marker or measurement result buffer, ResultType can be set to one of the values specified in the table below.

Unless otherwise specified, the following values require that you pass the FirstResultArrayPtr parameter the address of a double and the SecondResultArrayPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_ANGLE

Retrieves the angle, in degrees. Retrieves the angle, in degrees ...

If retrieved from a marker, M_ANGLE returns the angle of the marker relative to the positive X-axis. If retrieved from a measurement result buffer, M_ANGLE returns the angle of the line joining the two markers relative to the positive X-axis.

FirstResultArrayPtr info

Return values:
0.0 to 360.0 Angle, in degrees

Open Collapse M_LINE_EQUATION

Retrieves the line equation. Retrieves the line equation ...

If retrieved from a marker, M_LINE_EQUATION returns the mean line of the marker. If retrieved from a measurement result buffer, M_LINE_EQUATION returns the equation of the line joining two markers.

FirstResultArrayPtr info

Return values:
Value Slope of the equation. When the equation of the line has an infinite slope, the value returned as the slope is M_INFINITE_SLOPE (1.0E+300).

SecondResultArrayPtr info

Return values:
Value Y-intercept of the equation.

Open Collapse M_LINE_EQUATION_INTERCEPT

Retrieves the Y-intercept of the line equation. Retrieves the Y-intercept of the line equation ...

If retrieved from a marker, M_LINE_EQUATION_INTERCEPT returns the Y-intercept of the line equation of the marker. If retrieved from a measurement result buffer, M_LINE_EQUATION_INTERCEPT returns the Y-intercept of the line equation joining two markers.

Open Collapse M_LINE_EQUATION_SLOPE

Retrieves the slope of the line equation. Retrieves the slope of the line equation ...

If retrieved from a marker, M_LINE_EQUATION_SLOPE returns the slope of the marker's line equation. If retrieved from a measurement result buffer, M_LINE_EQUATION_SLOPE returns the slope of the line equation joining the two markers.

FirstResultArrayPtr info

Return values:
Value Slope of the equation. When the equation of the line has an infinite slope, the value returned as the slope is M_INFINITE_SLOPE (1.0E+300).

If retrieving a result from a marker, ResultType can be set to one of the values specified in the table below.

Unless otherwise specified, the following values require that you pass the FirstResultArrayPtr parameter the address of a double and the SecondResultArrayPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_BOX_CORNER_BOTTOM_LEFT

Retrieves the coordinates of the bottom-left corner of the measurement box. Retrieves the coordinates of the bottom-left corner of the measurement box ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_BOX_CORNER_BOTTOM_RIGHT

Retrieves the coordinates of the bottom-right corner of the measurement box. Retrieves the coordinates of the bottom-right corner of the measurement box ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_BOX_CORNER_TOP_LEFT

Retrieves the coordinates of the top-left corner of the measurement box. Retrieves the coordinates of the top-left corner of the measurement box ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_BOX_CORNER_TOP_RIGHT

Retrieves the coordinates of the top-right corner of the measurement box. Retrieves the coordinates of the top-right corner of the measurement box ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_BOX_EDGE_VALUES

Retrieves the edge values (as a normalized percentage of the buffer's maximum possible value for every profile value of the measurement box). Retrieves the edge values (as a normalized percentage of the buffer's maximum possible value for every profile value of the measurement box) ...

FirstResultArrayPtr info

Data type: array of type double
Array size: The number of edge values returned can be determined by calling MmeasGetResultSingle() with M_BOX_EDGE_VALUES_NUMBER.

Return values:
Value Edge value results returned as an array.

Open Collapse M_BOX_EDGE_VALUES_NUMBER

Retrieves the number of values to be returned by M_BOX_EDGE_VALUES. Retrieves the number of values to be returned by M_BOX_EDGE_VALUES ...

FirstResultArrayPtr info

Return values:
Value Number of edge values returned by M_BOX_EDGE_VALUES.

Open Collapse M_CONTRAST

Retrieves the typical difference in average grayscale values between the start and end of the intensity transition (edge width) from which an edge is established. Retrieves one value for an edge marker, and two for a stripe marker. Retrieves the typical difference in average grayscale values between the start and end of the intensity transition (edge width) from which an edge is established ...

FirstResultArrayPtr info

Return values:
Value Average grayscale difference for first edge.

SecondResultArrayPtr info

Return values:
Value Average grayscale difference for a second edge if a stripe marker.

Open Collapse M_EDGE_INSIDE

Retrieves the number of edges located between the two exterior edges of a stripe marker. Retrieves the number of edges located between the two exterior edges of a stripe marker.

Open Collapse M_EDGE_STRENGTH

Retrieves the maximum edge value variation (as a normalized percentage of the buffer's maximum possible value) of each edge of a marker. Retrieves one value for an edge marker, and two for a stripe marker. Retrieves the maximum edge value variation (as a normalized percentage of the buffer's maximum possible value) of each edge of a marker ...

Open Collapse M_LENGTH

Retrieves the length of the marker in pixels or real-world units. Retrieves the length of the marker in pixels or real-world units.

Open Collapse M_NUMBER

Retrieves the number of edges or stripes found in the measurement box. Retrieves the number of edges or stripes found in the measurement box ...

After a call to the MmeasFindMarker() function, the number of elements in the collection is the number of occurrences of edge or stripe marker found in the measurement box.

After a call to the MmeasCalculate() function, the number of elements in the collection is equal to the smallest number of occurrences held in either marker involved in the calculation.

Open Collapse M_ORIENTATION

Retrieves the orientation of the marker. Retrieves the orientation of the marker ...

FirstResultArrayPtr info

Return values:
M_HORIZONTAL, M_VERTICAL (details)
Open Collapse M_POLARITY

Retrieves the polarity of the marker. Retrieves one value for an edge marker, and two for a stripe marker. Retrieves the polarity of the marker ...

FirstResultArrayPtr info

Return values:

M_NEGATIVE, M_POSITIVE (details)

SecondResultArrayPtr info

Return values:

M_NEGATIVE, M_POSITIVE (details)
Open Collapse M_POSITION

Retrieves the coordinates of the marker center in the image. Retrieves the coordinates of the marker center in the image ...

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_POSITION_MAX

Retrieves the X and Y-coordinates of the maximum position of an edge in a marker. Retrieves the X and Y-coordinates of the maximum position of an edge in a marker ...

For a striper marker, the average value of maximum positions is returned unless otherwise specified (with M_EDGE_FIRST or M_EDGE_SECOND).

The X-coordinate is the maximum position within the edge width from which an edge is established. The Y-coordinate is the Y-coordinate of the measurement box center. The maximum position is always on the side of the measurement box furthest from the origin, regardless of how the measurement box is rotated. The diagram below illustrates an edge transion curve (a profile of gradual transition from dark to light) and a measurement box.

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_POSITION_MIN

Returns the X and Y-coordinates of the minimum position of an edge in a marker. Returns the X and Y-coordinates of the minimum position of an edge in a marker ...

For a striper marker, the average value of minimum positions is returned unless otherwise specified (with M_EDGE_FIRST or M_EDGE_SECOND).

The X-coordinate is the minimum position within the edge width from which an edge is established. The Y-coordinate is the Y-coordinate of the measurement box center. The minimum position is always on the side of the measurement box adjacent to the origin, regardless of how the measurement box is rotated. The diagram in M_POSITION_MAX illustrates an edge transion curve and a measurement box.

FirstResultArrayPtr info

Return values:
Value X-position.

SecondResultArrayPtr info

Return values:
Value Y-position.

Open Collapse M_POSITION_VARIATION

Retrieves the position variation of the marker, in pixels or real-world units (postive or negative values). Retrieves the position variation of the marker, in pixels or real-world units (postive or negative values).

Open Collapse M_SCORE

Retrieves the confidence score for the MmeasFindMarker() operation, as a percentage. Retrieves the confidence score for the MmeasFindMarker() operation, as a percentage.

Open Collapse M_SPACING

Retrieves the inter-edge or inter-stripe spacing between consecutive edges or stripes. Retrieves the inter-edge or inter-stripe spacing between consecutive edges or stripes.

Open Collapse M_TOTAL_SCORE

Retrieves the average confidence score of all edges or stripes found. Retrieves the average confidence score of all edges or stripes found.

Open Collapse M_VALID_FLAG

Retrieves the flag that denotes whether or not a marker was found. Retrieves the flag that denotes whether or not a marker was found ...

FirstResultArrayPtr info

Return values:
M_FALSE | Marker not found.
M_TRUE | Marker found.

SecondResultArrayPtr info

Return values:
M_FALSE | Marker not found.
M_TRUE | Marker found.
Open Collapse M_WIDTH

Retrieves the edge width of the edge marker or the width of the stripe marker, in pixels or real-world units. Retrieves the edge width of the edge marker or the width of the stripe marker, in pixels or real-world units.

Open Collapse M_WIDTH_VARIATION

Retrieves the width variation of the stripe marker, in pixels or real-world units. Retrieves the width variation of the stripe marker, in pixels or real-world units.

[Combination constants]

One of the following values can be added to the result types listed in the tables above. They can only be added if the results are obtained from a marker.

Open Collapse Value | Description
Open Collapse M_EDGE_FIRST | Retrieves results for the first exterior edge of a stripe, for the requested characteristic. Retrieves results for the first exterior edge of a stripe, for the requested characteristic.
Open Collapse M_EDGE_SECOND | Retrieves results for the second exterior edge of a stripe, for the requested characteristic. Retrieves results for the second exterior edge of a stripe, for the requested characteristic.

If retrieving a result from a measurement result buffer (MmeasCalculate()), the ResultType can be set to one of the values specified in the table below.

Unless otherwise specified, the following values require that you pass the FirstResultArrayPtr parameter the address of a double and the SecondResultArrayPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_DISTANCE | Retrieves the distance between two markers, in pixels or real-world units. Retrieves the distance between two markers, in pixels or real-world units.
Open Collapse M_DISTANCE_X | Retrieves the distance on the X-axis between two markers, in pixels or real-world units. Retrieves the distance on the X-axis between two markers, in pixels or real-world units.
Open Collapse M_DISTANCE_Y | Retrieves the distance on the Y-axis between two markers, in pixels or real-world units. Retrieves the distance on the Y-axis between two markers, in pixels or real-world units.

[Combination constants]

The values below can be added to the ResultType parameter to cast the requested results to a required data type. For example, M_ANGLE + M_TYPE_LONG.

Open Collapse Value Description
Open Collapse M_TYPE_LONG

Casts the requested results to a long. Casts the requested results to a long ...

FirstResultArrayPtr info

Data type:

  • array of type long
    Array size: Depends on the result type.
  • long
    note: When a single result is returned to either or both FirstResultArrayPtr and SecondResultArrayPtr.

Note, M_INVALID is returned if a measurement was not calculated.

FirstResultArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type double
  • array of type long
  • double
  • long

Specifies the address of the first array in which to write the requested information.

SecondResultArrayPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type long
  • double
  • long

Specifies the address of the second array in which to write the requested information.

For most result types, only FirstResultArrayPtr will be used and SecondResultArrayPtr should be set to M_NULL.

ResultIndex

Specifies the index of the result to retrieve.

Open Collapse Value Description
Open Collapse 0 to N-1

 Specifies the index value where N is the number of edges or stripes found or the number of results calculated.  Specifies the index value where N is the number of edges or stripes found or the number of results calculated.

NUMBER OUTPUT COORDINATE SYSTEM PIXEL ANGLE ANGLE LINE EQUATION LINE EQUATION LINE EQUATION INTERCEPT LINE EQUATION INTERCEPT LINE EQUATION SLOPE LINE EQUATION SLOPE BOX EDGE VALUES NUMBER BOX EDGE VALUES ANGLE TYPE LONG   ANGLE LINE EQUATION LINE EQUATION INTERCEPT LINE EQUATION SLOPE BOX CORNER BOTTOM LEFT BOX CORNER BOTTOM RIGHT BOX CORNER TOP LEFT BOX CORNER TOP RIGHT BOX EDGE VALUES BOX EDGE VALUES NUMBER CONTRAST EDGE INSIDE EDGE STRENGTH LENGTH NUMBER ORIENTATION POLARITY POSITION POSITION MAX POSITION MIN POSITION VARIATION SCORE SPACING TOTAL SCORE VALID FLAG WIDTH WIDTH VARIATION EDGE FIRST EDGE SECOND DISTANCE DISTANCE X DISTANCE Y TYPE LONG


MmeasInquire

See Also | Example | Availability | MmeasGetResultSingle | MmeasRestoreMarker
User Guide:
Steps to finding and obtaining measurements of markers

Reference:
MmeasControl
MmeasGetResult
MmeasGetResultSingle
MmeasSetMarker
There are no examples containing MmeasInquire().
Not available in MIL-Lite

Available in MIL
Synopsis
Inquire about a measurement context, marker, or result buffer.
Syntax
long MmeasInquire(
MIL_ID MeasId,
long InquireType,
void *FirstUserVarPtr,
void *SecondUserVarPtr
)
Description

This function inquires information about an expected marker characteristic, context setting, or measurement result buffer type. Set marker characteristics using MmeasSetMarker(), and set context settings using MmeasControl().

If the inquired setting is set to M_DEFAULT, this function will return M_DEFAULT. To inquire its default value, add M_DEFAULT to the inquire type.

Note that for a measurement result buffer, this function only retrieves information about result buffer settings (for example, set with MmeasSetMarker()). To retrieve information from the measurement result buffer, use MmeasGetResult() or MmeasGetResultSingle().

Parameters
MeasId

Specifies the identifier of the marker, measurement context, or measurement result buffer about which to inquire information.

InquireType

Specifies the type of setting about which to inquire.

When performing an inquiry on a marker (to determine the default or user-defined value of a marker characteristic), InquireType can be set to one of the values listed in the table below.

For certain inquire types, two values can be returned for a stripe marker: or, one for each of the edges. The value for the first edge is returned to FirstUserVarPtr and that of the second edge to SecondUserVarPtr. For an edge marker, all results are returned to FirstUserVarPtr. Inquire types which return a position always return the X-coordinate to FirstUserVarPtr and the Y-coordinate to SecondUserVarPtr.

Unless otherwise specified, the following values require that you pass the FirstUserVarPtr parameter the address of a double and the SecondUserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_BOX_ANGLE | Returns the angle of the measurement box. Returns the angle of the measurement box ...
 |  | FirstUserVarPtr info Return values: 0 to 360, M_ANY (details)
Open Collapse M_BOX_ANGLE_ACCURACY | Returns the required precision for the resulting angle of the marker. Returns the required precision for the resulting angle of the marker ...
 |  | FirstUserVarPtr info Return values: 0.1 to 180.0, M_DISABLE (details)
Open Collapse M_BOX_ANGLE_DELTA_NEG | Returns the lower limit of the range of angles to be searched for the marker. Returns the lower limit of the range of angles to be searched for the marker ...
 |  | FirstUserVarPtr info Return values: 0.1 to 360.0, M_DEFAULT (details)
Open Collapse M_BOX_ANGLE_DELTA_POS | Returns the upper limit of the range of angles to be searched for the marker. Returns the upper limit of the range of angles to be searched for the marker ...
 |  | FirstUserVarPtr info Return values: 0.1 to 360.0, M_DEFAULT (details)
Open Collapse M_BOX_ANGLE_INTERPOLATION_MODE | Returns the type of interpolation used when performing a search at an angle. Returns the type of interpolation used when performing a search at an angle ...
 |  | FirstUserVarPtr info Return values: M_BICUBIC, M_BILINEAR, M_NEAREST_NEIGHBOR (details)
Open Collapse M_BOX_ANGLE_MODE | Returns whether multiple-angle search is enabled. Returns whether multiple-angle search is enabled ...
 |  | FirstUserVarPtr info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_BOX_ANGLE_REFERENCE | Returns the center of rotation used when performing a search at an angle. Returns the center of rotation used when performing a search at an angle ...
 |  | FirstUserVarPtr info Return values: M_BOX_CENTER, M_BOX_ORIGIN (details)
Open Collapse M_BOX_ANGLE_TOLERANCE | Returns the rotation tolerance of the marker. This is the full range of degrees within which a marker can be rotated from a measurement box that is at a specific angle and still be found. This determines the step angle used for a multiple-angle search. Returns the rotation tolerance of the marker ...
 |  | FirstUserVarPtr info Return values: 0.1 to 360.0 (details)
Open Collapse M_BOX_CENTER | Returns the X and Y-coordinates of the measurement box's center. Returns the X and Y-coordinates of the measurement box's center ...
 |  | FirstUserVarPtr info Return values: M_DEFAULT, Value (details)
 |  | SecondUserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_BOX_ORIGIN | Returns the X and Y-coordinates of the measurement box's origin. Returns the X and Y-coordinates of the measurement box's origin ...
 |  | FirstUserVarPtr info Return values: Please see MmeasSetMarker() with M_BOX_ORIGIN. Note that M_DEFAULT, M_DEFAULT are not returned.
 |  | SecondUserVarPtr info Return values: Please see MmeasSetMarker() with M_BOX_ORIGIN. Note that M_DEFAULT, M_DEFAULT are not returned.
Open Collapse M_BOX_SIZE | Returns the width and height of the measurement box. The width is returned to FirstUserVarPtr and the height is returned to SecondUserVarPtr. Returns the width and height of the measurement box ...
 |  | FirstUserVarPtr info Return values: M_DEFAULT, Value (details)
 |  | SecondUserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_CONTRAST | Returns the contrast of a marker (one value for an edge; two for a stripe). Returns the contrast of a marker (one value for an edge; two for a stripe) ...
 |  | FirstUserVarPtr info Return values: 0 to maximum value of the buffer, M_ANY (details)
 |  | SecondUserVarPtr info Return values: 0 to maximum value of the buffer, M_ANY, M_NULL, M_SAME (details)
Open Collapse M_CONTRAST_VARIATION | Returns the contrast variation of a marker. Returns the contrast variation of a marker ...
 |  | FirstUserVarPtr info Return values: 0 to maximum value of the buffer, M_ANY (details)
Open Collapse M_CONTROL_FLAG | Returns the control flag given at marker allocation time. Returns the control flag given at marker allocation time ...
 |  | FirstUserVarPtr info Return values: Please see the ControlFlag parameter of MmeasAllocMarker().
Open Collapse M_EDGE_INSIDE | Returns the number of edges between the external edges of a stripe marker. Returns the number of edges between the external edges of a stripe marker ...
 |  | FirstUserVarPtr info Return values: M_ANY, Value (details)
Open Collapse M_EDGE_INSIDE_VARIATION | Returns the tolerance of the number of edges between the external edges of a stripe marker. Returns the tolerance of the number of edges between the external edges of a stripe marker ...
 |  | FirstUserVarPtr info Return values: M_ANY, Value (details)
Open Collapse M_EDGE_STRENGTH | Returns the maximum edge value of the edge along the edge width (as a percentage). Returns the maximum edge value of the edge along the edge width (as a percentage) ...
 |  | FirstUserVarPtr info Return values: 0.0 to 100.0, M_ANY (details)
 |  | SecondUserVarPtr info Return values: 0.0 to 100.0, M_ANY, M_NULL (details)
Open Collapse M_EDGE_STRENGTH_VARIATION | Returns the tolerance of the maximum edge value of the edge. Returns the tolerance of the maximum edge value of the edge ...
 |  | FirstUserVarPtr info Return values: 0.0 to 100.0, M_ANY (details)
Open Collapse M_EDGE_THRESHOLD | Returns the edge value beneath which a grayscale variation is not considered an edge. Returns the edge value beneath which a grayscale variation is not considered an edge ...
 |  | FirstUserVarPtr info Return values: 0.0 to 100.0 (details)
Open Collapse M_FILTER_SMOOTHNESS | Returns the degree of smoothness (strength of denoising) applied to the internal projection buffer of the measurement box during the edge extraction. Returns the degree of smoothness (strength of denoising) applied to the internal projection buffer of the measurement box during the edge extraction ...
 |  | FirstUserVarPtr info Return values: 0.0 to 100.0, M_DEFAULT (details)
Open Collapse M_FILTER_TYPE | Returns the type of the first derivative filter with which to perform the edge extraction. Returns the type of the first derivative filter with which to perform the edge extraction ...
 |  | FirstUserVarPtr info Return values: M_DEFAULT, M_EULER, M_PREWITT, M_SHEN (details)
Open Collapse M_MARKER_REFERENCE | Returns the X and Y-offsets of the marker reference. Returns the X and Y-offsets of the marker reference ...
 |  | FirstUserVarPtr info Return values: Please see MmeasSetMarker() with M_MARKER_REFERENCE. Note that M_DEFAULT, M_DEFAULT are not returned.
 |  | SecondUserVarPtr info Return values: Please see MmeasSetMarker() with M_MARKER_REFERENCE. Note that M_DEFAULT, M_DEFAULT are not returned.
Open Collapse M_MARKER_TYPE | Returns the type of marker. Returns the type of marker ...
 |  | FirstUserVarPtr info Return values: M_EDGE, M_POINT, M_STRIPE (details)
Open Collapse M_NUMBER | Returns the number of points, edges, or stripes. Returns the number of points, edges, or stripes ...
 |  | FirstUserVarPtr info Return values: Please see the ResultType parameter of MmeasGetResult().
Open Collapse M_NUMBER_MIN | Returns the minimum number of edges or stripes. Returns the minimum number of edges or stripes ...
 |  | FirstUserVarPtr info Return values: M_NUMBER, Value (details)
Open Collapse M_ORIENTATION | Returns the orientation of the marker. Returns the orientation of the marker ...
 |  | FirstUserVarPtr info Return values: M_HORIZONTAL, M_VERTICAL (details)
Open Collapse M_POLARITY | Returns the polarity of the marker. Returns the polarity of the marker ...
 |  | FirstUserVarPtr info Return values: M_NEGATIVE, M_POSITIVE (details)
 |  | SecondUserVarPtr info Return values: (details)
Open Collapse M_POSITION | Returns the X and Y-coordinates of the marker center, except when inquiring about a stripe marker whose M_POSITION_INSIDE_STRIPE control type setting defines the position to be outside the stripe. Returns the X and Y-coordinates of the marker center, except when inquiring about a stripe marker whose M_POSITION_INSIDE_STRIPE control type setting defines the position to be outside the stripe ...
 |  | FirstUserVarPtr info Return values: M_ANY, Value (details)
 |  | SecondUserVarPtr info Return values: M_ANY, Value (details)
Open Collapse M_POSITION_INSIDE_STRIPE | Returns whether the specified position is inside or outside of the stripe. Returns whether the specified position is inside or outside of the stripe ...
 |  | FirstUserVarPtr info Return values: M_ANY, M_NO, M_YES (details)
Open Collapse M_POSITION_VARIATION | Returns the tolerance of the position variation. Returns the tolerance of the position variation ...
 |  | FirstUserVarPtr info Return values: M_ANY, Value (details)
Open Collapse M_POSITION_X | Returns the X-coordinate of the marker center, except when using a stripe marker and whose M_POSITION_INSIDE_STRIPE control type setting defines the position to be outside the stripe. Returns the X-coordinate of the marker center, except when using a stripe marker and whose M_POSITION_INSIDE_STRIPE control type setting defines the position to be outside the stripe ...
 |  | FirstUserVarPtr info Return values: M_ANY, Value (details)
 |  | SecondUserVarPtr info Return values: M_ANY, Value (details)
Open Collapse M_POSITION_Y | Returns the Y-coordinate of the marker center, except when using a stripe marker and whose M_POSITION_INSIDE_STRIPE control type setting defines the position to be outside the stripe. Returns the Y-coordinate of the marker center, except when using a stripe marker and whose M_POSITION_INSIDE_STRIPE control type setting defines the position to be outside the stripe ...
 |  | FirstUserVarPtr info Return values: M_ANY, Value (details)
 |  | SecondUserVarPtr info Return values: M_ANY, Value (details)
Open Collapse M_SPACING | Returns the typical spacing, in pixels, between consecutive points, edges, or stripes. This setting is only available for a multiple marker. Returns the typical spacing, in pixels, between consecutive points, edges, or stripes ...
 |  | FirstUserVarPtr info Return values: M_ANY, M_SAME, Value (details)
Open Collapse M_SPACING_VARIATION | Returns the typical variation in spacing, in pixels, between edges or stripes (MmeasSetMarker()). Returns the typical variation in spacing, in pixels, between edges or stripes (MmeasSetMarker()) ...
 |  | FirstUserVarPtr info Return values: M_ANY, Value (details)
Open Collapse M_WIDTH | Returns the width of a stripe marker. Returns the width of a stripe marker ...
 |  | FirstUserVarPtr info Return values: M_ANY, M_SAME, Value (details)
Open Collapse M_WIDTH_VARIATION | Returns the width variation of a stripe marker. Returns the width variation of a stripe marker ...
 |  | FirstUserVarPtr info Return values: M_ANY, Value (details)

[Combination constants]

The value below can be added to M_CONTRAST, M_EDGE_INSIDE, M_EDGE_STRENGTH, M_POSITION, M_SPACING, or M_WIDTH.

Open Collapse Value | Description
Open Collapse M_WEIGHT_FACTOR | Returns the specific weight assigned to the specified characteristic, as a percentage. Returns the specific weight assigned to the specified characteristic, as a percentage ...
 |  | FirstUserVarPtr info Data type: double

When performing an inquiry on a measurement context buffer, InquireType can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the FirstUserVarPtr parameter the address of a double and the SecondUserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_CONTROL_FLAG | Returns the ControlFlag parameter setting given at context allocation time. Returns the ControlFlag parameter setting given at context allocation time ...
 |  | FirstUserVarPtr info Data type: long Return values: Please see the ControlFlag parameter of MmeasAllocMarker().
Open Collapse M_PIXEL_ASPECT_RATIO | Returns the ratio of the width of the pixel to its height. Returns the ratio of the width of the pixel to its height ...
 |  | FirstUserVarPtr info Return values: Please see MmeasControl() with M_PIXEL_ASPECT_RATIO.
Open Collapse M_PIXEL_ASPECT_RATIO_INPUT | Returns how the measurement module interprets specified measurement characteristics relative to the pixel aspect ratio. Returns how the measurement module interprets specified measurement characteristics relative to the pixel aspect ratio ...
 |  | FirstUserVarPtr info Return values: M_CORRECTED, M_NORMAL (details)
Open Collapse M_PIXEL_ASPECT_RATIO_OUTPUT | Returns how the measurement module returns results relative to the pixel aspect ratio. Returns how the measurement module returns results relative to the pixel aspect ratio ...
 |  | FirstUserVarPtr info Return values: M_CORRECTED, M_NORMAL (details)

When performing an inquiry on a measurement result buffer, InquireType can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the FirstUserVarPtr parameter the address of a double and the SecondUserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_RESULT_TYPE | Returns the type of result buffer allocated. Returns the type of result buffer allocated ...
 |  | FirstUserVarPtr info Return values: M_CALCULATE, M_DEFAULT (details)

[Combination constants]

The values below can be added to the InquireType parameter to cast the requested information to a required data type. For example, M_MARKER_TYPE + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_LONG | Casts the requested information to a long. Casts the requested information to a long ...
 |  | FirstUserVarPtr info Data type: long
FirstUserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • double
  • long

Specifies the address in which to write the requested information.

SecondUserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • double
  • long

Specifies the address in which to write the requested information. If only one value is to be returned, it will be returned to FirstUserVarPtr and SecondUserVarPtr should be set to M_NULL.

Return value
The returned value is the requested information, typically returned to FirstUserVarPtr, cast to long.
POSITION INSIDE STRIPE POSITION INSIDE STRIPE POSITION INSIDE STRIPE CONTRAST EDGE INSIDE EDGE STRENGTH POSITION SPACING WIDTH MARKER TYPE TYPE LONG BOX ANGLE BOX ANGLE ACCURACY BOX ANGLE DELTA NEG BOX ANGLE DELTA POS BOX ANGLE INTERPOLATION MODE BOX ANGLE MODE BOX ANGLE REFERENCE BOX ANGLE TOLERANCE BOX CENTER BOX ORIGIN BOX SIZE CONTRAST CONTRAST VARIATION CONTROL FLAG EDGE INSIDE EDGE INSIDE VARIATION EDGE STRENGTH EDGE STRENGTH VARIATION EDGE THRESHOLD FILTER SMOOTHNESS FILTER TYPE MARKER REFERENCE MARKER TYPE NUMBER NUMBER MIN ORIENTATION POLARITY POSITION POSITION INSIDE STRIPE POSITION VARIATION POSITION X POSITION Y SPACING SPACING VARIATION WIDTH WIDTH VARIATION WEIGHT FACTOR CONTROL FLAG PIXEL ASPECT RATIO PIXEL ASPECT RATIO INPUT PIXEL ASPECT RATIO OUTPUT RESULT TYPE TYPE LONG


MmeasRestoreMarker

See Also | Example | Availability | MmeasInquire | MmeasSaveMarker
User Guide:
Steps to finding and obtaining measurements of markers

Reference:
MsysAlloc
There are no examples containing MmeasRestoreMarker().
Not available in MIL-Lite

Available in MIL
Synopsis
Restore a marker from disk.
Syntax
MIL_ID MmeasRestoreMarker(
MIL_TEXT_PTR FileName,
MIL_ID SystemId,
long ControlFlag,
MIL_ID *MarkerIdPtr
)
Description

This function restores a previously saved marker from disk and returns a handle to it. It also restores all the marker characteristics that were in effect when the marker was saved.

Parameters
FileName

Specifies the marker file name. The function internally handles the opening and closing of the file.

SystemId

Specifies the system on which to restore the measurement marker.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Specifies the restore control flag and should be set to M_DEFAULT.

 MarkerIdPtr

 Specifies the address of the variable in which the marker identifier is to be written.  Since the MmeasRestoreMarker() function also returns the marker identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the marker identifier. If allocation fails, M_NULL is returned.

  DEFAULT HOST


MmeasSaveMarker

See Also | Example | Availability | MmeasRestoreMarker | MmeasSetMarker
User Guide:
Steps to finding and obtaining measurements of markers

Reference:
MmeasRestoreMarker
There are no examples containing MmeasSaveMarker().
Not available in MIL-Lite

Available in MIL
Synopsis
Save a marker to disk.
Syntax
void MmeasSaveMarker(
MIL_TEXT_PTR FileName,
MIL_ID MarkerId,
long ControlFlag
)
Description

This function saves an allocated marker to disk, including all of its current characteristics. The marker and its characteristics can later be restored, using MmeasRestoreMarker().

Parameters
FileName

Specifies the name of the file in which to save the marker. If this file already exists, it will be overwritten. The function internally handles the opening and closing of this file.

MarkerId

Specifies the identifier of the marker to save.

ControlFlag

Specifies the save control flag and must be set to M_DEFAULT.


MmeasSetMarker

See Also | Example | Availability | MmeasSaveMarker | MmeasStream
User Guide:
Markers
Steps to finding and obtaining measurements of markers
Measurement box
Search algorithm
Marker characteristics
Edge markers: fundamental characteristics
Edge markers: advanced characteristics
Stripe markers: fundamental characteristics
Multiple marker characteristics

Reference:
MmeasFindMarker
mcal.c
mmeas.c
Not available in MIL-Lite

Available in MIL
Synopsis
Set a marker characteristic.
Syntax
void MmeasSetMarker(
MIL_ID MarkerId,
long CharacteristicToSet,
double FirstValue,
double SecondValue
)
Description

This function sets a marker characteristic. Marker characteristics are used in determining the marker location of an edge or stripe marker in a target image or specifying the position of point markers, generally used as a reference marker. MmeasFindMarker() locates the edge(s) or stripe(s) that best correspond to the specified marker's characteristics. A marker's characteristics should describe the marker as accurately as possible to ensure that it will be successfully located in an image.

Parameters
MarkerId

Specifies the identifier of the marker.

CharacteristicToSet

Specifies the type of characteristic to set.

See the Parameter associations section for possible values.

FirstValue

Specifies the first value to assign to the characteristic. The FirstValue parameter must always be provided.

See the Parameter associations section for possible values.

SecondValue

Specifies the second value to assign to the characteristic. The SecondValue parameter should be set to M_NULL if no parameter setting is required.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the CharacteristicToSet, FirstValue, and SecondValue parameters are described below.

The following CharacteristicToSet and corresponding FirstValue and SecondValue parameter settings are used to specify the expected measurement marker characteristics. Note that, the SecondValue parameter should be set to M_NULL if no parameter setting is required.

You can set one the following values for point, edge, and stripe markers.

Open Collapse CharacteristicToSet Description
FirstValue
SecondValue
Open Collapse M_NUMBER

Sets the number of edges or stripes to locate in the measurement box, or the number of points used as a reference marker. Sets the number of edges or stripes to locate in the measurement box, or the number of points used as a reference marker ...

Unless a minimum number (M_NUMBER_MIN) is specified, no results will be returned if the number of edges or stripes found falls below M_NUMBER.

When M_NUMBER is set to a value greater than 1, the marker is considered a multiple marker.

FirstValue
M_ALL

Specifies that the search should locate all edges or stripes in the measurement box.

This setting cannot be used for a point marker.

Value

Specifies the number of points, edges, or stripes to locate.

The default value is 1.

Open Collapse M_POSITION

Sets the coordinates of the marker center within the marker (approximate except for a point marker). When using a stripe marker, you can define instead a position that must be outside of the stripe marker, depending on the M_POSITION_INSIDE_STRIPE setting. Sets the coordinates of the marker center within the marker (approximate except for a point marker) ...

For an edge or stripe marker, the defined position must be within the measurement box (taking into account the angle or scope of the angular search, if enabled).

The position is ignored for a multiple edge or stripe marker. For a multiple point marker, this defines the position of the first point.

FirstValue
M_ANY

Specifies any valid value as the X-coordinate. This setting can only be used when setting the marker center within the marker.

This setting cannot be used for a point marker.

This is the default value.
Value

Specifies a value as the X-coordinate, in pixels.

SecondValue
M_ANY

Specifies any valid value as the Y-coordinate. This setting can only be used when setting the marker center within the marker.

This setting cannot be used for a point marker.

This is the default value.
Value

Specifies a value as the Y-coordinate, in pixels.

Open Collapse M_POSITION_X

Sets the X-coordinate of the marker within the marker (approximate except for a point marker). When using a stripe marker, you can define instead a position that must be outside of the stripe marker depending on the M_POSITION_INSIDE_STRIPE setting. Sets the X-coordinate of the marker within the marker (approximate except for a point marker) ...

For an edge or stripe marker, the defined position must be within the measurement box (taking into account the angle or scope of the angular search, if enabled).

The position is ignored for a multiple edge or stripe marker. For a multiple point marker, this defines the position of the first point.

FirstValue
M_ANY

Specifies any valid value as the X-coordinate. This setting can only be used when setting the marker center within the marker.

This setting cannot be used for a point marker.

This is the default value.
Value

Specifies a value as the X-coordinate, in pixels.

Open Collapse M_POSITION_Y

Sets the Y-coordinate of the marker within the marker (approximate except for a point marker). When using a stripe marker, you can define instead a position that must be outside of the stripe marker depending on the M_POSITION_INSIDE_STRIPE setting. Sets the Y-coordinate of the marker within the marker (approximate except for a point marker) ...

For an edge or stripe marker, the defined position must be within the measurement box (taking into account the angle or scope of the angular search, if enabled).

The position is ignored for a multiple edge or stripe marker. For a multiple point marker, this defines the position of the first point.

FirstValue
M_ANY

Specifies any valid value as the Y-coordinate. This setting can only be used when setting the marker center within the marker.

This setting cannot be used for a point marker.

This is the default value.
Value

Specifies a value as the Y-coordinate, in pixels.

Open Collapse M_SPACING

Sets the typical spacing (distance) between consecutive edges or stripes to locate, or between the points used as a reference marker. This setting is only available for multiple markers. Sets the typical spacing (distance) between consecutive edges or stripes to locate, or between the points used as a reference marker ...

FirstValue
M_ANY

Specifies that spacing is not considered.

This setting cannot be used for a point marker.

This is the default value.
M_SAME

Specifies that the average spacing of all located edges or stripes will be used.

This setting cannot be set for a point marker.

Value

Specifies the spacing, in pixels.

You can set one of the following values for edge and stripe markers.

Open Collapse CharacteristicToSet Description
FirstValue
SecondValue
Open Collapse M_BOX_ANGLE

Sets the angle of the measurement box. Sets the angle of the measurement box ...

The measurement box's center of rotation is set with M_BOX_ANGLE_REFERENCE. For a multiple point marker, the box angle determines the angle from which subsequent points are placed (at the interval set with M_SPACING), proceeding from the coordinates defined by M_POSITION, M_POSITION_X, and M_POSITION_Y.

FirstValue
0 to 360

Specifies the angle of the measurement box, in degrees.

The default value is 0 °.

M_ANY

Specifies that the content of the measurement box is analyzed to automatically determine the angle of the marker.

Open Collapse M_BOX_ANGLE_ACCURACY

Sets the accuracy of the angular search. Sets the accuracy of the angular search ...

This determines the size of the step angle to use once the approximate location of the marker is found.

FirstValue
0.1 to 180.0

Specifies the accuracy of the angular search, in degrees.

M_DISABLE

Specifies the angle of accuracy to be equal to the angle of tolerance.

This is the default value.
Open Collapse M_BOX_ANGLE_DELTA_NEG

Sets the negative range of angles within which to search for the marker, in degrees. Sets the negative range of angles within which to search for the marker, in degrees ...

The search is performed between the range of angles defined by: (M_BOX_ANGLE- M_BOX_ANGLE_DELTA_NEG) to (M_BOX_ANGLE + M_BOX_ANGLE_DELTA_POS), inclusively, starting with an angle closest to that of M_BOX_ANGLE.

FirstValue
M_DEFAULT

Specifies the default negative range of angles, in degrees.

For a symmetrical stripe marker, the default is 180.0

For an edge marker or a non-symmetrical stripe marker, the default is 360.0.

0.1 to 360.0

Specifies the negative range of angles, in degrees.

Open Collapse M_BOX_ANGLE_DELTA_POS

Sets the positive range of angles within which to search for the marker, in degrees. Sets the positive range of angles within which to search for the marker, in degrees ...

The search is performed between the range of angles defined by: (M_BOX_ANGLE- M_BOX_ANGLE_DELTA_NEG) to (M_BOX_ANGLE + M_BOX_ANGLE_DELTA_POS), inclusively, starting with an angle closest to that of M_BOX_ANGLE.

FirstValue
M_DEFAULT

Specifies the default positive range of angles, in degrees.

For a symmetrical stripe marker, the default is 180.0

For an edge marker or a non-symmetrical stripe marker, the default is 360.0.

0.1 to 360.0

Specifies the positive range of angles, in degrees.

Open Collapse M_BOX_ANGLE_INTERPOLATION_MODE

Sets the type of interpolation used when M_BOX_ANGLE_MODE is enabled. Sets the type of interpolation used when M_BOX_ANGLE_MODE is enabled ...

FirstValue
M_BICUBIC

Specifies bicubic interpolation.

M_BILINEAR

Specifies bilinear interpolation.

This is the default value.
M_NEAREST_NEIGHBOR

Specifies nearest-neighbor interpolation.

Open Collapse M_BOX_ANGLE_MODE

Enables the use of multiple-angle search, as specified by the settings of other M_BOX_ANGLE... characteristics. The angle with the highest match score is returned. Enables the use of multiple-angle search, as specified by the settings of other M_BOX_ANGLE... characteristics ...

FirstValue
M_DISABLE

Specifies that the search only be performed at the angle specified by M_BOX_ANGLE.

This is the default value.
M_ENABLE

Specifies that multiple-angle search is enabled.

Open Collapse M_BOX_ANGLE_REFERENCE

Sets the center of rotation used when M_BOX_ANGLE is not zero. Sets the center of rotation used when M_BOX_ANGLE is not zero ...

FirstValue
M_BOX_CENTER

Specifies the center of rotation to the values specified in M_BOX_CENTER.

This is the default value.
M_BOX_ORIGIN

Specifies the center of rotation to the values specified in M_BOX_ORIGIN.

Open Collapse M_BOX_ANGLE_TOLERANCE

Sets the rotation tolerance of the marker. Sets the rotation tolerance of the marker ...

This is the full range of degrees within which a marker can be rotated from a measurement box that is at a specific angle and still be found. This determines the step angle used for a multiple-angle search.

FirstValue
M_DEFAULT

Specifies the default value. The default value is 5.0.

0.1 to 360.0

Specifies the rotation tolerance, in degrees.

Open Collapse M_BOX_CENTER

Sets the coordinates of the measurement box's center. Sets the coordinates of the measurement box's center ...

These coordinates are relative to the top-left corner of the target image.

FirstValue
M_DEFAULT

Specifies the target image's corresponding center coordinate is used.

Value

Specifies the X-coordinate of the center of the measurement box within the target image.

SecondValue
M_DEFAULT

Specifies the target image's corresponding center coordinate is used.

Value

Specifies the Y-coordinate of the center of the measurement box within the target image.

Open Collapse M_BOX_ORIGIN

Sets the coordinates of the measurement box's top-left corner. These coordinates are relative to the top-left corner of the target image. Sets the coordinates of the measurement box's top-left corner ...

FirstValue
M_DEFAULT

Specifies the default value of the X-coordinate. The default value is 0.

Value

Specifies the X-coordinate of the measurement box's top-left corner within the target image.

SecondValue
M_DEFAULT

Specifies the default value of the Y-coordinate. The default value is 0.

Value

Specifies the Y-coordinate of the measurement box's top-left corner within the target image.

Open Collapse M_BOX_SIZE

Sets the width and height of the measurement box. Sets the width and height of the measurement box ...

FirstValue
M_DEFAULT

Specifies the width of the entire target image used.

Value

Specifies the width of the measurement box within the target image.

SecondValue
M_DEFAULT

Specifies the height of the entire target image used.

Value

Specifies the height of the measurement box within the target image.

Open Collapse M_CONTRAST

Sets the typical difference in average grayscale values between the start and end of the intensity transition (edge width) from which an edge is established. Sets the typical difference in average grayscale values between the start and end of the intensity transition (edge width) from which an edge is established ...

For a stripe marker, M_CONTRAST sets the typical difference in average grayscale values for each of its edges.

FirstValue
0 to maximum value of the buffer

Specifies the typical difference for the first edge.

The maximum value of the buffer is determined by the size of the buffer. For example, for an 8-bit buffer, the value is 255; for a 16-bit buffer, the value is 65535.

M_ANY

Specifies that the difference in average grayscale values is not considered in the search.

This is the default value.
SecondValue
0 to maximum value of the buffer

Specifies the typical difference for the second edge (for a stripe marker).

The maximum value of the buffer is determined by the size of the buffer. For example, for an 8-bit buffer, the value is 255; for a 16-bit buffer, the value is 65535.

M_ANY

Specifies that the difference in average grayscale values is not considered in the search.

This is the default value.
M_NULL

Specifies that this parameter does not apply.

This setting must be used for an edge marker.

M_SAME

Specifies that the difference in average grayscale values is the same as the first edge.

Open Collapse M_CONTRAST_VARIATION

Sets the contrast variation of an edge. Sets the contrast variation of an edge ...

This setting is ingored if M_CONTRAST is set to M_ANY.

For a stripe marker, this value should be the maximum of the contrast variation for each of its edges.

FirstValue
0 to maximum value of the buffer

Specifies the maximum tolerance of the difference.

The maximum value of the buffer is determined by the size of the buffer. For example, for an 8-bit buffer, the value is 255; for a 16-bit buffer, the value is 65535.

M_ANY

Specifies that the contrast variation is not considered in the search.

This is the default value.
Open Collapse M_EDGE_STRENGTH

Sets the maximum/minimum edge value along the edge width (depending on the polarity of the edge). Sets the maximum/minimum edge value along the edge width (depending on the polarity of the edge) ...

In an 8-bit image buffer, the maximum pixel value is 255. Therefore, a 50% edge strength in this buffer represents a maximum filter edge value of 128 and a rising edge.

FirstValue
0.0 to 100.0

Specifies the maximum/minimum edge value along the edge width of the first edge as a normalized percentage of the maximum pixel value.

M_ANY

Specifies that the strongest edge value found in the search is set as the maximum.

This is the default value.
SecondValue
0.0 to 100.0

Specifies the maximum/minimum edge value along the edge width of the second edge as a normalized percentage of the maximum pixel value (for a stripe marker).

M_ANY

Specifies that the strongest edge value found in the search is set as the maximum.

This is the default value.
M_NULL

Specifies that this parameter does not apply.

This setting must be used for an edge marker.

Open Collapse M_EDGE_STRENGTH_VARIATION

Sets the maximum tolerance of the maximum/minimum edge value of an edge. Sets the maximum tolerance of the maximum/minimum edge value of an edge ...

This setting is ignored if M_EDGE_STRENGTH is set to M_ANY.

For a stripe marker, the edge strength variation applies to both edges.

FirstValue
0.0 to 100.0

Specifies the maximum tolerance as a normalized percentage of the image buffer's maximum possible value.

For example, for an 8-bit image buffer, 10% is an edge strength variation of 25.5.

M_ANY

Specifies that the edge strength variation is not considered in the search.

This is the default value.
Open Collapse M_EDGE_THRESHOLD

Sets the edge value beneath which a grayscale variation is not considered an edge. Sets the edge value beneath which a grayscale variation is not considered an edge ...

FirstValue
M_DEFAULT

Specifies the default edge value threshold.

0.0 to 100.0

Specifies the minimum edge value (as a percentage) permissible in the target image buffer.

To consider all grayscale variations as edges, irrespective of their values, set FirstValue to 0.0. However, due to the increased number of edges, MmeasFindMarker() will execute relatively slowly.

Open Collapse M_FILTER_SMOOTHNESS

Sets the degree of smoothness (strength of denoising) applied to the internal projection buffer of the measurement box during the edge extraction. The recursive edge extraction process involves a denoising operation. Sets the degree of smoothness (strength of denoising) applied to the internal projection buffer of the measurement box during the edge extraction ...

Note that M_FILTER_SMOOTHNESS is only available if M_FILTER_TYPE is set to M_SHEN.

FirstValue
M_DEFAULT

Specifies the default value. The default value is 50.0.

0.0 to 100.0

Specifies the smoothness value.

A value of 100.0 results in a strong noise reduction effect, while a value of 0.0 has almost no noise reduction effect.

Open Collapse M_FILTER_TYPE

Sets the type of the first derivative filter with which to perform the edge extraction. The edge value calculated for each projection value of the measurement box is dependent on this setting. Sets the type of the first derivative filter with which to perform the edge extraction ...

FirstValue
M_DEFAULT

Specifies the default filter type.

The default setting is M_EULER
M_EULER

Specifies an Euler FIR filter. This filter performs a non-recursive edge extraction operation with a predefined kernel of size 2:

[-1,1]

This filter is faster but more sensitive to noise, compared to M_PREWITT filter.

M_PREWITT

Specifies a Prewitt FIR filter. This filter performs a non-recursive edge extraction operation with a predefined kernel of size 3:

[-1,0,1]

This filter is slower but less sensitive to noise, compared to M_EULER filter.

M_SHEN

Specifies a Shen-Castan Infinite Support Exponential filter. This is an exponential weighting function, of the general form:

This filter performs a recursive edge extraction operation using an IIR filter. If this filter actually used a kernel, the kernel size would be theoretically infinite.

This IIR filter is slower than FIR filters (M_EULER or M_PREWITT). However, this filter is less sensitive to noise and provides more accurate results. You can also control the strength of denoising applied to the projection buffer of the measurement box during the edge extraction, using the M_FILTER_SMOOTHNESS setting.

Open Collapse M_MARKER_REFERENCE

Sets the X and Y-offsets of the marker's reference position relative to the marker's center. Sets the X and Y-offsets of the marker's reference position relative to the marker's center ...

FirstValue
M_DEFAULT

Specifies the default X-offset value. The default value is 0.

Value

Specifies the X-offset value, in pixels.

SecondValue
M_DEFAULT

Specifies the default Y-offset value, in pixels.

Value

Specifies the Y-offset value, in pixels.

Open Collapse M_NUMBER_MIN

Sets the minimum number of edges or stripes to locate in the measurement box. Sets the minimum number of edges or stripes to locate in the measurement box ...

FirstValue
M_NUMBER

Specifies the number of edges or stripes specified in M_NUMBER.

This is the default value.
Value

Specifies the minimum number of edges or stripes to locate.

Open Collapse M_ORIENTATION

Sets the orientation of an edge or stripe marker. Sets the orientation of an edge or stripe marker ...

FirstValue
M_ANY

Specifies that the marker orientation is unknown.

M_HORIZONTAL

Specifies that the marker has a horizontal orientation.

M_VERTICAL

Specifies that the marker has a vertical orientation.

This is the default value.
Open Collapse M_POLARITY

Specifies whether an edge is a rising edge (increase in grayscale value) or a falling edge (decrease in grayscale value). Specifies whether an edge is a rising edge (increase in grayscale value) or a falling edge (decrease in grayscale value) ...

FirstValue
M_ANY

Specifies that polarity is not considered.

This is the default value.
M_NEGATIVE

Specifies that the polarity of the first edge is negative (falling edge).

M_POSITIVE

Specifies that the polarity of the first edge is positive (rising edge).

SecondValue
M_ANY

Specifies that the polarity is not considered.

M_NEGATIVE

Specifies that the polarity of the second edge is negative (falling edge).

M_NULL

Specifies that this parameter does not apply.

This setting must be used for an edge marker.

M_OPPOSITE

Specifies that the polarity of the second edge of a stripe marker is the opposite of that of the first edge.

This is the default value.
M_POSITIVE

Specifies that the polarity of the second edge is positive (rising edge).

M_SAME

Specifies that the polarity of the second edge of a stripe marker is the same as that of the first edge.

Open Collapse M_POSITION_VARIATION

Sets the tolerance of position variation. Sets the tolerance of position variation ...

FirstValue
M_ANY

Specifies that the position variation tolerance is not considered in the search.

This is the default value.
Value

Specifies the position variation tolerance within the target image, in pixels.

Open Collapse M_SPACING_VARIATION

Sets the inter-edge or inter-stripe spacing tolerance. Sets the inter-edge or inter-stripe spacing tolerance ...

FirstValue
M_ANY

Specifies that spacing variation is not considered in the search.

This is the default value.
Value

Specifies the inter-edge or inter-stripe variation, in pixels.

[Combination constants]

For weighting purposes, you can add the following value to M_CONTRAST, M_EDGE_INSIDE, M_EDGE_STRENGTH, M_POSITION, M_SPACING, and M_WIDTH.

Open Collapse Value Description
Open Collapse M_WEIGHT_FACTOR

 Add a specific weight to the specified characteristic.  Add a specific weight to the specified characteristic ...

 The value assigned to each characteristic represents the percentage of weight assigned to that characteristics. The sum of weights of the M_WEIGHT_FACTOR + M_... characteristics must be 100.

 Default assigns 50% to M_EDGE_STRENGTH and 50% to all other characteristics.

 You can set one the following values for stripe markers only.

  Open   Collapse  CharacteristicToSet
Description

FirstValue

SecondValue

  Open   Collapse   M_EDGE_INSIDE

 Sets the typical number of edges occurring inside a stripe marker.  Sets the typical number of edges occurring inside a stripe marker ...

FirstValue

 M_ANY

 Specifies that the number of edges inside a stripe marker is not considered in the search.

This is the default value.

 Value

 Specifies the number of edges inside a stripe marker.

  Open   Collapse   M_EDGE_INSIDE_VARIATION

 Sets the maximum variation (tolerance) in the number of inside edges of a stripe.  Sets the maximum variation (tolerance) in the number of inside edges of a stripe ...

FirstValue

 M_ANY

 Specifies that the maximum variation in the number of inside edges of a stripe is not considered in the search.

This is the default value.

 Value

 Specifies the maximum variation in the number of inside edges of a stripe.

 Note that this tolerance should be in increments of two if stripes are contained within stripes, since two edges are recognized for each stripe.

  Open   Collapse   M_POSITION_INSIDE_STRIPE

 Sets the location of the position, specified with M_POSITION, relative to the stripe.  Sets the location of the position, specified withM_POSITION, relative to the stripe ...

 If the position is defined as being within the stripe, the search algorithm proceeds outwards in both directions from that point. If defined as outside, no stripe including the position is considered.

FirstValue

 M_ANY

 Specifies that the position can be either inside or outside the stripe.

This is the default value.

 M_NO

 Specifies that the position is outside the stripe.

 M_YES

 Specifies that the position is inside the stripe.

  Open   Collapse   M_WIDTH

 Sets the typical width of a stripe marker (the distance between the marker's edges). This setting is only available for a stripe marker.  Sets the typical width of a stripe marker (the distance between the marker's edges) ...

FirstValue

 M_ANY

 Specifies that the typical width of a stripe marker is not considered in the search.

This is the default value.

 M_SAME

 Specifies that the typical width of a stripe marker is the average width of all located stripes.

 Value

 Specifies the typical width of a stripe marker, in pixels.

  Open   Collapse   M_WIDTH_VARIATION

 Sets the maximum variation (tolerance) of a stripe's width, in pixels.  Sets the maximum variation (tolerance) of a stripe's width, in pixels ...

 This setting must be used with M_WIDTH.

FirstValue

 M_ANY

 Specifies that the maximum variation of a stripe's width is not considered in the search.

This is the default value.

 Value

 Specifies the maximum variation of a stripe's width.

      [Combination constants]

 You can add one of the following values to a specified characteristic to set the value for a specific exterior edge of a stripe. (for example, M_EDGE_FIRST + M_CONTRAST).

  Open   Collapse  Value
Description

  Open   Collapse  M_EDGE_FIRST

 Specifies the values for the first exterior edge of a stripe for the specified characteristic.  Specifies the values for the first exterior edge of a stripe for the specified characteristic.

  Open   Collapse  M_EDGE_SECOND

 Specifies the values for the second exterior edge of a stripe for the specified characteristic.  Specifies the values for the second exterior edge of a stripe for the specified characteristic.

NUMBER MIN NUMBER NUMBER POSITION INSIDE STRIPE POSITION INSIDE STRIPE POSITION INSIDE STRIPE BOX ANGLE REFERENCE SPACING POSITION POSITION X POSITION Y BOX ANGLE MODE BOX ANGLE BOX ANGLE BOX CENTER BOX ORIGIN CONTRAST CONTRAST ANY EDGE STRENGTH ANY FILTER SMOOTHNESS FILTER TYPE SHEN EULER PREWITT EULER EULER PREWITT FILTER SMOOTHNESS NUMBER BOX ANGLE BOX ANGLE DELTA NEG BOX ANGLE BOX ANGLE DELTA POS BOX ANGLE CONTRAST EDGE INSIDE EDGE STRENGTH POSITION SPACING WIDTH WEIGHT FACTOR EDGE STRENGTH POSITION WIDTH EDGE FIRST CONTRAST     NUMBER ALL  POSITION  ANY  ANY  POSITION X ANY  POSITION Y ANY  SPACING ANY SAME  BOX ANGLE  ANY BOX ANGLE ACCURACY  DISABLE BOX ANGLE DELTA NEG DEFAULT  BOX ANGLE DELTA POS DEFAULT  BOX ANGLE INTERPOLATION MODE BICUBIC BILINEAR NEAREST NEIGHBOR BOX ANGLE MODE DISABLE ENABLE  BOX ANGLE REFERENCE BOX CENTER
                         BOX ORIGIN BOX ANGLE TOLERANCE DEFAULT  BOX CENTER DEFAULT  DEFAULT  BOX ORIGIN DEFAULT  DEFAULT  BOX SIZE DEFAULT  DEFAULT  CONTRAST  ANY  ANY NULL SAME CONTRAST VARIATION  ANY EDGE STRENGTH   ANY  ANY NULL EDGE STRENGTH VARIATION  ANY EDGE THRESHOLD DEFAULT  FILTER SMOOTHNESS DEFAULT  FILTER TYPE DEFAULT EULER PREWITT SHEN MARKER REFERENCE DEFAULT  DEFAULT  NUMBER MIN NUMBER  ORIENTATION ANY HORIZONTAL VERTICAL POLARITY ANY NEGATIVE POSITIVE ANY NEGATIVE NULL OPPOSITE POSITIVE SAME POSITION VARIATION ANY  SPACING VARIATION ANY  WEIGHT FACTOR EDGE INSIDE ANY  EDGE INSIDE VARIATION ANY  POSITION INSIDE STRIPE ANY  NO YES WIDTH ANY SAME  WIDTH VARIATION ANY  EDGE FIRST EDGE SECOND


MmeasStream

See Also | Example | Availability | MmeasSetMarker
Reference:
MappInquire
MmeasSaveMarker
MsysAlloc
There are no examples containing MmeasStream().
Not available in MIL-Lite

Available in MIL
Synopsis
Load, restore, or save a marker from/to a file or a memory stream.
Syntax
void MmeasStream(
MIL_TEXT_PTR MemPtrOrFileName,
MIL_ID SystemId,
long Operation,
long StreamType,
double Version,
long ControlFlag,
MIL_ID *MarkerIdPtr,
long *SizeByteVarPtr
)
Description

This function can load or restore a previously saved marker from a file or memory stream. All the marker characteristics that were in effect when the marker was saved is restored. This function can also save an allocated marker, including all its characteristics, to a specified file or memory stream.

To inquire the number of bytes necessary to save a marker to memory stream, you should call this function (MmeasStream()) first with M_INQUIRE_SIZE_BYTE.

The content saved to memory stream is equivalent to the content saved to file. In addition, any file saved with MmeasSaveMarker() is equivalent to a file saved using this function.

You can use this and other MIL stream functions, for example, to save all required MIL objects, as well as any other custom data, for your application to a memory stream. Once in a memory stream, you can write the stream to a single file or transfer it over a network. You are responsible for concatenating the streams and for saving the stream to file.

Parameters
MemPtrOrFileName

Specifies the file or memory stream.

When the StreamType parameter is set to M_FILE, MemPtrOrFileName specifies the name and path of the file required for the operation. The function internally handles the opening and closing of the file. If the file already exists, it will be overwritten when M_SAVE is performed.

When the StreamType parameter is set to M_MEMORY, MemPtrOrFileName specifies the address of the block of memory required for the operation. The designated block must be large enough to stream the entire object. To know the required size, call this function (MmeasStream()) first with M_INQUIRE_SIZE_BYTE.

When performing an M_INQUIRE_SIZE_BYTE operation, set this parameter to M_NULL.

SystemId

Specifies the system on which to restore the measurement marker. For M_INQUIRE_SIZE_BYTE, M_LOAD, and M_SAVE, SystemId is ignored and should be set to M_NULL.

For an M_RESTORE operation, this parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 Operation

 Specifies the operation to perform on the measurement marker.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_INQUIRE_SIZE_BYTE

 Inquires the number of bytes required to save a measurement marker to memory stream. This operation is not supported when the StreamType parameter is set to M_FILE.  Inquires the number of bytes required to save a measurement marker to memory stream ...

  Open   Collapse  M_LOAD

 Loads the content of a specified file or memory stream into a previously allocated measurement marker.  Loads the content of a specified file or memory stream into a previously allocated measurement marker.

  Open   Collapse  M_RESTORE

 Restores a measurement marker from a file or memory stream and assigns it an identifier.  Restores a measurement marker from a file or memory stream and assigns it an identifier.

  Open   Collapse  M_SAVE

 Saves a measurement marker to a specified file or memory stream.  Saves a measurement marker to a specified file or memory stream.

 StreamType

 Specifies the type of stream that holds the measurement marker.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_FILE

 Specifies a file stream.  Specifies a file stream.

  Open   Collapse  M_MEMORY

 Specifies a memory stream. You are responsible for allocating a block of memory for the stream.  Specifies a memory stream ...

 Version

 Specifies the MIL version of the measurement marker. For M_LOAD and M_RESTORE, this parameter must be set to M_DEFAULT.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the version to current version of MIL.  Sets the version to current version of MIL.

  Open   Collapse  Value

 Sets the version to a specific version of MIL. This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.  Sets the version to a specific version of MIL ...

 The version specified must be greater or equal to 7.1 for a memory stream, and greater or equal to 5.0 for a file. The version specified must never be greater than the current MIL version. To know the current MIL version, call MappInquire() with M_VERSION.

 By supplying a specific version, you can control the marker's accessibility. For instance, if you allocate a marker's using MIL 8.0 and set its version to 7.5, this object can be restored on a computer where MIL 7.5 is installed. However, all settings unique to the higher version will be ignored when opened in the lower version. Note that a program using MIL of a higher version can access a marker's stream created or designated with a lower or equal version. Settings that do not exist in the lower version will be filled with default values when the file or memory stream is restored.

 ControlFlag

 Specifies the function's control flag and should be set to M_DEFAULT.

 MarkerIdPtr

 Specifies the address of the variable in which to write or from which to read the identifier of the marker.

 For M_INQUIRE_SIZE_BYTE and M_SAVE operations, MarkerIdPtr specifies the address of the variable from which to read the marker idenfier.

 For an M_LOAD operation, the MarkerIdPtr specifies the address of the variable from which to read the identifier of the marker where the file or memory stream content will be loaded.

 For an M_RESTORE operation, the MarkerIdPtr specifies the address in which to return the identifier of the restored marker. If the operation is not successful, M_NULL is returned.

 SizeByteVarPtr

 Specifies the address of the variable in which to write the size of the measurement marker, in bytes.

 If the size is not required, you can set this parameter to M_NULL.

 Note that the size of a measurement marker will vary depending on the MIL version specified.

INQUIRE SIZE BYTE FILE SAVE MEMORY INQUIRE SIZE BYTE INQUIRE SIZE BYTE INQUIRE SIZE BYTE LOAD SAVE RESTORE FILE LOAD  RESTORE DEFAULT INQUIRE SIZE BYTE SAVE VERSION INQUIRE SIZE BYTE SAVE LOAD RESTORE   DEFAULT HOST   INQUIRE SIZE BYTE LOAD RESTORE SAVE  FILE MEMORY  DEFAULT


mod

Mmod functions

Example | Availability
There are no examples containing mod().
Not available in MIL-Lite

Available in MIL
Synopsis
The Geometric Model Finder module is a set of functions which find occurrences of models, or sets or image characteristics, in target images or Edge Finder result buffers. The Model Finder module uses a geometric search method to help solve machine vision problems, such as alignment, measurement, and inspection. The model finder control also 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.
Functions
  • MmodAlloc
  • MmodAllocResult
  • MmodControl
  • MmodDefine
  • MmodDefineFromFile
  • MmodDraw
  • MmodFind
  • MmodFree
  • MmodGetResult
  • MmodInquire
  • MmodMask
  • MmodPreprocess
  • MmodRestore
  • MmodSave
  • MmodStream


MmodAlloc

See Also | Example | Availability | MmodAllocResult
User Guide:
Steps to performing a search
Types of Model Finder contexts
Defining and adding models to your Model Finder context

Reference:
MmodControl
MmodDefine
MmodFind
MmodFree
MsysAlloc
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a Model Finder context.
Syntax
MIL_ID MmodAlloc(
MIL_ID SystemId,
long ModelFinderType,
long ControlFlag,
MIL_ID *ContextIdPtr
)
Description

This function allocates a Model Finder context on the specified system. A Model Finder context contains all the information necessary to perform an MmodFind() search, including global search settings, and the individual model(s) to locate. When the Model Finder context is no longer required, you should release its memory, using MmodFree().

Models can be defined and added to a Model Finder context using MmodDefine().

The Model Finder context and individual model search settings can be adjusted using MmodControl().

Parameters
SystemId

Specifies the system on which to allocate the context. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ModelFinderType

 Sets the type of Model Finder context. This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_GEOMETRIC

 Specifies that the Model Finder context uses a general geometric search algorithm. This algorithm uses geometric features to locate user-specified model(s).  Specifies that the Model Finder context uses a general geometric search algorithm ...

  Open   Collapse  M_GEOMETRIC_CONTROLLED

 Specifies that the Model Finder context uses a controlled geometric search algorithm.  Specifies that the Model Finder context uses a controlled geometric search algorithm ...

 This search method is recommended when there are only small differences in rotation and scale between the occurrence and the nominal angle and scale of the model (M_ANGLE and M_SCALE, respectively). When there is a lot of geometric complexity, this search method is often faster than M_GEOMETRIC. Also, it is often more robust in such conditions.

M_SEARCH_ANGLE_RANGE and M_SEARCH_SCALE_RANGE are both disabled by default and cannot be set to M_ENABLE. As well, you cannot get or draw the target edges for all of the target (M_GENERAL); you can only get or draw them in the region of the occurrence.

 ControlFlag

 Specifies the function's control flag. This parameter must be set to M_DEFAULT.

 ContextIdPtr

 Specifies the address of the variable in which to write the Model Finder context identifier.  Since the MmodAlloc() function also returns the Model Finder context identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the Model Finder context's identifier. If allocation fails, M_NULL is returned.

ANGLE SCALE GEOMETRIC SEARCH ANGLE RANGE SEARCH SCALE RANGE GENERAL  DEFAULT HOST   GEOMETRIC GEOMETRIC CONTROLLED


MmodAllocResult

See Also | Example | Availability | MmodAlloc | MmodControl
User Guide:
Steps to performing a search

Reference:
MmodFind
MmodFree
MsysAlloc
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a Model Finder result buffer.
Syntax
MIL_ID MmodAllocResult(
MIL_ID SystemId,
long ControlFlag,
MIL_ID *ModResultIdPtr
)
Description

This function allocates a result buffer, on the specified system, to store results obtained from a MmodFind() operation. When the result buffer is no longer required, release its memory, using MmodFree().

Parameters
SystemId

Specifies the system on which to allocate the result buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 ModResultIdPtr

 Specifies the address of the variable in which to write the Model Finder result buffer identifier.  Since the MmodAllocResult() function also returns the model result buffer identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the Model Finder result buffer identifier. If allocation fails, M_NULL is returned.

 DEFAULT HOST


MmodControl

See Also | Example | Availability | MmodAllocResult | MmodDefine
User Guide:
Steps to performing a search
Defining and adding models to your Model Finder context
Search targets
Position, angle, and scale
Customizing search settings
Advanced search settings
Global context settings
Speeding up the search
Retrieving and analyzing results
Calibration

Reference:
MmodAlloc
MmodAllocResult
MmodDefine
MmodDraw
MmodFind
MmodGetResult
MmodInquire
MmodPreprocess
MmodRestore
MmodStream
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Morphis
Fully supported on Matrox Orion
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Synopsis
Control a Model Finder context, individual model setting, or Model Finder result buffer.
Syntax
void MmodControl(
MIL_ID ContextOrResultID,
long Index,
long ControlType,
double ControlValue
)
Description

This function sets the specified control for either a Model Finder context itself, for one (or all) of the models contained therein, or for a Model Finder result buffer. These settings control the execution of MmodFind() operations. All the control type settings can be inquired using MmodInquire().

Changing certain control type settings might require preprocessing of the Model Finder context again, using MmodPreprocess(). To know if the Model Finder context needs to be preprocessed, call MmodInquire() with the M_PREPROCESSED inquire type.

Parameters
ContextOrResultID

Specifies the Model Finder context or Model Finder result buffer whose settings you want to modify. The Model Finder context or result buffer must have been previously allocated on the system using MmodAlloc() or MmodAllocResult(), respectively.

Index

Specifies that the Model Finder context, an individual model, or a Model Finder result buffer is controlled. Set this parameter to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default.  Specifies the default ...

 If a Model Finder context is specified, same as M_ALL.

 If a Model Finder result buffer is specified, same as M_GENERAL.

  Open   Collapse  M_ALL

 Applies the specified control setting to all models, if a Model Finder context is specified.  Applies the specified control setting to all models, if a Model Finder context is specified.

  Open   Collapse  M_CONTEXT

 Controls a general setting of a specified Model Finder context, if one is specified.  Controls a general setting of a specified Model Finder context, if one is specified.

  Open   Collapse  M_GENERAL

 Controls a general setting of a Model Finder result buffer when ContextOrResultID is a result buffer.  Controls a general setting of a Model Finder result buffer when ContextOrResultID is a result buffer.

  Open   Collapse  Value

 Specifies the index of the individual model to control, if a Model Finder context is specified.  Specifies the index of the individual model to control, if a Model Finder context is specified ...

 User labels cannot be used as indices; to retrieve the index of a model from its user label, use MmodInquire() with M_INDEX_FROM_LABEL.

 ControlType

 Specifies the setting to change.

See the Parameter associations section for possible values.

 ControlValue

 Specifies the setting's new value.

 All values are set in pixels, regardless of whether the model is calibrated.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue
         parameters are described below.

 The following ControlType and corresponding ControlValue setting can be specified for both the Model Finder context (M_CONTEXT) and each individual model in the Model Finder context:

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_NUMBER

 Sets the maximum number of all model occurrences, or the maximum number of occurrences of the specified model, to find in the target.  Sets the maximum number of all model occurrences, or the maximum number of occurrences of the specified model, to find in the target ...

 Once the number of occurrences for the context, with scores and target scores above their certainty levels, has been reached, the search will stop, regardless of whether the actual number set for any individual model has been found.

 To further illustrate the relationship between the M_NUMBER setting for the context and that of the individual models, see the Customizing search settings section in
          Chapter 8: Geometric Model Finder.

 M_DEFAULT

 Specifies the default value.

 For M_CONTEXT, the default is M_ALL.

 For a model, the default value is 1.

 M_ALL

 Specifies to find all occurrences.

 For M_CONTEXT, M_ALL finds all the occurrences specified for each model in the context.

 For a model, M_ALL finds all the occurrences of the specified model.

 Note that this setting can increase the search time; always set M_NUMBER to a specific number whenever possible.

 Value

 Specifies the number of occurrences.

 For M_CONTEXT, this value specifies the number of occurrences, for all models within the context, to find in the target.

 For a model, this value specifies the maximum number of occurrences of the specified model to find in the target.

 The possible ControlType and corresponding ControlValue settings for M_CONTEXT are:

  Open   Collapse  ControlType
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

ControlValue

  Open   Collapse   M_ACCURACY

 Sets the accuracy with which to find occurrences. The precision achieved is dependent on the quality of the model and the target. In addition, positional accuracy is slightly affected by the setting of the M_SPEED.  Sets the accuracy with which to find occurrences ...

 Note that lower accuracy can speed up the MmodFind() operation.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_MEDIUM.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_HIGH

 Sets the accuracy to high.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_MEDIUM

 Sets the accuracy to medium.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_ASPECT_RATIO

 Sets the nominal search aspect ratio for the target. When the target is not calibrated, this control type allows you to quickly compensate for aspect ratio distortion in the target, typically a side effect of the sampling rate used by the frame grabber. When the target is calibrated, this control type is ignored.  Sets the nominal search aspect ratio for the target ...

 This control type is mainly useful when dealing with synthetic models since it does not compensate for aspect ratio distortion in the model.

 When performing the search, the nominal search aspect ratio is taken into account horizontally, adjusting the target pixel width to equal the pixel height. As such, results will be returned for this corrected target coordinate system. However, the results are converted to the original target coordinate system if you draw them using MmodDraw().

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Specifies the default value. The default value is 1.0.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 0.5 to 2.0

 Specifies the pixel width/pixel height of the target.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_DETAIL_LEVEL

 Sets the level of details to extract from model images and target images during edge extraction. The detail level determines what is considered an edge/background.  Sets the level of details to extract from model images and target images during edge extraction ...

 A higher detail level will include more edges than a lower detail level.

 This setting is only used when dealing with image-type models and image-type targets.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_MEDIUM.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_HIGH

 Sets the detail level to high.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_MEDIUM

 Sets the detail level to medium.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_VERY_HIGH

 Sets the detail level to very high.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_FILTER_MODE

 Sets the mode in which to perform the edge extraction filter.  Sets the mode in which to perform the edge extraction filter ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Specifies the default filter mode. The default is typically set to the most efficient mode.

 If special hardware is available to perform the convolution, the default is M_KERNEL.

 If special hardware is not available to perform the convolution, the default is M_RECURSIVE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_KERNEL

 Specifies the use of a non-recursive implementation of the edge extraction filter.

 In this case, a kernel is used to perform the neighborhood operation. To set the size of the filter's convolution kernel, use MmodControl() with M_KERNEL_WIDTH. Note that the size of the kernel can be constrained by the available hardware resources.

 Typically, you would only use M_KERNEL if dedicated hardware is available to perform the convolution.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 Except for very small kernels (for example, 3x3), M_RECURSIVE is more efficient than M_KERNEL.

a
b

f
g
h
i
j
k
l

p

 M_RECURSIVE

 Specifies the use of a recursive implementation of the edge extraction filter.

 If this mode actually used a kernel, the kernel size would be theoretically infinite.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_FIRST_LEVEL

 Sets the resolution level for the initial stage (lowest resolution) of the search.  Sets the resolution level for the initial stage (lowest resolution) of the search ...

 Level 0 is the original target and each higher level is half the size (and resolution) of the previous one. If the specified level is not supported by the search algorithm, the highest possible level will be used.

 A higher first level speeds up the initial search but might make it less reliable, because the model might not retain enough distinctive features at lower resolution.

M_FIRST_LEVEL is not supported if the Model Finder context uses a general geometric search algorithm.

M_FIRST_LEVEL is for advanced users of the Model Finder module. The default settings usually provide the best results for search operations.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Determines the first resolution automatically.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 0 to 7

 Specifies the resolution level. Only integer values are accepted.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_KERNEL_DEPTH

 Sets the depth of the convolution kernel used for the kernel filtering mode. M_KERNEL_DEPTH is ignored unless MmodControl() with M_FILTER_MODE is set to M_KERNEL.  Sets the depth of the convolution kernel used for the kernel filtering mode ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Specifies the default depth of the convolution kernel. The default is 8-bit.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 8

 Specifies an 8-bit kernel depth. This is faster, though less accurate, than using a 16-bit kernel depth.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 16

 Specifies a 16-bit kernel depth. This is slower, though more accurate, than using an 8-bit kernel depth.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_KERNEL_WIDTH

 Sets the maximum X and Y size of the convolution kernel used for kernel filtering mode.  Sets the maximum X and Y size of the convolution kernel used for kernel filtering mode ...

 The size of the kernel can be constrained by the available hardware resources. Larger kernels result in longer processing times.

M_KERNEL_WIDTH is ignored unless MmodControl() with M_FILTER_MODE is set to M_KERNEL.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_AUTO.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_AUTO

 Specifies the maximum X and Y size of the convolution kernel automatically, for a given smoothness factor. You can set the smoothness factor using MmodControl() with M_SMOOTHNESS.

 The size of the kernel, for a given smoothness factor, is calculated as the size beyond which the quantified filter values are zero. If the smoothness factor calls for a kernel size that is beyond the limits of your hardware, the smoothness will be sacrificed to achieve the largest possible kernel size.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 Value >= 3

 Specifies the maximum X and Y size of the convolution kernel directly. Only odd integer values are accepted.

 If your hardware cannot handle the kernel size, the effective smoothness factor will be saturated to the maximum possible value for the specified kernel size. You can set the smoothness factor using MmodControl() with M_SMOOTHNESS.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_LAST_LEVEL

 Sets the resolution level for the final stage (the highest resolution) of the search.  Sets the resolution level for the final stage (the highest resolution) of the search ...

 Level 0 is the original target and each higher level is half the size (and resolution) of the previous one. If the specified level is not supported by the search algorithm, the highest possible level will be used.

 A higher last level speeds up the initial search but might make it less reliable and less accurate, because the model might not retain enough distinctive features at such a low resolution.

 If the specified level is not supported by the search algorithm, the highest acceptable level will be used.

M_LAST_LEVEL is not supported if the Model Finder context uses a general geometric search algorithm.

M_LAST_LEVEL is for advanced users of the Model Finder module. The default settings usually provide the best results for search operations.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Determines the last resolution automatically.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 0 to 7

 Specifies the resolution level. Only integer values are accepted.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_SAVE_TARGET_EDGES

 Sets whether to save the target edges in the result buffer.  Sets whether to save the target edges in the result buffer ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_DISABLE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables saving the target edges.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Enables the saving of the target edges. By enabling this value, you can retrieve target chain information with MmodGetResult() and you can draw target edges with MmodDraw().

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_SEARCH_ANGLE_RANGE

 Sets whether to perform calculations specific to angular-range search strategies.  Sets whether to perform calculations specific to angular-range search strategies ...

 Typically, to search for models within their specified angular range (M_ANGLE- M_ANGLE_DELTA_NEG to M_ANGLE + M_ANGLE_DELTA_POS) in the target, calculations specific to angular-range search strategies should be enabled for the context. These calculations are not required to search for models at their nominal angle (M_ANGLE). In addition, if you expect that the occurrences sought are close to their model's nominal angle, you can try disabling these calculations to see if Model Finder can still find the required occurrences. Disabling these calculations might speed up the search depending on the model and the target.

 Note that candidates can only be returned as occurrences if found within the angular range specified for their model. Therefore, if you have disabled these calculations and occurrences at angles outside of a required range are being returned, you can restrict which candidates are returned as occurrences by narrowing the angular range.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Specifies the default value.

 The default is the same as M_ENABLE if the Model Finder context uses a general geometric search algorithm.

 The default is the same as M_DISABLE if the Model Finder context uses a controlled geometric search algorithm.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables calculations specific to angular-range search strategies.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Enables calculations specific to angular-range search strategies.

 This setting is not available if the Model Finder context uses a controlled geometric search algorithm.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_SEARCH_POSITION_RANGE

 Sets whether to perform calculations specific to position-range search strategies.  Sets whether to perform calculations specific to position-range search strategies ...

 Typically, to search for models within their specified position range (M_POSITION_X, M_POSITION_Y, M_POSITION_DELTA_NEG_X, M_POSITION_DELTA_POS_X, M_POSITION_DELTA_NEG_Y, M_POSITION_DELTA_POS_Y) in the target, calculations specific to position-range search strategies should be enabled for the context. These calculations are not required to search for models at their nominal position (M_POSITION_X and M_POSITION_Y). In addition, if you expect that the occurrences sought are close to their model's nominal position, you can try disabling these calculations to see if Model Finder can still find the required occurrences. Disabling these calculations might speed up the search depending on the model and the target.

 Note that candidates can only be returned as occurrences if found within the position range specified for their model. Therefore, if you have disabled these calculations and occurrences at positions outside of a required range are being returned, you can restrict which candidates are returned as occurrences by narrowing the position range.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_ENABLE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables calculations specific to position-range search strategies.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Enables calculations specific to position-range search strategies.

 Note that when these calculations are enabled, limiting the position range to the minimum required generally decreases the search time.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_SEARCH_SCALE_RANGE

 Sets whether to perform calculations specific to scale-range search strategies.  Sets whether to perform calculations specific to scale-range search strategies ...

 Typically, to search for models within their specified scale range (M_SCALE x M_SCALE_MIN_FACTOR) to (M_SCALE x M_SCALE_MAX_FACTOR) in the target, calculations specific to scale-range search strategies should be enabled for the context. These calculations are not required to search for models at their nominal scale (M_SCALE). In addition, if you expect that the occurrences sought are close to their model's nominal scale, you can try disabling these calculations to see if Model Finder can still find the required occurrences. Disabling these calculations might speed up the search depending on the model and the target.

 Note that candidates can only be returned as occurrences if found within the scale range specified for their model. Therefore, if you have disabled these calculations and occurrences at scales outside of a required range are being returned, you can restrict which candidates are returned as occurrences by narrowing the scale range.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_DISABLE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables calculations specific to scale-range search strategies.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Enables calculations specific to scale-range search strategies.

 Note that when these calculations are enabled, limiting the scale range to the minimum required generally decreases the search time.

 This setting is not available if the Model Finder context uses a controlled geometric search algorithm.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_SHARED_EDGES

 Sets whether to enable sharing of edges between occurrences.  Sets whether to enable sharing of edges between occurrences ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_DISABLE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables sharing of edges. When disabled, edges that are part of more than one occurrence are considered as part of the occurrence with the greatest score only.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Enables sharing of edges.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_SMOOTHNESS

 Sets the degree of smoothness (noise reduction) applied to the model images and target images during the edge extraction.  Sets the degree of smoothness (noise reduction) applied to the model images and target images during the edge extraction ...

 This setting is only used when dealing with image-type models or using image-type targets.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Specifies the default value. The default value is 50.0.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 0.0 to 100.0

 Specifies the smoothness value applied to the images.

 A setting of 0.0 indicates almost no noise reduction effect, while a setting of 100.0 indicates a very strong noise reduction effect.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_SPEED

 Sets the algorithm's search speed. Note that increasing the search speed can decrease the robustness and subpixel accuracy of the MmodFind() operation.  Sets the algorithm's search speed ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_MEDIUM.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_HIGH

 Sets the speed to high.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_MEDIUM

 Sets the speed to medium.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_VERY_HIGH

 Sets the speed to very high.

M_VERY_HIGH is not supported when searching for models in an Edge Finder result buffer. Models will not be found if this setting is used.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_TARGET_CACHING

 Sets whether target caching is enabled. When target caching is enabled, the geometric representation of the target, generated by MmodFind(), is kept in the result.  Sets whether target caching is enabled ...

 Subsequent calls to MmodFind() can reuse the representation, if they use the same result object and target. This increases the speed of the searches.

 Note that the geometric representation generated with a given Model Finder context might not be compatible with another context. In such a case, the cache will not be used.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Same as M_DISABLE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables target caching. Each call to MmodFind() will generate the geometric representation of the target.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Enables target caching in the result.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_TIMEOUT

 Sets the maximum search time for MmodFind(), in msec. If a search times out, the number of occurrences found at that point will be returned.  Sets the maximum search time for MmodFind(), in msec ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

Specifies the default value. The default value is 2000.0 msec.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables timing out of the search.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 Value

 Specifies the maximum search time, in msec.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 The possible ControlType and corresponding ControlValue settings for models (all or a specified one) are:

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_ACCEPTANCE

 Sets the acceptance level for the score. An occurrence will be returned only if the match score between the target and the model is greater than or equal to this level.  Sets the acceptance level for the score ...

 The score is a measure, as a percentage, of the presence and fit of the model's active edges in the occurrence. Using M_FIT_ERROR_WEIGHTING_FACTOR, you can specify how much the fit influences the score.

 M_DEFAULT

Specifies the default value. The default value is 60.0 percent.

 0.0 to 100.0

 Specifies an acceptable score. 100% indicates that for every active edge in the model, a corresponding edge must be found in the occurrence with a perfect fit (generally hard to obtain).

  Open   Collapse   M_ACCEPTANCE_TARGET

 Sets the acceptance level for the target score. An occurrence will be returned only if the target score between the target and the model is greater than or equal to this level.  Sets the acceptance level for the target score ...

 The target score is a measure, as a percentage, of edges found in the occurrence that are not found in the original model, weighted by the deviation in position of the common edges. Using M_FIT_ERROR_WEIGHTING_FACTOR, you can specify how much the fit influences the target score.

 M_DEFAULT

Specifies the default value. The default value is 0.0 percent.

 0.0 to 100.0

 Specifies an acceptable target score, as a percentage. At 0.0%, any number of extra edges is tolerated (100% allows for no extra edges in the occurrence and the occurrence must have a perfect fit).

  Open   Collapse   M_ANGLE

 Sets the nominal search angle, relative to the model reference axis angle.  Sets the nominal search angle, relative to the model reference axis angle ...

 M_DEFAULT

Specifies the default value. The default value is 0.0 °.

 0.0 to 360.0

 Specifies the nominal search angle, in degrees.

  Open   Collapse   M_ANGLE_DELTA_NEG

 Sets the lower limit of the angular range, relative to the nominal search angle (M_ANGLE). Occurrences with angles outside the angular-range cannot be returned as results.  Sets the lower limit of the angular range, relative to the nominal search angle (M_ANGLE) ...

 Note that typically, to search for model occurrences within the angular range, calculations specific to angular-range search strategies should be enabled (M_SEARCH_ANGLE_RANGE) for the context. When enabled, the angular range should be used to cover an expected variance in angle. Note that the actual angle of the occurrence does not affect search speed. If you need to search for a model at discrete angles only (for example, at intervals of 90 degrees), it is typically more efficient to define several models with different expected angles, than to search through the full angular range.

 M_DEFAULT

Specifies the default value. The default value is 180.0 °.

 0.0 to 180.0

 Specifies the lower limit of the angular range, in degrees.

  Open   Collapse   M_ANGLE_DELTA_POS

 Sets the upper limit of the angular range, relative to the nominal search angle (M_ANGLE). Occurrences with angles outside the angular-range cannot be returned as results.  Sets the upper limit of the angular range, relative to the nominal search angle (M_ANGLE) ...

 Note that typically, to search for model occurrences within the angular range, calculations specific to angular-range search strategies should be enabled (M_SEARCH_ANGLE_RANGE) for the context. When enabled, the angular range should be used to cover an expected variance in angle. Note that the actual angle of the occurrence does not affect search speed. If you need to search for a model at discrete angles only (for example, at intervals of 90 degrees), it is typically more efficient to define several models with different expected angles, than to search through the full angular range.

 M_DEFAULT

Specifies the default value. The default value is 180.0 °.

 0.0 to 180.0

 Specifies the upper limit of the angular range, in degrees.

  Open   Collapse   M_ASSOCIATED_CALIBRATION

 Associates the specified calibration object with the specified model. Note that you must reassociate (if necessary) each model with its calibration object after restoring a Model Finder context using MmodRestore() or MmodStream(), since the calibration object is not saved with the Model Finder context.  Associates the specified calibration object with the specified model ...

 In addition, for a synthetic model, you should use M_ASSOCIATED_CALIBRATION to associate the calibration object of a calibrated target with the model.

 M_DEFAULT

Same as M_NULL.

 M_NULL

 Removes the association between a model and a calibration object.

 MIL Calibration object identifier

 Specifies the calibration object to associate with the model.

  Open   Collapse   M_BOX_MARGIN_BOTTOM

 Sets a margin at the bottom of the bounding box of the model's active edges.  Sets a margin at the bottom of the bounding box of the model's active edges ...

 The bounding box of the model's active edges plus the specified margins define the size of the model box.

 The model box is used to compute the target score and to set the different masks of the model. If you change this value, all of this model's previous masks are discarded, since their size is no longer valid.

M_BOX_MARGIN_BOTTOM is only available for synthetic models.

 M_DEFAULT

 Specifies the default value. The default value is 10.0 percent of the height of the bounding box of the model's active edges.

 Value >= 0.0

 Specifies the margin, in the user-defined units for the model.

  Open   Collapse   M_BOX_MARGIN_LEFT

 Sets a margin at the left side of the bounding box of the model's active edges.  Sets a margin at the left side of the bounding box of the model's active edges ...

 The bounding box of the model's active edges plus the specified margins define the size of the model box.

 The model box is used to compute the target score and to set the different masks of the model. If you change this value, all of this model's previous masks are discarded, since their size is no longer valid.

M_BOX_MARGIN_LEFT is only available for synthetic models.

 M_DEFAULT

 Specifies the default value. The default value is 10.0 percent of the width of the bounding box of the model's active edges.

 Value >= 0.0

 Specifies the margin, in the user-defined units for the model.

  Open   Collapse   M_BOX_MARGIN_RIGHT

 Sets a margin at the right side of the bounding box of the model's active edges.  Sets a margin at the right side of the bounding box of the model's active edges ...

 The bounding box of the model's active edges plus the specified margins define the size of the model box.

 The model box is used to compute the target score and to set the different masks of the model. If you change this value, all of this model's previous masks are discarded, since their size is no longer valid.

M_BOX_MARGIN_RIGHT is only available for synthetic models.

 M_DEFAULT

 Specifies the default value. The default value is 10.0 percent of the width of the bounding box of the model's active edges.

 Value >= 0.0

 Specifies the margin, in the user-defined units for the model.

  Open   Collapse   M_BOX_MARGIN_TOP

 Sets a margin at the top of the bounding box of the model's active edges.  Sets a margin at the top of the bounding box of the model's active edges ...

 The bounding box of the model's active edges plus the specified margins define the size of the model box.

 The model box is used to compute the target score and to set the different masks of the model. If you change this value, all of this model's previous masks are discarded, since their size is no longer valid.

M_BOX_MARGIN_TOP is only available for synthetic models.

 M_DEFAULT

 Specifies the default value. The default value is 10.0 percent of the height of the bounding box of the model's active edges.

 Value >= 0.0

 Specifies the margin, in the user-defined units for the model.

  Open   Collapse   M_CAD_Y_AXIS

 Sets the direction of the Y-axis for a model of type M_DXF_FILE.  Sets the direction of the Y-axis for a model of type M_DXF_FILE ...

 When the model is added to the Model Finder context from a CAD DXF file, the model will retain its coordinate sytem (the origin and the axis). Most CAD DXF files are oriented so that the Y-axis is positive going up, whereas the coordinate system MIL uses is oriented with the Y-axis positive going down. So if you take the edge coordinates of an object from a CAD DXF file and put them in an image, the imaged object will look flipped when compared to the original object. This is also the case for a model defined from a CAD DXF file. This means that, unless the object is symmetrical, the match will not be made.

 M_DEFAULT

 Same as M_FLIP for a model of type M_DXF_FILE. If the model is not of type M_DXF_FILE, this control type must remain set to M_DEFAULT, otherwise an error is generated.

 M_FLIP

 Flips the Y-axis for the model so that the Y-axis is positive going down.

 M_NO_FLIP

 Does not flip the Y-axis for the model.

  Open   Collapse   M_CERTAINTY

 Sets the certainty level for the score, as a percentage. If both the score and target scores are above their respective certainty levels, the occurrence is considered a match, without searching the rest of the target for better matches (provided the specified number of occurrences has been found).  Sets the certainty level for the score, as a percentage ...

 M_DEFAULT

Specifies the default value. The default value is 90.0 percent.

 0.0 to 100.0

 Specifies the certainty level for the score, as a percentage.

 If you set the certainty level too high (close to 100.0%), you slow down the search because you force the search algorithm to check the whole position range for the best possible match(es). A good certainty level is slightly lower than the expected score, so that the search can finish as soon as a match is found. However, if you set the certainty level too low, false matches might be found.

  Open   Collapse   M_CERTAINTY_TARGET

 Sets the certainty level for the target score. If both the score and target scores are above their respective certainty levels, the occurrence is considered a match, without searching the rest of the target for better matches (provided the specified number of occurrences has been found).  Sets the certainty level for the target score ...

 M_DEFAULT

Specifies the default value. The default value is 0.0 percent.

 0.0 to 100.0

 Specifies the certainty level for the target score, as a percentage. See the possible values of M_CERTAINTY for more details.

  Open   Collapse   M_FIT_ERROR_WEIGHTING_FACTOR

 Sets the fit error weighting factor. This factor determines the contribution of the fit error in the score and target score calculation.  Sets the fit error weighting factor ...

 M_DEFAULT

Specifies the default value. The default value is 25.0 percent.

 0.0 to 100.0

 Specifies the fit error weighting factor, as a percentage. The higher the percentage, the greater the contribution of the fit error in determining the score and target score.

  Open   Collapse   M_MIN_SEPARATION_ANGLE

 Sets the minimum angular separation required for two occurrences to be considered two distinct matches (two separate occurrences). Note, only one of the separation criteria needs to be met for occurrences to be considered distinct.  Sets the minimum angular separation required for two occurrences to be considered two distinct matches (two separate occurrences) ...

 DISTINCT OCCURRENCE = (Separation in X) OR (Separation in Y) OR (Separation in Angle) OR (Separation in Scale)

 M_DEFAULT

Specifies the default value. The default value is 10.0 degrees.

 0.0 < Value <= 180.0

 Specifies the minimum angular separation required. This value is specified as an absolute angle value.

 M_DISABLE

 Disables the minimum angle separation criteria. When disabled (M_DISABLE), the angle is not a factor when determining if occurrences are distinct.

  Open   Collapse   M_MIN_SEPARATION_SCALE

 Sets the minimum separation required in scale for two occurrences to be considered distinct matches (two separate occurrences). This value is specified as a scale factor. Note, only one of the separation criteria needs to be met for occurrences to be considered distinct.  Sets the minimum separation required in scale for two occurrences to be considered distinct matches (two separate occurrences) ...

 DISTINCT OCCURRENCE = (Separation in X) OR (Separation in Y) OR (Separation in Angle) OR (Separation in Scale)

 M_DEFAULT

Specifies the default value. The default value is 1.1.

 1.0 < Value <= 4.0

 Specifies the criteria for minimum separation in scale.

 M_DISABLE

 Disables the minimum scale separation criteria. When disabled, the scale is not a factor when determining if occurrences are distinct.

  Open   Collapse   M_MIN_SEPARATION_X

 Sets the minimum separation required along the X-axis for two occurrences to be considered distinct matches (two separate occurrences). Note, only one of the separation criteria needs to be met for occurrences to be considered distinct.  Sets the minimum separation required along the X-axis for two occurrences to be considered distinct matches (two separate occurrences) ...

 DISTINCT OCCURRENCE = (Separation in X) OR (Separation in Y) OR (Separation in Angle) OR (Separation in Scale)

 M_DEFAULT

Specifies the default value. The default value is 10.0 percent.

 M_DISABLE

 Disables the minimum separation in X criteria. When disabled, separation along the X-axis is not a factor when determining if occurrences are distinct.

 Value

 Specifies the minimum separation as a percentage of the model's width at M_SCALE. This value can be greater than 100%.

  Open   Collapse   M_MIN_SEPARATION_Y

 Sets the minimum separation required along the Y-axis for two occurrences to be considered distinct matches (two separate occurrences). Note, only one of the separation criteria needs to be met for occurrences to be considered distinct.  Sets the minimum separation required along the Y-axis for two occurrences to be considered distinct matches (two separate occurrences) ...

 DISTINCT OCCURRENCE = (Separation in X) OR (Separation in Y) OR (Separation in Angle) OR (Separation in Scale)

 M_DEFAULT

Specifies the default value. The default value is 10.0 percent.

 M_DISABLE

 Disables the minimum separation in Y criteria. When disabled, separation along the Y-axis is not a factor when determining if occurrences are distinct.

 Value

 Specifies the minimum separation as a percentage of the model's height at M_SCALE. This value can be greater than 100%.

  Open   Collapse   M_PIXEL_SCALE

 Sets the pixel scale of the model, if it is a synthetic model. This value is the scale to apply to the model to go from model units to pixel units. M_PIXEL_SCALE is used for the match if the target is not calibrated.  Sets the pixel scale of the model, if it is a synthetic model ...

 If the target is calibrated, this value is not used for the match nor for the returned results. However, this value will be used for draw operations.

 M_DEFAULT

 Specifies the pixel scale.

 If it is a calibrated model, the default is 1/(pixel size in X of the associated calibration).

 If it is not a calibrated model, the default is 1.0

 Value > 0.0

 Specifies the pixel scale.

 Note that if the model is not a synthetic model, the only valid value is 1.0. Any other value will generate an error.

  Open   Collapse   M_POLARITY

 Sets the expected polarity of occurrences, compared to that of the model.  Sets the expected polarity of occurrences, compared to that of the model ...

 M_DEFAULT

Same as M_SAME.

 M_ANY

 Specifies that the occurrences can be a mixture of polarities.

 M_REVERSE

 Specifies that the polarity of occurrences is the reverse of that of the model.

 M_SAME

 Specifies that the polarity of occurrences is the same as that of the model.

 M_SAME_OR_REVERSE

 Specifies that the polarity of occurrences can be either the same or the reverse of that of the model.

  Open   Collapse   M_POSITION_DELTA_NEG_X

 Sets the valid position range in the negative X-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y).  Sets the valid position range in the negative X-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y) ...

 The position range limits the region in which the position of a model occurrence can be found; position coordinates which fall outside this region cannot be returned as results (MmodGetResult() with M_POSITION_X and M_POSITION_Y). Note that the position returned for an occurrence is determined by the model's reference axis position. The region defined by the position range can lie partially, or totally, outside the target.

 Note that typically, to search for model occurrences within the position range, calculations specific to position-range search strategies should be enabled (M_SEARCH_POSITION_RANGE) for the context. When enabled, using a small position range generally decreases the search time, depending on the number of details present in the target. Always set the position range to the minimum required when speed is a consideration.

 When M_POSITION_X is set to M_ALL, M_POSITION_DELTA_NEG_X will be treated as if set to M_INFINITE regardless of its actual setting.

 M_DEFAULT

Specifies the default value. The default value is 0.0.

 M_INFINITE

 Specifies the position range as the entire image plane in the negative X-direction. This means that any X-coordinate in the negative X-direction from the nominal position (even outside the target) can be returned as a result.

 Value >= 0.0

 Specifies the position range's negative X-offset, in pixels, and can be specified with subpixel accuracy.

  Open   Collapse   M_POSITION_DELTA_NEG_Y

 Sets the valid position range in the negative Y-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y).  Sets the valid position range in the negative Y-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y) ...

 The position range limits the region in which the position of a model occurrence can be found; position coordinates which fall outside this region cannot be returned as results (MmodGetResult() with M_POSITION_X and M_POSITION_Y). Note that the position returned for an occurrence is determined by the model's reference axis position. The region defined by the position range can lie partially, or totally, outside the target.

 Note that typically, to search for model occurrences within the position range, calculations specific to position-range search strategies should be enabled (M_SEARCH_POSITION_RANGE) for the context. When enabled, using a small position range generally decreases the search time, depending on the number of details present in the target. Always set the position range to the minimum required when speed is a consideration.

 When M_POSITION_Y is set to M_ALL, M_POSITION_DELTA_NEG_Y will be treated as if set to M_INFINITE regardless of its actual setting.

 M_DEFAULT

Specifies the default value. The default value is 0.0.

 M_INFINITE

 Specifies the position range as the entire image plane in the negative Y-direction. This means that any Y-coordinate in the negative Y-direction from the nominal position (even outside the target) can be returned as a result.

 Value >= 0.0

 Specifies the position range's negative Y-offset, in pixels, and can be specified with subpixel accuracy.

  Open   Collapse   M_POSITION_DELTA_POS_X

 Sets the valid position range in the positive X-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y).  Sets the valid position range in the positive X-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y) ...

 The position range limits the region in which the position of a model occurrence can be found; position coordinates which fall outside this region cannot be returned as results (MmodGetResult() with M_POSITION_X and M_POSITION_Y). Note that the position returned for an occurrence is determined by the model's reference axis position. The region defined by the position range can lie partially, or totally, outside the target.

 Note that typically, to search for model occurrences within the position range, calculations specific to position-range search strategies should be enabled (M_SEARCH_POSITION_RANGE) for the context. When enabled, using a small position range generally decreases the search time, depending on the number of details present in the target. Always set the position range to the minimum required when speed is a consideration.

 When M_POSITION_X is set to M_ALL, M_POSITION_DELTA_POS_X will be treated as if set to M_INFINITE regardless of its actual setting.

 M_DEFAULT

 Same as M_INFINITE.

 M_INFINITE

 Specifies the position range as the entire image plane in the positive X-direction. This means that any X-coordinate in the positive X-direction from the nominal position (even outside the target) can be returned as a result.

 Value >= 0.0

 Specifies the position range's positive X-offset, in pixels, and can be specified with subpixel accuracy.

  Open   Collapse   M_POSITION_DELTA_POS_Y

 Sets the valid position range in the positive Y-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y).  Sets the valid position range in the positive Y-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y) ...

 The position range limits the region in which the position of a model occurrence can be found; position coordinates which fall outside this region cannot be returned as results (MmodGetResult() with M_POSITION_X and M_POSITION_Y). Note that the position returned for an occurrence is determined by the model's reference axis position. The region defined by the position range can lie partially, or totally, outside the target.

 Note that typically, to search for model occurrences within the position range, calculations specific to position-range search strategies should be enabled (M_SEARCH_POSITION_RANGE) for the context. When enabled, using a small position range generally decreases the search time, depending on the number of details present in the target. Always set the position range to the minimum required when speed is a consideration.

 When M_POSITION_Y is set to M_ALL, M_POSITION_DELTA_POS_Y will be treated as if set to M_INFINITE regardless of its actual setting.

 M_DEFAULT

 Same as M_INFINITE.

 M_INFINITE

 Specifies the position range as the entire image plane in the positive Y-direction. This means that any Y-coordinate in the positive Y-axis from the nominal position (even outside the target) can be returned as a result.

 Value >= 0.0

 Specifies the position range's positive Y-offset, in pixels, and can be specified with subpixel accuracy.

  Open   Collapse   M_POSITION_X

 Sets the nominal search position for the X-coordinate.  Sets the nominal search position for the X-coordinate ...

 M_DEFAULT

 Specifies the default value. The default is M_ALL.

 M_ALL

 Specifies all X-coordinates.

 Value

 Specifies the nominal search position, in pixels, and can be specified with subpixel accuracy.

  Open   Collapse   M_POSITION_Y

 Sets the nominal search position for the Y-coordinate.  Sets the nominal search position for the Y-coordinate ...

 M_DEFAULT

 Specifies the default value. The default is M_ALL.

 M_ALL

 Specifies all Y-coordinates.

 Value

 Specifies the nominal search position, in pixels, and can be specified with subpixel accuracy.

  Open   Collapse   M_REFERENCE_ANGLE

 Sets the angle of the reference axis for the model. Angle results are returned relative to this axis, rather than the model source image axis.  Sets the angle of the reference axis for the model. Angle results are returned relative to this axis, rather than the model source image axis ...

 M_DEFAULT

Specifies the default value. The default value is 0.0 degrees.

 0.0 to 360.0

 Specifies the angle, in degrees.

  Open   Collapse   M_REFERENCE_X

 Sets the X-offset of the reference axis origin of the model, relative to the model origin. Position results return the X-coordinate of the model's reference axis origin transformed at the model occurrence. Position results are relative to the target origin.  Sets the X-offset of the reference axis origin of the model, relative to the model origin ...

 Note that the reference axis origin need not be in the model.

 M_DEFAULT

 Specifies that the default X-offset will be used.

 For a synthetic model, the default value is 0.0. For other types of models, the default value is the center of the model.

 Value

 Specifies the X-offset value. The value is in pixels, and can be specified in subpixel accuracy.

  Open   Collapse   M_REFERENCE_Y

 Sets the Y-offset of the reference axis origin of the model, relative to the model origin. Position results return the Y-coordinate of the model's reference axis origin transformed at the model occurrence. Position results are relative to the target origin.  Sets the Y-offset of the reference axis origin of the model, relative to the model origin ...

 Note that the reference axis origin need not be in the model.

 M_DEFAULT

 Specifies that the default Y-offset will be used.

 For a synthetic model, the default value is 0.0. For other types of models, the default value is the center of the model.

 Value

 Specifies the Y-offset value. The value is in pixels, and can be specified in subpixel accuracy.

  Open   Collapse   M_SCALE

 Sets the nominal search scale.  Sets the nominal search scale ...

 M_DEFAULT

Specifies the default value. The default value is 1.0.

 Value

 Specifies the value of the nominal search scale.

 For a synthetic model, the nominal scale can be any positive value. For all other models, the nominal scale must be from 0.5 to 2.0.

  Open   Collapse   M_SCALE_MAX_FACTOR

 Sets the factor used to determine the upper limit (maximum permitted scale) of the scale range. M_SCALE is multiplied by this factor. Occurrences with scales outside the scale-range cannot be returned as results.  Sets the factor used to determine the upper limit (maximum permitted scale) of the scale range ...

 Note that typically, to search for model occurrences within the scale range, calculations specific to scale-range search strategies should be enabled (M_SEARCH_SCALE_RANGE) for the context. When enabled, the scale range should only cover the expected variance in scale to avoid slowing down the search and avoid finding unwanted occurrences. A search through a range of scales is performed in parallel, meaning that the actual scale of an occurrence has no bearing on which occurrence will be found first.

 M_DEFAULT

Specifies the default value. The default value is 2.0.

 1.0 to 2.0

 Specifies the factor that determines the maximum scale of the occurrence.

  Open   Collapse   M_SCALE_MIN_FACTOR

 Sets the factor used to determine the lower limit (minimum permitted scale) of the scale range. M_SCALE is multiplied by this factor. Occurrences with scales outside the scale-range cannot be returned as results.  Sets the factor used to determine the lower limit (minimum permitted scale) of the scale range ...

 Note that typically, to search for model occurrences within the scale range, calculations specific to scale-range search strategies should be enabled (M_SEARCH_SCALE_RANGE) for the context. When enabled, the scale range should only cover the expected variance in scale to avoid slowing down the search and avoid finding unwanted occurrences. A search through a range of scales is performed in parallel, meaning that the actual scale of an occurrence has no bearing on which occurrence will be found first.

 M_DEFAULT

Specifies the default value. The default value is 0.5.

 0.5 to 1.0

 Specifies the factor that determines the minimum scale of the occurrence.

  Open   Collapse   M_USER_LABEL

 Sets a unique user-defined label for the specified model. This label can be used as a means of identifying your model, independently from its index, in the Model Finder context.  Sets a unique user-defined label for the specified model ...

 M_DEFAULT

Same as M_NO_LABEL.

 M_NO_LABEL

 Specifies that no user label is associated with the model.

 Value

 Specifies the user label of the model. The value must be an integer value that is not associated as a label with any other model in the Model Finder context. Since the same label cannot be associated with multiple models, you cannot pass a user label if the Index parameter of this function is set to M_ALL.

 The possible ControlType and corresponding ControlValue settings for a model, all models, or a result are:

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_DRAW_RELATIVE_ORIGIN_X

 Sets the X-offset of the region in the model image, if drawing for a model, or in the Model Finder result buffer, if drawing for a result, to draw in the destination image buffer.  Sets the X-offset of the region in the model image, if drawing for a model, or in the Model Finder result buffer, if drawing for a result, to draw in the destination image buffer ...

 This control type is not saved with the context. If you restore the context, this control type must be set again.

 M_DEFAULT

 Same as the current value of MmodInquire() M_BOX_OFFSET_X when drawing a model.

 When drawing a result, the default is 0.0 pixels.

 Value

 Specifies the relative X-offset, in pixels.

  Open   Collapse   M_DRAW_RELATIVE_ORIGIN_Y

 Sets the Y-offset of the region in the model image, if drawing for a model, or in the Model Finder result buffer, if drawing for a result, to draw in the destination image buffer.  Sets the Y-offset of the region in the model image, if drawing for a model, or in the Model Finder result buffer, if drawing for a result, to draw in the destination image buffer ...

 This control type is not saved with the context. If you restore the context, this control type must be set again.

 M_DEFAULT

 Same as the current value of MmodInquire() M_BOX_OFFSET_Y when drawing a model.

 When drawing a result, the default is 0.0 pixels.

 Value

 Specifies the relative Y-offset, in pixel units.

  Open   Collapse   M_DRAW_SCALE_X

 Sets the scale in the X-direction when drawing models or results in the destination image buffer.  Sets the scale in the X-direction when drawing models or results in the destination image buffer ...

 This control type is not saved with the context. If you restore the context, this control type must be set again.

 M_DEFAULT

 Same as the current value of M_PIXEL_SCALE, for a model.

 When drawing a result, the default is 1.0.

 Value >= 0

 Specifies the scale in the X-direction. This value must be positive.

  Open   Collapse   M_DRAW_SCALE_Y

 Sets the scale in the Y-direction when drawing models or results in the destination image buffer.  Sets the scale in the Y-direction when drawing models or results in the destination image buffer ...

 This control type is not saved with the context. If you restore the context, this control type must be set again.

 M_DEFAULT

 Same as the current value of M_PIXEL_SCALE, for a model.

 When drawing a result, the default is 1.0.

 Value >= 0

 Specifies the scale in the Y-direction. This value must be positive.

 The possible ControlType and corresponding ControlValue settings for a result are:

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_MOD_DEFINE_COMPATIBLE |  | Saves all the necessary information in the result buffer to be able to define a model from a result occurrence (MmodDefine() with M_MOD_RESULT). Saves all the necessary information in the result buffer to be able to define a model from a result occurrence (MmodDefine() with M_MOD_RESULT) ...
 | M_DEFAULT | Same as M_DISABLE.
 | M_DISABLE | Disables saving information.
 | M_ENABLE | Enables saving information.

GENERAL CONTEXT NUMBER CONTEXT ALL CONTEXT ALL ALL NUMBER CONTEXT CONTEXT SPEED KERNEL RECURSIVE KERNEL WIDTH KERNEL RECURSIVE KERNEL FIRST LEVEL FIRST LEVEL KERNEL DEPTH FILTER MODE KERNEL KERNEL WIDTH FILTER MODE KERNEL SMOOTHNESS SMOOTHNESS LAST LEVEL LAST LEVEL ANGLE ANGLE DELTA NEG ANGLE ANGLE DELTA POS ANGLE ENABLE DISABLE POSITION X POSITION Y POSITION DELTA NEG X POSITION DELTA POS X POSITION DELTA NEG Y POSITION DELTA POS Y POSITION X POSITION Y SCALE
           SCALE MIN FACTOR SCALE
           SCALE MAX FACTOR SCALE VERY HIGH FIT ERROR WEIGHTING FACTOR FIT ERROR WEIGHTING FACTOR ANGLE ANGLE ASSOCIATED CALIBRATION BOX MARGIN BOTTOM BOX MARGIN LEFT BOX MARGIN RIGHT BOX MARGIN TOP FLIP DEFAULT CERTAINTY DISABLE SCALE SCALE PIXEL SCALE POSITION X POSITION Y POSITION X POSITION Y SEARCH POSITION RANGE POSITION X ALL POSITION DELTA NEG X INFINITE POSITION X POSITION Y POSITION X POSITION Y SEARCH POSITION RANGE POSITION Y ALL POSITION DELTA NEG Y INFINITE POSITION X POSITION Y POSITION X POSITION Y SEARCH POSITION RANGE POSITION X ALL POSITION DELTA POS X INFINITE INFINITE POSITION X POSITION Y POSITION X POSITION Y SEARCH POSITION RANGE POSITION Y ALL POSITION DELTA POS Y INFINITE INFINITE ALL ALL SCALE SCALE ALL SEARCH ANGLE RANGE SEARCH SCALE RANGE POSITION X POSITION Y SEARCH POSITION RANGE BOX OFFSET X BOX OFFSET Y PIXEL SCALE PIXEL SCALE MOD RESULT DISABLE   DEFAULT ALL CONTEXT GENERAL    NUMBER DEFAULT ALL  ACCURACY DEFAULT HIGH MEDIUM ASPECT RATIO DEFAULT  DETAIL LEVEL DEFAULT VERY HIGH
                         HIGH MEDIUM FILTER MODE DEFAULT RECURSIVE KERNEL FIRST LEVEL DEFAULT  KERNEL DEPTH DEFAULT   KERNEL WIDTH DEFAULT  AUTO LAST LEVEL DEFAULT  SAVE TARGET EDGES DEFAULT
                         DISABLE ENABLE SEARCH ANGLE RANGE DEFAULT DISABLE ENABLE SEARCH POSITION RANGE DEFAULT DISABLE ENABLE SEARCH SCALE RANGE DEFAULT DISABLE
                         ENABLE  SHARED EDGES DEFAULT DISABLE
                         ENABLE SMOOTHNESS DEFAULT  SPEED DEFAULT VERY HIGH HIGH MEDIUM TARGET CACHING DEFAULT
                         DISABLE ENABLE TIMEOUT DEFAULT DISABLE  ACCEPTANCE DEFAULT  ACCEPTANCE TARGET DEFAULT  ANGLE DEFAULT  ANGLE DELTA NEG DEFAULT  ANGLE DELTA POS DEFAULT  ASSOCIATED CALIBRATION DEFAULT  NULL BOX MARGIN BOTTOM DEFAULT  BOX MARGIN LEFT DEFAULT  BOX MARGIN RIGHT DEFAULT  BOX MARGIN TOP DEFAULT  CAD Y AXIS DEFAULT FLIP NO FLIP CERTAINTY DEFAULT  CERTAINTY TARGET DEFAULT  FIT ERROR WEIGHTING FACTOR DEFAULT  MIN SEPARATION ANGLE DEFAULT  DISABLE MIN SEPARATION SCALE DEFAULT  DISABLE MIN SEPARATION X DEFAULT DISABLE  MIN SEPARATION Y DEFAULT DISABLE  PIXEL SCALE DEFAULT
                          POLARITY DEFAULT ANY REVERSE SAME
                         SAME OR REVERSE POSITION DELTA NEG X DEFAULT INFINITE  POSITION DELTA NEG Y DEFAULT INFINITE  POSITION DELTA POS X DEFAULT INFINITE  POSITION DELTA POS Y DEFAULT INFINITE  POSITION X ALL DEFAULT  POSITION Y ALL DEFAULT  REFERENCE ANGLE DEFAULT  REFERENCE X DEFAULT  REFERENCE Y DEFAULT  SCALE DEFAULT  SCALE MAX FACTOR DEFAULT  SCALE MIN FACTOR DEFAULT  USER LABEL DEFAULT NO LABEL  DRAW RELATIVE ORIGIN X DEFAULT  DRAW RELATIVE ORIGIN Y DEFAULT  DRAW SCALE X DEFAULT  DRAW SCALE Y DEFAULT  MOD DEFINE COMPATIBLE DEFAULT DISABLE ENABLE


MmodDefine

See Also | Example | Availability | MmodControl | MmodDefineFromFile
User Guide:
Steps to performing a search
Defining and adding models to your Model Finder context
Interfacing with the Geometric Model Finder module

Reference:
MedgeAllocResult
MedgeCalculate
MedgeControl
MmodAlloc
MmodControl
MmodDefineFromFile
MmodFind
MmodInquire
MmodPreprocess
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Iris
Synopsis
Add a model to, or delete a model from, a Model Finder context.
Syntax
void MmodDefine(
MIL_ID ContextId,
long ModelType,
double Param1,
double Param2,
double Param3,
double Param4,
double Param5
)
Description

This function allows you to add a model to, or delete a model from, a Model Finder context. You can define a model from an image, from a result buffer, from two other models, or you can define a synthetic model. Image-type, result-type, merge-type and synthetic models can be mixed in the same Model Finder context.

There are two types of result-type models: models defined from an Edge Finder result buffer (Edge Finder-type models), and models defined from a Model Finder result buffer (Model Finder-type model).

Merge-type models are composed of the edges of two different models. The merge-model will be added to the end of the Model Finder context, without disturbing the two models it is merged from.

There are two types of synthetic models: models of a predefined shape (predefined-shape models) and models defined from a CAD DXF file (CAD-file models). Use MmodDefineFromFile() to define a CAD-file model.

By default, synthetic models are defined to have a 10% margin around the bounding box of their active edges. When finding an occurrence, any extra edges found in this area will reduce the target score. You can change the size of the margins with the MmodControl() M_BOX_MARGIN_... control types.

Specify the dimensions of synthetic models in user-defined units. Then, specify the ratio between model units and pixel units using MmodControl() with M_PIXEL_SCALE. If the target is not calibrated, then M_PIXEL_SCALE is used for the match. If the target is calibrated, the model units should be the same as the calibrated units. If the target is calibrated, M_PIXEL_SCALE will be used for draw operations, but not for the match nor the returned results. If you are searching for a synthetic model in a calibrated target, you must also associate the calibration object of the target with the model, using M_ASSOCIATED_CALIBRATION. MIL needs the calibration object for internal purposes at preprocessing time. MIL will not use the calibration object to compensate for incongruencies between the model and the target, nor will MIL map the model's coordinate system to that of the target.

After you have specified your pixel scale and scale settings, you can verify if your synthetic models are valid, using MmodInquire() with M_VALID. Synthetic models can be invalid if their global size in X or Y (size of the model box * M_PIXEL_SCALE * M_SCALE) is greater than 1024.

If the image or the result buffer used to define the model is calibrated, then that calibration object is automatically associated with the model. Models can use different calibration objects within the same Model Finder context, provided all calibrations map to the same world. All image-type or result-type models must be either calibrated or not.

When a call to MmodFind() is made, all models that are part of the specified context are searched for simultaneously in the target.

Note, when a model is added or deleted, the Model Finder context must be preprocessed again, using MmodPreprocess().

The search is performed according to the general search settings specified in the Model Finder context (M_CONTEXT), as well as the individual model search settings. Both the context and individual model search settings can be specified using MmodControl().

The model index starts at 0, and each subsequent model added to the Model Finder context is given a sequential index number, in the order that the model was added. If a model is deleted, all entries with higher indices are shifted down one.

For more information on defining models, see the Guidelines for choosing models section in Chapter 8: Geometric Model Finder.

Parameters
ContextId

Specifies the Model Finder context to which to add, or from which to delete, the model. The Model Finder context must have been previously allocated on the required system using MmodAlloc().

ModelType

Specifies the type of model to define when adding models to the context, or specifies to delete a model from the Model Finder context.

See the Parameter associations section for possible values.

Param1

Specifies an attribute of the model to add. Its definition is dependent on the model type chosen.

See the Parameter associations section for possible values.

Param2

Specifies an attribute of the model to add. Its definition is dependent on the model type chosen.

See the Parameter associations section for possible values.

Param3

Specifies an attribute of the model to add. Its definition is dependent on the model type chosen.

See the Parameter associations section for possible values.

Param4

Specifies an attribute of the model to add. Its definition is dependent on the model type chosen.

See the Parameter associations section for possible values.

Param5

Specifies an attribute of the model to add. Its definition is dependent on the model type chosen.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ModelType, Param1, Param2, Param3, Param4, and Param5 parameters are described below.

Note that any unused parameters should be set to M_DEFAULT.

Open Collapse ModelType Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Param1
Param2
Param3
Param4
Param5
Open Collapse M_CIRCLE

Specifies a predefined circle as the model. Specifies a predefined circle as the model ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the foreground color of the circle.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_ANY.

a b c d e f g h i j k l m n o p q r
M_ANY

Specifies that the model has no specific polarity.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_BLACK

Specifies that black is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_WHITE

Specifies that white is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
Param2

Sets the radius of the circle.

a b c d e f g h i j k l m n o p q r
Open Collapse M_CROSS

Specifies a predefined cross as the model. Specifies a predefined cross as the model ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the foreground color of the cross.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_ANY.

a b c d e f g h i j k l m n o p q r
M_ANY

Specifies that the model has no specific polarity.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_BLACK

Specifies that black is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_WHITE

Specifies that white is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
Param2

Sets the width of the cross.

a b c d e f g h i j k l m n o p q r
Param3

Sets the height of the cross.

a b c d e f g h i j k l m n o p q r
Param4

Sets the horizontal thickness of the cross.

a b c d e f g h i j k l m n o p q r
Param5

Sets the vertical thickness of the cross.

a b c d e f g h i j k l m n o p q r
Open Collapse M_DIAMOND

Specifies a predefined diamond as the model. Specifies a predefined diamond as the model ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the foreground color of the diamond.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_ANY.

a b c d e f g h i j k l m n o p q r
M_ANY

Specifies that the model has no specific polarity.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_BLACK

Specifies that black is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_WHITE

Specifies that white is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
Param2

Sets the width of the diamond.

a b c d e f g h i j k l m n o p q r
Param3

Sets the height of the diamond.

a b c d e f g h i j k l m n o p q r
Open Collapse M_EDGE_RESULT

Defines a model from the results of an edge extraction performed using Edge Finder. Defines a model from the results of an edge extraction performed using Edge Finder ...

To define a model from an Edge Finder result buffer, the buffer must have been previously allocated using MedgeAllocResult(). MedgeCalculate() must have been already called. In addition, the Edge Finder result buffer must be compatible with the Model Finder context. Enable compatibility using MedgeControl() with M_MODEL_FINDER_COMPATIBLE prior to calling MedgeCalculate().

The model is defined to have all currently included edges in the result buffer.

In the case of an Edge Finder-type model, the model source image is the image from which the Edge Finder results were obtained.

a b c d e f g h i j k l m n o p q r
Param1

Sets the identifier of the Edge Finder result buffer.

a b c d e f g h i j k l m n o p q r
Specifics

The Edge Finder result buffer (Param1) must be allocated on the same system as the Model Finder context (ContextId). If it is not, an error will occur.

m n o q r
Param2

Sets the X-offset of the model origin.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that the X-offset of the model origin is the origin of the model source image.

a b c d e f g h i j k l m n o p q r
Value

Specifies the X-offset of the model origin in the model source image, in pixels.

a b c d e f g h i j k l m n o p q r
Param3

Sets the Y-offset of the model origin.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that the Y-offset of the model origin is the origin of the model source image.

a b c d e f g h i j k l m n o p q r
Value

Specifies the Y-offset of the model origin in the model source image, in pixels.

a b c d e f g h i j k l m n o p q r
Param4

Sets the width of the model.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that the width of the model is the width of the model source image.

a b c d e f g h i j k l m n o p q r
16.0 <= Value <= 1024.0

Specifies the width of the model (in X), in pixels.

a b c d e f g h i j k l m n o p q r
Param5

Sets the height of the model.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that the height of the model is the height of the model source image.

a b c d e f g h i j k l m n o p q r
16.0 <= Value <= 1024.0

Specifies the height of the model (in Y), in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_ELLIPSE

Specifies a predefined ellipse as the model. Specifies a predefined ellipse as the model ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the foreground color of the ellipse.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_ANY.

a b c d e f g h i j k l m n o p q r
M_ANY

Specifies that the model has no specific polarity.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_BLACK

Specifies that black is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_WHITE

Specifies that white is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
Param2

Sets the width of the ellipse.

a b c d e f g h i j k l m n o p q r
Param3

Sets the height of the ellipse.

a b c d e f g h i j k l m n o p q r
Open Collapse M_IMAGE

Defines a model from the specified source image (Param1). The default settings use the entire image as the model. The minimum and maximum model sizes are 16.0 x 16.0 and 1024.0 x 1024.0 pixels, respectively. Defines a model from the specified source image (Param1) ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the identifier of the image buffer (model source image) from which to extract the model. The image buffer must be a 1-band 8-bit unsigned buffer.

a b c d e f g h i j k l m n o p q r
Param2

Sets the X-offset of the model origin.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that the X-offset of the model origin is the origin of the model source image.

a b c d e f g h i j k l m n o p q r
Value

Specifies the X-offset of the model origin in the source image, in pixels.

a b c d e f g h i j k l m n o p q r
Param3

Sets the Y-offset of the model origin.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that the Y-offset of the model origin is the origin of the model source image.

a b c d e f g h i j k l m n o p q r
Value

Specifies the Y-offset of the model origin in the source image, in pixels.

a b c d e f g h i j k l m n o p q r
Param4

Sets the width of the model.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that the width of the model is the width of the model source image.

a b c d e f g h i j k l m n o p q r
16.0<=Value<=1024.0

Specifies the width of the model (in X), in pixels.

a b c d e f g h i j k l m n o p q r
Param5

Sets the height of the model.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Specifies that the height of the model is the height of the model source image.

a b c d e f g h i j k l m n o p q r
16.0<= Value <=1024.0

Specifies the height of the model (in Y), in pixels.

a b c d e f g h i j k l m n o p q r
Open Collapse M_MERGE_MODEL

Defines a model from two other models. These models have to be in the same Model Finder context. Defines a model from two other models ...

The model is defined with the edges of the first model and the edges of the second model that are not equal to the edges of the first model.

The size of the merge-type model is the size of the first model. To include all of the edges of both models in the new model, set the first parameter to the index of the larger model.

If the models being merged are calibrated, the new merge-type model will be associated with the calibration object of the first model.

a b c d e f g h i j k l m n o p q r
Param1

Sets the index of the first model. User labels cannot be used as indices; to retrieve the index of a model from its user label, use MmodInquire() with M_INDEX_FROM_LABEL.

a b c d e f g h i j k l m n o p q r
Param2

Sets the index of the second model. User labels cannot be used as indices; to retrieve the index of a model from its user label, use MmodInquire() with M_INDEX_FROM_LABEL.

a b c d e f g h i j k l m n o p q r
Open Collapse M_MOD_RESULT

Defines a model from a Model Finder result buffer. Defines a model from a Model Finder result buffer ...

The model is defined with the edges of the target at the position of the specified occurrence.

To define a model from a Model Finder result buffer, enable MmodControl() with M_MOD_DEFINE_COMPATIBLE. In the case of a Model Finder-type model, the model source image is the target from which the results were obtained.

a b c d e f g h i j k l m n o p q r
Param1

Sets the identifier of the Model Finder result buffer.

a b c d e f g h i j k l m n o p q r
Specifics

The Model Finder result buffer must be allocated on the same system as the Model Finder context (ContextId). If it is not, an error will occur.

m n o q r
Param2

Sets the index of the occurrence.

a b c d e f g h i j k l m n o p q r
Open Collapse M_RECTANGLE

Specifies a predefined rectangle as the model. Specifies a predefined rectangle as the model ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the foreground color of the rectangle.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_ANY.

a b c d e f g h i j k l m n o p q r
M_ANY

Specifies that the model has no specific polarity.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_BLACK

Specifies that black is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_WHITE

Specifies that white is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
Param2

Sets the width of the rectangle.

a b c d e f g h i j k l m n o p q r
Param3

Sets the height of the rectangle.

a b c d e f g h i j k l m n o p q r
Open Collapse M_RING

Specifies a predefined ring as the model. Specifies a predefined ring as the model ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the foreground color of the ring.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_ANY.

a b c d e f g h i j k l m n o p q r
M_ANY

Specifies that the model has no specific polarity.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_BLACK

Specifies that black is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_WHITE

Specifies that white is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
Param2

Sets the radius of the inner ring.

a b c d e f g h i j k l m n o p q r
Param3

Sets the radius of the outer ring.

a b c d e f g h i j k l m n o p q r
Open Collapse M_SQUARE

Specifies a predefined square as the model. Specifies a predefined square as the model ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the foreground color of the square.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_ANY.

a b c d e f g h i j k l m n o p q r
M_ANY

Specifies that the model has no specific polarity.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_BLACK

Specifies that black is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_WHITE

Specifies that white is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
Param2

Sets the width and height of the square.

a b c d e f g h i j k l m n o p q r
Open Collapse M_TRIANGLE

Specifies a predefined triangle as the model. Specifies a predefined triangle as the model ...

a b c d e f g h i j k l m n o p q r
Param1

Sets the foreground color of the triangle.

a b c d e f g h i j k l m n o p q r
M_DEFAULT

Same as M_ANY.

a b c d e f g h i j k l m n o p q r
M_ANY

Specifies that the model has no specific polarity.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_BLACK

Specifies that black is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
M_FOREGROUND_WHITE

Specifies that white is the foreground color of the model.

a b c d e f g h i j k l m n o p q r
Param2

Sets the width of the triangle.

a b c d e f g h i j k l m n o p q r
Param3

Sets the height of the triangle.

a b c d e f g h i j k l m n o p q r

The following ModelType parameter setting can be used to remove a model from the context.

Note that any unused parameters should be set to M_DEFAULT.

Open Collapse ModelType |  |  | Description
 | Param1
 | Param2
 | Param3
 | Param4
 | Param5
Open Collapse M_DELETE |  |  | Deletes the specified model from the context. Deletes the specified model from the context ...
 | Param1 |  | Sets the model index.
 |  | Value | Specifies the model index. User labels cannot be used as indices; to retrieve the index of a model from its user label, use MmodInquire() with M_INDEX_FROM_LABEL.

PIXEL SCALE PIXEL SCALE PIXEL SCALE ASSOCIATED CALIBRATION VALID CONTEXT ANY ANY ANY MODEL FINDER COMPATIBLE ANY INDEX FROM LABEL INDEX FROM LABEL MOD DEFINE COMPATIBLE ANY ANY ANY ANY INDEX FROM LABEL CIRCLE DEFAULT ANY FOREGROUND BLACK FOREGROUND WHITE CROSS DEFAULT ANY FOREGROUND BLACK FOREGROUND WHITE DIAMOND DEFAULT ANY FOREGROUND BLACK FOREGROUND WHITE EDGE RESULT DEFAULT DEFAULT DEFAULT DEFAULT ELLIPSE DEFAULT ANY FOREGROUND BLACK FOREGROUND WHITE IMAGE DEFAULT DEFAULT DEFAULT DEFAULT MERGE MODEL MOD RESULT RECTANGLE DEFAULT ANY FOREGROUND BLACK FOREGROUND WHITE RING DEFAULT ANY FOREGROUND BLACK FOREGROUND WHITE SQUARE DEFAULT ANY FOREGROUND BLACK FOREGROUND WHITE TRIANGLE DEFAULT ANY FOREGROUND BLACK FOREGROUND WHITE DELETE


MmodDefineFromFile

See Also | Example | Availability | MmodDefine | MmodDraw
User Guide:
Steps to performing a search
Defining and adding models to your Model Finder context

Reference:
MmodControl
MmodDefine
There are no examples containing MmodDefineFromFile().
Not available in MIL-Lite

Available in MIL
Synopsis
Defines a model from a file and adds it to a Model Finder context.
Syntax
void MmodDefineFromFile(
MIL_ID ContextID,
long Filetype,
MIL_TEXT_PTR Filename,
long ControlFlag
)
Description

This function defines a model from a file and adds it to a Model Finder context. Models defined from a file are CAD-type synthetic models; use MmodDefine() to add other types of models to the Model Finder context.

You must preprocess the Model Finder context after you add a model.

By default, synthetic models are defined to have a 10% margin around the bounding box of their active edges. When finding an occurrence, any extra edges found in this area will reduce the target score. You can change the size of the margins with the MmodControl() M_BOX_MARGIN_... control types.

When the model is added to the Model Finder context from a CAD DXF file, the model will retain the CAD-file's coordinate system (the origin and the axis). Specify the ratio between model units and pixel units using MmodControl() with M_PIXEL_SCALE.

Note that if the model is used to search in a calibrated target, you must also associate the calibration object of the target with the model, using M_ASSOCIATED_CALIBRATION. MIL needs the calibration object for internal purposes at preprocessing time. MIL will not use the calibration object to compensate for inconguencies between the model and the target, nor will MIL map the model's coordinate system to that of the target.

If the target is calibrated, the model units should be the same as the calibrated units. If the target is calibrated, M_PIXEL_SCALE will be used for draw operations, but not for the match nor the returned results.

Most CAD DXF files are oriented so that the Y-axis is positive going up, whereas the coordinate system MIL uses is oriented with the Y-axis positive going down. So if you take the edge coordinates of an object from a CAD DXF file and put them in an image, the imaged object will look flipped when compared to the original object. This is also the case for a model defined from a CAD DXF file. This means that, unless the object is symmetrical, the match will not be made. You can use M_CAD_Y_AXIS to set the Y-axis in the appropriate direction.

To delete a model from a Model Finder context, use MmodDefine() with M_DELETE.

Parameters
ContextID

Specifies the identifier of the Model Finder context.

Filetype

Specifies the type of file from which to define the model.

Open Collapse Value Description
Open Collapse M_DXF_FILE

 Defines the model from the entities in the specified CAD DXF file. This function does not support all entities that are possible in a CAD DXF file. If there are unsupported entities in the file, they are ignored, and the rest of the entities are read. The supported entities are as follows: LINE, POLYLINE, LWPOLYLINE, CIRCLE, ARC, ELLIPSE, INSERT, and BLOCK.  Defines the model from the entities in the specified CAD DXF file ...

 A model defined from a CAD DXF file has no polarity.

 Filename

 Specifies the name of the file from which to define the model.

 ControlFlag

 This parameter is reserved for future use. Set this parameter to M_DEFAULT.

PIXEL SCALE ASSOCIATED CALIBRATION PIXEL SCALE CAD Y AXIS DELETE   DXF FILE


MmodDraw

See Also | Example | Availability | MmodDefineFromFile | MmodFind
User Guide:
Defining and adding models to your Model Finder context
Masking your model
Retrieving and analyzing results
Calibration

Reference:
MgraAlloc
MmodAlloc
MmodAllocResult
MmodControl
MmodInquire
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Iris
Synopsis
Draw specific features of models or result occurrences in the destination image buffer.
Syntax
void MmodDraw(
MIL_ID GraphContId,
MIL_ID ContextOrResultId,
MIL_ID DestImageId,
long Operation,
long Index,
long ControlFlag
)
Description

This function draws specific features of models or result occurrences in the destination buffer.

You can also draw features of a zoomed region of the model image or target by specifying the appropriate values for the MmodControl() M_DRAW_RELATIVE_ORIGIN_X, M_DRAW_RELATIVE_ORIGIN_Y, M_DRAW_SCALE_X, and M_DRAW_SCALE_Y control types. The relative origin values specify, in pixels, the coordinates of the top-left corner of the region in the model image or target, while the scale values specify the X- and Y-scaling factors used to fill the destination image buffer.

When zooming, MmodDraw will draw into the destination image buffer even if the buffer is not large enough to contain all of the zoomed image. The image will be truncated.

You can use MmodInquire() with the M_CHAIN_INDEX, M_CHAIN_X, and M_CHAIN_Y controls to inquire the active edges of the model.

Note that if you try to draw a model's edges and its Model Finder context has not been preprocessed, a preliminary edge extraction operation will be performed for the model.

Parameters
GraphContId

Specifies the graphics context to use when drawing. The graphics context must have been previously allocated using MgraAlloc(). Set this parameter to M_DEFAULT to use the default graphics context.

ContextOrResultId

Specifies the Model Finder context or result buffer from which to extract the features to draw. The Model Finder context or result buffer must have been previously allocated using MmodAlloc() or MmodAllocResult(), respectively.

[Matrox Odyssey XA, Matrox Odyssey XCL, Matrox Odyssey XD, Matrox Solios XA, and Matrox Solios XCL]

The Model Finder context or result buffer must be allocated on the same system as the graphics context (GraphContId). If it is not, an error will occur.

DestImageId

Specifies the identifier of the destination image buffer in which to draw. The buffer can be any supported MIL image buffer. By drawing into its display's overlay buffer, you can also annotate an image non-destructively.

When using MmodDraw() to draw features extracted from models or targets that are associated with a calibration object, the destination drawing buffer must also be calibrated to the same world coordinate system. MmodDraw() draws all the requested features according to whether the destination image buffer is physically corrected or not.

When drawing a model, the destination image must be at least the size of the model. Use MmodInquire() with the M_ALLOC_SIZE... inquire types to get the correct size.

When drawing a synthetic model, the destination image must have a size that matches the size of the model box scaled by M_PIXEL_SCALE.

Operation

Specifies the type of operation to perform. Operations can be added together to draw multiple features at a time. For example, to draw both the result occurrence's position and active edges, you would set the Operation parameter to M_DRAW_POSITION + M_DRAW_EDGES. The Operation parameter can be set to a combination of the following values:

Open Collapse Value Description
Open Collapse M_DRAW_BOX

 Draws the model box, or a bounding box around the occurrence. Note that when drawing an occurrence, the bounding box is drawn maintaining the angle and scale of the occurrence.  Draws the model box, or a bounding box around the occurrence ...

  Open   Collapse  M_DRAW_DONT_CARES

 Draws the model's "don't care" pixels. This is available for models only.  Draws the model's "don't care" pixels ...

  Open   Collapse  M_DRAW_EDGES

 Draws the active edges of the model (not masked out) or the result occurrence. M_MODEL or M_TARGET can be added to M_DRAW_EDGES when you are working with a result occurrence. See the combination values below.  Draws the active edges of the model (not masked out) or the result occurrence ...

  Open   Collapse  M_DRAW_FLAT_REGIONS

 Draws the model's "flat regions". This is available for models only.  Draws the model's "flat regions" ...

  Open   Collapse  M_DRAW_IMAGE

 Draws the model image. This is available for models only.  Draws the model image ...

  Open   Collapse  M_DRAW_POSITION

 Draws a cross-like symbol at the model's reference axis origin or occurrence position. The cross is drawn maintaining the angle of the model's reference axis or the occurrence.  Draws a cross-like symbol at the model's reference axis origin or occurrence position ...

  Open   Collapse  M_DRAW_WEIGHT_REGIONS

 Draws the model's weighted region mask. This is available for models only.  Draws the model's weighted region mask ...

      [Combination constants]

 The values below can be added to M_DRAW_EDGES when you are working with a result occurrence.

  Open   Collapse  Value
Description

  Open   Collapse  M_MODEL

 Draws the active edges of the model transformed at the occurrence position.  Draws the active edges of the model transformed at the occurrence position ...

This is the default value.

  Open   Collapse  M_TARGET

 Draws the edges of the target in the region on the occurrence. If the Index parameter is set to M_GENERAL, then all the edges of the target are drawn. If set to M_GENERAL, M_TARGET is not supported if you use a M_GEOMETRIC_CONTROLLED Model Finder context.  Draws the edges of the target in the region on the occurrence ...

 Index

 Specifies the index of the model in the specified Model Finder context, or of the result occurrence.  This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Refers to index 0 for models and M_ALL for results.  Refers to index 0 for models and M_ALL for results.

  Open   Collapse  M_ALL

 Draws the specified feature of all models or all occurrences.  Draws the specified feature of all models or all occurrences.

  Open   Collapse  M_GENERAL

 Draws the specified feature of the entire target. This setting can only be used with M_DRAW_EDGES + M_TARGET.  Draws the specified feature of the entire target ...

  Open   Collapse  Value > = 0

 Specifies the model index or the result occurrence.  Specifies the model index or the result occurrence.

 User labels cannot be used as indices; to retrieve the index of a model from its user label, use MmodInquire() with M_INDEX_FROM_LABEL.

 ControlFlag

 Specifies where in the destination image buffer to draw.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Draws at the top-left corner of the destination image buffer.  Draws at the top-left corner of the destination image buffer ...

 When drawing features of a result occurrence, this parameter must be set to M_DEFAULT.

  Open   Collapse  M_ORIGINAL

 Draws at the offsets used to define the model region in the model source. If M_ORIGINAL is selected, the drawing is done at the original position of the model.  Draws at the offsets used to define the model region in the model source ...

M_ORIGINAL is only supported for image-type or Edge Finder-type models.

DRAW RELATIVE ORIGIN X DRAW RELATIVE ORIGIN Y DRAW SCALE X DRAW SCALE Y CHAIN INDEX CHAIN X CHAIN Y PIXEL SCALE DRAW POSITION DRAW EDGES MODEL TARGET DRAW EDGES DRAW EDGES GENERAL GENERAL TARGET GEOMETRIC CONTROLLED ALL DRAW EDGES TARGET INDEX FROM LABEL DEFAULT ORIGINAL ORIGINAL     DRAW BOX DRAW DONT CARES DRAW EDGES DRAW FLAT REGIONS DRAW IMAGE DRAW POSITION DRAW WEIGHT REGIONS MODEL TARGET   DEFAULT ALL GENERAL   DEFAULT ORIGINAL


MmodFind

See Also | Example | Availability | MmodDraw | MmodFree
User Guide:
Steps to performing a search
Defining and adding models to your Model Finder context
Search targets
Customizing search settings
Retrieving and analyzing results

Reference:
MedgeAllocResult
MedgeCalculate
MedgeControl
MmodAlloc
MmodControl
MmodGetResult
MmodPreprocess
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Search for the model(s) of the specified Model Finder context in a target image buffer or Edge Finder result buffer.
Syntax
void MmodFind(
MIL_ID ContextId,
MIL_ID TargetImageOrEdgeResultId,
MIL_ID ModResultId
)
Description

This function searches for the model(s) defined in the specified Model Finder context, in a target image or an Edge Finder result buffer, and writes the results in the provided result buffer. When an Edge Finder result buffer is specified, MmodFind() will search for the models only in the included edges in the Edge Finder result buffer. The search is performed using both the global search settings of the Model Finder context and each model's current search settings (see MmodControl()). The resulting values can be read with the MmodGetResult() function.

If an occurrence has both a score and target score equal to or above its model's respective certainty levels (specified using MmodControl() with M_CERTAINTY and M_CERTAINTY_TARGET), it is automatically considered an occurrence (default 80%); the remaining occurrences will be the best of those above (or equal to) the model's acceptance levels (specified using MmodControl() with M_ACCEPTANCE and M_ACCEPTANCE_TARGET).

The maximum number of occurrences found depends on the maximum number specified for the context (specified using MmodControl() with Index set to M_CONTEXT and ControlType set to M_NUMBER). If it is set to M_ALL, MmodFind() tries to find the maximum number of occurrences specified for each model (specified using MmodControl() with Index set to an index value and ControlType set to M_NUMBER), equal to or above the acceptance levels.

Note, the Model Finder context must be preprocessed (MmodPreprocess()) before calling this function.

If you are using a Model Finder context whose models are calibrated, the target image or Edge Finder results must also be calibrated. Conversely, if the models are uncalibrated, the target must be uncalibrated as well.

If the target image or Edge Finder results are calibrated, results are calculated in the world coordinate system, otherwise they are calculated in the image coordinate system.

If the target image or Edge Finder results are calibrated, you can retrieve results in real-world or in pixel units. However, in the presence of distortion, some results are meaningless when converted from real-world to pixel units (for example, angle, scale, and transformation coefficient results). For example, if a model appears warped in the target image, but the calibration object of the target image compensates for this during the model search, the resulting angle is meaningful in the real-world coordinate system, and meaningless in the image coordinate system.

If the target image or Edge Finder results are not calibrated and the nominal search aspect ratio is not set to 1 (MmodControl() with M_ASPECT_RATIO), the nominal search aspect ratio is taken into account horizontally when performing the search, adjusting the target pixel width to equal the pixel height (the model's aspect ratio is not adjusted). As such, results will be returned for this corrected target coordinate system.

Parameters
ContextId

Specifies the Model Finder context to use for the search. The Model Finder context must have been previously allocated on the system using MmodAlloc().

TargetImageOrEdgeResultId

Specifies the target image or Edge Finder result buffer in which to search for the models.

Target images must be 1-band 8-bit unsigned images. The minimum and maximum target image sizes are 16x16 and 32768x32768 pixels, respectively. It is important to note that the minimum and maximum target image sizes are MIL limits. To make sure that you have enough memory, you can call MmodFind(); if you don't have enough memory, you will get a MIL error.

The Edge Finder result buffer must have been previously allocated on the required system using MedgeAllocResult(); MedgeCalculate() must have already been called. In addition, the Edge Finder result buffer must be compatible with the Model Finder context. Enable compatibility using MedgeControl() with M_MODEL_FINDER_COMPATIBLE prior to calling MedgeCalculate().

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

If an Edge Finder result buffer is specified, then this result buffer must be allocated on the same system as the Model Finder context (ContextId). If it is not, an error will occur.

ModResultId

Specifies the result buffer in which to write the results of the search.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The Model Finder result buffer (ModResultId) must be allocated on the same system as the Model Finder context (ContextId). If it is not, an error will occur.

CERTAINTY CERTAINTY TARGET ACCEPTANCE ACCEPTANCE TARGET CONTEXT NUMBER ALL NUMBER ASPECT RATIO MODEL FINDER COMPATIBLE


MmodFree

See Also | Example | Availability | MmodFind | MmodGetResult
User Guide:
Steps to performing a search

Reference:
MmodAlloc
MmodAllocResult
MmodDefine
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free a Model Finder context or a result buffer.
Syntax
void MmodFree(
MIL_ID ObjectId
)
Description

This function deletes the specified Model Finder context (and all its models) or result buffer identifier, and releases any memory associated with it. Note that to only delete individual models in the context, use MmodDefine().

All Model Finder contexts and all result buffers allocated on a particular system must be freed before the system can be freed.

Parameter
ObjectId

Specifies the identifier of the Model Finder context or result buffer to free. These must have been successfully allocated (with MmodAlloc() or MmodAllocResult()) prior to calling this function.


MmodGetResult

See Also | Example | Availability | MmodFree | MmodInquire
User Guide:
Steps to performing a search
Position, angle, and scale
Global context settings
Retrieving and analyzing results
Calibration

Reference:
McalControl
MmodControl
MmodFind
MmodFree
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified type of result(s) from a Model Finder result buffer.
Syntax
void MmodGetResult(
MIL_ID ResultId,
long ResultIndex,
long ResultType,
void *ResultArrayPtr
)
Description

This function retrieves the result(s) of the specified type from a Model Finder result buffer. Results are only available after calling MmodFind().

The result entries will be ordered by match score, starting with the highest score (regardless of the result type requested). When searching for multiple models, results are not sorted according to which model occurrence was found; results are still sorted according to score. The M_INDEX result type returns the index of the model associated with the Model Finder result; whereas the M_USER_LABEL result type returns its user label.

Note that if your target has been associated with a calibration object, positional results are, by default, returned in real-world units. To have results returned in pixel units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to M_PIXEL. You should ensure that the models and targets are calibrated using the same world. Note that in the presence of distortion, some results are meaningless when converted from real-world to pixel units (for example, angle, scale, and transformation coefficient results). For example, if a model appears warped in the target, but the calibration object of the target compensates for this during the model search, the resulting angle is meaningful in the real-world coordinate system, and meaningless in the image coordinate system.

If the target is not calibrated and the nominal search aspect ratio is not set to 1 (MmodControl() with M_ASPECT_RATIO), results are returned for the corrected target coordinate system (whereby the target pixel width is equal to the pixel height).

All positional results are relative to the center of the top-left pixel in the target or the origin of the world-coordinate if the target is calibrated.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set ResultArrayPtr to M_NULL. When this parameter is set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when you pass the parameter an array instead. You must ensure that the array is sufficiently large to hold the current and previously queued results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
ResultId

Specifies the identifier of the Model Finder result buffer from which to retrieve results.

ResultIndex

Specifies where to get results. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Same as M_ALL.  Same as M_ALL.

  Open   Collapse  0 to M_NUMBER-1

 Specifies the result index.  Specifies the result index.

  Open   Collapse  M_ALL

 Retrieves the results of the specified type for all model occurrences found.  Retrieves the results of the specified type for all model occurrences found.

  Open   Collapse  M_GENERAL

 Retrieves a result relating to the entire Model Finder context.  Retrieves a result relating to the entire Model Finder context.

 ResultType

 Specifies the type of result to retrieve.

 When retrieving a general result, the ResultType parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                a
                  double.

  Open   Collapse  Value
Description

  Open   Collapse   M_CONTEXT_ID

 Returns the identifier of the Model Finder context used by MmodFind() to obtain the results in the result buffer. Note that this identifier might not be valid if the Model Finder context has been freed using MmodFree().  Returns the identifier of the Model Finder context used by MmodFind() to obtain the results in the result buffer ...

  Open   Collapse   M_MOD_DEFINE_COMPATIBLE

 Returns whether the result can be used to define a model.  Returns whether the result can be used to define a model ...

ResultArrayPtr info

Return values:
M_FALSE | Returned if the result can not be used to define a model.
M_TRUE | Returned if the result can be used to define a model.

  Open   Collapse   M_NUMBER

 Returns the number of occurrences found (all models).  Returns the number of occurrences found (all models).

  Open   Collapse   M_TIMEOUT_END

 Returns whether the timeout has been reached. You can set the timeout limit using MmodControl() with M_TIMEOUT. By default, there is no limit.  Returns whether the timeout has been reached ...

ResultArrayPtr info

Return values:
M_FALSE | Returned if the timeout has not been reached.
M_TRUE | Returned if the timeout has been reached.

 When retrieving a general result, a result for an individual occurrence, or a result for all occurrences (M_ALL), the ResultType parameter can be set to the following value.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                a
                    double (when retrieving an individual occurrence or a general result)
                   or an
                    array of type double (when retrieving all results (M_ALL))
                   with a size of M_NUMBER.

  Open   Collapse  Value
Description

  Open   Collapse   M_NUMBER_OF_CHAINED_EDGELS

 Returns the total number of chained edgels.  Returns the total number of chained edgels ...

 For a general result, M_NUMBER_OF_CHAINED_EDGELS returns the number of chained edgels in the target.

 For a specified occurrence, M_NUMBER_OF_CHAINED_EDGELS returns the chained edgels in the occurrence. When used with M_ALL, an array of results is returned, with one result per occurrence.

 You can use M_NUMBER_OF_CHAINED_EDGELS to determine the required array size for the M_CHAIN_... result types.

M_NUMBER_OF_CHAINED_EDGELS is not supported for a general result if the Model Finder context uses a controlled geometric search algorithm.

 When retrieving a general result or result(s) for a single occurrence, the ResultType parameter can be set to one of the following values.

 When retrieving a general result, the following values are not supported if the Model Finder context is an M_GEOMETRIC_CONTROLLED type of context.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                an
                  array of type double (with a size of the number of chained
                edgels
                (M_NUMBER_OF_CHAINED_EDGELS))
                .

  Open   Collapse  Value
Description

  Open   Collapse   M_CHAIN_ANGLE

 Retrieves the angle values of each edgel in all chains in the entire target or in the model occurrence.  Retrieves the angle values of each edgel in all chains in the entire target or in the model occurrence.

  Open   Collapse   M_CHAIN_INDEX

 Retrieves the chain index of each edgel in all chains in the entire target, or in the model occurrence.  Retrieves the chain index of each edgel in all chains in the entire target, or in the model occurrence ...

 The first chain in the target is identified as index 1, with increasing indices for subsequent chains.

  Open   Collapse   M_CHAIN_X

 Retrieves the X-coordinate of each edgel in all chains in the entire target or in the model occurrence.  Retrieves the X-coordinate of each edgel in all chains in the entire target or in the model occurrence.

  Open   Collapse   M_CHAIN_Y

 Retrieves the Y-coordinate of each edgel in all chains in the entire target or in the model occurrence.  Retrieves the Y-coordinate of each edgel in all chains in the entire target or in the model occurrence.

      [Combination constants]

 The following values can be added to M_NUMBER_OF_CHAINED_EDGELS, M_CHAIN_INDEX, M_CHAIN_X, or M_CHAIN_Y if retrieving results for a specific occurrence.

Open Collapse Value | Description
Open Collapse M_MODEL | Retrieves the edge information of the model transformed at the occurrence position. Retrieves the edge information of the model transformed at the occurrence position.
Open Collapse M_TARGET | Retrieves the edge information of the target in the region of the occurrence. Retrieves the edge information of the target in the region of the occurrence.

 When retrieving a result for a single occurrence or for all occurrences, the ResultType parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                a
                    double (when retrieving an individual occurrence)
                   or an
                    array of type double (when retrieving all results (M_ALL))
                   with a size of M_NUMBER.

  Open   Collapse  Value
Description

  Open   Collapse   M_ANGLE

 Retrieves the angle of the occurrence, relative to the reference axis angle specified for the model (MmodControl() with M_REFERENCE_ANGLE).  Retrieves the angle of the occurrence, relative to the reference axis angle specified for the model (MmodControl() with M_REFERENCE_ANGLE).

  Open   Collapse   M_ASPECT_RATIO

 Retrieves the found aspect ratio of all occurrences.  Retrieves the found aspect ratio of all occurrences.

  Open   Collapse   M_FIT_ERROR

 Retrieves the fit error as the average quadratic distance, in pixels or calibrated units, between the edges in the occurrence and the corresponding edges in the model. A perfect fit is represented as 0.0.  Retrieves the fit error as the average quadratic distance, in pixels or calibrated units, between the edges in the occurrence and the corresponding edges in the model ...

  Open   Collapse   M_INDEX

 Retrieves the index of the model that was found.  Retrieves the index of the model that was found.

  Open   Collapse   M_MODEL_COVERAGE

 Retrieves the model coverage of the occurrence. The model coverage is the percentage of the total length of the model's active edges found in the occurrence. 100% indicates that for every active edge in the model, a corresponding edge was found in the occurrence.  Retrieves the model coverage of the occurrence ...

 Note that using a weighted mask with a model affects the calculation of the model coverage. To view the modified equation, refer to the Determining what is a match section in
          Chapter 8: Geometric Model Finder.

  Open   Collapse   M_POLARITY

 Retrieves the polarity of the occurrence.  Retrieves the polarity of the occurrence ...

ResultArrayPtr info

Return values:
M_ANY, M_DEFAULT, M_REVERSE, M_SAME, M_SAME_OR_REVERSE (details)

  Open   Collapse   M_POSITION_X

 Retrieves the X-coordinate of the occurrence. This is the X-position of the model's reference axis transformed at the occurrence (MmodControl() with M_REFERENCE_X).  Retrieves the X-coordinate of the occurrence ...

  Open   Collapse   M_POSITION_Y

 Retrieves the Y-coordinate of the occurrence. This is the Y-position of the model's reference axis transformed at the occurrence (MmodControl() with M_REFERENCE_Y).  Retrieves the Y-coordinate of the occurrence ...

  Open   Collapse   M_SCALE

 Retrieves the scale of the occurrence.  Retrieves the scale of the occurrence.

  Open   Collapse   M_SCORE

 Retrieves the score of the occurrence (as a percentage). The score is calculated as follows:  Retrieves the score of the occurrence (as a percentage) ...

Score = Model coverage x (1 - Fit error
                        weighting factor * Normalized fit error)

 Note that the normalized fit error is the fit error converted to a number between 0.0 and 1.0.

  Open   Collapse   M_SCORE_TARGET

 Retrieves the target score of the occurrence. The target score is calculated as follows:  Retrieves the target score of the occurrence ...

Target Score = Target coverage x (1 - Fit
                        error weighting factor * Normalized fit error)

 Note that the normalized fit error is the fit error converted to a number between 0.0 and 1.0.

  Open   Collapse   M_TARGET_COVERAGE

 Retrieves the target coverage of the model. The target coverage is the total length of the model's active edges found in the occurrence, divided by the total length of edges present in the occurrence's bounding box, given as a percentage. Edges found in the target that are not present in the model will reduce this score.  Retrieves the target coverage of the model ...

 Note that using a weighted mask with a model affects the calculation of the target coverage. To view the modified equation, refer to the Determining what is a match section in
          Chapter 8: Geometric Model Finder.

  Open   Collapse   M_USER_LABEL

 Retrieves the user label of the model that was found.  Retrieves the user label of the model that was found.

 When retrieving a result for a single occurrence or for all occurrences, the ResultType parameter can be set to one of the following values. The following values are not available for all model types. For one of these values to be available for a result occurrence, the result occurrence must be of the appropriate type. Use M_SUPPORTED to ensure that the value can be used with the occurrence. If the ResultIndex parameter is set to M_ALL, all the occurrences must support the result type, otherwise an error is generated.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                a
                    double (when retrieving an individual occurrence)
                   or an
                    array of type double (when retrieving all results (M_ALL))
                   with a size of M_NUMBER.

Open Collapse Value | Description
Open Collapse M_HEIGHT | Retrieves the height of the shape. This result type is only available for M_CROSS, M_DIAMOND, M_ELLIPSE, M_RECTANGLE and M_TRIANGLE. Retrieves the height of the shape ...
Open Collapse M_HORIZONTAL_THICKNESS | Retrieves the horizontal thickness of the cross. This result type is only available for M_CROSS. Retrieves the horizontal thickness of the cross ...
Open Collapse M_INNER_RADIUS | Retrieves the inner radius of the ring. This result type is only available for M_RING. Retrieves the inner radius of the ring ...
Open Collapse M_OUTER_RADIUS | Retrieves the outer radius of the ring. This result type is only available for M_RING. Retrieves the outer radius of the ring ...
Open Collapse M_RADIUS | Retrieves the radius of the circle. This result type is only available for M_CIRCLE. Retrieves the radius of the circle ...
Open Collapse M_VERTICAL_THICKNESS | Retrieves the vertical thickness of the cross. This result type is only available for M_CROSS. Retrieves the vertical thickness of the cross ...
Open Collapse M_WIDTH | Retrieves the width of the shape. This result type is only available for M_CROSS, M_DIAMOND, M_ELLIPSE, M_RECTANGLE, M_SQUARE and M_TRIANGLE. Retrieves the width of the shape ...

 To retrieve a transformation coefficient for a single occurrence or for all occurrences, the ResultType parameter can be set to one of the following values. These coefficients allow you to convert coordinates in the model coordinate system to the corresponding coordinates in the target coordinate system for that occurrence (or vice versa). These coefficients handle variations in scale, translation, and angle. If the model is calibrated, these coefficients are given for the real world.

 Use the following equations:

 xd = axs + bys
                + c

 yd= -bxs + ays
                + d

 where a, b, c, and d are the transformation coefficients (forward or reverse); x s and y s specify the source coordinates (with respect to the origin of the model coordinate system for a forward transformation or target coordinate system for a reverse transformation); and, x d and y d are the destination coordinates (with respect to the origin of the target coordinate system for a forward transformation or model coordinate system for a reverse transformation).

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                an
                  array of type double (with a size of M_NUMBER)
                .

Open Collapse Value | Description
Open Collapse M_A_FORWARD | Retrieves the forward transformation coefficient A for the occurrence. Retrieves the forward transformation coefficient A for the occurrence.
Open Collapse M_A_REVERSE | Retrieves the reverse transformation coefficient A for the occurrence. Retrieves the reverse transformation coefficient A for the occurrence.
Open Collapse M_B_FORWARD | Retrieves the forward transformation coefficient B for the occurrence. Retrieves the forward transformation coefficient B for the occurrence.
Open Collapse M_B_REVERSE | Retrieves the reverse transformation coefficient B for the occurrence. Retrieves the reverse transformation coefficient B for the occurrence.
Open Collapse M_C_FORWARD | Retrieves the forward transformation coefficient C for the occurrence. Retrieves the forward transformation coefficient C for the occurrence.
Open Collapse M_C_REVERSE | Retrieves the reverse transformation coefficient C for the occurrence. Retrieves the reverse transformation coefficient C for the occurrence.
Open Collapse M_D_FORWARD | Retrieves the forward transformation coefficient D for the occurrence. Retrieves the forward transformation coefficient D for the occurrence.
Open Collapse M_D_REVERSE | Retrieves the reverse transformation coefficient D for the occurrence. Retrieves the reverse transformation coefficient D for the occurrence.

      [Combination constants]

 The following value can be combined with ResultType:

  Open   Collapse  Value
Description

  Open   Collapse   M_AVAILABLE

 Returns whether a result is available to be retrieved for a general result, an occurrence, or for all occurrences.  Returns whether a result is available to be retrieved for a general result, an occurrence, or for all occurrences ...

ResultType info

Return values:
M_NULL | The result is not available to be retrieved.
Value <> 0 | The result is available to be retrieved.

  Open   Collapse   M_SUPPORTED

 Returns whether a result is supported for a general result, an occurrence, or for all occurrences.  Returns whether a result is supported for a general result, an occurrence, or for all occurrences ...

ResultType info

Return values:
M_NULL | The result is not supported.
Value <> 0 | The result is supported.

      [Combination constants]

 The values below can be added to the ResultType parameter to cast the requested results to a required data type.

  Open   Collapse  Value
Description

  Open   Collapse   M_TYPE_DOUBLE

 Casts the requested results to a double.  Casts the requested results to a double ...

This is the default value.

ResultArrayPtr info

Data type:

  • array of type double
    Array size:  Depends on the result type.
    note:  When multiple results.
    •

  • double
    note:  When a single result.
    •

  Open   Collapse   M_TYPE_LONG

 Casts the requested results to a long.  Casts the requested results to a long ...

ResultArrayPtr info

Data type:

  • array of type long
    Array size:  Depends on the result type.
    note:  When multiple results.
    •

  • long
    note:  When a single result.
    •

  Open   Collapse   M_TYPE_MIL_ID

 Casts the requested results to a MIL ID.  Casts the requested results to a MIL ID ...

ResultArrayPtr info

Data type:

  • array of type MIL_ID
    Array size:  Depends on the result type.
    note:  When multiple results.
    •

  • MIL_ID
    note:  When a single result.
    •

 ResultArrayPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type double
    •

  • array of type long
    •

  • array of type MIL_ID
    •

  • double
    •

  • long
    •

  • MIL_ID
    •

 Specifies the address in which to write results.

 You can set this parameter to M_NULL to put the result request on the local queue of the result buffer.

INDEX USER LABEL OUTPUT COORDINATE SYSTEM PIXEL ASPECT RATIO ALL TIMEOUT ALL NUMBER OF CHAINED EDGELS NUMBER OF CHAINED EDGELS ALL NUMBER OF CHAINED EDGELS NUMBER OF CHAINED EDGELS GEOMETRIC CONTROLLED NUMBER OF CHAINED EDGELS CHAIN INDEX CHAIN X CHAIN Y ALL REFERENCE ANGLE REFERENCE X REFERENCE Y ALL ALL SUPPORTED ALL CROSS DIAMOND ELLIPSE RECTANGLE TRIANGLE CROSS RING RING CIRCLE CROSS CROSS DIAMOND ELLIPSE RECTANGLE SQUARE TRIANGLE ALL   DEFAULT NUMBER-1 ALL GENERAL  CONTEXT ID MOD DEFINE COMPATIBLE NUMBER TIMEOUT END NUMBER OF CHAINED EDGELS CHAIN ANGLE CHAIN INDEX CHAIN X CHAIN Y MODEL TARGET ANGLE ASPECT RATIO FIT ERROR INDEX MODEL COVERAGE POLARITY POSITION X POSITION Y SCALE SCORE SCORE TARGET TARGET COVERAGE USER LABEL HEIGHT HORIZONTAL THICKNESS INNER RADIUS OUTER RADIUS RADIUS VERTICAL THICKNESS WIDTH A FORWARD A REVERSE B FORWARD B REVERSE C FORWARD C REVERSE D FORWARD D REVERSE AVAILABLE SUPPORTED TYPE DOUBLE TYPE LONG TYPE MIL ID


MmodInquire

See Also | Example | Availability | MmodGetResult | MmodMask
User Guide:
Defining and adding models to your Model Finder context
Customizing search settings

Reference:
MmodAlloc
MmodAllocResult
MmodControl
MmodDefine
MmodDraw
MmodFind
MmodGetResult
mmodeltracking.c
Not available in MIL-Lite

Available in MIL
Synopsis
Inquire information about a specified Model Finder context or result buffer.
Syntax
long MmodInquire(
MIL_ID ContextOrResultId,
long Index,
long InquireType,
void *UserVarPtr
)
Description

This function inquires information about a specified Model Finder context, the models contained therein, or a specified Model Finder result buffer.

If the inquired setting is set to M_DEFAULT, MmodInquire() will return M_DEFAULT. To inquire its default value, add M_DEFAULT to the inquire type.

Note that Model Finder result buffer values can be obtained with MmodGetResult().

Parameters
ContextOrResultId

Specifies the Model Finder context or Model Finder result buffer about which to inquire information. The Model Finder context or result buffer must have been previously allocated on the required system using MmodAlloc() or MmodAllocResult(), respectively.

Index

Specifies that information will be inquired about the Model Finder context, an individual model, or a Model Finder result buffer. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default.  Specifies the default ...

 If a Model Finder context is specified, this parameter inquires information about model index 0.

 If a result buffer is specified, same as M_GENERAL.

  Open   Collapse  M_CONTEXT

 Inquires information about a Model Finder context, if one is specified.  Inquires information about a Model Finder context, if one is specified.

  Open   Collapse  M_GENERAL

 Inquires general information about the Model Finder result buffer, if one is specified.  Inquires general information about the Model Finder result buffer, if one is specified.

  Open   Collapse  Value

 Inquires information about a model, if a Model Finder context is specified. Set the Index parameter to the index of the required model.  Inquires information about a model, if a Model Finder context is specified ...

 To retrieve the index of a model from its user label, set this parameter to the user label and set the inquire type to M_INDEX_FROM_LABEL.

 InquireType

 Specifies the type of setting about which to inquire.

 For M_CONTEXT or individual model inquiries, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

Open Collapse Value | Description
Open Collapse M_NUMBER | Returns the maximum number of occurrences of all models to find in the target, or the maximum number of occurrences of the specified model to find in the target. Returns the maximum number of occurrences of all models to find in the target, or the maximum number of occurrences of the specified model to find in the target ...
 |  | UserVarPtr info Return values: M_ALL, M_DEFAULT, Value (details)

 The possible settings to inquire for M_CONTEXT are:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

  Open   Collapse  Value
Description

  Open   Collapse   M_ACCURACY

 Returns the search accuracy.  Returns the search accuracy ...

UserVarPtr info

Return values:
M_DEFAULT, M_HIGH, M_MEDIUM (details)

  Open   Collapse   M_ASPECT_RATIO

 Returns the nominal search aspect ratio.  Returns the nominal search aspect ratio ...

UserVarPtr info

Return values:
0.5 to 2.0, M_DEFAULT (details)

  Open   Collapse   M_CONTEXT_TYPE

 Returns the type of search context allocated.  Returns the type of search context allocated ...

UserVarPtr info

Return values:
M_GEOMETRIC, M_GEOMETRIC_CONTROLLED (details)

  Open   Collapse   M_DETAIL_LEVEL

 Returns the level of details to extract from the model source and target image.  Returns the level of details to extract from the model source and target image ...

UserVarPtr info

Return values:
M_DEFAULT, M_HIGH, M_MEDIUM, M_VERY_HIGH (details)

  Open   Collapse   M_FILTER_MODE

 Returns the mode in which to perform the edge extraction filter.  Returns the mode in which to perform the edge extraction filter ...

UserVarPtr info

Return values:
M_DEFAULT, M_KERNEL, M_RECURSIVE (details)

  Open   Collapse   M_FIRST_LEVEL

 Returns the resolution level for the initial stage of the search.  Returns the resolution level for the initial stage of the search ...

UserVarPtr info

Return values:
0 to 7, M_DEFAULT (details)

  Open   Collapse   M_KERNEL_DEPTH

 Returns the depth of the convolution kernel used for kernel filtering mode.  Returns the depth of the convolution kernel used for kernel filtering mode ...

UserVarPtr info

Return values:
8, 16, M_DEFAULT (details)

  Open   Collapse   M_KERNEL_WIDTH

 Returns the maximum size (same in X and Y) of the convolution kernel set for kernel filtering mode.  Returns the maximum size (same in X and Y) of the convolution kernel set for kernel filtering mode ...

UserVarPtr info

Return values:
M_AUTO, M_DEFAULT, Value >= 3 (details)

  Open   Collapse   M_LAST_LEVEL

 Returns the resolution level for the final stage of the search.  Returns the resolution level for the final stage of the search ...

UserVarPtr info

Return values:
0 to 7, M_DEFAULT (details)

  Open   Collapse   M_MODIFICATION_COUNT

 Returns the current value of the modification counter. The modification counter is increased by one each time settings for the context are modified. The modification counter is initialized to a number that is unique to the Model Finder context and is given its own unique range. If the context is freed, this number will not be reassigned to a new context.  Returns the current value of the modification counter. The modification counter is increased by one each time settings for the context are modified ...

 This feature can be useful when designing your application. For example, if the modification counter has changed, you can prompt the user to save before closing the application.

  Open   Collapse   M_NUMBER_MODELS

 Returns the number of models in the context.  Returns the number of models in the context.

  Open   Collapse   M_OWNER_SYSTEM

 Returns the identifier of the system on which the context was allocated.  Returns the identifier of the system on which the context was allocated.

  Open   Collapse   M_PREPROCESSED

 Returns whether the Model Finder context is preprocessed. The context must be preprocessed before calling MmodFind(). This inquire type will indicate that the context is not preprocessed after certain settings of the Model Finder context are changed with MmodControl(), and after a model is added or removed with MmodDefine().  Returns whether the Model Finder context is preprocessed ...

UserVarPtr info

Return values:
Value!= 0 | The context is preprocessed.
0 | The context is not preprocessed.

  Open   Collapse   M_SAVE_TARGET_EDGES

 Returns whether the target edges in the result will be saved.  Returns whether the target edges in the result will be saved ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_SEARCH_ANGLE_RANGE

 Returns whether to perform calculations specific to angular-range search strategies.  Returns whether to perform calculations specific to angular-range search strategies ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_SEARCH_POSITION_RANGE

 Returns whether to perform calculations specific to position-range search strategies.  Returns whether to perform calculations specific to position-range search strategies ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_SEARCH_SCALE_RANGE

 Returns whether to perform calculations specific to scale-range search strategies.  Returns whether to perform calculations specific to scale-range search strategies ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_SHARED_EDGES

 Returns whether multiple occurrences can share edges.  Returns whether multiple occurrences can share edges ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_SMOOTHNESS

 Returns the degree of smoothness (denoising) applied to the model images and the target images during edge extraction.  Returns the degree of smoothness (denoising) applied to the model images and the target images during edge extraction ...

UserVarPtr info

Return values:
0.0 to 100.0, M_DEFAULT (details)

  Open   Collapse   M_SPEED

 Returns the search speed.  Returns the search speed ...

UserVarPtr info

Return values:
M_DEFAULT, M_HIGH, M_MEDIUM, M_VERY_HIGH (details)

  Open   Collapse   M_TARGET_CACHING

 Returns whether target caching is enabled.  Returns whether target caching is enabled ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_TIMEOUT

 Returns the maximum search time for MmodFind(), in msec.  Returns the maximum search time for MmodFind(), in msec ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, Value (details)

 The possible settings to inquire for an individual model are:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

  Open   Collapse  Value
Description

  Open   Collapse   M_ACCEPTANCE

 Returns the acceptance level for the score.  Returns the acceptance level for the score ...

UserVarPtr info

Return values:
0.0 to 100.0, M_DEFAULT (details)

  Open   Collapse   M_ACCEPTANCE_TARGET

 Returns the acceptance level for the target score.  Returns the acceptance level for the target score ...

UserVarPtr info

Return values:
0.0 to 100.0, M_DEFAULT (details)

  Open   Collapse   M_ALLOC_OFFSET_X

 Returns the X-offset, in pixels, of the model in the model source image.  Returns the X-offset, in pixels, of the model in the model source image ...

 This is only supported for image-type or Edge Finder-type models. For a synthetic model, use M_BOX_OFFSET_X instead.

  Open   Collapse   M_ALLOC_OFFSET_Y

 Returns the Y-offset, in pixels, of the model in the model source image.  Returns the Y-offset, in pixels, of the model in the model source image ...

 This is only supported for image-type or Edge Finder-type models. For a synthetic model, use M_BOX_OFFSET_Y instead.

  Open   Collapse   M_ALLOC_SIGN

 Returns the data range of the model image.  Returns the data range of the model image ...

UserVarPtr info

Return values:
M_SIGNED | Data range is signed.
M_UNSIGNED | Data range is unsigned. Synthetic, Model Finder-type and merge-type models will always return M_UNSIGNED.

  Open   Collapse   M_ALLOC_SIZE_BAND

 Returns the number of bands of the model image. When drawing the model image, use M_ALLOC_SIZE_BAND to establish the required number of bands for the destination buffer.  Returns the number of bands of the model image ...

UserVarPtr info

Return values:
1 | 1-band buffer.
3 | 3-band buffer.

  Open   Collapse   M_ALLOC_SIZE_BIT

 Returns the depth per band, in bits, of the model image.  Returns the depth per band, in bits, of the model image ...

UserVarPtr info

Return values:
1 | 1-bit depth.
8 | 8-bit depth.
16 | 16-bit depth.
32 | 32-bit depth.

  Open   Collapse   M_ALLOC_SIZE_X

 Returns the width of the model box, in pixels.  Returns the width of the model box, in pixels ...

 For a synthetic model, use M_BOX_SIZE_X to get this value in user-defined units.

  Open   Collapse   M_ALLOC_SIZE_Y

 Returns the height of the model box, in pixels.  Returns the height of the model box, in pixels ...

 For a synthetic model, use M_BOX_SIZE_Y to get this value in user-defined units.

  Open   Collapse   M_ALLOC_TYPE

 Returns the data type and depth of the model image.  Returns the data type and depth of the model image ...

UserVarPtr info

Return values:
1 + M_UNSIGNED | 1-bit unsigned data.
8 + M_SIGNED | 8-bit signed data.
8 + M_UNSIGNED | 8-bit unsigned data.
16 + M_SIGNED | 16-bit signed data.
16 + M_UNSIGNED | 16-bit unsigned data.
32 + M_FLOAT | 32-bit float data.
32 + M_SIGNED | 32-bit signed data.
32 + M_UNSIGNED | 32-bit unsigned data.

  Open   Collapse   M_ANGLE

 Returns the nominal search angle, relative to the model reference axis angle.  Returns the nominal search angle, relative to the model reference axis angle ...

UserVarPtr info

Return values:
0.0 to 360.0, M_DEFAULT (details)

  Open   Collapse   M_ANGLE_DELTA_NEG

 Returns the lower limit of the angular range, relative to the nominal search angle.  Returns the lower limit of the angular range, relative to the nominal search angle ...

UserVarPtr info

Return values:
0.0 to 180.0, M_DEFAULT (details)

  Open   Collapse   M_ANGLE_DELTA_POS

 Returns the upper limit of the angular range, relative to the nominal search angle.  Returns the upper limit of the angular range, relative to the nominal search angle ...

UserVarPtr info

Return values:
0.0 to 180.0, M_DEFAULT (details)

  Open   Collapse   M_ASSOCIATED_CALIBRATION

 Returns the calibration object associated with the specified model.  Returns the calibration object associated with the specified model ...

UserVarPtr info

Return values:
M_DEFAULT, M_NULL, MIL Calibration object identifier (details)

  Open   Collapse   M_BOX_MARGIN_BOTTOM

 Returns the margin at the bottom of the bounding box of the model's active edges, in the user-defined units for the model.  Returns the margin at the bottom of the bounding box of the model's active edges, in the user-defined units for the model ...

 This is only valid for synthetic models.

UserVarPtr info

Return values:
M_DEFAULT, Value >= 0.0 (details)

  Open   Collapse   M_BOX_MARGIN_LEFT

 Returns the margin at the left of the bounding box of the model's active edges, in the user-defined units for the model.  Returns the margin at the left of the bounding box of the model's active edges, in the user-defined units for the model ...

 This is only valid for synthetic models.

UserVarPtr info

Return values:
M_DEFAULT, Value >= 0.0 (details)

  Open   Collapse   M_BOX_MARGIN_RIGHT

 Returns the margin at the right of the bounding box of the model's active edges, in the user-defined units for the model.  Returns the margin at the right of the bounding box of the model's active edges, in the user-defined units for the model ...

 This is only valid for synthetic models.

UserVarPtr info

Return values:
M_DEFAULT, Value >= 0.0 (details)

  Open   Collapse   M_BOX_MARGIN_TOP

 Returns the margin at the top of the bounding box of the model's active edges, in the user-defined units for the model.  Returns the margin at the top of the bounding box of the model's active edges, in the user-defined units for the model ...

 This is only valid for synthetic models.

UserVarPtr info

Return values:
M_DEFAULT, Value >= 0.0 (details)

  Open   Collapse   M_BOX_OFFSET_X

 Returns the X-offset of the top-left corner of the model box from the model origin.  Returns the X-offset of the top-left corner of the model box from the model origin ...

 This is only valid for synthetic models.

 For pre-defined shape models, the origin of the model is the center of the shape. For CAD-file models, the origin is the same as the one defined in the CAD file.

M_BOX_OFFSET_X is updated when the margins that define the model box are changed.

 The X-offset is returned in the units of the model.

  Open   Collapse   M_BOX_OFFSET_Y

 Returns the Y-offset of the top-left corner of the model box from the model origin.  Returns the Y-offset of the top-left corner of the model box from the model origin ...

 This is only valid for synthetic models.

 For pre-defined shape models, the origin of the model is the center of the shape. For CAD-file models, the origin is the same as the one defined in the CAD file.

M_BOX_OFFSET_Y is updated when the margins that define the model box are changed.

 The Y-offset is returned in the units of the model.

  Open   Collapse   M_BOX_SIZE_X

 Returns the size along the X-axis of the model box, in the user-defined units for the model.  Returns the size along the X-axis of the model box, in the user-defined units for the model ...

 This is only valid for synthetic models.

  Open   Collapse   M_BOX_SIZE_Y

 Returns the size along the Y-axis of the model box, in the user-defined units for the model.  Returns the size along the Y-axis of the model box, in the user-defined units for the model ...

 This is only valid for synthetic models.

  Open   Collapse   M_CAD_Y_AXIS

 Returns the direction of the Y-axis for a CAD-type model.  Returns the direction of the Y-axis for a CAD-type model ...

UserVarPtr info

Return values:
M_DEFAULT, M_FLIP, M_NO_FLIP (details)

  Open   Collapse   M_CERTAINTY

 Returns the certainty level for the score.  Returns the certainty level for the score ...

UserVarPtr info

Return values:
0.0 to 100.0, M_DEFAULT (details)

  Open   Collapse   M_CERTAINTY_TARGET

 Returns the certainty level for the target score.  Returns the certainty level for the target score ...

UserVarPtr info

Return values:
0.0 to 100.0, M_DEFAULT (details)

  Open   Collapse   M_CHAIN_ANGLE

 Returns the angle value of each edgel in the chains composing the model's active edges.  Returns the angle value of each edgel in the chains composing the model's active edges ...

UserVarPtr info

Data type:
                  array of type double

            Array size:  Use M_NUMBER_OF_CHAINED_EDGELS to determine the size of the array necessary to hold the chained edgel information.

  Open   Collapse   M_CHAIN_INDEX

 Returns the indices which differentiate each active edge's chain of edgels, for each edgel within the model. The first chain is identified as index 1, with each subsequent chain's index incremented by 1.  Returns the indices which differentiate each active edge's chain of edgels, for each edgel within the model ...

UserVarPtr info

Data type:
                  array of type long

            Array size:  Use M_NUMBER_OF_CHAINED_EDGELS to determine the size of the array necessary to hold the chained edgel information.

  Open   Collapse   M_CHAIN_X

 Returns the X-coordinates, in pixels (with subpixel accuracy), of each edgel in the chains composing the model's active edges. Coordinates are returned for all the active edge chains contained within the model and are relative to the model origin.  Returns the X-coordinates, in pixels (with subpixel accuracy), of each edgel in the chains composing the model's active edges ...

UserVarPtr info

Data type:
                  array of type double

            Array size:  Use M_NUMBER_OF_CHAINED_EDGELS to determine the size of the array necessary to hold the chained edgel information.

  Open   Collapse   M_CHAIN_Y

 Returns the Y-coordinates, in pixels (with subpixel accuracy), of each edgel in the chains composing the model's active edges. Coordinates are returned for all the active edge chains contained within the model and are relative to the model origin.  Returns the Y-coordinates, in pixels (with subpixel accuracy), of each edgel in the chains composing the model's active edges ...

UserVarPtr info

Data type:
                  array of type double

            Array size:  Use M_NUMBER_OF_CHAINED_EDGELS to determine the size of the array necessary to hold the chained edgel information.

  Open   Collapse   M_FIT_ERROR_WEIGHTING_FACTOR

 Returns the contribution of the fit error in the score and target score calculation.  Returns the contribution of the fit error in the score and target score calculation ...

UserVarPtr info

Return values:
0.0 to 100.0, M_DEFAULT (details)

  Open   Collapse   M_FOREGROUND_VALUE

 Returns the foreground value of the model. The foreground is the interior of the shape.  Returns the foreground value of the model ...

 This is only valid for pre-defined shape models. CAD-type models do not have a polarity. For these model types, M_ANY will be returned.

UserVarPtr info

Return values:
M_ANY, M_DEFAULT, M_FOREGROUND_BLACK, M_FOREGROUND_WHITE (details)

  Open   Collapse   M_HEIGHT

 Returns the height of the shape in model, in the user-defined units for the model.  Returns the height of the shape in model, in the user-defined units for the model ...

 This is only valid for a model of type M_CROSS, M_DIAMOND, M_ELLIPSE, M_RECTANGLE, and M_TRIANGLE.

  Open   Collapse   M_HORIZONTAL_THICKNESS

 Returns the horizontal thickness of the cross in model, in the user-defined units for the model.  Returns the horizontal thickness of the cross in model, in the user-defined units for the model ...

 This is only valid for a model of type M_CROSS.

  Open   Collapse   M_INNER_RADIUS

 Returns the inner radius of the ring in the model, in the user-defined units for the model.  Returns the inner radius of the ring in the model, in the user-defined units for the model ...

 This is only valid for a model of type M_RING.

  Open   Collapse   M_MIN_SEPARATION_ANGLE

 Returns the minimum angular separation required for two occurrences to be considered distinct matches. This value is an absolute angle value.  Returns the minimum angular separation required for two occurrences to be considered distinct matches ...

UserVarPtr info

Return values:
0.0 < Value <= 180.0, M_DEFAULT, M_DISABLE (details)

  Open   Collapse   M_MIN_SEPARATION_SCALE

 Returns the minimum separation required in scale for two occurrences to be considered distinct matches. This value is a scale factor.  Returns the minimum separation required in scale for two occurrences to be considered distinct matches ...

UserVarPtr info

Return values:
1.0 < Value <= 4.0, M_DEFAULT, M_DISABLE (details)

  Open   Collapse   M_MIN_SEPARATION_X

 Returns the minimum separation required along the X-axis for two occurrences to be considered distinct matches. This value is a percentage of the model's height at M_SCALE.  Returns the minimum separation required along the X-axis for two occurrences to be considered distinct matches ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, Value (details)

  Open   Collapse   M_MIN_SEPARATION_Y

 Returns the minimum separation required along the Y-axis for two occurrences to be considered distinct matches. This value is a percentage of the model's height at M_SCALE.  Returns the minimum separation required along the Y-axis for two occurrences to be considered distinct matches ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, Value (details)

  Open   Collapse   M_MODEL_TYPE

 Returns the type of model.  Returns the type of model ...

UserVarPtr info

Return values:
M_CIRCLE, M_CROSS, M_DELETE, M_DIAMOND, M_EDGE_RESULT, M_ELLIPSE, M_IMAGE, M_MERGE_MODEL, M_MOD_RESULT, M_RECTANGLE, M_RING, M_SQUARE, M_TRIANGLE (details)

  Open   Collapse   M_NUMBER_OF_CHAINED_EDGELS

 Returns the total number of chained edgels in the active edges of the model.  Returns the total number of chained edgels in the active edges of the model ...

UserVarPtr info

Return values:
 Please see the
                  ResultType parameter of
                  MmodGetResult().

  Open   Collapse   M_ORIGINAL_X

 Returns the X-coordinate of the model's reference axis origin, relative to the top-left corner of the model source image. This is only valid for image-type and Edge Finder-type models.  Returns the X-coordinate of the model's reference axis origin, relative to the top-left corner of the model source image ...

  Open   Collapse   M_ORIGINAL_Y

 Returns the Y-coordinate of the model's reference axis origin, relative to the top-left corner of the model source image This is only valid for image-type and Edge Finder-type models.  Returns the Y-coordinate of the model's reference axis origin, relative to the top-left corner of the model source image This is only valid for image-type and Edge Finder-type models.

  Open   Collapse   M_OUTER_RADIUS

 Returns the outer radius of the ring in the model, in the user-defined units for the model.  Returns the outer radius of the ring in the model, in the user-defined units for the model ...

 This is only valid for a model of type M_RING.

  Open   Collapse   M_PIXEL_SCALE

 Returns the pixel scale of the model.  Returns the pixel scale of the model ...

 This is only valid for synthetic models.

UserVarPtr info

Return values:
M_DEFAULT, Value > 0.0 (details)

  Open   Collapse   M_POLARITY

 Returns the expected polarity of occurrences relative to the model.  Returns the expected polarity of occurrences relative to the model ...

UserVarPtr info

Return values:
M_ANY, M_DEFAULT, M_REVERSE, M_SAME, M_SAME_OR_REVERSE (details)

  Open   Collapse   M_POSITION_DELTA_NEG_X

 Returns the position range, in pixels, in the negative X-direction relative to the nominal search position.  Returns the position range, in pixels, in the negative X-direction relative to the nominal search position ...

UserVarPtr info

Return values:
M_DEFAULT, M_INFINITE, Value >= 0.0 (details)

  Open   Collapse   M_POSITION_DELTA_NEG_Y

 Returns the position range, in pixels, in the negative Y-direction relative to the nominal search position.  Returns the position range, in pixels, in the negative Y-direction relative to the nominal search position ...

UserVarPtr info

Return values:
M_DEFAULT, M_INFINITE, Value >= 0.0 (details)

  Open   Collapse   M_POSITION_DELTA_POS_X

 Returns the position range, in pixels, in the positive X-direction relative to the nominal search position.  Returns the position range, in pixels, in the positive X-direction relative to the nominal search position ...

UserVarPtr info

Return values:
M_DEFAULT, M_INFINITE, Value >= 0.0 (details)

  Open   Collapse   M_POSITION_DELTA_POS_Y

 Returns the position range, in pixels, in the positive Y-direction relative to the nominal search position.  Returns the position range, in pixels, in the positive Y-direction relative to the nominal search position ...

UserVarPtr info

Return values:
M_DEFAULT, M_INFINITE, Value >= 0.0 (details)

  Open   Collapse   M_POSITION_X

 Returns the nominal search position for the X-coordinate, in pixels.  Returns the nominal search position for the X-coordinate, in pixels ...

UserVarPtr info

Return values:
M_ALL, M_DEFAULT, Value (details)

  Open   Collapse   M_POSITION_Y

 Returns the nominal search position for the Y-coordinate, in pixels.  Returns the nominal search position for the Y-coordinate, in pixels ...

UserVarPtr info

Return values:
M_ALL, M_DEFAULT, Value (details)

  Open   Collapse   M_RADIUS

 Returns the radius of the circle in the model, in the user-defined units for the model.  Returns the radius of the circle in the model, in the user-defined units for the model ...

 This is only valid for a model of type M_CIRCLE.

  Open   Collapse   M_REFERENCE_ANGLE

 Returns the reference axis angle of the model.  Returns the reference axis angle of the model ...

UserVarPtr info

Return values:
0.0 to 360.0, M_DEFAULT (details)

  Open   Collapse   M_REFERENCE_X

 Returns the X-coordinate, in pixels, of the reference axis origin of the model, relative to the model origin.  Returns the X-coordinate, in pixels, of the reference axis origin of the model, relative to the model origin ...

UserVarPtr info

Return values:
M_DEFAULT, Value (details)

  Open   Collapse   M_REFERENCE_Y

 Returns the Y-coordinate, in pixels, of the reference axis origin of the model, relative to the model origin.  Returns the Y-coordinate, in pixels, of the reference axis origin of the model, relative to the model origin ...

UserVarPtr info

Return values:
M_DEFAULT, Value (details)

  Open   Collapse   M_SCALE

 Returns the nominal search scale.  Returns the nominal search scale ...

UserVarPtr info

Return values:
M_DEFAULT, Value (details)

  Open   Collapse   M_SCALE_MAX_FACTOR

 Returns the factor used to determine the upper limit (maximum permitted scale) of the scale range.  Returns the factor used to determine the upper limit (maximum permitted scale) of the scale range ...

UserVarPtr info

Return values:
1.0 to 2.0, M_DEFAULT (details)

  Open   Collapse   M_SCALE_MIN_FACTOR

 Returns the factor used to determine the lower limit (minimum permitted scale) of the scale range.  Returns the factor used to determine the lower limit (minimum permitted scale) of the scale range ...

UserVarPtr info

Return values:
0.5 to 1.0, M_DEFAULT (details)

  Open   Collapse   M_USER_LABEL

 Returns the user-defined label.  Returns the user-defined label ...

UserVarPtr info

Return values:
M_DEFAULT, M_NO_LABEL, Value (details)

  Open   Collapse   M_VALID

 Returns whether the model is valid or not.  Returns whether the model is valid or not ...

 Note that a synthetic model is invalid if size of the model box  * M_PIXEL_SCALE * M_SCALE is greater than 1024 pixels in the X-direction or the Y-direction.

UserVarPtr info

Return values:
M_FALSE | The model is not valid.
M_TRUE | The model is valid.

  Open   Collapse   M_VERTICAL_THICKNESS

 Returns the vertical thickness of the cross in the model, in the user-defined units for the model.  Returns the vertical thickness of the cross in the model, in the user-defined units for the model ...

 This is only valid for a model of type M_CROSS.

  Open   Collapse   M_WIDTH

 Returns the width of the shape in the model, in the user-defined units for the model.  Returns the width of the shape in the model, in the user-defined units for the model ...

 This is only valid for a model of type M_CROSS, M_DIAMOND, M_ELLIPSE, M_RECTANGLE, M_SQUARE, and M_TRIANGLE.

 The possible settings to inquire for a model, all models, or a result buffer are:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

Open Collapse Value | Description
Open Collapse M_DRAW_RELATIVE_ORIGIN_X | Returns the X-offset of the region in the model image, if inquiring about a model, or in the Model Finder result buffer, if inquiring about a result, to draw in the destination image buffer when using MmodDraw(). Returns the X-offset of the region in the model image, if inquiring about a model, or in the Model Finder result buffer, if inquiring about a result, to draw in the destination image buffer when using MmodDraw() ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_DRAW_RELATIVE_ORIGIN_Y | Returns the Y-offset of the region in the model image, if inquiring about a model, or in the Model Finder result buffer, if inquiring about a result, to draw in the destination image buffer when using MmodDraw(). Returns the Y-offset of the region in the model image, if inquiring about a model, or in the Model Finder result buffer, if inquiring about a result, to draw in the destination image buffer when using MmodDraw() ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_DRAW_SCALE_X | Returns the scale in the X-direction when drawing models or results in the destination image buffer. Returns the scale in the X-direction when drawing models or results in the destination image buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value >= 0 (details)
Open Collapse M_DRAW_SCALE_Y | Returns the scale in the Y-direction when drawing models or results in the destination image buffer. Returns the scale in the Y-direction when drawing models or results in the destination image buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value >= 0 (details)

 The possible settings to inquire for a result buffer are:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

Open Collapse Value | Description
Open Collapse M_MOD_DEFINE_COMPATIBLE | Returns whether the information necessary to define a model from an occurrence will be saved in the result buffer. Returns whether the information necessary to define a model from an occurrence will be saved in the result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_DISABLE, M_ENABLE (details)

      [Combination constants]

 To inquire whether an inquire type is supported, add the value below to the specified inquire type.

  Open   Collapse  Value
Description

  Open   Collapse   M_SUPPORTED

 Returns whether an inquire type is supported. To test if an inquire is supported, add M_SUPPORTED to the inquire type.  Returns whether an inquire type is supported ...

UserVarPtr info

Return values:
Value<>0 | The inquire type is available. If the index value is different from M_ALL, the inquire type is supported for the model with the appropriate index value. If the index value is M_ALL, the inquire type is supported for all models. If the index value is M_CONTEXT, the inquire type is supported for the context.
0 | The inquire type is not available.

      [Combination constants]

 To inquire the default value of an inquire type, add the value below to the specified inquire type.

Open Collapse Value | Description
Open Collapse M_DEFAULT | Returns the default value of the specified inquire type. Returns the default value of the specified inquire type ...
 |  | UserVarPtr info Data type: double

 For user label inquiries (the label is specified as the index), the InquireType parameter can be set to the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

  Open   Collapse  Value
Description

  Open   Collapse   M_INDEX_FROM_LABEL

 Returns the model index associated with a model user label if the user label is used. Pass the user label as the Index parameter.  Returns the model index associated with a model user label if the user label is used ...

UserVarPtr info

Return values:
M_INVALID | Invalid user label. This is returned if the specified model label is not associated with a model.
Value | Model index associated with the specified user label.

      [Combination constants]

 The values below can be added to the InquireType parameter to cast the requested information to a required data type. For example, M_ORIGINAL_X + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_DOUBLE | Casts the requested information to a double. This is the default. Casts the requested information to a double ... This is the default value.
 |  | UserVarPtr info Data type: array of type double Array size: Number of chained edgels (M_NUMBER_OF_CHAINED_EDGELS).
Open Collapse M_TYPE_LONG | Casts the requested information to a long. Casts the requested information to a long ...
 |  | UserVarPtr info Data type: array of type long Array size: Number of chained edgels (M_NUMBER_OF_CHAINED_EDGELS).

 UserVarPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type double
    •

  • array of type long
    •

  • double
    •

 Specifies the address in which to write the requested information.  Since the MmodInquire() function also returns the requested information, you can set this parameter to M_NULL.

Return value

 The return value is the required information, cast to a long.

GENERAL INDEX FROM LABEL CONTEXT CONTEXT BOX OFFSET X BOX OFFSET Y ALLOC SIZE BAND BOX SIZE X BOX SIZE Y BOX OFFSET X BOX OFFSET Y NUMBER OF CHAINED EDGELS NUMBER OF CHAINED EDGELS NUMBER OF CHAINED EDGELS NUMBER OF CHAINED EDGELS CROSS DIAMOND ELLIPSE RECTANGLE TRIANGLE CROSS RING SCALE SCALE RING CIRCLE CROSS CROSS DIAMOND ELLIPSE RECTANGLE SQUARE TRIANGLE SUPPORTED ALL ALL CONTEXT ORIGINAL X TYPE LONG NUMBER OF CHAINED EDGELS NUMBER OF CHAINED EDGELS   DEFAULT CONTEXT GENERAL   NUMBER ACCURACY ASPECT RATIO CONTEXT TYPE DETAIL LEVEL FILTER MODE FIRST LEVEL KERNEL DEPTH KERNEL WIDTH LAST LEVEL MODIFICATION COUNT NUMBER MODELS OWNER SYSTEM PREPROCESSED SAVE TARGET EDGES SEARCH ANGLE RANGE SEARCH POSITION RANGE SEARCH SCALE RANGE SHARED EDGES SMOOTHNESS SPEED TARGET CACHING TIMEOUT ACCEPTANCE ACCEPTANCE TARGET ALLOC OFFSET X ALLOC OFFSET Y ALLOC SIGN ALLOC SIZE BAND ALLOC SIZE BIT ALLOC SIZE X ALLOC SIZE Y ALLOC TYPE ANGLE ANGLE DELTA NEG ANGLE DELTA POS ASSOCIATED CALIBRATION BOX MARGIN BOTTOM BOX MARGIN LEFT BOX MARGIN RIGHT BOX MARGIN TOP BOX OFFSET X BOX OFFSET Y BOX SIZE X BOX SIZE Y CAD Y AXIS CERTAINTY CERTAINTY TARGET CHAIN ANGLE CHAIN INDEX CHAIN X CHAIN Y FIT ERROR WEIGHTING FACTOR FOREGROUND VALUE HEIGHT HORIZONTAL THICKNESS  INNER RADIUS MIN SEPARATION ANGLE MIN SEPARATION SCALE MIN SEPARATION X MIN SEPARATION Y MODEL TYPE NUMBER OF CHAINED EDGELS ORIGINAL X ORIGINAL Y OUTER RADIUS PIXEL SCALE POLARITY POSITION DELTA NEG X POSITION DELTA NEG Y POSITION DELTA POS X POSITION DELTA POS Y POSITION X POSITION Y RADIUS  REFERENCE ANGLE REFERENCE X REFERENCE Y SCALE SCALE MAX FACTOR SCALE MIN FACTOR USER LABEL VALID VERTICAL THICKNESS WIDTH DRAW RELATIVE ORIGIN X DRAW RELATIVE ORIGIN Y DRAW SCALE X DRAW SCALE Y MOD DEFINE COMPATIBLE SUPPORTED DEFAULT INDEX FROM LABEL TYPE DOUBLE TYPE LONG


MmodMask

See Also | Example | Availability | MmodInquire | MmodPreprocess
User Guide:
Steps to performing a search
Masking your model
Speeding up the search

Reference:
MmodAlloc
MmodInquire
There are no examples containing MmodMask().
Not available in MIL-Lite

Available in MIL
Synopsis
Mask regions of a model.
Syntax
void MmodMask(
MIL_ID ContextId,
long Index,
MIL_ID MaskBufferId,
long MaskType,
long ControlFlag
)
Description

This function allows you to apply masks to a model. Each mask can set pixels in the specified model to one of three states: a "don't care" state, a "flat region" state, or a "weighted region" state. You can apply different types of masks with the same model by making multiple calls to this function. Note that "don't care" and "flat region" masks are not supported for synthetic models.

"Don't care" pixels in a model will not be considered when searching for occurrences of the model in the target.

"Flat region" pixels denote a region where no features are expected, other than consistent pixel values with no edges present; any edge found in a "flat region" reduces the target score.

"Weighted region" pixels denote that the extracted model features will have weights to indicate their importance in the occurrence. The weight of the features will affect the calculation of the score; although the weights themselves don't affect the target score, features corresponding to negative weights will be ignored when calculating the target score.

Note that if you modify the margin of a synthetic model's bounding box after a mask has been applied, the mask will be discarded since it is no longer the same size as the model.

Parameters
ContextId

Specifies the Model Finder context of the model to mask. The Model Finder context must have been previously allocated on the system using MmodAlloc().

Index

Specifies the individual model for which to create a mask.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default model index. This is the same as index 0.  Specifies the default model index ...

  Open   Collapse  Value >= 0

 Specifies the index of the model for which the mask is being created.  Specifies the index of the model for which the mask is being created ...

 User labels cannot be used as indices; to retrieve the index of a model from its user label, use MmodInquire() with M_INDEX_FROM_LABEL.

 MaskBufferId

 Specifies the identifier of the image buffer used to identify the masked pixels in the model.  This buffer must be a 1-band 8-bit unsigned buffer for a "don't care" or "flat region" mask. For a "weighted region" mask, the buffer must be a 1-band 8-bit signed buffer. The buffer must be of the same size as the model. This buffer can be calibrated; however, even if the model is calibrated, the mask is applied on a pixel basis. Setting the MaskBufferId parameter to M_NULL removes the mask.

 MaskType

 Specifies which type of mask to employ.  Set this parameter to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DONT_CARES

 Specifies that features present in the masked region (non-zero pixels) are ignored during the search. Features present in this region of the occurrence will not affect the scores.  Specifies that features present in the masked region (non-zero pixels) are ignored during the search ...

  Open   Collapse  M_FLAT_REGIONS

 Specifies that no features are expected in the masked region (non-zero pixels). If features are present in this region of the occurrence, the target score will decrease.  Specifies that no features are expected in the masked region (non-zero pixels) ...

  Open   Collapse  M_WEIGHT_REGIONS

 Specifies that the pixels corresponding to the model's active edges are weighted according to the values of the weighted region mask. The weights affect the calculation of the score; although the weights themselves don't affect the target score, edges corresponding to negative weights will be ignored when calculating the target score. The valid mask weights range from -127 to +127.  Specifies that the pixels corresponding to the model's active edges are weighted according to the values of the weighted region mask ...

 Positive weights indicate how significant it is for a given pixel to be part of an edge in the occurrence; the more positive the weight, the greater the influence on the score. The absence of a pixel with a very positive weight will reduce the score more than the absence of one with a lower weight.

 The longer the edges with a positive weight, the more significant the edges to the target coverage and to the target score.

 Negative weights indicate how significant it is for a pixel not to be part of an edge in the occurrence; the more negative the weight, the greater the influence on the score. The presence of a pixel with a very negative weight will reduce the score more than the presence of one with a less negative weight.

 Note that weights that have no correspondence to edges in the model have no effect on the score.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

INDEX FROM LABEL   DEFAULT    DONT CARES FLAT REGIONS WEIGHT REGIONS


MmodPreprocess

See Also | Example | Availability | MmodMask | MmodRestore
User Guide:
Steps to performing a search
Defining and adding models to your Model Finder context

Reference:
MmodAlloc
MmodFind
MmodInquire
dtkobjecttracking.c
mmod.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL
Synopsis
Preprocess a Model Finder context.
Syntax
void MmodPreprocess(
MIL_ID ContextId,
long ControlFlag
)
Description

This function preprocesses the specified Model Finder context. It extracts the active edges of the models contained within the Model Finder context and sets internal search settings so that future searches will be optimized for speed and robustness. The procedure is potentially quite lengthy (up to a few seconds) and increases the size of the Model Finder context significantly.

This function must be called before performing the first MmodFind() search. Call this function after all search settings have been set. When you save the Model Finder context, the model's preprocessing changes are not stored with the model. Upon restoration, the model must be preprocessed again.

Note that if some of the model's search settings are changed after a call to MmodPreprocess(), the model must be preprocessed again. To inquire if your model is in a preprocessed state, use MmodInquire() with M_PREPROCESSED (this value must be true to perform an MmodFind() search).

Parameters
ContextId

Specifies the Model Finder context of the model to preprocess. The Model Finder context must have been previously allocated on the system using MmodAlloc().

ControlFlag

Specifies whether to undo preprocessing. Set this parameter to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Does not undo processing.  Does not undo processing.

  Open   Collapse  M_RESET

 Undoes preprocessing.  Undoes preprocessing ...

 Undoing processing can be useful if you want to conserve computer memory within an application and preserve Model Finder context settings.

PREPROCESSED   DEFAULT RESET


MmodRestore

See Also | Example | Availability | MmodPreprocess | MmodSave
Reference:
MmodControl
MmodFind
MmodPreprocess
MmodSave
MsysAlloc
There are no examples containing MmodRestore().
Not available in MIL-Lite

Available in MIL
Synopsis
Restore a Model Finder context from disk.
Syntax
MIL_ID MmodRestore(
MIL_TEXT_PTR Filename,
MIL_ID SystemId,
long ControlFlag,
MIL_ID *ContextIdPtr
)
Description

This function restores a Model Finder context that was previously saved to a file, using MmodSave(). This function restores all of the Model Finder context's settings that were in effect when the Model Finder context was saved. A restored Model Finder context is not preprocessed, therefore you must call MmodPreprocess() before performing a search with MmodFind().

If you had associated a calibration object with the model(s) in your Model Finder context, you must re-associate the calibration object, using MmodControl() with M_ASSOCIATED_CALIBRATION. Moreover, if you had previously set drawing control types, using MmodControl() with M_DRAW_..., then you must reset them since they were not saved with the context.

Parameters
Filename

Specifies the name and path of the file. This function internally handles the opening and closing of the file.

SystemId

Specifies the system on which to restore the Model Finder context.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 ContextIdPtr

 Specifies the address of the variable in which to write the Model Finder context identifier.  Since this function also returns the Model Finder context identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the Model Finder context identifier. If allocation fails, M_NULL is returned.

ASSOCIATED CALIBRATION   DEFAULT HOST


MmodSave

See Also | Example | Availability | MmodRestore | MmodStream
User Guide:
Steps to performing a search

Reference:
MmodRestore
There are no examples containing MmodSave().
Not available in MIL-Lite

Available in MIL
Synopsis
Save a Model Finder context to a file.
Syntax
void MmodSave(
MIL_TEXT_PTR FileName,
MIL_ID ContextId,
long ControlFlag
)
Description

This function saves all the information about the previously allocated Model Finder context to disk, including all of the individual models' current settings. This information can be reloaded, using MmodRestore(). However, preprocessing, any associated calibration objects, and all drawing control type settings are not saved.

Parameters
FileName

Specifies the name and the path in which to save the Model Finder context; it is recommended that you use the MMF file extension for easier use with other Matrox Imaging software products. If the specified file already exists, it will be overwritten. This function internally handles the opening and closing of this file.

ContextId

Specifies the identifier of the Model Finder context to save.

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.


MmodStream

See Also | Example | Availability | MmodSave
Reference:
MappInquire
MmodControl
MmodFind
MmodPreprocess
MmodSave
MsysAlloc
There are no examples containing MmodStream().
Not available in MIL-Lite

Available in MIL
Synopsis
Load, restore, or save a Model Finder context from/to a file or a memory stream.
Syntax
void MmodStream(
MIL_TEXT_PTR MemPtrOrFileName,
MIL_ID SystemId,
long Operation,
long StreamType,
double Version,
long ControlFlag,
MIL_ID *ContextIdPtr,
long *SizeByteVarPtr
)
Description

This function can load or restore a Model Finder context from a file or memory stream. All of the Model Finder context's setting that were in effect when the Model Finder context was saved will be restored. A loaded or restored Model Finder context is not preprocessed, therefore you must call MmodPreprocess() before performing a search with MmodFind(). If you had associated a calibration object with the model(s) in your Model Finder context, you must re-associate the calibration object, using MmodControl() with M_ASSOCIATED_CALIBRATION.

Moreover, this function can also save a Model Finder context to a file or memory stream. All information about the previously allocated Model Finder context is saved, including all of the individual models' current settings. However, preprocessing, any associated calibration objects and drawing control type settings are not saved.

To inquire the number of bytes necessary to save a Model Finder context to memory stream, you should call this function (MmodStream()) first with M_INQUIRE_SIZE_BYTE.

The content saved to memory stream is equivalent to the content saved to file. In addition, any file saved with MmodSave() is equivalent to a file saved using this function.

You can use this and other MIL stream functions, for example, to save all required MIL objects, as well as any other custom data, for your application to a memory stream. Once in a memory stream, you can write the stream to a single file or transfer it over a network. You are responsible for concatenating the streams and for saving the stream to file.

Parameters
MemPtrOrFileName

Specifies the file or memory stream.

When the StreamType parameter is set to M_FILE, MemPtrOrFileName specifies the name and path of the file required for the operation. For easier use with other Matrox Imaging software products, when saving a Model Finder context to a file, use the MMF file extension. The function internally handles the opening and closing of the file. If the file already exists, it will be overwritten when M_SAVE is performed.

When the StreamType parameter is set to M_MEMORY, MemPtrOrFileName specifies the address of the block of memory required for the operation. The designated block must be large enough to stream the entire object. To know the required size, call this function (MmodStream()) first with M_INQUIRE_SIZE_BYTE.

When performing an M_INQUIRE_SIZE_BYTE operation, set this parameter to M_NULL.

SystemId

Specifies the system on which to restore the Model Finder context. For M_INQUIRE_SIZE_BYTE, M_LOAD, and M_SAVE, SystemId is ignored and should be set to M_NULL.

For an M_RESTORE operation, this parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 Operation

 Specifies the operation to perform on the Model Finder context.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_INQUIRE_SIZE_BYTE

 Inquires the number of bytes required to save a Model Finder context to memory stream. This operation is not supported when the StreamType parameter is set to M_FILE.  Inquires the number of bytes required to save a Model Finder context to memory stream ...

  Open   Collapse  M_LOAD

 Loads the content of a specified file or memory stream into a previously allocated Model Finder context.  Loads the content of a specified file or memory stream into a previously allocated Model Finder context.

  Open   Collapse  M_RESTORE

 Restores a Model Finder context from a file or memory stream and assigns it an identifier.  Restores a Model Finder context from a file or memory stream and assigns it an identifier.

  Open   Collapse  M_SAVE

 Saves a Model Finder context to a specified file or memory stream.  Saves a Model Finder context to a specified file or memory stream.

 StreamType

 Specifies the type of stream that holds the Model Finder context.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_FILE

 Specifies a file stream.  Specifies a file stream.

  Open   Collapse  M_MEMORY

 Specifies a memory stream. You are responsible for allocating a block of memory for the stream.  Specifies a memory stream ...

 Version

 Specifies the MIL version of the Model Finder context. For M_LOAD and M_RESTORE, this parameter must be set to M_DEFAULT.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the version to current version of MIL.  Sets the version to current version of MIL.

  Open   Collapse  Value

 Sets the version to a specific version of MIL. This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.  Sets the version to a specific version of MIL ...

 The version specified must never be greater than the current MIL version, but must be greater or equal to 7.0. To know the current MIL version, call MappInquire() with M_VERSION.

 By supplying a specific version, you can control the Model Finder context's accessibility. For instance, if you allocate a Model Finder context using MIL 8.0 and set its version to 7.0, then this context can be restored ona computer where MIL 7.0 is installed. However, all settings unique to the higher version will be ignored when opened in the lower version. Note that a program using MIL of a higher version can access a Model Finder context stream created or designated with a lower or equal version. Settings that do not exist in the lower version will be filled with default values when the file or memory stream is restored.

 ControlFlag

 Specifies the function's control flag and should be set to M_DEFAULT.

 ContextIdPtr

 Specifies the address of the variable in which to write or from which to read the identifier of the Model Finder context.

 For M_INQUIRE_SIZE_BYTE and M_SAVE operations, ContextIdPtr specifies the address of the variable from which to read the Model Finder context idenfier.

 For an M_LOAD operation, the ContextIdPtr specifies the address of the variable from which to read the identifier of the Model Finder context where the file or memory stream content will be loaded.

 For an M_RESTORE operation, the ContextIdPtr specifies the address in which to return the identifier of the restored Model Finder context. If the operation is not successful, M_NULL is returned.

 SizeByteVarPtr

 Specifies the address of the variable in which to write the size of the Model Finder context, in bytes.

 If the size is not required, you can set this parameter to M_NULL.

 Note that the size of a Model Finder context will vary depending on the MIL version specified.

ASSOCIATED CALIBRATION INQUIRE SIZE BYTE FILE SAVE MEMORY INQUIRE SIZE BYTE INQUIRE SIZE BYTE INQUIRE SIZE BYTE LOAD SAVE RESTORE FILE LOAD  RESTORE DEFAULT INQUIRE SIZE BYTE SAVE VERSION INQUIRE SIZE BYTE SAVE LOAD RESTORE   DEFAULT HOST   INQUIRE SIZE BYTE LOAD RESTORE SAVE  FILE MEMORY  DEFAULT


ocr

Mocr functions

Example | Availability
There are no examples containing ocr().
Not available in MIL-Lite

Available in MIL
Synopsis
The MIL Optical Character Recognition module reads and verifies mechanically generated, character strings in 8-bit grayscale images, and provides results such as quality scores and validity flags. It is especially designed to operate on character strings with known lengths in degraded images with a few degrees of rotation in the target image. Functions are available to create, save, restore, modify, and inquire about fonts. The module also allows you to calibrate fonts, define search constraints, and read/verify character strings in the target image. The font information can be saved in a MIL-compatible (.mfo) font file format that can be used with other Matrox Imaging software products.
Functions
  • MocrAllocFont
  • MocrAllocResult
  • MocrCalibrateFont
  • MocrControl
  • MocrCopyFont
  • MocrFree
  • MocrGetResult
  • MocrHookFunction
  • MocrImportFont
  • MocrInquire
  • MocrModifyFont
  • MocrPreprocess
  • MocrReadString
  • MocrRestoreFont
  • MocrSaveFont
  • MocrSetConstraint
  • MocrVerifyString


MocrAllocFont

See Also | Example | Availability | MocrAllocResult
User Guide:
Steps to reading or verifying a string in an image
Guidelines for choosing context types
OCR font

Reference:
MocrCalibrateFont
MocrControl
MocrCopyFont
MocrFree
MocrImportFont
MocrModifyFont
MocrPreprocess
MocrRestoreFont
MocrSaveFont
MocrSetConstraint
MsysAlloc
There are no examples containing MocrAllocFont().
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate an OCR font context.
Syntax
MIL_ID MocrAllocFont(
MIL_ID SystemId,
long FontType,
long CharNumber,
long CharCellSizeX,
long CharCellSizeY,
long CharOffsetX,
long CharOffsetY,
long CharSizeX,
long CharSizeY,
long CharThickness,
long StringLength,
long InitFlag,
MIL_ID *FontIdPtr
)
Description

This function allocates an OCR font context on the specified system. An OCR font context contains the OCR font, target image information, and processing controls. When the OCR font context is no longer required, you should release its memory, using MocrFree().

If the OCR font context already exists as an OCR font file that matches your constraints and character sizes, such as Semi1292.mfo (SEMI M12-92) or Semi1388.mfo (SEMI M13-88), restore it using MocrRestoreFont(). If you need a modified version of a SEMI font (changing its character size, offset, thickness, or the number of characters in the OCR font context) or need a user-defined font, you should allocate a new OCR font context. Note that using either M_SEMI_M12_92 or M_SEMI_M13_88 automatically sets the OCR font context type to M_CONSTRAINED.

A newly allocated OCR font context must have its grayscale character representations initialized using MocrImportFont() or MocrCopyFont(). Each part of the OCR font context can be changed using MocrControl() and MocrModifyFont(). Constraints are set using MocrSetConstraint().

When allocating an OCR font context, you must specify an OCR font context type. This can be modified later using MocrControl() with M_CONTEXT_CONVERT. If your target image has a visible threshold difference between the target characters and the background, uniform illumination, and unknown spacing between characters, and unknown string lengths, and if your font is proportional, start by allocating an M_GENERAL OCR font context. If your target image contains noisy, scratched, or low contrast characters, or if the illumination is not uniform, or if your font includes broken characters start by allocating an M_CONSTRAINED OCR font context.

You must calibrate the OCR font context when the cell, offset, size, or thickness of the characters in your target image differs from the OCR font. Calibration can be either automatic (using MocrCalibrateFont()) or manual (using MocrControl()). Note, to use MocrCalibrateFont(), you must use an M_CONSTRAINED OCR font context.

If you change any controls or constraints, use MocrPreprocess() to speed up any following read or verify operation.

If you intend to reuse a font that you modified, save it using MocrSaveFont(), and restore it using MocrRestoreFont() when you need it.

Parameters
SystemId

Specifies the system on which to allocate the OCR font context. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 FontType

 Specifies the OCR font context type and the type of its font.  This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

Same as M_USER_DEFINED.

  Open   Collapse  M_SEMI_M12_92

 Specifies a font respecting the SEMI M12-92 standard as the type of font. StringLength must be set to 12, the constraints (MocrSetConstraint()) for the target image are preset, and a checksum calculation is activated.  Specifies a font respecting the SEMI M12-92 standard as the type of font ...

  Open   Collapse  M_SEMI_M13_88

 Specifies a font respecting the SEMI M13-88 standard as the type of font. StringLength must be set to 18, the constraints (MocrSetConstraint()) for the target image are preset, and a checksum calculation is activated.  Specifies a font respecting the SEMI M13-88 standard as the type of font ...

  Open   Collapse  M_USER_DEFINED

 Specifies a general, user-defined type of font. No maximum string length is set, the scale is set to 1.0, and the character spacing is the same as CharCellSizeX. No checksum is automatically associated to this OCR font context.  Specifies a general, user-defined type of font ...

      [Combination constants]

 One of the following values must be added to M_USER_DEFINED to specify the OCR font context type.

  Open   Collapse  Value
Description

  Open   Collapse  M_CONSTRAINED

 Specifies an OCR font context that works well with degraded target images and requires more information about the target string, but provides a more robust search. Note that using either M_SEMI_M12_92 or M_SEMI_M13_88 automatically sets the OCR font context type to M_CONSTRAINED. For more information, see the Guidelines for choosing context types section in
          Chapter 10: Optical character recognition.  Specifies an OCR font context that works well with degraded target images and requires more information about the target string, but provides a more robust search ...

This is the default value.

  Open   Collapse  M_GENERAL

 Specifies an OCR font context that works well with clean target images. It requires less information about the target string, but provides a less robust search. For more information, see the Guidelines for choosing context types section in
          Chapter 10: Optical character recognition.  Specifies an OCR font context that works well with clean target images ...

 CharNumber

 Specifies how many characters can be stored in the OCR font context. The maximum number of characters supported is 500.

 CharCellSizeX

 Specifies the width of the characters in the OCR font context, in pixels.

  Open   Collapse  Value
Description

  Open   Collapse  6 <= Value <= 256

 Sets the width, in pixels.  Sets the width, in pixels.

 CharCellSizeY

 Specifies the height of the characters in the OCR font context, in pixels.

  Open   Collapse  Value
Description

  Open   Collapse  6 <= Value <= 256

 Sets the height, in pixels.  Sets the height, in pixels.

 CharOffsetX

 Specifies the distance between the edge of each character and their surrounding cell, along the X-axis, in pixels.  The minimum recommended value is 1.

 Typically, this is set to the same value as the character thickness.

 CharOffsetY

 Specifies the distance between the edge of each character and their surrounding cell, along the Y-axis, in pixels.  The minimum recommended value is 1.

 CharSizeX

 Specifies the width of the characters without their surrounding cell, in pixels.

  Open   Collapse  Value
Description

  Open   Collapse  6 <= Value <= 256

 Sets the width, in pixels. This should be equal to: CharCellSizeX-(CharOffsetX*2).  Sets the width, in pixels ...

 CharSizeY

 Specifies the height of the characters without their surrounding cell, in pixels.

  Open   Collapse  Value
Description

  Open   Collapse  6 <= Value <= 256

 Sets the height, in pixels. This should be equal to: CharCellSizeY-(CharOffsetY*2).  Sets the height, in pixels ...

 CharThickness

 Specifies the maximum thickness (stroke width) of the characters in the OCR font context, in pixels.

 StringLength

 Specifies the maximum length of the string that can be read or verified using the OCR font context.  Note that if M_SEMI_M12_92 is used, the string length must be 12. If M_SEMI_M13_88 is used, the string length must be 18. The maximum supported length of a string is 100 characters.

 InitFlag

 Specifies whether the characters are brighter than the background.  This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_FOREGROUND_BLACK

 Specifies that the characters to read or verify are darker than the background.  Specifies that the characters to read or verify are darker than the background.

  Open   Collapse  M_FOREGROUND_WHITE

 Specifies that the characters to read or verify are brighter than the background.  Specifies that the characters to read or verify are brighter than the background.

 FontIdPtr

 Specifies the address of the variable to which the OCR font context identifier is to be written.  Since the MocrAllocFont() function also returns the OCR font context identifier, you can set this parameter to M_NULL.

Return value

 This function returns the new OCR font context identifier. If allocation fails, M_NULL is returned.

Example

 An example of one character from the font, the letter 'E', follows:

MIL_ID FontID=M_NULL;
 MocrAllocFont(M_DEFAULT, M_USER_DEFINED+M_GENERAL,
        26, 8, 11, 1, 1, 6, 9, 1, 26, M_FOREGROUND_BLACK, &FontId);

 Would look as follows:

SEMI M12 92 SEMI M13 88 CONSTRAINED CONTEXT CONVERT GENERAL CONSTRAINED CONSTRAINED USER DEFINED SEMI M12 92 SEMI M13 88 CONSTRAINED SEMI M12 92 SEMI M13 88  DEFAULT HOST   DEFAULT SEMI M12 92  SEMI M13 88 USER DEFINED  CONSTRAINED GENERAL               FOREGROUND BLACK FOREGROUND WHITE


MocrAllocResult

See Also | Example | Availability | MocrAllocFont | MocrCalibrateFont
User Guide:
Steps to reading or verifying a string in an image

Reference:
MocrFree
MsysAlloc
mocr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate an OCR result buffer.
Syntax
MIL_ID MocrAllocResult(
MIL_ID SystemId,
long InitFlag,
MIL_ID *OcrResultIdPtr
)
Description

This function allocates a result buffer for use with other OCR functions. You should check if the operation was successful by verifying that the OCR result buffer identifier returned is not M_NULL.

When the result buffer is no longer required, you should release it using the MocrFree() function.

Parameters
SystemId

Specifies the system on which to allocate the OCR result buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Sets the default Host system of the current MIL application.  Sets the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Sets a valid system identifier, which you have allocated using the MsysAlloc() function.  Sets a valid system identifier, which you have allocated using the MsysAlloc() function.

 InitFlag

 Specifies the initialization flag and should be set to M_DEFAULT.

 OcrResultIdPtr

 Specifies the address of the variable to which the OCR result buffer identifier is to be written.  Since the MocrAllocResult() function also returns the OCR result buffer identifier, you can set this parameter to M_NULL.

Return value

 This function returns the OCR result buffer identifier. If allocation fails, M_NULL is returned as the identifier.

 DEFAULT HOST


MocrCalibrateFont

See Also | Example | Availability | MocrAllocResult | MocrControl
User Guide:
Steps to reading or verifying a string in an image
Guidelines for choosing context types
OCR font
Defining the target strings
Improving search speed

Reference:
MappGetError
MocrControl
MocrInquire
mocr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Calibrate the OCR font context's character size, and target spacing to match the characters in a sample target image.
Syntax
void MocrCalibrateFont(
MIL_ID ImageBufId,
MIL_ID FontId,
MIL_TEXT_PTR String,
double TargetCharSizeXMin,
double TargetCharSizeXMax,
double TargetCharSizeXStep,
double TargetCharSizeYMin,
double TargetCharSizeYMax,
double TargetCharSizeYStep,
long Operation
)
Description

This function automatically calibrates the X and Y size and spacing of the font of a specified OCR font context to match that of a string in the sample target image. Note that these values can also be set manually with MocrControl() with M_TARGET_CHAR_SPACING, M_TARGET_CHAR_SIZE_X, and M_TARGET_CHAR_SIZE_Y. This function can only calibrate an M_CONSTRAINED OCR font context. You can change the type of context using MocrControl() with M_CONTEXT_CONVERT.

The sample image must contain the string specified in the String parameter, and both the size and spacing must be representative of the images to be read or verified with the calibrated OCR font context. This function might not return the expected results if the sample image contains more or fewer characters than the specified target string length of the target (MocrControl() with M_STRING_SIZE).

The better the sample image, the better the calibration results. If a string cannot be located in the sample image, an error will be generated. Use MappGetError() to learn the error code and related information.

MocrCalibrateFont() should be called after defining a new OCR font context or when the character size in the target images changes.

The resulting target values are the best match between the minimum and the maximum target character sizes specified in the parameters of this function. Calibration will increment the minimum target character size by a step value until it reaches the maximum target character size. You can inquire the target character sizes and spacing with MocrInquire(). For best results, use a range of +/- 1 pixel with, for example, a step of between 0.1 and 0.2 pixels. Note that the greater the number of steps between the minimum and the maximum target character sizes, the longer this operation will take.

Parameters
ImageBufId

Specifies the identifier of the sample target image buffer. The characters of the string in this sample image must be of the same type and size as that in the images to be read or verified using the OCR font context.

FontId

Specifies the identifier of the OCR font context to be calibrated.

String

Specifies the character string present in the sample target image. This string must be null-terminated.

TargetCharSizeXMin

Specifies the minimum width of the characters in the sample target image, in pixels.

Open Collapse Value Description
Open Collapse 6 <= Value <= 256

 Sets the minimum width, in pixels. Note that the specified value must satisfy the following: (TargetCharSizeXMin/CharSizeX)
                >= 0.25.  Sets the minimum width, in pixels ...

 TargetCharSizeXMax

 Specifies the maximum width of the characters in the sample target image, in pixels.

  Open   Collapse  Value
Description

  Open   Collapse  6 <= Value <= 256

 Sets the maximum width, in pixels. Note that the specified value must satisfy the following: (TargetCharSizeXMax/CharSizeX)
                <= 4.0 .  Sets the maximum width, in pixels ...

 TargetCharSizeXStep

 Specifies the increment to use when searching for the character width between TargetCharSizeXMin and TargetCharSizeXMax. Note that very small step sizes should only be used within small ranges, otherwise application performance can be adversely affected.

 TargetCharSizeYMin

 Specifies the minimum height of the characters in the sample target image, in pixels.

  Open   Collapse  Value
Description

  Open   Collapse  6 <= Value <= 256

 Sets the minimum height, in pixels. Note that the specified value must satisfy the following: (TargetCharSizeYMin/CharSizeY)
                >= 0.25 .  Sets the minimum height, in pixels ...

 TargetCharSizeYMax

 Specifies the maximum height of the characters in the sample target image, in pixels.

  Open   Collapse  Value
Description

  Open   Collapse  6 <= Value <= 256

 Sets the maximum height, in pixels. Note that the specified value must satisfy the following: (TargetCharSizeYMax/CharSizeY)
                <= 4.0.  Sets the maximum height, in pixels ...

 TargetCharSizeYStep

 Specifies the increment to use when searching for the character height between TargetCharSizeYMin and TargetCharSizeYMax. Note that very small step sizes should only be used within small ranges, otherwise application performance can be adversely affected.

 Operation

 Specifies the operation to be performed.  This should be set to M_DEFAULT.

TARGET CHAR SPACING TARGET CHAR SIZE X TARGET CHAR SIZE Y CONSTRAINED CONTEXT CONVERT STRING SIZE


MocrControl

See Also | Example | Availability | MocrCalibrateFont | MocrCopyFont
User Guide:
Steps to reading or verifying a string in an image
Guidelines for choosing context types
OCR font
Defining the target strings
Locating your text
Determining what is a match
Retrieving and analyzing the results
Improving search speed

Reference:
MocrCalibrateFont
MocrGetResult
MocrInquire
MocrPreprocess
There are no examples containing MocrControl().
Not available in MIL-Lite

Available in MIL
Synopsis
Control an OCR font context or an OCR result buffer setting.
Syntax
void MocrControl(
MIL_ID FontContextorResultId,
long ControlType,
double ControlValue
)
Description

This function sets various OCR controls for a read/verify operation. This function also sets various controls that affect how results are retrieved by MocrGetResult(). To inquire the current value of a particular control type, use MocrInquire().

After changing the OCR controls or constraints, use MocrPreprocess() to speed up any following read or verify operation.

Parameters
FontContextorResultId

Specifies the identifier of the OCR font context or the OCR result buffer to control.

ControlType

Specifies the type of control to set.

See the Parameter associations section for possible values.

ControlValue

Specifies the required value for the control.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

The following ControlType and corresponding ControlValue parameter settings are used to specify the characteristics of the font.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_CHAR_ERASE |  | Erases a character from the font of the OCR font context. Erases a character from the font of the OCR font context ...
 | Value | Specifies the ASCII character associated with the character. Note that the character must be present in the OCR font context.

The following ControlType and corresponding ControlValue parameter settings are used to specify operational controls for read and verify operations.

Open Collapse ControlType Description
ControlValue
Open Collapse M_BLANK_CHARACTERS

Sets whether the space between characters in the target image is read or not. Sets whether the space between characters in the target image is read or not ...

Note that this is available only when using an M_GENERAL OCR font context.

M_DISABLE

Specifies that blank spaces will not be read from the target image into the result string.

Note that spaces could still be erroneously read if your OCR font context is not manually calibrated properly or the string length for your target image is wrong.

This is the default value.
M_ENABLE

Specifies that blank spaces will be read from the target image into the result string.

Open Collapse M_BROKEN_CHAR

Sets the capability to read/verify a broken character. Sets the capability to read/verify a broken character ...

M_DISABLE

Specifies that, during the read/verify, OCR should not try to compensate for broken characters. Note that this enables a faster algorithm for reading/verifying a string within the target image.

Note that broken characters could still be erroneously read if your target image is noisy, scratched, has low contrast characters, or if the illumination is not uniform.

This is the default value.
M_ENABLE

Specifies that broken characters should be identifies as possible characters.

Open Collapse M_CHAR_ACCEPTANCE

Sets the acceptance level used to determine a successful match between the font and the characters found within the target image. During a read/verify operation, the character found with the highest match score, either equal to or greater than the acceptance level, will be returned. Sets the acceptance level used to determine a successful match between the font and the characters found within the target image ...

If the match score is less than the acceptance level, the result with the highest match score closest to the acceptance level will be returned. If the match score is 0% the invalid character (M_CHAR_INVALID) is returned.

A perfect match is 100%, no correlation is 0%. The match score depends on the image quality. You should experiment to decide what is a typical match score for your application.

0.0 to 100.0

Specifies the acceptance level for a target character.

The default value is 1.0.

Open Collapse M_CHAR_INVALID

Sets the ASCII character for all characters within the selected string or strings during the next read or verify operation whose match scores fall below the character acceptance level. Sets the ASCII character for all characters within the selected string or strings during the next read or verify operation whose match scores fall below the character acceptance level ...

1 to 255

Specifies the character that will replace unrecognized characters.

M_NULL

Specifies that no special character will replace unrecognized characters.

This is the default value.
Open Collapse M_CONTEXT_CONVERT

Changes the type of OCR font context. Note that not all controls are available with both types of OCR font contexts. The restrictions are indicated within each control. When you change the type of OCR font context, invalid controls are replaced by their default value. Changes the type of OCR font context ...

M_CONSTRAINED

Specifies an OCR font context that works well with degraded target images. It requires more information about the target string, but provides a more robust search.

M_GENERAL

Specifies an OCR font context that works well with clean target images. It requires less information about the target string, but provides a less robust search.

Open Collapse M_MORPHOLOGIC_FILTERING

Sets the number of iterations of morphological filtering. Sets the number of iterations of morphological filtering ...

Morphological filtering can add robustness to the OCR operation by internally enhancing the contrast of the image, but it requires processing time. The optimal number of iterations depends on the complexity of the target image.

0.0 to 100.0

Specifies the number of iterations. 0 disables the morphologic filtering.

The default value is 2.

Open Collapse M_SKIP_STRING_LOCATION

Sets whether to first locate the strings in the target image before trying to identify characters against the OCR font context or to skip this step and save processing time. Sets whether to first locate the strings in the target image before trying to identify characters against the OCR font context or to skip this step and save processing time ...

M_DISABLE

Specifies that the step will not be skipped.

This is the default value.
M_ENABLE

Specifies that the step will be skipped.

Open Collapse M_SPEED

Sets the algorithm's search speed. Note that increasing the search speed can decrease the robustness and subpixel accuracy of a read/verify operation. This is most effective on large-sized characters. Sets the algorithm's search speed ...

M_HIGH

Sets the speed to high.

M_LOW

Sets the speed to low.

M_MEDIUM

Sets the speed to medium.

This is the default value.
M_VERY_HIGH

Sets the speed to very high.

M_VERY_LOW

Sets the speed to very low.

Open Collapse M_STRING_ACCEPTANCE

Sets the acceptance level used to determine a successful match between the font and a read/verified string. During a read/verify operation, the string found with the highest match score, either equal to or greater than the acceptance level, will be returned. Sets the acceptance level used to determine a successful match between the font and a read/verified string ...

If the match score is less than the acceptance level, the result with the highest match score closest to the acceptance level will be returned. If the match score is 0%, a blank string is returned. Note that, in this case, MocrGetResult() with M_STRING_VALID_FLAG would be false.

A perfect match is 100%, no correlation is 0%. The match score depends on the image quality. You should experiment to decide what is a typical match score for your application.

0.0 to 100.0

Specifies the acceptance level for a string.

The default value is 1.0.

Open Collapse M_STRING_ANGLE_INTERPOLATION_MODE

Sets the interpolation mode to use when reading/verifying a string at an angle. Sets the interpolation mode to use when reading/verifying a string at an angle ...

M_BICUBIC

Specifies that bicubic interpolation should be used.

M_BILINEAR

Specifies that bilinear interpolation should be used.

This is the default value.
M_NEARST_NEIGHBOR

Specifies that nearest neighbor interpolation should be used.

Open Collapse M_TOUCHING_CHAR

Sets the capability to read/verify characters that touch each other in the target image. Sets the capability to read/verify characters that touch each other in the target image ...

M_DISABLE

Disables the identification of touching characters. Enables a faster algorithm for read or verify operations.

This is the default value.
M_ENABLE

Enables the identification of touching characters.

The following ControlType and corresponding ControlValue parameter settings are used to set the characteristics of the target characters.

Open Collapse ControlType Description
ControlValue
Open Collapse M_STRING_ANGLE

Sets the expected angle at which the string can be found. Sets the expected angle at which the string can be found ...

0 <= Value <= 360°

Specifies the angle, in degrees.

The default value is 0.0.

Open Collapse M_STRING_ANGLE_DELTA_NEG

Sets the possible angle variation in a clockwise rotation, relative to M_STRING_ANGLE. Sets the possible angle variation in a clockwise rotation, relative to M_STRING_ANGLE ...

0 <= Value <= 180°

Specifies the possible clockwise angle variation.

The default value is 0.0.

Open Collapse M_STRING_ANGLE_DELTA_POS

Sets the possible angle variation in a counter-clockwise rotation, relative to M_STRING_ANGLE. Sets the possible angle variation in a counter-clockwise rotation, relative to M_STRING_ANGLE ...

0 <= Value <= 180°

Specifies the possible counter-clockwise angle variation.

The default value is 0.0.

Open Collapse M_STRING_NUMBER

Sets the number of strings to be read/verified from the target image. Multiple strings can only be found if each string resides on a different line within the target image and each line of text does not overlap the previous. Sets the number of strings to be read/verified from the target image ...

Note that, for best results, all strings read in an image with multiple strings should be of similar length, have a consistent inter-line spacing and should start at a similar location along the X-axis.

M_ALL

Specifies that the number of strings in the target image should be determined automatically.

Value

Specifies the number of lines of text in the target image. Note that specifying this value can improve the speed of a following read/verify operation.

The default value is 1.

Open Collapse M_STRING_SIZE

Sets the length of the string to be read/verified from the target image. Sets the length of the string to be read/verified from the target image ...

M_ANY

Specifies that the length of the string is unknown.

Note that this is available only when using an M_GENERAL OCR font context.

Value

Specifies the string length to read/verify, which must be less than or equal to the maximum string length of the OCR font context.

Note that when using an M_GENERAL OCR font context and M_BLANK_CHARACTERS are enabled, blank characters must be counted in the string length.

The default value is set to the maximum string length of the OCR font context. When OCR font context constraints are set, specifying a string length can improve the speed of a following read/verify operation.

Note that if M_SEMI_M12_92 is used, the string length must be 12. If M_SEMI_M13_88 is used, the string length must be 18.

Open Collapse M_TARGET_CHAR_POSITION_VARIATION_X

Sets the amount by which the position of the characters in the target string can vary along the X-axis. This tolerance is relative to the position of each character, as determined by M_TARGET_CHAR_SPACING. This tolerance increases the region being searched for characters within the target image. Sets the amount by which the position of the characters in the target string can vary along the X-axis ...

0.0 to 100.0

Specifies the position tolerance, in pixels.

The default value is 0.0.

Open Collapse M_TARGET_CHAR_POSITION_VARIATION_Y

Sets the amount by which the position of the characters in the target string can vary along the Y-axis. This tolerance is relative to the position of each character, as determined by M_TARGET_CHAR_SPACING. This tolerance increases the region being searched for characters within the target image. Sets the amount by which the position of the characters in the target string can vary along the Y-axis ...

0.0 to 100.0

Specifies the position tolerance, in pixels.

The default value is 0.0.

Open Collapse M_TARGET_CHAR_SIZE_X

Sets the width of the target characters. Note that this can also be automatically set using MocrCalibrateFont(). Sets the width of the target characters ...

M_SAME

Specifies that the character width is found automatically. Use this value when the font uses a fixed width for all its characters.

Note that this is available only when using an M_GENERAL OCR font context.

Value > 1

Specifies the character width in pixels (with subpixel accuracy).

The default value is set to the character size X of the font.

Open Collapse M_TARGET_CHAR_SIZE_Y

Sets the height of the target characters. Note that this can also be automatically set using MocrCalibrateFont(). Sets the height of the target characters ...

M_SAME

Specifies that the character height is found automatically. Use this value when the font uses a fixed height for all its characters.

Note that this is available only when using an M_GENERAL OCR font context.

Value > 1

Specifies the character height in pixels (with subpixel accuracy).

The default value is set to the character size Y of the font.

Open Collapse M_TARGET_CHAR_SPACING

Sets the amount of space between characters in the string. Note that this can also be automatically set using MocrCalibrateFont(). Sets the amount of space between characters in the string ...

M_ANY

Specifies that the inter-character spacing is unknown and not the same between the characters. This enables automatic spacing detection.

Note that this is available only when using an M_GENERAL OCR font context.

M_SAME

Specifies that the inter-character spacing is the same throughout the target string. This enables automatic spacing detection.

Note that this is available only when using an M_GENERAL OCR font context.

Value > 1

Specifies the inter-character spacing, with subpixel accuracy.

The default value is set to the character cell size of the font.

Open Collapse M_TEXT_STRING_SEPARATOR

Sets the ASCII character to be used as a string separator within the text read/verified. This separator will be inserted between each string. Note that this must be set before the text is read/verified. Sets the ASCII character to be used as a string separator within the text read/verified ...

Value

Specifies the ASCII code of the character.

The default value is '\n'.

Open Collapse M_THICKEN_CHAR

Sets the number of times a font character should be thickened to better match the target characters. Sets the number of times a font character should be thickened to better match the target characters ...

0.0 to 100.0

Specifies the number of times a character should be thickened.

The default value is 0.0.

The following ControlType and corresponding ControlValue parameter settings are used to retrieve results from the result buffer.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_SELECT_STRING |  | Selects the line of text to return from the result buffer, when multiple lines of text are read/verified. Selects the line of text to return from the result buffer, when multiple lines of text are read/verified ...
 | M_ALL | Specifies that all strings are selected. This is the default value.
 | Value | Specifies a specific string. Strings are identified by numbers from 0 to (M_STRING_NUMBER-1).

GENERAL CHAR INVALID STRING VALID FLAG STRING ANGLE STRING ANGLE GENERAL GENERAL BLANK CHARACTERS SEMI M12 92 SEMI M13 88 TARGET CHAR SPACING TARGET CHAR SPACING GENERAL GENERAL GENERAL GENERAL STRING NUMBER CHAR ERASE BLANK CHARACTERS DISABLE ENABLE BROKEN CHAR DISABLE ENABLE CHAR ACCEPTANCE CHAR INVALID NULL CONTEXT CONVERT CONSTRAINED GENERAL MORPHOLOGIC FILTERING SKIP STRING LOCATION DISABLE ENABLE SPEED VERY HIGH HIGH MEDIUM LOW VERY LOW STRING ACCEPTANCE STRING ANGLE INTERPOLATION MODE BICUBIC BILINEAR NEARST NEIGHBOR TOUCHING CHAR DISABLE ENABLE STRING NUMBER ALL STRING ANGLE STRING ANGLE DELTA NEG STRING ANGLE DELTA POS STRING SIZE ANY TARGET CHAR POSITION VARIATION X TARGET CHAR POSITION VARIATION Y TARGET CHAR SIZE X SAME TARGET CHAR SIZE Y SAME TARGET CHAR SPACING ANY SAME TEXT STRING SEPARATOR THICKEN CHAR SELECT STRING ALL


MocrCopyFont

See Also | Example | Availability | MocrControl | MocrFree
User Guide:
Steps to reading or verifying a string in an image
OCR font

Reference:
MocrAllocFont
MocrInquire
mocr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Copy a font character to or from an image buffer.
Syntax
void MocrCopyFont(
MIL_ID ImageBufId,
MIL_ID FontId,
long Operation,
MIL_TEXT_PTR CharListString
)
Description

This function copies a character representation of one, or many, font characters to/from the specified image buffer. This buffer can then be used to initialize, change or obtain a visual representation of the font's characters.

If character representations from the image buffer are being copied to the OCR font context, the OCR font context must be large enough to hold the representations of all the specified characters. You can use MocrInquire() to determine the maximum number of characters that can be stored in the font and the size of each character.

The characters are stored in contiguous cells in the image buffer.

The character representations are read from either a font or an image buffer, assuming that the source image is a grid of character representations matching the specified font size. The character representations are read from left to right, and the characters in CharListString must exist in the font.

If the character representation being added already exists in the font, it will be replaced by the new character representation. If the character representation does not already exist in the font, it is appended to the end of the font. If the maximum string length, as set using MocrAllocFont(), is equal to or greater than the number of characters in the font (use MocrInquire() with M_CHAR_NUMBER_IN_FONT), an error will occur and the copy operation will fail.

Note that it is crucial that the character representation respects the foreground value as set in MocrAllocFont(). If the foreground value of the character representation does not match, the font will be unusable.

Parameters
ImageBufId

Specifies the identifier of the image buffer to/from which characters are copied.

FontId

Specifies the identifier of the OCR font context to/from which the characters are copied.

Operation

Specifies the direction of the copy operation. This parameter can be set to one of the following values:

Open Collapse Value Description
Open Collapse M_COPY_FROM_FONT

 Copies character(s) from a font buffer to an image buffer.  Copies character(s) from a font buffer to an image buffer ...

 Note that the maximum number of characters that can be copied from a font buffer to an image buffer is limited to the number of characters in the font.

  Open   Collapse  M_COPY_TO_FONT

 Copies character(s) from an image buffer to a font buffer.  Copies character(s) from an image buffer to a font buffer.

      [Combination constants]

 The following value can be added to the Operation parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL_CHAR

 Copies all font characters to/from the image buffer, stacked from left to right.  Copies all font characters to/from the image buffer, stacked from left to right ...

 Note that when M_ALL_CHAR is added, the CharListString parameter should be set to M_NULL and is ignored.

      [Combination constants]

 The following value can be added to M_COPY_FROM_FONT.

  Open   Collapse  Value
Description

  Open   Collapse  M_SORT

 Sorts font by its ASCII character values.  Sorts font by its ASCII character values.

 CharListString

 Specifies a string containing the list of characters to be copied.  This string must be null-terminated.

 Character representations copied to the font are associated with the characters, and their ASCII code, in the string. If a character exists in both the list and the font, the character representation will be overwritten with the new character representation. New characters will be added to the font provided that there is sufficient space in the OCR font context.

 The CharListString parameter must be set to M_NULL if M_ALL_CHAR is added to the Operation parameter.

CHAR NUMBER IN FONT ALL CHAR COPY FROM FONT ALL CHAR    COPY FROM FONT COPY TO FONT  ALL CHAR  SORT


MocrFree

See Also | Example | Availability | MocrCopyFont | MocrGetResult
User Guide:
Steps to reading or verifying a string in an image

Reference:
MocrAllocFont
MocrAllocResult
mocr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free an OCR font or result buffer.
Syntax
void MocrFree(
MIL_ID FontOrResultId
)
Description

This function deletes the specified OCR font context or result buffer identifier, and releases any memory associated with it.

Parameter
FontOrResultId

Specifies the identifier of the OCR font context, or result buffer to free. The OCR font context, or result buffer, must have been successfully allocated with MocrAllocFont() or MocrAllocResult(), respectively, prior to calling this function.


MocrGetResult

See Also | Example | Availability | MocrFree | MocrHookFunction
User Guide:
Steps to reading or verifying a string in an image
Retrieving and analyzing the results

Reference:
McalControl
MocrControl
MocrReadString
MocrVerifyString
mocr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified type of result(s) from an OCR result buffer.
Syntax
void MocrGetResult(
MIL_ID OcrResultId,
long ResultType,
void *ResultPtr
)
Description

This function retrieves the result(s) of the specified type from an OCR result buffer. The information can be retrieved as a text, a string or a character. A text contains one or more strings. A string contains one or more characters. Results are only available after calling MocrReadString() or MocrVerifyString().

Note that if your target image has been associated with a calibration object, positional results are by default returned in real-world units. To have results returned in pixel units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to M_PIXEL. If the target image is not calibrated, positional results are returned in pixels, relative to the top-left pixel in the target image.

Note that, by default, the first string found is returned as a result. To get the result for a specific string or for all strings from a result buffer, use MocrControl() with M_SELECT_STRING.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set ResultPtr to M_NULL. When this parameter is set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when you pass the parameter an array instead. You must ensure that the array is sufficiently large to hold the current and previously queued results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
OcrResultId

Specifies the identifier of the OCR result buffer from which to retrieve results.

ResultType

Specifies the type of result(s) to retrieve. The following values are available to retrieve results from a read or a verify operation, unless otherwise specified.

To get a result for all strings, use one of the following:

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_TEXT | Retrieves the entire text. This includes all available strings, their separators, and the terminating character. Note that the string separator can be controlled using MocrControl() with M_TEXT_STRING_SEPARATOR. Retrieves the entire text ...
 |  | ResultPtr info Data type: array of type char Array size: M_TEXT_LENGTH
Open Collapse M_TEXT_LENGTH | Retrieves the total number of characters in the entire text. This includes all available strings, their separators, and the terminating character. Note that the string separator can be controlled using MocrControl() with M_TEXT_STRING_SEPARATOR. Retrieves the total number of characters in the entire text ...
Open Collapse M_TEXT_SCORE | Retrieves the match score for the entire text as determined during the read/verify operation. Retrieves the match score for the entire text as determined during the read/verify operation.
Open Collapse M_THRESHOLD | Retrieves the value used to binarize the target image. Note that this is available only when using an M_GENERAL OCR font context, or when using an M_CONSTRAINED OCR font context if your target image has multiple lines, or its string angle is not 0.0°. Retrieves the value used to binarize the target image. Note that this is available only when using an M_GENERAL OCR font context, or when using an M_CONSTRAINED OCR font context if your target image has multiple lines, or its string angle is not 0.0° ...

The following values are available to retrieve results from a read or a verify operation, unless otherwise specified. To get a result for a string or all strings, use one of the following:

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_NB_STRING

Retrieves the number of strings read by MocrReadString(). Retrieves the number of strings read by MocrReadString() ...

If no strings are found, 0 is returned.

Open Collapse M_STRING

Retrieves the null-terminated string found during the read/verify operation. By default, any unrecognized character in the string will be replaced by the most-likely character, even if the match score for that character is lower than the specified character acceptance level (MocrControl() with M_CHAR_ACCEPTANCE). You can replace all unrecognized characters in the string with an invalid character symbol by calling MocrControl() with M_CHAR_INVALID. Retrieves the null-terminated string found during the read/verify operation ...

Note that no string separator is inserted between the different strings when getting all strings simultaneously. Refer to M_TEXT to retrieve the strings with separators.

ResultPtr info

Data type:

  • array of type char
    Array size: M_STRING_SIZE +1
    note: for a single string
  • array of type char
    Array size: the sum of all string lengths +1 (M_STRING_SIZE + M_SUM)+1
    note: for multiple strings
Open Collapse M_STRING_ALLOC_SIZE

Retrieves the total size of the string or each string. This includes the null-termination character. Retrieves the total size of the string or each string. This includes the null-termination character ...

Open Collapse M_STRING_ANGLE

Retrieves the angle of the string or each string, in degrees. Retrieves the angle of the string or each string, in degrees.

Open Collapse M_STRING_SCORE

Retrieves the score calculated during the read/verify operation for the entire string, or for each string. Retrieves the score calculated during the read/verify operation for the entire string, or for each string.

Open Collapse M_STRING_SIZE

Retrieves the length of the null-terminated string, or each string, found during the read/verify operation. Note that this does not include the null-termination character. Retrieves the length of the null-terminated string, or each string, found during the read/verify operation ...

Open Collapse M_STRING_VALID_FLAG

Retrieves the result of the read or verify operation as a flag that denotes the validity of the string. Each flag is set by comparing the match score with the acceptance level (MocrControl() with M_STRING_ACCEPTANCE). Retrieves the result of the read or verify operation as a flag that denotes the validity of the string ...

ResultPtr info

Return values:
M_FALSE | The string was not found by the read/verify operation.
M_TRUE | The string was successfully found by the read/verify operation.

[Combination constants]

The following value can be added to M_STRING_SIZE.

Open Collapse Value | Description
Open Collapse M_SUM | Returns the total length of all available strings without the NULL terminating character or string separators. Returns the total length of all available strings without the NULL terminating character or string separators.

To get a result for a specific character, use one of the following.

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of an array of type double (for a single string) with a size of M_STRING_SIZE or an array of type double (for multiple strings) with a size of M_STRING_SIZE+M_SUM.

Open Collapse Value Description
Open Collapse M_CHAR_POSITION_X

Gets the X position of each individual character in the string, or strings. Gets the X position of each individual character in the string, or strings.

Open Collapse M_CHAR_POSITION_Y

Gets the Y position of each individual character in the string, or strings. Gets the Y position of each individual character in the string, or strings.

Open Collapse M_CHAR_SCORE

Gets the match score of each individual character within the string, or strings. Gets the match score of each individual character within the string, or strings.

Open Collapse M_CHAR_SIZE_X

Gets the cell width of each character within the string, or strings. Gets the cell width of each character within the string, or strings.

Open Collapse M_CHAR_SIZE_Y

Gets the cell height of each character within the string, or strings. Gets the cell height of each character within the string, or strings.

Open Collapse M_CHAR_SPACING

Gets the spacing between each pair of characters in the selected string, or strings. Note that the spacing of the last character in each string is M_NULL. Gets the spacing between each pair of characters in the selected string, or strings ...

Open Collapse M_CHAR_VALID_FLAG

Gets the result of the read or verify operation as flags that denote the validity of each character within the string. Each flag is set by comparing the character's match score with the character's acceptance level (MocrControl() with M_CHAR_ACCEPTANCE). Gets the result of the read or verify operation as flags that denote the validity of each character within the string ...

ResultPtr info

Return values:
M_FALSE | The character was not found in the read/verify string.
M_TRUE | The character was successfully found in the read/verify string.

[Combination constants]

The values below can be added to the ResultType parameter to cast the requested results to a required data type. For example, M_CHAR_POSITION_X + M_TYPE_LONG.

Open Collapse Value Description
Open Collapse M_TYPE_CHAR

Casts the requested results to a char. Casts the requested results to a char ...

ResultPtr info

Data type: char
Open Collapse M_TYPE_DOUBLE

Casts the requested results to a double. Casts the requested results to a double ...

This is the default value.

ResultPtr info

Data type: double
Open Collapse M_TYPE_FLOAT

Casts the requested results to a float. Casts the requested results to a float ...

ResultPtr info

Data type: float
Open Collapse M_TYPE_LONG

Casts the requested results to a long. Casts the requested results to a long ...

ResultPtr info

Data type: long
Open Collapse M_TYPE_SHORT

Casts the requested results to a short. Casts the requested results to a short ...

ResultPtr info

Data type: short
Open Collapse M_TYPE_TEXT_CHAR

Cast the requested results to a MIL_TEXT_CHAR. Cast the requested results to a MIL_TEXT_CHAR ...

ResultPtr info

Data type:

  • MIL_TEXT_CHAR
  • array of type MIL_TEXT_CHAR
    Array size: Size depends on the contents of the array
ResultPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type char
  • array of type double
  • array of type MIL_TEXT_CHAR
  • char
  • double
  • float
  • long
  • short
  • MIL_TEXT_CHAR

Specifies the address in which to write the results. Each line of text found within the target image is read as a separate string. If there is only one line of text, there is only one string. Only the results from the first string or selected strings (MocrControl() with M_SELECT_STRING) are obtained.

You can set this parameter to M_NULL to put the result request on the local queue of the result buffer.

OUTPUT COORDINATE SYSTEM PIXEL SELECT STRING TEXT STRING SEPARATOR TEXT STRING SEPARATOR GENERAL CONSTRAINED CHAR ACCEPTANCE CHAR INVALID TEXT STRING SIZE STRING SIZE SUM STRING ACCEPTANCE STRING SIZE STRING SIZE STRING SIZE SUM CHAR ACCEPTANCE CHAR POSITION X TYPE LONG SELECT STRING TEXT TEXT LENGTH TEXT SCORE THRESHOLD NB STRING STRING STRING ALLOC SIZE STRING ANGLE STRING SIZE STRING SCORE STRING VALID FLAG SUM CHAR POSITION X CHAR POSITION Y CHAR SCORE CHAR SIZE X CHAR SIZE Y CHAR SPACING CHAR VALID FLAG TYPE CHAR TYPE DOUBLE TYPE FLOAT TYPE LONG TYPE SHORT TYPE TEXT CHAR


MocrHookFunction

See Also | Example | Availability | MocrGetResult | MocrImportFont
User Guide:
Steps to reading or verifying a string in an image
Retrieving and analyzing the results

Reference:
MocrReadString
MocrVerifyString
There are no examples containing MocrHookFunction().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox CronosPlus
Fully supported on Matrox Genesis
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Morphis
Fully supported on Matrox Orion
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Not supported on:
Not supported on Matrox Odyssey XA
Not supported on Matrox Odyssey XCL
Not supported on Matrox Odyssey XD
Synopsis
Hook a function to an event.
Syntax
MOCRHOOKFCTPTR MocrHookFunction(
MIL_ID FontId,
long HookType,
MOCRHOOKFCTPTR HookHandlerPtr,
void MPTYPE *UserDataPtr
)
Description

This function allows you to attach or detach a user-defined function to an event when the specified font is used. A type of event to which a user-defined function can be hooked is string validation. This would immediately follow a read or verify operation. When this type of event occurs, the MocrReadString() or MocrVerifyString() function will call the hooked function one or many times during the operation to validate each string after it is read but before being written to the OCR result buffer. This function allows you to impose global string constraints, and can be used to implement custom checksum functions or to reject strings that would have otherwise met the character constraints imposed.

Note that a function hooked to an event executes on a distinct thread. This permits the functions to run asynchronously from the operation that fired the event and from functions hooked to another event.

Hooked functions should not take longer to execute than the period in which two of their associated events can occur. You cannot determine the instance of the event that fired the function, and even if this were possible, this information would generally not be very useful. Typically, a hooked function performs the minimum number of operations required and, if necessary, performs longer processes by launching other threads.

Parameters
FontId

Specifies the identifier of the font.

HookType

Specifies the event type. This parameter can be set to the following value:

Open Collapse Value Description
Open Collapse M_STRING_VALIDATION

 Specifies the character string to be validated.  Specifies the character string to be validated.

      [Combination constants]

 The value below must be added to the HookType parameter to unhook the function.

  Open   Collapse  Value
Description

  Open   Collapse  M_UNHOOK

 Unhooks the function that was hooked to the event.  Unhooks the function that was hooked to the event.

 HookHandlerPtr

 Specifies the address of the function that should be called when the event occurs.

 The hook handler function, pointed to by HookHandlerPtr, must be declared as follows:

long MFTYPE HookHandler(
long HookType,

void MPTYPE *StringPtr,

void MPTYPE *UserDataPtr

        )

HookType

 Specifies the type of event hooked.

StringPtr

 Points to the string to validate.

UserDataPtr

 Specifies the user data pointer passed to MocrHookFunction().

 The value returned by the hook function must contain the string validity status: either M_TRUE or M_FALSE. Note that, MFTYPE and MOCRHOOKFCTPTR are reserved MIL predefined types for functions and data pointers.

 UserDataPtr

 Specifies the address of the user data that you want to make available to the hook-handler function.  This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if the UserDataPtr is not required.

Return value

 This function returns a NULL pointer.

Remark

  •  Note that the prototype of this function is kept for backwards-compatibility.
    •

  STRING VALIDATION  UNHOOK


MocrImportFont

Example | Availability | MocrHookFunction | MocrInquire
There are no examples containing MocrImportFont().
Not available in MIL-Lite

Available in MIL
Synopsis
Import character representations into an OCR font context.
Syntax
void MocrImportFont(
MIL_TEXT_PTR FileName,
long FileFormat,
long Operation,
MIL_TEXT_PTR CharListString,
MIL_ID FontId
)
Description

This function imports character representations from a file to initialize or overwrite those of an existing OCR font context. This function's main use is to initialize custom fonts.

Font character representations can come from either a grayscale image or a text file.

When taken from an image file, character representations are associated to the ASCII characters in the string, specified by CharListString. The image file must be a grid of character representations matching the specifications of the font. The character representations are read from left to right and top to bottom, and the number of characters in the source image must equal the number of characters in the list, specified by CharListString.

When taken from an ASCII file, font character representations must be presented as in the table below.

Row | Description
01 | Specifies ASCII file format.
02 | Blank row.
03 | Specifies the start of a new character representation and its associated (generally ASCII) character.
04 to 36 | Specifies the alpha-numerical representation of the character.
37 | Blank row.
38 | Specifies the start of a new character representation and its associated (generally ASCII) character.
39 to 71 | Specifies the alpha-numerical representation of the character.
etc. | This pattern is repeated for every character in the font.
Parameters
FileName

Specifies the file name and path of the OCR font context. The function handles the opening and closing of the file.

FileFormat

Specifies how the data is stored in the file. This parameter can be set to one of the following values:

Open Collapse Value Description
Open Collapse M_FONT_ASCII

 Specifies a user-drawn ASCII file.  Specifies a user-drawn ASCII file ...

 Note that the CharListString must be set to M_NULL.

  Open   Collapse  M_MIL

 Specifies a MIL format image file.  Specifies a MIL format image file ...

 Note that only one-band images can be used.

  Open   Collapse  M_TIFF

 Specifies a TIFF format image file.  Specifies a TIFF format image file ...

 Note that only one-band images can be used.

 Operation

 Indicates the type of import operation to be performed. This parameter must be set to the following value:

  Open   Collapse  Value
Description

  Open   Collapse  M_LOAD_CHARACTER

 Specifies that the font character representations should be imported.  Specifies that the font character representations should be imported.

 CharListString

 Lists the ASCII characters to associate with the font character representations in the file. This parameter can be set to one of the following values

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Specifies that this parameter is ignored. Use this setting when the FileFormat parameter is set to M_FONT_ASCII.  Specifies that this parameter is ignored ...

  Open   Collapse  String

 Specifies the list of ASCII characters to associate with the font character representations in the image file. Note that the number of characters in this list must match the number of font character representations present in the source file. This string must be null-terminated.  Specifies the list of ASCII characters to associate with the font character representations in the image file ...

 FontId

 Specifies the identifier of the OCR font context.

FONT ASCII   FONT ASCII MIL TIFF  LOAD CHARACTER   NULL


MocrInquire

See Also | Example | Availability | MocrImportFont | MocrModifyFont
User Guide:
Steps to reading or verifying a string in an image
OCR font
Defining the target strings

Reference:
MocrControl
MocrGetResult
MocrPreprocess
MocrSetConstraint
There are no examples containing MocrInquire().
Not available in MIL-Lite

Available in MIL
Synopsis
Inquire about OCR font context or an OCR result buffer setting.
Syntax
long MocrInquire(
MIL_ID FontContextorResultId,
long InquireType,
void *ResultPtr
)
Description

This function inquires about an OCR font context or an OCR result buffer setting.

Note that for an OCR result buffer, this function only retrieves information about result buffer settings (set with MocrControl(), for example). To retrieve results from the OCR result buffer, use MocrGetResult().

Parameters
FontContextorResultId

Specifies the identifier of the OCR font context or the OCR result buffer from which to read information.

InquireType

Specifies the type of setting about which to inquire. It can be set to one of the following values:

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of a double.

Open Collapse Value Description
Open Collapse M_BLANK_CHARACTERS

Returns whether the space between characters in the target image is read. Note that this is available only when using an M_GENERAL OCR font context. Returns whether the space between characters in the target image is read ...

ResultPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_BROKEN_CHAR

Returns the capacity to read/verify broken characters. Returns the capacity to read/verify broken characters ...

ResultPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_CHAR_ACCEPTANCE

Returns the acceptance level used to determine a successful match between the font and the characters found within the target image. Returns the acceptance level used to determine a successful match between the font and the characters found within the target image ...

ResultPtr info

Return values:
0.0 to 100.0 (details)
Open Collapse M_CHAR_CELL_SIZE_X

Returns the font's character cell width, in pixels. Returns the font's character cell width, in pixels ...

ResultPtr info

Return values:
6 <= Value <= 256 (details)
Open Collapse M_CHAR_CELL_SIZE_Y

Returns the font's character cell height, in pixels. Returns the font's character cell height, in pixels ...

ResultPtr info

Return values:
6 <= Value <= 256 (details)
Open Collapse M_CHAR_IN_FONT

Returns a list of the ASCII characters associated to the character representations present in the font. Returns a list of the ASCII characters associated to the character representations present in the font ...

ResultPtr info

Data type: array of type char
Array size: M_CHAR_NUMBER_IN_FONT +1.

Return values:
M_NULL, String (details)
Open Collapse M_CHAR_INVALID

Returns the symbol for the unrecognized characters within the string, or strings. Returns the symbol for the unrecognized characters within the string, or strings ...

ResultPtr info

Return values:
1 to 255, M_NULL (details)
Open Collapse M_CHAR_NUMBER

Returns the number of characters that can be stored in the font of the OCR font context. Returns the number of characters that can be stored in the font of the OCR font context ...

ResultPtr info

Return values:
Please see the CharNumber parameter of MocrAllocFont(). Note that M_DEFAULT is not returned.

Open Collapse M_CHAR_NUMBER_IN_FONT

Returns the number of characters that are actually stored in the OCR font context. Returns the number of characters that are actually stored in the OCR font context.

Open Collapse M_CHAR_OFFSET_X

Returns the font's character offset along the X-axis, in pixels. Returns the font's character offset along the X-axis, in pixels ...

ResultPtr info

Return values:
Please see the CharOffsetX parameter of MocrAllocFont(). Note that M_DEFAULT is not returned.

Open Collapse M_CHAR_OFFSET_Y

Returns the font's character offset along the Y-axis, in pixels. Returns the font's character offset along the Y-axis, in pixels ...

ResultPtr info

Return values:
Please see the CharOffsetY parameter of MocrAllocFont(). Note that M_DEFAULT is not returned.

Open Collapse M_CHAR_SIZE_X

Returns the width of the font's characters, in pixels. Returns the width of the font's characters, in pixels ...

ResultPtr info

Return values:
6 <= Value <= 256 (details)
Open Collapse M_CHAR_SIZE_Y

Returns the height of the font's characters, in pixels. Returns the height of the font's characters, in pixels ...

ResultPtr info

Return values:
6 <= Value <= 256 (details)
Open Collapse M_CHAR_THICKNESS

Returns the average thickness of the font's characters, in pixels. Returns the average thickness of the font's characters, in pixels ...

ResultPtr info

Return values:
Please see the CharThickness parameter of MocrAllocFont(). Note that M_DEFAULT is not returned.

Open Collapse M_CONSTRAINT + n

Returns the constraint string for the nth position in the read/verified null-terminated string. Returns the constraint string for the nth position in the read/verified null-terminated string ...

ResultPtr info

Data type: array of type char
Array size: The array must be large enough to hold the value(s) of the specified parameter.

Return values:
M_NULL, String (details)
Open Collapse M_CONSTRAINT_TYPE + n

Returns the constraint type for the nth character in the string, as set by MocrSetConstraint(). Returns the constraint type for the nth character in the string, as set by MocrSetConstraint() ...

ResultPtr info

Return values:
M_ANY, M_DEFAULT, M_DIGIT, M_LETTER (details)
Open Collapse M_CONTEXT

Returns the type of the OCR font context. Returns the type of the OCR font context ...

ResultPtr info

Return values:
M_CONSTRAINED, M_GENERAL (details)
Open Collapse M_FONT_INITFLAG

Returns the initialization flag passed at font allocation. Returns the initialization flag passed at font allocation ...

ResultPtr info

Return values:
Please see the FontIdPtr parameter of MocrAllocFont(). Note that M_DEFAULT is not returned.

Open Collapse M_FONT_TYPE

Returns the font type of the OCR font context. Returns the font type of the OCR font context ...

ResultPtr info

Return values:
M_SEMI_M12_92, M_SEMI_M13_88, M_USER_DEFINED (details)
Open Collapse M_FOREGROUND_VALUE

Returns the foreground value of the font. Returns the foreground value of the font ...

ResultPtr info

Return values:
M_FOREGROUND_BLACK, M_FOREGROUND_WHITE (details)
Open Collapse M_MORPHOLOGIC_FILTERING

Returns the number of iterations of morphological filtering. Returns the number of iterations of morphological filtering ...

ResultPtr info

Return values:
0.0 to 100.0 (details)
Open Collapse M_OWNER_SYSTEM

Returns the MIL identifier of the system on which the OCR font context is allocated. Returns the MIL identifier of the system on which the OCR font context is allocated ...

ResultPtr info

Data type: MIL_ID

Return values:
M_DEFAULT_HOST, MIL system identifier (details)
Open Collapse M_PREPROCESSED

Returns whether preprocessing (using MocrPreprocess()) is needed to prepare the font for use. Returns whether preprocessing (using MocrPreprocess()) is needed to prepare the font for use ...

ResultPtr info

Return values:
Value > 0 | Preprocessing is not necessary.
0 | Preprocessing is necessary.
Open Collapse M_SKIP_STRING_LOCATION

Returns whether the string location step will be skipped or not. Returns whether the string location step will be skipped or not ...

ResultPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_SPEED

Returns the algorithm's search speed. Returns the algorithm's search speed ...

ResultPtr info

Return values:
M_HIGH, M_LOW, M_MEDIUM, M_VERY_HIGH, M_VERY_LOW (details)
Open Collapse M_STRING_ACCEPTANCE

Returns the acceptance level used to determine a successful match between the font and the read/verified string. Returns the acceptance level used to determine a successful match between the font and the read/verified string ...

ResultPtr info

Return values:
0.0 to 100.0 (details)
Open Collapse M_STRING_ANGLE

Returns the angle at which the string is expected to be found. Returns the angle at which the string is expected to be found ...

ResultPtr info

Return values:
0 <= Value <= 360° (details)
Open Collapse M_STRING_ANGLE_DELTA_NEG

Returns the possible angle variation in a clockwise rotation, relative to M_STRING_ANGLE. Returns the possible angle variation in a clockwise rotation, relative to M_STRING_ANGLE ...

ResultPtr info

Return values:
0 <= Value <= 180° (details)
Open Collapse M_STRING_ANGLE_DELTA_POS

Returns the possible angle variation in a counter-clockwise rotation, relative to M_STRING_ANGLE. Returns the possible angle variation in a counter-clockwise rotation, relative to M_STRING_ANGLE ...

ResultPtr info

Return values:
0 <= Value <= 180° (details)
Open Collapse M_STRING_ANGLE_INTERPOLATION_MODE

Returns the interpolation mode to use when reading/verifying a string at an angle. Returns the interpolation mode to use when reading/verifying a string at an angle ...

ResultPtr info

Return values:
M_BICUBIC, M_BILINEAR, M_NEARST_NEIGHBOR (details)
Open Collapse M_STRING_NUMBER

Returns the number of strings to read from the target image. Returns the number of strings to read from the target image ...

ResultPtr info

Return values:
M_ALL, Value (details)
Open Collapse M_STRING_SIZE

Returns the expected length of the string within the target image. Returns the expected length of the string within the target image ...

ResultPtr info

Return values:
M_ANY, Value (details)
Open Collapse M_STRING_SIZE_MAX

Returns the maximum string length that will be read/verified using the OCR font context. Returns the maximum string length that will be read/verified using the OCR font context ...

ResultPtr info

Return values:
Please see the StringLength parameter of MocrAllocFont(). Note that M_DEFAULT is not returned.

Open Collapse M_TARGET_CHAR_POSITION_VARIATION_X

Returns the amount by which the position of the characters in the target image can vary along the X axis. Returns the amount by which the position of the characters in the target image can vary along the X axis ...

ResultPtr info

Return values:
0.0 to 100.0 (details)
Open Collapse M_TARGET_CHAR_POSITION_VARIATION_Y

Returns the amount by which the position of the characters in the target image can vary along the Y axis. Returns the amount by which the position of the characters in the target image can vary along the Y axis ...

ResultPtr info

Return values:
0.0 to 100.0 (details)
Open Collapse M_TARGET_CHAR_SIZE_X

Returns the width of the expected target characters, in pixels. Returns the width of the expected target characters, in pixels ...

ResultPtr info

Return values:
M_SAME, Value > 1 (details)
Open Collapse M_TARGET_CHAR_SIZE_Y

Returns the height of the expected target characters, in pixels. Returns the height of the expected target characters, in pixels ...

ResultPtr info

Return values:
M_SAME, Value > 1 (details)
Open Collapse M_TARGET_CHAR_SPACING

Returns the expected amount of space (in pixels) between characters in the string. Returns the expected amount of space (in pixels) between characters in the string ...

ResultPtr info

Return values:
M_ANY, M_SAME, Value > 1 (details)
Open Collapse M_TEXT_STRING_SEPARATOR

Returns the ASCII code of the character to be used as a string separator within the text read. Returns the ASCII code of the character to be used as a string separator within the text read ...

ResultPtr info

Return values:
Please see MocrControl() with M_TEXT_STRING_SEPARATOR.

Open Collapse M_THICKEN_CHAR

Returns the number of times a character should be thickened. Returns the number of times a character should be thickened ...

ResultPtr info

Return values:
0.0 to 100.0 (details)
Open Collapse M_TOUCHING_CHAR

Returns whether the capability to read characters that touch is enabled or not. Returns whether the capability to read characters that touch is enabled or not ...

ResultPtr info

Return values:
M_DISABLE, M_ENABLE (details)

[Combination constants]

The value below can be added to M_CHAR_IN_FONT.

Open Collapse Value | Description
Open Collapse M_SORT | Sorts the returned string in ascending ASCII order. Sorts the returned string in ascending ASCII order.

[Combination constants]

The values below can be added to the InquireType parameter to cast the requested information to a required type. For example, M_SPEED + M_TYPE_LONG.

Open Collapse Value Description
Open Collapse M_TYPE_CHAR

Casts the requested information to a char. Casts the requested information to a char ...

ResultPtr info

Data type: char
Open Collapse M_TYPE_DOUBLE

Casts the requested information to a double. Casts the requested information to a double ...

ResultPtr info

Data type: double
Open Collapse M_TYPE_FLOAT

Casts the requested information to a float. Casts the requested information to a float ...

ResultPtr info

Data type: float
Open Collapse M_TYPE_LONG

Casts the requested information to a long. Casts the requested information to a long ...

ResultPtr info

Data type: long
Open Collapse M_TYPE_MIL_ID

Casts the requested information to a MIL_ID. Casts the requested information to a MIL_ID ...

ResultPtr info

Data type: MIL_ID
Open Collapse M_TYPE_SHORT

Casts the requested information to a short. Casts the requested information to a short ...

ResultPtr info

Data type: short
Open Collapse M_TYPE_TEXT_CHAR

Casts the requested information to a MIL_TEXT_CHAR. Casts the requested information to a MIL_TEXT_CHAR ...

ResultPtr info

Data type:

  • MIL_TEXT_CHAR
  • array of type MIL_TEXT_CHAR
    Array size: Size depends on the contents of the array

The following inquire type specifies the result for MocrGetResult().

Unless otherwise specified, the following values require that you pass the ResultPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_SELECT_STRING | Returns the index of the string, selected from a multiple line text, for which to get the results with MocrGetResult(). Returns the index of the string, selected from a multiple line text, for which to get the results with MocrGetResult() ...
 |  | ResultPtr info Return values: M_ALL, Value (details)
ResultPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • array of type char
  • array of type MIL_TEXT_CHAR
  • char
  • double
  • float
  • long
  • short
  • MIL_ID
  • MIL_TEXT_CHAR

Specifies the address in which to write the requested information.

Return value
This function returns the result of the inquire, cast to a long.
GENERAL CHAR NUMBER IN FONT STRING ANGLE STRING ANGLE CHAR IN FONT SPEED TYPE LONG BLANK CHARACTERS BROKEN CHAR CHAR ACCEPTANCE CHAR CELL SIZE X CHAR CELL SIZE Y CHAR IN FONT CHAR INVALID CHAR NUMBER CHAR NUMBER IN FONT CHAR OFFSET X CHAR OFFSET Y CHAR SIZE X CHAR SIZE Y CHAR THICKNESS CONSTRAINT n CONSTRAINT TYPE n CONTEXT FONT INITFLAG FONT TYPE FOREGROUND VALUE MORPHOLOGIC FILTERING STRING NUMBER OWNER SYSTEM PREPROCESSED SKIP STRING LOCATION SPEED STRING ACCEPTANCE STRING ANGLE STRING ANGLE DELTA NEG STRING ANGLE DELTA POS STRING ANGLE INTERPOLATION MODE STRING SIZE STRING SIZE MAX TARGET CHAR POSITION VARIATION X TARGET CHAR POSITION VARIATION Y TARGET CHAR SIZE X TARGET CHAR SIZE Y TARGET CHAR SPACING TEXT STRING SEPARATOR THICKEN CHAR TOUCHING CHAR SORT TYPE CHAR TYPE DOUBLE TYPE FLOAT TYPE LONG TYPE MIL ID TYPE SHORT TYPE TEXT CHAR SELECT STRING


MocrModifyFont

See Also | Example | Availability | MocrInquire | MocrPreprocess
User Guide:
Steps to reading or verifying a string in an image
OCR font

Reference:
MocrAllocFont
There are no examples containing MocrModifyFont().
Not available in MIL-Lite

Available in MIL
Synopsis
Invert or resize the font of an OCR font context to match the target image characters.
Syntax
void MocrModifyFont(
MIL_ID FontId,
long Operation,
long OperationFlag
)
Description

This function physically modifies the polarity and sizing of the font of an OCR font context.

Parameters
FontId

Specifies the identifier of the OCR font context to modify.

Operation

Specifies the type of operation to perform. This parameter can be set to one or more of the following values:

Open Collapse Value Description
Open Collapse M_INVERT

 Physically inverts the character representation of the font (for example, if the foreground is white, this will change it to black).  Physically inverts the character representation of the font (for example, if the foreground is white, this will change it to black).

  Open   Collapse  M_RESIZE

 Scales the font.  Scales the font ...

 This operation physically changes the size of the characters of the font to match the target character size (M_TARGET_CHAR_SIZE_X and M_TARGET_CHAR_SIZE_Y). Once performed, all of the font's specifications, which were set at allocation (MocrAllocFont()), are modified to this new size.

 Note that changing the size of the font permanently in the OCR font context can save time when compared to resizing the font before each read/verify operation. Increasing the size of the font might be slower because the resize time might be less than the additional processing time required during a read or verify operation to find characters of a larger font.

 OperationFlag

 Specifies the interpolation mode for the function.  This parameter can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_BILINEAR.  Same as M_BILINEAR ...

 Note that if the Operation parameter is set to M_INVERT, this parameter should be set to M_DEFAULT. No interpolation is done with M_INVERT.

  Open   Collapse  M_BICUBIC

 Sets the interpolation mode to bicubic interpolation.  Sets the interpolation mode to bicubic interpolation.

  Open   Collapse  M_BILINEAR

 Sets the interpolation mode to bilinear interpolation.  Sets the interpolation mode to bilinear interpolation.

  Open   Collapse  M_NEAREST_NEIGHBOR

 Sets the interpolation mode to nearest neighbor interpolation.  Sets the interpolation mode to nearest neighbor interpolation.

TARGET CHAR SIZE X TARGET CHAR SIZE Y BILINEAR INVERT DEFAULT INVERT   INVERT RESIZE  DEFAULT BICUBIC BILINEAR NEAREST NEIGHBOR


MocrPreprocess

See Also | Example | Availability | MocrModifyFont | MocrReadString
User Guide:
Steps to reading or verifying a string in an image
Defining the target strings

Reference:
MocrInquire
There are no examples containing MocrPreprocess().
Not available in MIL-Lite

Available in MIL
Synopsis
Preprocess an OCR font context.
Syntax
void MocrPreprocess(
MIL_ID FontId,
long ControlFlag
)
Description

This function preprocesses the specified OCR font context. This function must be called before any read or verify operation and after all the control and constraints are set to speed up all subsequent read or verify operations. Note that preprocessing will be done automatically during the first read or verify operation if this function is not explicitly called.

Each time a font-specific control or target constraint is changed the OCR font context should be preprocessed. To learn if the OCR font context requires preprocessing, call MocrInquire() with M_PREPROCESSED.

Parameters
FontId

Specifies the OCR font context identifier.

ControlFlag

Specifies the type of operation to perform. This parameter must be set to the following value.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Preprocesses the OCR font context.  Preprocesses the OCR font context.

PREPROCESSED   DEFAULT


MocrReadString

See Also | Example | Availability | MocrPreprocess | MocrRestoreFont
User Guide:
Steps to reading or verifying a string in an image
Retrieving and analyzing the results

Reference:
MocrCalibrateFont
MocrControl
MocrGetResult
MocrSetConstraint
mocr.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Read an unknown string from a target image.
Syntax
void MocrReadString(
MIL_ID ImageBufId,
MIL_ID FontId,
MIL_ID OcrResultId
)
Description

This function reads an unknown string from the specified target image using the specified OCR font context. All existing font controls and constraints (which can be set with MocrControl() and MocrSetConstraint() respectively) are taken into account, and results are stored in the specified result buffer. Results can be read from the result buffer using the MocrGetResult() function.

This function assumes that the string to be read has the same length as specified in the font, and that the target string characters have the same type, size, and spacing as the characters in OCR font context used for calibration (either automatically with MocrCalibrateFont() or manually with MocrControl()). This is particularly important when using an M_CONSTRAINED OCR font context.

For best results, the angle of the string(s) to be read should be as close to 0 as possible.

When reading multiple strings, a search performed at an angle or any use of the M_GENERAL OCR font context, the target image should have a clearly-defined threshold between the characters and their background. Note that the threshold must preserve the shape of the characters. Broken and/or touching characters can degrade the results.

Parameters
ImageBufId

Specifies the identifier of the image which contains the string to be read.

FontId

Specifies the identifier of the OCR font context to use to read the string from the target image.

OcrResultId

Specifies the OCR result buffer in which to place results of the read operation.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The OCR result buffer (OcrResultId) must be allocated on the same system as the OCR font context (FontId). If it is not, an error will occur.

CONSTRAINED GENERAL


MocrRestoreFont

See Also | Example | Availability | MocrReadString | MocrSaveFont
User Guide:
Steps to reading or verifying a string in an image
OCR font

Reference:
MocrFree
MocrSaveFont
MsysAlloc
mocr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Restore an OCR font context, font constraint data, or control data from file.
Syntax
MIL_ID MocrRestoreFont(
MIL_TEXT_PTR FileName,
long Operation,
MIL_ID SystemId,
MIL_ID *FontIdPtr
)
Description

This function restores an OCR font context, previously saved with MocrSaveFont(), from a file. Alternatively, this function can load only font constraint or control data from the file into the specified OCR font context.

When a font is no longer required, it should be freed with MocrFree().

Parameters
FileName

Specifies the MIL OCR font context path and file name. For easier use with other Matrox Imaging software products, it is recommended that, when restoring an OCR font context from a file, you use the MFO file extension. The function handles the opening and closing of the file.

Operation

Specifies which type of OCR font context data to restore. It can be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Same as M_RESTORE.  Same as M_RESTORE.

  Open   Collapse  M_LOAD_CONSTRAINT

 Loads only font constraint data into the specified OCR font context.  Loads only font constraint data into the specified OCR font context.

  Open   Collapse  M_LOAD_CONTROL

 Loads only font control data into the specified OCR font context.  Loads only font control data into the specified OCR font context.

  Open   Collapse  M_RESTORE

 Allocates a new OCR font context on the specified system, and initializes it with the font, control, and constraint data, restored from file.  Allocates a new OCR font context on the specified system, and initializes it with the font, control, and constraint data, restored from file.

 SystemId

 Specifies the system on which the OCR font context is allocated.

 This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 FontIdPtr

 Specifies the address of the variable to/from which the font identifier is to be written/read.

 Since after performing a restore operation, MocrRestoreFont() also returns the OCR font context identifier, this parameter can be set to M_NULL. If the restore operation fails, M_NULL is returned as the identifier.

Return value

 Returns the identifier of the existing or newly allocated OCR font context. If allocation fails, M_NULL is returned as the identifier.

RESTORE   DEFAULT LOAD CONSTRAINT LOAD CONTROL RESTORE  DEFAULT HOST


MocrSaveFont

Example | Availability | MocrRestoreFont | MocrSetConstraint
mocr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Save an existing OCR font context to disk.
Syntax
void MocrSaveFont(
MIL_TEXT_PTR FileName,
long Operation,
MIL_ID FontId
)
Description

This function saves an existing OCR font context to disk using the MIL font file format. The OCR font context's control, constraint, and/or font character data can all be saved; which data is saved depends on the value of the Operation parameter.

The font character data contains the character representation of each character in the OCR font context. The control data includes controls used to specify the operational controls for a read/verify operation (such as M_BLANK_CHARACTERS, and M_TOUCHING_CHAR) and those used to set the characteristics of the target characters (such as M_THICKEN_CHAR, and M_TARGET_CHAR_SPACING). The constraint data specifies which characters can appear at given positions in the search string.

Parameters
FileName

Specifies the path and file to which font data will be saved. If the font file already exists, its entire contents will be overwritten. For easier use with other Matrox Imaging software products, it is recommended that, when restoring an OCR font context from a file, you use the MFO file extension. If the file already exists, it will be overwritten. The function handles the opening and closing of the file.

Operation

Specifies which data to save to disk. The Operation parameter can take one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Saves the same data as M_SAVE.  Saves the same data as M_SAVE.

  Open   Collapse  M_SAVE

 Saves the OCR font context.  Saves the OCR font context.

  Open   Collapse  M_SAVE_CONSTRAINT

 Saves only character constraint data.  Saves only character constraint data.

  Open   Collapse  M_SAVE_CONTROL

 Saves only control data.  Saves only control data.

 FontId

 Specifies the OCR font context to be saved.

BLANK CHARACTERS TOUCHING CHAR THICKEN CHAR TARGET CHAR SPACING SAVE   DEFAULT SAVE  SAVE CONSTRAINT SAVE CONTROL


MocrSetConstraint

See Also | Example | Availability | MocrSaveFont | MocrVerifyString
User Guide:
Steps to reading or verifying a string in an image
Defining the target strings
Improving search speed

Reference:
MocrPreprocess
mocr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Set character position constraints.
Syntax
void MocrSetConstraint(
MIL_ID FontId,
long CharPos,
long CharPosType,
MIL_TEXT_PTR CharValidString
)
Description

This function specifies which character value constraints to apply to each position of the strings in the target image, when using the specified OCR font context. This function specifies which characters can appear at given positions in the string to be read, and associates these constraints with the OCR font context. Using this function increases both speed and reliability as long as the strings in the target image have a known format and obey certain grammatical rules.

Note that constraints are set in regards to the character's position in the string. When dealing with multiple strings, the same constraints are applied to each string.

If you change any constraints, use MocrPreprocess() to speed up any following read or verify operation.

Parameters
FontId

Specifies the OCR font context identifier with which to associate the constraints.

CharPos

Specifies the character position in the string for which a constraint is being set. Valid values range from zero to the length of the string -1.

CharPosType

Specifies the type of character that can appear at the specified string position.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

Same as M_ANY.

  Open   Collapse  M_ANY

 Sets all characters present in the font as valid.  Sets all characters present in the font as valid ...

  Open   Collapse  M_DIGIT

 Sets only characters "0...9" (ASCII codes 48 to 57) as valid.  Sets only characters "0 ...

  Open   Collapse  M_LETTER

 Sets only characters "A...Z" and "a...z" (ASCII codes 65 to 90 and 97 to 122) as valid.  Sets only characters "A ...

      [Combination constants]

 The values below can be added to M_LETTER to further specify what characters are accepted.

  Open   Collapse  Value
Description

  Open   Collapse  M_LOWERCASE

 Sets only characters "a...z" (ASCII codes 97 to 122) as valid.  Sets only characters "a ...

  Open   Collapse  M_UPPERCASE

 Sets only characters "A...Z" (ASCII codes 65 to 90 ) as valid.  Sets only characters "A...Z" (ASCII codes 65 to 90 ) as valid ...

 CharValidString

 Specifies that any character matching the given CharPosType will be accepted as valid, or explicitly lists valid characters for the specified position.

  Open   Collapse  Value
Description

  Open   Collapse  M_NULL

 Sets all font characters matching the CharPosType parameter value as valid.  Sets all font characters matching the CharPosType parameter value as valid.

  Open   Collapse  String

 Specifies an explicit list of valid characters for the specified position, as a null-teminated string. The accepted characters must match the CharPosType parameter definition and must exist in the font.  Specifies an explicit list of valid characters for the specified position, as a null-teminated string ...

LETTER    DEFAULT ANY DIGIT LETTER LOWERCASE UPPERCASE  NULL


MocrVerifyString

See Also | Example | Availability | MocrSetConstraint
User Guide:
Steps to reading or verifying a string in an image
Retrieving and analyzing the results

Reference:
MocrControl
MocrGetResult
MocrReadString
There are no examples containing MocrVerifyString().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Verify a known string in an image.
Syntax
void MocrVerifyString(
MIL_ID ImageBufId,
MIL_ID FontId,
MIL_TEXT_PTR String,
MIL_ID OcrResultId
)
Description

This function determines whether a known string is present in the target image, and evaluates the quality of the string. These operations can be performed more quickly with MocrVerifyString() than with MocrReadString(). After verification, the specified result buffer can be read with the MocrGetResult() function.

If string location is disabled (using MocrControl() with M_SKIP_STRING_LOCATION), use a child buffer to limit the search area for best results.

The verification can only be performed on a single string and not multiple strings. When dealing with multiple lines of text in a target image, the returned string is the first one found within the target image. Note that this is not necessarily the first string within the target image. The string is located according to its OCR font context type, constraints, and processing controls. Once located, the string can then be read and compared against the validation string provided by this function.

For a more robust search, use an M_CONSTRAINED OCR font context. You can change the type of context using MocrControl() with M_CONTEXT_CONVERT.

Blank characters and cannot be verified and will be ignored.

Parameters
ImageBufId

Specifies the identifier of the target image containing the string to be verified.

FontId

Specifies the identifier of the OCR font context to use to verify the string in the target image.

String

Specifies the character string to be verified in the sample target image. This string must be null-terminated.

Note that blank characters cannot be verified and will be ignored.

OcrResultId

Specifies the OCR result buffer in which to place the verification results.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The OCR result buffer (OcrResultId) must be allocated on the same system as the OCR font context (FontId). If it is not, an error will occur.

SKIP STRING LOCATION CONSTRAINED CONTEXT CONVERT


pat

Mpat functions

Example | Availability
There are no examples containing pat().
Not available in MIL-Lite

Available in MIL
Synopsis
The basic pattern recognition or pattern matching module is a set of pattern location functions that can be used for alignment, measurement, and inspection.
Functions
  • MpatAllocAutoModel
  • MpatAllocModel
  • MpatAllocResult
  • MpatAllocRotatedModel
  • MpatCopy
  • MpatDraw
  • MpatFindModel
  • MpatFindMultipleModel
  • MpatFree
  • MpatGetNumber
  • MpatGetResult
  • MpatInquire
  • MpatPreprocModel
  • MpatRead
  • MpatRestore
  • MpatSave
  • MpatSetAcceptance
  • MpatSetAccuracy
  • MpatSetAngle
  • MpatSetCenter
  • MpatSetCertainty
  • MpatSetDontCare
  • MpatSetNumber
  • MpatSetPosition
  • MpatSetSearchParameter
  • MpatSetSpeed
  • MpatWrite


MpatAllocAutoModel

See Also | Example | Availability | MpatAllocModel
User Guide:
Defining a model

Reference:
MpatFindModel
MpatFindMultipleModel
MpatFree
MpatInquire
MpatSetAngle
MpatSetDontCare
MsysAlloc
mpat.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox CronosPlus
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Automatically allocate unique pattern matching models of the specified type, from a source image.
Syntax
MIL_ID MpatAllocAutoModel(
MIL_ID SystemId,
MIL_ID SrcImageBufId,
long SizeX,
long SizeY,
long PosUncertaintyX,
long PosUncertaintyY,
long ModelType,
long Mode,
MIL_ID *ModelIdArrayPtr
)
Description

This function searches for the specified number of most-suitable unique areas, of the specified dimensions, in the model's source image. From each area found, the function automatically allocates a model. If none are found, no model is allocated and an error is reported. It can take several seconds to find the best models (more for large or small images).

To be effective, the model's target image should be a typical target image. Therefore, MpatAllocAutoModel() is useful, for example, when you want to perform whole image alignment, for which allocation of a unique model is essential.

You can determine the offset of a model's origin relative to its source image, using the MpatInquire() function.

[All except Matrox Genesis]

If the eventual model can appear at an angle, in most cases, it is better to allocate an M_NORMALIZED + M_CIRCULAR_OVERSCAN type of model and then use MpatSetAngle() to specify the angular range.

You can change a model's search parameter settings at any time, using the appropriate MpatSet...() function. When the model(s) is no longer required, you should release its memory, using MpatFree().

You can only define models that respect the following condition: (maxvalue2 * SizeX * SizeY) < 232 where maxvalue is the maximum pixel value (typically, 255) in the target image and the model. This restriction is imposed to avoid overflows in the internal 32-bit accumulators.

The total area of the defined model must be greater or equal to 4 pixels (SizeX * SizeY >= 4).

Parameters
SystemId

Specifies the system on which to allocate the models.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 SrcImageBufId

 Specifies the identifier of the image buffer from which to extract the models.  This image should be representative of the target images. This function currently supports only unsigned 8-bit grayscale images.

 SizeX

 Defines the width of the required models.

 SizeY

 Defines the height of the required models.

 PosUncertaintyX

 Specifies the maximum displacement (shift) expected between the reference position of the models in the source image and their position when found in the target images in the horizontal direction.  This information is used to select models that are far enough from the image borders to be present in the target images.

 This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Selects models from anywhere in the whole width of the image. The default search region of each model is automatically set using the original position of the model, plus or minus the specified positional uncertainty.  Selects models from anywhere in the whole width of the image ...

  Open   Collapse  Value

 Sets PosUncertaintyX to the expected maximum pixel displacement in the horizontal direction. This value will select models that are far enough from the image borders to be present in the target images.  Sets PosUncertaintyX to the expected maximum pixel displacement in the horizontal direction ...

 PosUncertaintyY

 Specifies the maximum displacement (shift) expected between the reference position of the models in the source image and their position when found in the target images in the vertical direction.  This information is used to select models that are far enough from the image borders to be present in the target images.

 This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Selects models from anywhere in the whole height of the image. The default search region of each model is automatically set using the original position of the model, plus or minus the specified positional uncertainty.  Selects models from anywhere in the whole height of the image ...

  Open   Collapse  Value

 Sets PosUncertaintyY to the expected maximum pixel displacement in the vertical direction. This value will select models that are far enough from the image borders to be present in the target images.  Sets PosUncertaintyY to the expected maximum pixel displacement in the vertical direction ...

 ModelType

 Specifies the type of the model.  The parameter must be set to the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_NORMALIZED

 Specifies a model used to search for the position, match score, and angle (if angular search is enabled) of a model occurrence in a target image, using MpatFindModel() and MpatFindMultipleModel().  Specifies a model used to search for the position, match score, and angle (if angular search is enabled) of a model occurrence in a target image, using MpatFindModel() and MpatFindMultipleModel().

      [Combination constants]

[All except
        Matrox Genesis]

 The value below can be added to the ModelType parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_CIRCULAR_OVERSCAN

 Extracts the model, as well as circular overscan data from the source image. The overscan data is determined by rotating the area from which to extract the model, about its center. The overscan data of an M_CIRCULAR_OVERSCAN type model is used if you search for an occurrence of the model at an angle.  Extracts the model, as well as circular overscan data from the source image ...

 For this model, you cannot define "don't care" pixels (MpatSetDontCare()).

 Mode

 Specifies the speed of the allocation process.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Allocates the models at high-speed, the same as M_FAST.  Allocates the models at high-speed, the same as M_FAST.

  Open   Collapse  M_BEST

 Allocates the models with high precision.  Allocates the models with high precision.

  Open   Collapse  M_FAST

 Allocates the models at high-speed.  Allocates the models at high-speed.

      [Combination constants]

 The value below can be added to the Mode parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_MULTIPLE + n

 Allocates several models from the same image. Set n to the number of models to allocate.  Allocates several models from the same image ...

 For example, set Mode to M_BEST + M_MULTIPLE + 4 to find and allocate the four most unique models available in your image. Models can overlap within the image by half the size of the model (in X and Y).

 ModelIdArrayPtr

 Specifies the address of the array in which to write the model identifiers.  The identifier is required to use a model with other pattern matching functions. Since MpatAllocAutoModel() also returns the model identifier, you can set this parameter to M_NULL when allocating a single model. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the model identifier. If allocation fails, M_NULL is returned.

Default values

 Models are associated with some default search parameters. For an M_NORMALIZED model type, the model's search parameters are set to the following defaults:

Characteristic | Default Value
Search region | The default search region of each model is automatically set using the original position of the model, plus or minus the specified positional uncertainty.
Positional accuracy | M_MEDIUM (typically ± 0.10 pixels)
Search number | 1
Search speed | M_MEDIUM
Acceptance level | 70%
Certainty level | 80%
Search angle | 0°
Center of model (reference position) | A double value equal to: ((SizeX- 1) / 2.0, (SizeY- 1) / 2.0) (relative to the model origin).

NORMALIZED CIRCULAR OVERSCAN CIRCULAR OVERSCAN BEST NORMALIZED MEDIUM MEDIUM  DEFAULT HOST      DEFAULT   DEFAULT   NORMALIZED CIRCULAR OVERSCAN  DEFAULT BEST  FAST  MULTIPLE  n


MpatAllocModel

See Also | Example | Availability | MpatAllocAutoModel | MpatAllocResult
User Guide:
Defining a model
Rotation

Reference:
MpatFindModel
MpatFindMultipleModel
MpatFree
MpatSetAngle
MpatSetDontCare
MsysAlloc
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Corona-II
Fully supported on Matrox Meteor-II /1394
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Multi-Channel
Fully supported on Matrox Meteor-II /Standard
Fully supported on Matrox Orion
Fully supported on Matrox CronosPlus
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Morphis
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL
Fully supported on Matrox Iris

Partially supported on:
Partially supported on Matrox Genesis
Synopsis
Allocate a pattern matching model from a source image.
Syntax
MIL_ID MpatAllocModel(
MIL_ID SystemId,
MIL_ID SrcImageBufId,
long OffX,
long OffY,
long SizeX,
long SizeY,
long ModelType,
MIL_ID *ModelIdPtr
)
Description

This function allocates a model, using data from the specified area of the model's source image.

You can change a model's search parameter settings at any time, using the appropriate MpatSet...() function. When the model is no longer required, you should release its memory, using MpatFree().

An M_NORMALIZED type model (without overscan data) is usually used for an image with an inconsistent surrounding region, such as an image of loose nuts and bolts lying on a metal sheet. To peform an angular search, define the angular range in which the model can appear using MpatSetAngle(). When preprocessing an M_NORMALIZED model (without overscan data) for which an angular search range is specified, rotated versions of the model are created assigning "don't care" pixels to regions that do not have corresponding data in the original model.

[All except Matrox Genesis]

Angular search is fastest when performed with an M_CIRCULAR_OVERSCAN model; however, M_CIRCULAR_OVERSCAN should only be used when the region around the model is consistent, for example, when searching for a chip in the image of an integrated circuit.

When preprocessing an M_CIRCULAR_OVERSCAN model for which an angular search range has been specified, a set of models is extracted from rotated versions of the M_CIRCULAR_OVERSCAN model, creating models that would appear upright if the target image were rotated. For this type of model, a larger region than the one defined is extracted from the model's source image so as to allow creation of models at different angles.

You can only define models that respect the following condition: (maxvalue2 * SizeX * SizeY) < 232 where maxvalue is the maximum pixel value (typically, 255) in the target image and the model. This restriction is imposed to avoid overflows in the internal 32-bit accumulators.

The total area of the defined model must be greater or equal to 4 pixels (SizeX * SizeY >= 4).

Parameters
SystemId

Specifies the system on which to allocate the model.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 SrcImageBufId

 Specifies the identifier of the image buffer from which to extract the model (that is, the model's source image). This function currently supports only unsigned 8-bit grayscale images.

 OffX

 Specifies the coordinates of the model origin in the source image (SrcImageBufId).  The specified model position (OffX) must be valid in the source image.

 OffY

 Specifies the coordinates of the model origin in the source image (SrcImageBufId).  The specified model position (OffY) must be valid in the source image.

 SizeX

 Specifies the width of the model.  The specified model width (SizeX) must be valid in the source image.

 SizeY

 Specifies the height of the model.  The specified model height (SizeY) must be valid in the source image.

 ModelType

 Specifies the type of the model.  This parameter must be set to the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_NORMALIZED

 Speicifies a model used to search for the position, match score, and angle (if angular search is enabled) of a model occurrence in a target image, using MpatFindModel() and MpatFindMultipleModel().  Speicifies a model used to search for the position, match score, and angle (if angular search is enabled) of a model occurrence in a target image, using MpatFindModel() and MpatFindMultipleModel().

      [Combination constants]

[All except
        Matrox Genesis]

 The value below can be added to the ModelType parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_CIRCULAR_OVERSCAN

 Extracts the model, as well as circular overscan data from the source image. The overscan data is determined by rotating the area from which to extract the model, about its center. The overscan data of an M_CIRCULAR_OVERSCAN type model is used if you search for an occurrence of the model at an angle.  Extracts the model, as well as circular overscan data from the source image ...

 The model must not be extracted from a region too close to the edge of the model's source image. In addition, the M_CIRCULAR_OVERSCAN model should be complex enough so that if models are created from it at the required angles, they are representative of the pattern being sought.

 For this model, you cannot define "don't care" regions (MpatSetDontCare()).

 ModelIdPtr

 Specifies the address of the variable in which to write the model identifier.  This identifier is required to use the model with other pattern matching functions. Since MpatAllocModel() also returns the model identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the model identifier. If allocation fails, M_NULL is returned.

Default values

 Models are associated with some default search parameter settings. For an M_NORMALIZED model type, the model's search parameter settings are set to the following defaults:

Characteristic | Default Value
Positional accuracy | M_MEDIUM (typically ± 0.10 pixels)
Positional uncertainty (search region) | M_ALL (full image)
Search number | 1
Search speed | M_MEDIUM
Acceptance level | 70%
Certainty level | 80%
Search angle | Disabled
Center of model (reference position) | A double value equal to: ((SizeX- 1) / 2.0, (SizeY- 1) / 2.0) (relative to the model origin).

NORMALIZED NORMALIZED CIRCULAR OVERSCAN CIRCULAR OVERSCAN CIRCULAR OVERSCAN CIRCULAR OVERSCAN CIRCULAR OVERSCAN CIRCULAR OVERSCAN NORMALIZED MEDIUM ALL MEDIUM  DEFAULT HOST        NORMALIZED  CIRCULAR OVERSCAN


MpatAllocResult

See Also | Example | Availability | MpatAllocModel | MpatAllocRotatedModel
User Guide:
Steps to perform a search

Reference:
MpatFree
MpatSetNumber
MsysAlloc
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a pattern matching result buffer.
Syntax
MIL_ID MpatAllocResult(
MIL_ID SystemId,
long NbEntries,
MIL_ID *PatResultIdPtr
)
Description

This function allocates a result buffer with the specified number of entries. When the result buffer is no longer required, release its memory, using MpatFree().

Parameters
SystemId

Specifies the system on which to allocate the result buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 NbEntries

 Specifies the number of result entries to allocate.  If NbEntries is set to M_DEFAULT, the number of entries will be allocated dynamically to match the number of actual occurrences found at runtime; used in conjunction with an M_ALL search (MpatSetNumber()), this provides an efficient method of allocating the correct size result buffer.

 This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies that the number of entries will be allocated dynamically to match the number of actual occurrences found at runtime.  Specifies that the number of entries will be allocated dynamically to match the number of actual occurrences found at runtime.

  Open   Collapse  Value

 Specifies the number of result entries to allocate. Value should be less than or equal to the number of occurrences specified with MpatSetNumber().  Specifies the number of result entries to allocate ...

 PatResultIdPtr

 Specifies the address of the variable in which the pattern matching result buffer identifier is to be written.  Since the MpatAllocResult() function also returns the pattern matching result buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the pattern matching result buffer identifier. If allocation fails, M_NULL is returned.

DEFAULT  DEFAULT HOST   DEFAULT


MpatAllocRotatedModel

See Also | Example | Availability | MpatAllocResult | MpatCopy
Reference:
MpatFindModel
MpatFindMultipleModel
MpatFree
MpatInquire
MpatSetAngle
MsysAlloc
There are no examples containing MpatAllocRotatedModel().
Not available in MIL-Lite

Available in MIL
Synopsis
Rotate a pattern matching model.
Syntax
MIL_ID MpatAllocRotatedModel(
MIL_ID SystemId,
MIL_ID SrcModelId,
double Angle,
long InterpolationMode,
long ModelType,
MIL_ID *NewModelIdPtr
)
Description

This function allocates a new model and initializes it with the rotated version of the specified source model.

This function has the same effect as creating an M_NORMALIZED model (without M_CIRCULAR_OVERSCAN) for which a single angle is specified (that is, delta minimum and maximum are set to 0).

Note that the allocated model size is usually greater than the size of its source, due to the rectangular shape of the model and the nature of the rotation operation. The additional pixel locations produced by the rotation, which have no corresponding pixels in the source model, are set to "don't care" values. The size (X and Y) of the new model can be inquired, using MpatInquire().

Note that the settings of the source model are copied to the new model. You can change any of the model's search parameters (using any appropriate MpatSet...() function), except its angle (MpatSetAngle() function).

Once you have a rotated version of a model, if you no longer require the original source model, it can be deleted with MpatFree().

Parameters
SystemId

Specifies the system on which to allocate the rotated model.

This parameter should be set to one of the values in the following table.

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 SrcModelId

 Specifies the identifier of the source model.  It must be an M_NORMALIZED model without overscan data. A new rotated model is generated from this model.

 Angle

 Specifies the angle at which to rotate the model in a counter-clockwise direction.  This parameter can be set to any value from 0° to 360°.

 InterpolationMode

 Specifies the mode of interpolation.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Same as M_NEAREST_NEIGHBOR.  Same as M_NEAREST_NEIGHBOR.

  Open   Collapse  M_BICUBIC

 Specifies bicubic interpolation.  Specifies bicubic interpolation.

  Open   Collapse  M_BILINEAR

 Specifies bilinear interpolation.  Specifies bilinear interpolation.

  Open   Collapse  M_NEAREST_NEIGHBOR

 Specifies nearest neighbor interpolation.  Specifies nearest neighbor interpolation.

 ModelType

 Specifies the type of the new model.  This parameter must be set to the value below.

  Open   Collapse  Value
Description

  Open   Collapse  M_NORMALIZED

 Searches for the position and match score of a model occurrence in a target image, using MpatFindModel() and MpatFindMultipleModel().  Searches for the position and match score of a model occurrence in a target image, using MpatFindModel() and MpatFindMultipleModel().

 NewModelIdPtr

 Specifies the address of the variable in which to write the rotated model identifier.  Since the MpatAllocRotatedModel() function also returns the model identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the new model identifier. If the rotation fails, M_NULL is returned.

Default values

 Models are associated with a set of default search parameters. For an M_NORMALIZED model type, the model's search parameters are set to the defaults in the table that follows.

Characteristic | Default Value
Positional accuracy | M_MEDIUM (typically ± 0.10 pixels)
Positional uncertainty (search region) | M_ALL (full image)
Search number | 1
Search speed | M_MEDIUM
Acceptance level | 70%
Certainty level | 80%
Search angle | 0°
Center of model (reference position) | A double value equal to ((SizeX- 1) / 2, (SizeY- 1) / 2) (relative to the model origin).

NORMALIZED CIRCULAR OVERSCAN NORMALIZED NEAREST NEIGHBOR NORMALIZED MEDIUM MEDIUM  DEFAULT HOST     DEFAULT BICUBIC BILINEAR  NEAREST NEIGHBOR
                  NORMALIZED


MpatCopy

See Also | Example | Availability | MpatAllocRotatedModel | MpatDraw
User Guide:
Defining a model
Masking the model

Reference:
MpatSetDontCare
There are no examples containing MpatCopy().
Not available in MIL-Lite

Available in MIL
Synopsis
Copy a pattern matching model to an image buffer.
Syntax
void MpatCopy(
MIL_ID ModelId,
MIL_ID DestImageBufId,
long CopyMode
)
Description

This function copies the specified model to the specified destination image buffer, starting at the top-left corner of the buffer. Once the model is copied to the destination buffer, it can then be displayed (if the destination buffer is displayable).

By making two calls to this function, one in which M_DEFAULT is used as the copy mode and the other in which M_DONT_CARE is used, it is possible to achieve the effect of overlaying the "don't care" pixels onto the original model.

Parameters
ModelId

Specifies the identifier of the model that you want copied to the image buffer.

DestImageBufId

Specifies the identifier of the destination image buffer in which to place the model. You must ensure that the buffer is at least as large as the model. Note that the function only supports unsigned 8-bit grayscale images.

CopyMode

Specifies how the model will be copied. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Copies the portion of the source image from which the model was extracted to the destination buffer. That is, the model as it was first defined before any "don't care" pixels where associated with it (see MpatSetDontCare()). Overscan data is not copied.  Copies the portion of the source image from which the model was extracted to the destination buffer ...

  Open   Collapse  M_DONT_CARE

 Copies only the "don't care" pixels of the model to the destination buffer. When copied, these pixels are given the value zero. To give these pixels a value other than zero, add the value to the M_DONT_CARE copy mode. Note, by default when using the M_DONT_CARE copy mode, any pixel value other than the "don't care" pixels in the destination image buffer will not be overwritten.  Copies only the "don't care" pixels of the model to the destination buffer ...

      [Combination constants]

 The value below can be added to M_DONT_CARE to affect the destination buffer.

  Open   Collapse  Value
Description

  Open   Collapse  M_CLEAR_BACKGROUND

 Clears pixels in the resulting destination buffer that are not "don't care" pixels to zero.  Clears pixels in the resulting destination buffer that are not "don't care" pixels to zero.

Example

 The following example demonstrates how to copy "don't care" pixels as value 255 and set the other pixels in the destination buffer to zero.

MpatCopy(ModelId, ImageBufId, M_DONT_CARE +255 +M_CLEAR_BACKGROUND);

DEFAULT DONT CARE DONT CARE DONT CARE DONT CARE    DEFAULT DONT CARE CLEAR BACKGROUND


MpatDraw

See Also | Example | Availability | MpatCopy | MpatFindModel
User Guide:
Steps to perform a search
Defining a model
Masking the model

Reference:
MgraAlloc
MpatCopy
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Draw specific features of the model or result occurrence in the destination image buffer.
Syntax
void MpatDraw(
MIL_ID GraphContId,
MIL_ID ModelOrResultId,
MIL_ID DestImageId,
long Operation,
long Index,
long ControlFlag
)
Description

This function draws specific model or result occurrence features in the destination buffer. MpatDraw() can be used with multiple results.

Parameters
GraphContId

Specifies the graphics context to use. The graphics context must have been previously allocated using MgraAlloc().

This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default graphics context.  Specifies the default graphics context.

  Open   Collapse  Value

 Specifies the graphics context.  Specifies the graphics context.

 ModelOrResultId

 Specifies the model or result buffer identifier from which to extract the features to draw.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

 The model or result buffer must be allocated on the same system as the graphics context (GraphContId). If it is not, an error will occur.

 DestImageId

 Specifies the identifier of the destination image buffer into which to draw.  You can also choose to annotate an image non-destructively, by drawing into its display's overlay buffer.

 Operation

 Specifies the type of operation to perform.  Operations can be added together to draw multiple features at a time. For example, to draw both the result occurrence's bounding box and position, you would specify M_DRAW_BOX + M_DRAW_POSITION as the Operation parameter. The Operation parameter can be set to one or a combination of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DRAW_BOX

 Draws the bounding box of the model or of the result occurrence(s). For a result occurrence, the box is drawn at the coordinates at which its origin was found in the target image (not the reference position), respecting the occurrence's angle.  Draws the bounding box of the model or of the result occurrence(s) ...

  Open   Collapse  M_DRAW_DONT_CARES

 Draws the model's don't care pixels (for models only).  Draws the model's don't care pixels (for models only).

  Open   Collapse  M_DRAW_IMAGE

 Draws the region of the model source image from which the model was extracted. (equivalent to MpatCopy()) (for models only).  Draws the region of the model source image from which the model was extracted ...

  Open   Collapse  M_DRAW_POSITION

 Draws a cross at the model's reference position, or at the result occurrence(s) position and angle found in the target image (with respect to the reference position).  Draws a cross at the model's reference position, or at the result occurrence(s) position and angle found in the target image (with respect to the reference position).

 Index

 Specifies the index of the result occurrence to draw. M_DEFAULT always refers to all results. Note, when drawing features of a model, the index must be set to M_DEFAULT.

 ControlFlag

 Specifies where to draw a model.  This parameter must be set to one of the values below.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies to draw the model at the top-left corner of the destination image.  Specifies to draw the model at the top-left corner of the destination image.

  Open   Collapse  M_ORIGINAL

 Specifies to draw the model at the offsets used to define the model region in the source image.  Specifies to draw the model at the offsets used to define the model region in the source image.

DRAW BOX DRAW POSITION  DEFAULT     DRAW BOX DRAW DONT CARES  DRAW IMAGE DRAW POSITION   DEFAULT ORIGINAL


MpatFindModel

See Also | Example | Availability | MpatDraw | MpatFindMultipleModel
User Guide:
Steps to perform a search
Rotation
Search constraints
Speeding up the search
The pattern matching algorithm (for advanced users)
Pattern matching examples

Reference:
MpatAllocResult
MpatPreprocModel
MpatSetAcceptance
MpatSetAngle
MpatSetCertainty
MpatSetNumber
MpatSetPosition
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Find a pattern matching model in the target image buffer.
Syntax
void MpatFindModel(
MIL_ID ImageBufId,
MIL_ID ModelId,
MIL_ID PatResultId
)
Description

This function finds occurrences of the specified model in the given image and returns the position of each occurrence. The search is performed using the model's current search parameters. Note, this function assumes that the model has been preprocessed (MpatPreprocModel()).

This function assumes that the model was extracted from a source image with the same scaling as the target image. In addition, if using a normalized grayscale non-rotational model, it assumes that the source image and the model's target image are of the same orientation (with approx. 5° tolerance). For angular search, use MpatSetAngle() to set the angular search range of the model.

The model's search parameters specify the maximum number of occurrences for which to look in the target image (MpatSetNumber()).

If a correlation has a match score equal or above the certainty level (MpatSetCertainty()), it is automatically considered an occurrence (default 80%), the remaining occurrences will be the best of those above the acceptance level (MpatSetAcceptance()).

Results are written to the specified result buffer. Use the MpatGet..() functions to read the results. See MpatAllocResult() for more information on allocating result buffers.

This function returns results in decreasing match-score order. This means that the most-likely occurrence is always returned first.

Patterns that are very close to the edge of the image might be found with lower match scores than usual due to edge effects. For this reason, you should use MpatSetPosition(), rather than a child buffer, to restrict the search to a portion of the image.

Parameters
ImageBufId

Specifies the identifier of the target image. Note that this function only supports unsigned 8-bit grayscale images.

ModelId

Specifies the identifier of the model for which to search in the specified target image buffer.

PatResultId

Specifies the identifier of the pattern matching result buffer in which to store results.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

The pattern matching result buffer (PatResultId) must be allocated on the same system as the model (ModelId). If it is not, an error will occur.


MpatFindMultipleModel

See Also | Example | Availability | MpatFindModel | MpatFree
User Guide:
Steps to perform a search
Speeding up the search
The pattern matching algorithm (for advanced users)

Reference:
MpatAllocResult
MpatFindModel
MpatGetResult
MpatSetAcceptance
MpatSetAngle
MpatSetCertainty
MpatSetNumber
MpatSetPosition
There are no examples containing MpatFindMultipleModel().
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Find multiple pattern matching models in the target image buffer.
Syntax
void MpatFindMultipleModel(
MIL_ID ImageBufId,
MIL_ID *ModelIdArray,
MIL_ID *PatResultIdArray,
long NumModels,
long SearchMode
)
Description

This function finds occurrences of the specified models in the given image and returns the position of each occurrence for each model or of the best matches from the group of models. If you want to search for several models in a given image region, a single call to this function is more efficient than multiple calls to MpatFindModel(). This function assumes all models have been preprocessed.

This function assumes that each model was extracted from an image with the same scaling as the target image. In addition, if using a normalized grayscale non-rotational model, it assumes that the model's source image and the target image are at the same orientation (with approximately 5° tolerance). For angular search, use the MpatSetAngle() function to set the angular search range of the model.

Results are written to the specified result buffers. This function returns results in decreasing match-score order. This means that the most-likely occurrence is always returned first. Use the MpatGet..() functions to read the results. See MpatAllocResult() for more information on allocating result buffers.

Patterns that are very close to the edge of the image might be found with lower match scores than usual due to edge effects. For this reason, you should use MpatSetPosition(), rather than a child buffer, to restrict the search to a portion of the image. Note that all models must use the same search region.

Parameters
ImageBufId

Specifies the identifier of the target image buffer. Note that this function only supports unsigned 8-bit grayscale images.

ModelIdArray

Specifies the address of the one-dimensional array that contains the identifiers of the models for which to search in the specified target image buffer. Note, all models must be of the same size and must use the same search region in the target image.

PatResultIdArray

Specifies the address of the one-dimensional array that contains the identifiers of the pattern matching result buffers in which to store results.

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

All pattern matching result buffers and models must be allocated on the same system. If they are not, an error will occur.

NumModels

Specifies the number of models.

SearchMode

Specifies the search mode. This parameter must be set to:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_FIND_ALL_MODELS

 Searches for all the specified models in the target image and writes the result of each model search in the corresponding buffer. The search is performed using each model's current search parameters. Each model's search parameters also determine the maximum number of occurrences for which to look in the target image (MpatSetNumber()). If a correlation has a match score above the model's certainty level (MpatSetCertainty()), it is automatically considered an occurrence (default 80%), the remaining occurrences will be the best of those above the acceptance level (MpatSetAcceptance()). Note, the results for the model in the ModelIdArray [n] are written in the corresponding result buffer PatResultIdArray [n]. Therefore, you must specify the same number of result buffers as the number of models.  Searches for all the specified models in the target image and writes the result of each model search in the corresponding buffer. The search is performed using each model's current search parameters ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_FIND_BEST_MODELS

 Searches for the specified models in the target image and writes the results which have the highest match scores in a single result buffer (PatResultIdArray [0]). Note, the number of different matches that are found depends on MpatSetNumber(), MpatSetCertainty(), and MpatSetAcceptance() of the first model in the array. The certainty, speed, angle and all other search parameters are also specified by the first model in the array; the search parameter settings of the other models are ignored. The model index of the model that generated the best match scores can be read from the result buffer by setting the MpatGetResult() ResultType parameter to M_MODEL_INDEX.  Searches for the specified models in the target image and writes the results which have the highest match scores in a single result buffer (PatResultIdArray[0]) ...

a

d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

MODEL INDEX      FIND ALL MODELS
                 FIND BEST MODELS


MpatFree

See Also | Example | Availability | MpatFindMultipleModel | MpatGetNumber
User Guide:
Steps to perform a search

Reference:
MpatAllocAutoModel
MpatAllocModel
MpatAllocResult
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free a pattern matching model or a result buffer.
Syntax
void MpatFree(
MIL_ID PatId
)
Description

This function deletes the specified pattern matching model or result buffer identifier and releases any memory associated with it.

Parameter
PatId

Specifies the identifier of the pattern matching model or result buffer to free. These must have been successfully allocated (with MpatAllocModel(), MpatAllocAutoModel(), or MpatAllocResult()) prior to calling this function.


MpatGetNumber

See Also | Example | Availability | MpatFree | MpatGetResult
User Guide:
Steps to perform a search
Search constraints

Reference:
MpatFindModel
MpatGetResult
MpatSetNumber
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the number of model occurrences found in the target image.
Syntax
long MpatGetNumber(
MIL_ID PatResultId,
long *CountPtr
)
Description

This function retrieves the number of matches found after searching for a model. It returns the number of occurrences of the model that were found with match scores equal to or above the model's acceptance level to a maximum of MpatSetNumber(). The returned number will never be bigger than the number of entries allocated for the result buffer.

This function determines the number of results retrieved with MpatGetResult(). Call MpatGetNumber() prior to checking results with MpatGetResult(). Note that when no occurrences of the model are found, there is no need to check the results.

Parameters
PatResultId

Specifies the identifier of the pattern matching result buffer that was used to store results obtained by MpatFindModel().

CountPtr

Specifies the address of the variable in which to write the number of occurrences. Since the MpatGetNumber() function also returns the requested information, you can set this parameter to M_NULL.

Return value
The returned value is the number of occurrences of the model that were found at or above the acceptance level.


MpatGetResult

See Also | Example | Availability | MpatGetNumber | MpatInquire
User Guide:
Steps to perform a search
Search constraints
The pattern matching algorithm (for advanced users)

Reference:
McalControl
MpatFindModel
MpatFindMultipleModel
MpatGetNumber
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified type of result(s) from a pattern matching result buffer.
Syntax
void MpatGetResult(
MIL_ID PatResultId,
long ResultType,
double *UserArrayPtr
)
Description

This function retrieves the result(s) of the specified type from a specified pattern matching result buffer. Results are only available after calling MpatFindModel() or MpatFindMultipleModel().

Note that if your target image has been associated with a calibration object, positional results are by default returned in real-world units. To have results returned in pixel units, use McalControl() with the M_OUTPUT_COORDINATE_SYSTEM control type set to M_PIXEL. If the target image is not calibrated, positional results are returned in pixels, relative to the top-left pixel in the target image.

To decrease result retrieval time, especially for remote systems such as Matrox Odyssey, you can retrieve different types of results from the result buffer all at once. To do so, set UserArrayPtr to M_NULL. When this parameter is set to M_NULL, the results are not retrieved, but the result request is instead put onto a local queue associated with the given result buffer identifier. All the queued results are retrieved when you pass the parameter an array instead. You must ensure that the array is sufficiently large to hold the current and previously queued results. Once the results are retrieved, the queue associated with the result buffer is cleared.

Parameters
PatResultId

Specifies the identifier of the pattern matching result buffer from which to retrieve result(s).

ResultType

Specifies the type of result to retrieve for each model occurrence. This parameter must be set to one of the following values.

Open Collapse Value Description
Open Collapse M_ANGLE

 Retrieves the angle of the occurrence (if found) using an MpatFindModel() search at the specified angle.  Retrieves the angle of the occurrence (if found) using an MpatFindModel() search at the specified angle.

  Open   Collapse  M_MODEL_INDEX

 Retrieves the index of the model, in the model identifier array, for which the occurrence was found when using MpatFindMultipleModel() with M_FIND_BEST_MODELS.  Retrieves the index of the model, in the model identifier array, for which the occurrence was found when using MpatFindMultipleModel() with M_FIND_BEST_MODELS.

  Open   Collapse  M_POSITION_X

 Retrieves the X-coordinate of the occurrence.  Retrieves the X-coordinate of the occurrence.

  Open   Collapse  M_POSITION_Y

 Retrieves the Y-coordinate of the occurrence.  Retrieves the Y-coordinate of the occurrence.

  Open   Collapse  M_SCORE

 Retrieves the match score of the occurrence, as a percentage.  Retrieves the match score of the occurrence, as a percentage.

 UserArrayPtr

 Specifies the address of the one-dimensional array in which to write the specified results.  The array must be big enough to hold the number of results indicated by MpatGetNumber(). Results are returned in the user array as type double.

 You can set this parameter to M_NULL to put the result request on the local queue of the result buffer.

OUTPUT COORDINATE SYSTEM PIXEL FIND BEST MODELS   ANGLE MODEL INDEX  POSITION X POSITION Y  SCORE


MpatInquire

See Also | Example | Availability | MpatGetResult | MpatPreprocModel
User Guide:
Steps to perform a search
The pattern matching algorithm (for advanced users)

Reference:
MpatFindModel
MpatFindMultipleModel
MpatSetCenter
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Helios XA
Fully supported on Matrox Helios XCL
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD
Fully supported on Matrox Solios XA
Fully supported on Matrox Solios XCL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox Genesis
Partially supported on Matrox CronosPlus
Partially supported on Matrox Morphis
Partially supported on Matrox Iris
Synopsis
Inquire about the pattern matching model or the result buffer parameter setting.
Syntax
long MpatInquire(
MIL_ID PatId,
long InquireType,
void *UserVarPtr
)
Description

This function returns information about the specified model or result buffer. It is useful to determine, for example, the size of a model that has been restored from disk and its position in the model's source image.

The position (M_ORIGINAL_X and M_ORIGINAL_Y) can be directly compared with search results (by MpatFindModel() or MpatFindMultipleModel()), to calculate the displacement of target images relative to the model's source image.

Parameters
PatId

Specifies the identifier of the model or result buffer for which to read the information.

InquireType

Specifies the parameter about which to inquire. For a model identifier, this parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_ACCEPTANCE_THRESHOLD

Returns the minimum acceptable match score to be considered as an occurrence of the model. Returns the minimum acceptable match score to be considered as an occurrence of the model ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see the AcceptanceThreshold parameter of MpatSetAcceptance().

Open Collapse M_ALLOC_OFFSET_X

Returns the X-offset of model's top-left corner relative to the top-left corner of the model's source image (set using MpatAlloc...()). Returns the X-offset of model's top-left corner relative to the top-left corner of the model's source image (set using MpatAlloc ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_ALLOC_OFFSET_Y

Returns the Y-offset of model's top-left corner relative to the top-left corner of the model's source image (set using MpatAlloc...()). Returns the Y-offset of model's top-left corner relative to the top-left corner of the model's source image (set using MpatAlloc ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_ALLOC_SIZE_X

Returns the model width (set using MpatAlloc...()). Returns the model width (set using MpatAlloc ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_ALLOC_SIZE_Y

Returns the model height (set using MpatAlloc...()). Returns the model height (set using MpatAlloc ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_ALLOC_TYPE

Returns the model type (set using MpatAlloc...()). Returns the model type (set using MpatAlloc ...

a b c d e f g h i j k l m n o p q r
Open Collapse M_CENTER_X

Returns the X-offset of the model's reference position relative to the top-left corner of model. Returns the X-offset of the model's reference position relative to the top-left corner of model ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see the OffX parameter of MpatSetCenter().

Open Collapse M_CENTER_Y

Returns the Y-offset of the model's reference position relative to the top-left corner of model. Returns the Y-offset of the model's reference position relative to the top-left corner of model ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see the OffY parameter of MpatSetCenter().

Open Collapse M_CERTAINTY_THRESHOLD

Returns the match score at which an occurrence is assumed, without looking for better matches elsewhere in the image. Returns the match score at which an occurrence is assumed, without looking for better matches elsewhere in the image ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see the CertaintyThreshold parameter of MpatSetCertainty().

Open Collapse M_COARSE_SEARCH_ACCEPTANCE

Returns the minimum acceptable match score at all levels except the last level, to be considered as an occurrence of the model. Returns the minimum acceptable match score at all levels except the last level, to be considered as an occurrence of the model ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
1.0 to 100.0, M_DEFAULT (details)
Open Collapse M_EXTRA_CANDIDATES

Returns the number of extra candidates to consider as possible candidates. Returns the number of extra candidates to consider as possible candidates ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
Please see MpatSetSearchParameter() with M_EXTRA_CANDIDATES.

Open Collapse M_FAST_FIND

Returns whether forcing or preventing fast peak finding is used. Returns whether forcing or preventing fast peak finding is used ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)
Open Collapse M_FIRST_LEVEL

Returns the resolution level for the initial stage of the search. Returns the resolution level for the initial stage of the search ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0 to 7, M_DEFAULT (details)
Open Collapse M_LAST_LEVEL

Returns the resolution level for the final stage of the search. Returns the resolution level for the final stage of the search ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0 to 7, M_DEFAULT (details)
Open Collapse M_MIN_SPACING_X

Returns the minimum spacing (in X) between two models in order for them to be considered distinct. Returns the minimum spacing (in X) between two models in order for them to be considered distinct ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
1.0 to 100.0 (details)
Open Collapse M_MIN_SPACING_Y

Returns the minimum spacing (in Y) between two models in order for them to be considered distinct. Returns the minimum spacing (in Y) between two models in order for them to be considered distinct ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
1.0 to 100.0 (details)
Open Collapse M_MODEL_STEP

Returns whether all or every second model pixel is used in the high-resolution stage of the search. Returns whether all or every second model pixel is used in the high-resolution stage of the search ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
1, 2, M_DEFAULT (details)
Open Collapse M_NATIVE_ID

Returns the Genesis library identifier of the display associated with the given pattern matching model or MIL result buffer. Returns the Genesis library identifier of the display associated with the given pattern matching model or MIL result buffer ...

This value is applicable to both the Main Board and the Processor Board.

c d e m n o q r
Open Collapse M_NUMBER_OF_OCCURRENCES

Returns the number of model occurrences for which to search in the target image. Returns the number of model occurrences for which to search in the target image ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_ALL, Value (details)
Open Collapse M_ORIGINAL_X

Returns the x-offset of the model's reference position relative to the top-left corner of the model's source image (takes into account the MpatSetCenter() setting). Returns the x-offset of the model's reference position relative to the top-left corner of the model's source image (takes into account the MpatSetCenter() setting).

a b c d e f g h i j k l m n o p q r
Open Collapse M_ORIGINAL_Y

Returns the y-offset of the model's reference position relative to the top-left corner of the model's source image (takes into account the MpatSetCenter() setting). Returns the y-offset of the model's reference position relative to the top-left corner of the model's source image (takes into account the MpatSetCenter() setting).

a b c d e f g h i j k l m n o p q r
Open Collapse M_OWNER_SYSTEM

Returns the system on which the model is allocated. Returns the system on which the model is allocated ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DEFAULT_HOST, MIL system identifier (details)
Open Collapse M_POSITION_ACCURACY

Returns the search position accuracy. Returns the search position accuracy ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_HIGH, M_LOW, M_MEDIUM (details)
Open Collapse M_POSITION_START_X

Returns the x-coordinate of search region origin within target image. Returns the x-coordinate of search region origin within target image ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_ALL, M_NO_CHANGE, Value (details)
Open Collapse M_POSITION_START_Y

Returns the y-coordinate of search region origin within target image. Returns the y-coordinate of search region origin within target image ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_ALL, M_NO_CHANGE, Value (details)
Open Collapse M_POSITION_UNCERTAINTY_X

Returns the search region width. Returns the search region width ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_ALL, M_NO_CHANGE, Value (details)
Open Collapse M_POSITION_UNCERTAINTY_Y

Returns the search region height. Returns the search region height ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_ALL, M_NO_CHANGE, Value (details)
Open Collapse M_PREPROCESSED

Returns whether or not the model is preprocessed. Returns whether or not the model is preprocessed ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0 | The model is not preprocessed.
1 | The model is preprocessed.
Open Collapse M_PROC_FIRST_LEVEL

Returns the default resolution level for the initial stage (lowest resolution) of the search. Returns the default resolution level for the initial stage (lowest resolution) of the search ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0 to 7 The lowest resolution level.

Open Collapse M_PROC_LAST_LEVEL

Returns the default level for the final stage (highest resolution) of the search. Returns the default level for the final stage (highest resolution) of the search ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0 to 7 The highest resolution level.

Open Collapse M_SEARCH_ANGLE

Returns the value of the initial search angle. Returns the value of the initial search angle ...

a b d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0.0 to 360.0 (details)
Open Collapse M_SEARCH_ANGLE_ACCURACY

Returns the angular accuracy. Returns the angular accuracy ...

a b d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0.1 to 180.0, M_DISABLE (details)
Open Collapse M_SEARCH_ANGLE_DELTA_NEG

Returns the difference that determines the lower limit of the search angle's range. Returns the difference that determines the lower limit of the search angle's range ...

a b d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0.0 to 180.0 (details)
Open Collapse M_SEARCH_ANGLE_DELTA_POS

Returns the difference that determines the upper limit of the search angle's range. Returns the difference that determines the upper limit of the search angle's range ...

a b d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0.0 to 180.0 (details)
Open Collapse M_SEARCH_ANGLE_INTERPOLATION_MODE

Returns the interpolation mode. Returns the interpolation mode ...

a b d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_BICUBIC, M_BILINEAR, M_NEAREST_NEIGHBOR (details)
Open Collapse M_SEARCH_ANGLE_MODE

Returns the state of angular search mode. Returns the state of angular search mode ...

a b d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)
Open Collapse M_SEARCH_ANGLE_TOLERANCE

Returns the full range of degrees within which the pattern in the target image can be rotated from a model at a specific angle and still meet the acceptance level. Returns the full range of degrees within which the pattern in the target image can be rotated from a model at a specific angle and still meet the acceptance level ...

a b d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
0.1 to 180.0 (details)
Open Collapse M_SPEED

Returns the model search speed. Returns the model search speed ...

a b c d e f g h i j k l m n o p q r

UserVarPtr info

Return values:
M_HIGH, M_LOW, M_MEDIUM, M_VERY_HIGH, M_VERY_LOW (details)

For a result buffer identifier, this parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a double.

Open Collapse Value | Description
Open Collapse M_NUMBER_OF_ENTRIES | Returns the number of entries allocated in the result buffer. Returns the number of entries allocated in the result buffer ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value (details)
Open Collapse M_OWNER_SYSTEM | Returns the system on which the result buffer is allocated. Returns the system on which the result buffer is allocated ...
 |  | UserVarPtr info Return values: M_DEFAULT_HOST, MIL system identifier (details)
Open Collapse M_TARGET_CACHING | Returns whether the pyramidal representation of the buffer is kept in the result buffer. Returns whether the pyramidal representation of the buffer is kept in the result buffer ...
 |  | UserVarPtr info Return values: M_DISABLE, M_ENABLE (details)

[Combination constants]

The values below can be added to the InquireType parameter to cast the requested information to a required data type. For example, M_ORIGINAL_X + M_TYPE_LONG.

Open Collapse Value | Description
Open Collapse M_TYPE_LONG | Casts the requested information to a long. Casts the requested information to a long ...
 |  | UserVarPtr info Data type: long
UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • double
  • long

Specifies the address in which to write the requested information. Since this function also returns the requested information, you can set this parameter to M_NULL.

Return value
The returned value is the requested system information cast to long.
ORIGINAL X ORIGINAL Y ORIGINAL X TYPE LONG ACCEPTANCE THRESHOLD ALLOC OFFSET X ALLOC OFFSET Y ALLOC SIZE X ALLOC SIZE Y ALLOC TYPE CENTER X CENTER Y CERTAINTY THRESHOLD COARSE SEARCH ACCEPTANCE EXTRA CANDIDATES FAST FIND FIRST LEVEL LAST LEVEL MIN SPACING X MIN SPACING Y MODEL STEP NATIVE ID NUMBER OF OCCURRENCES ORIGINAL X ORIGINAL Y OWNER SYSTEM POSITION ACCURACY POSITION START X POSITION START Y POSITION UNCERTAINTY X POSITION UNCERTAINTY Y PREPROCESSED PROC FIRST LEVEL PROC LAST LEVEL SEARCH ANGLE SEARCH ANGLE ACCURACY SEARCH ANGLE DELTA NEG SEARCH ANGLE DELTA POS SEARCH ANGLE INTERPOLATION MODE SEARCH ANGLE MODE SEARCH ANGLE TOLERANCE SPEED NUMBER OF ENTRIES OWNER SYSTEM TARGET CACHING TYPE LONG


MpatPreprocModel

See Also | Example | Availability | MpatInquire | MpatRead
User Guide:
Steps to perform a search
Rotation
Preprocess the search model
Speeding up the search
The pattern matching algorithm (for advanced users)

Reference:
MpatInquire
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Preprocess a pattern matching model.
Syntax
void MpatPreprocModel(
MIL_ID TypicalImageBufId,
MIL_ID ModelId,
long Mode
)
Description

This function preprocesses the specified model. It trains the system to search for the model in the most efficient manner (optionally within a specified typical image). The procedure is potentially quite lengthy (up to several seconds).

Call this function after all search parameters have been set. When you save, the model's preprocessing changes are stored with the model. Upon restoration, the model need not be preprocessed.

Note that if some of the model's search parameters are changed after a call to MpatPreprocModel(), the model must be preprocessed again. To inquire if your model is in a preprocessed state, use MpatInquire() with M_PREPROCESSED.

Parameters
TypicalImageBufId

Specifies the identifier of a typical target image. The specified typical image will be used to refine and adapt the model to search on this typical background. You should only specify an image buffer if the model will always appear on such a background; otherwise, set this parameter to M_NULL.

ModelId

Specifies the identifier of the model to preprocess.

Mode

Specifies the preprocessing mode. Set this parameter to M_DEFAULT.

PREPROCESSED


MpatRead

See Also | Example | Availability | MpatPreprocModel | MpatRestore
Reference:
MpatSave
MpatWrite
MsysAlloc
There are no examples containing MpatRead().
Not available in MIL-Lite

Available in MIL
Synopsis
Read a pattern matching model from an open file.
Syntax
MIL_ID MpatRead(
MIL_ID SystemId,
FILE *FileHandle,
MIL_ID *ModelIdPtr
)
Description

This function reads a model (previously saved with MpatWrite() or MpatSave()) from an open file and returns an identifier to it.

This function also restores all the model's search parameters that were in effect when the model was saved. If the model was preprocessed before saving, you do not need to preprocess it again.

Parameters
SystemId

Specifies the system on which to allocate the pattern matching model.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  Value

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 FileHandle

 Specifies the handle of the file (opened with the standard C function fopen()).  The file handle must be compatible with MIL. To achieve this, link your project with the multi-threaded DLL run-time library. For example, in the Microsoft Visual C++.NET development environment, select Properties from the Project menu. On the C/C++ page, select Code Generation as a category and Multi-threaded DLL as the run-time library to use.

 Before calling this function, the file pointer must be positioned just before the start of the valid pattern matching model. After the function call, the file remains open and is positioned immediately after the model.

 ModelIdPtr

 Specifies the address of the variable in which the model identifier is to be written.  Since the MpatRead() function also returns the model identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the model identifier. If allocation fails, M_NULL is returned.

 DEFAULT HOST


MpatRestore

See Also | Example | Availability | MpatRead | MpatSave
User Guide:
Steps to perform a search

Reference:
MpatSave
MsysAlloc
There are no examples containing MpatRestore().
Not available in MIL-Lite

Available in MIL
Synopsis
Restore a pattern matching model from disk.
Syntax
MIL_ID MpatRestore(
MIL_ID SystemId,
MIL_TEXT_PTR FileName,
MIL_ID *ModelIdPtr
)
Description

This function restores a model that was previously saved to a file, using MpatSave(). If the model was preprocessed before saving, you do not need to preprocess it again.

This function also restores all the model's search parameters that were in effect when the model was saved.

Parameters
SystemId

Specifies the system on which to restore the model.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  Value

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 FileName

 Specifies the model file name.  The function handles (internally) the opening and closing of the file.

 ModelIdPtr

 Specifies the address of the variable in which to write the model identifier.  Since the MpatRestore() function also returns the model identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the model identifier. If allocation fails, M_NULL is returned.

 DEFAULT HOST


MpatSave

See Also | Example | Availability | MpatRestore | MpatSetAcceptance
User Guide:
Steps to perform a search
Defining a model

Reference:
MpatRead
MpatRestore
There are no examples containing MpatSave().
Not available in MIL-Lite

Available in MIL
Synopsis
Save a pattern matching model to disk.
Syntax
void MpatSave(
MIL_TEXT_PTR FileName,
MIL_ID ModelId
)
Description

This function saves all the information about the previously allocated model to disk, including all of the model's current search parameters values and any effects of preprocessing. Later, this information can be reloaded, using MpatRestore() or MpatRead().

Parameters
FileName

Specifies the model file name. If this file already exists, it will be overwritten. The function handles (internally) the opening and closing of this file.

ModelId

Specifies the identifier of the model to save.


MpatSetAcceptance

Example | Availability | MpatSave | MpatSetAccuracy
dtkobjecttracking.c
mmodeltracking.c
Not available in MIL-Lite

Available in MIL
Synopsis
Set the acceptance level of a model.
Syntax
void MpatSetAcceptance(
MIL_ID ModelId,
double AcceptanceThreshold
)
Description

This function sets the acceptance level for a match made with the specified model when it is sought in an image. If the correlation (match score) between the image and the model is less than this level, it is not considered a match (an occurrence). The default acceptance is set when the model is allocated.

Parameters
ModelId

Specifies the identifier of the model for which to change the acceptance threshold search parameter.

AcceptanceThreshold

Specifies the acceptance level, as a percentage. A perfect match is 100%, no correlation is 0%. The match score depends on the image quality. You should experiment to decide what is a typical match score for your application.


MpatSetAccuracy

See Also | Example | Availability | MpatSetAcceptance | MpatSetAngle
User Guide:
Search constraints
The pattern matching algorithm (for advanced users)

Reference:
MpatPreprocModel
MpatSetSpeed
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Set the positional accuracy of a model.
Syntax
void MpatSetAccuracy(
MIL_ID ModelId,
long Accuracy
)
Description

This function sets the specified model's search parameter for positional accuracy and the complexity of the image. You can enhance speed performance by selecting a lower positional accuracy. Also, whenever the positional accuracy of a model changes, the effect of any preprocessing is undone. Therefore, if the accuracy is changed, call MpatPreprocModel() before searching for the model.

The positional accuracy is also slightly affected by the search speed (MpatSetSpeed()).

Parameters
ModelId

Specifies the identifier of the model for which to change the positional accuracy search parameter.

Accuracy

Sets the required positional accuracy for the search. This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_HIGH

 Specifies a high accuracy (typically ± 0.05 pixels)  Specifies a high accuracy (typically ± 0 ...

  Open   Collapse  M_LOW

 Specifies a low accuracy (typically ± 0.20 pixels)  Specifies a low accuracy (typically ± 0 ...

  Open   Collapse  M_MEDIUM

 Specifies a medium accuracy (typically ± 0.10 pixels)  Specifies a medium accuracy (typically ± 0 ...

 Note, the precision achieved is dependent on the quality of the model and the image (the tolerances listed above are typical for high-quality, low-noise images).

 The method used to find a model with M_LOW accuracy more quickly can also produce match scores that are slightly lower than usual. If a precise match score is important to you, use at least medium accuracy.

LOW   HIGH MEDIUM LOW


MpatSetAngle

See Also | Example | Availability | MpatSetAccuracy | MpatSetCenter
User Guide:
Rotation
Speeding up the search

Reference:
MpatAllocRotatedModel
MpatPreprocModel
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Set the angular search parameters of a model.
Syntax
void MpatSetAngle(
MIL_ID ModelId,
long ControlType,
double ControlValue
)
Description

This function sets the specified model's angular search parameters. Also, whenever the angular search parameters of a model change, the effect of any preprocessing of the model is undone. Therefore, if the search angle is changed, call MpatPreprocModel() before searching for the model.

Parameters
ModelId

Specifies the identifier of the model for which to change the angular search parameter. This can be any type of model except a model created using MpatAllocRotatedModel().

ControlType

Specifies the type of control to set.

By default, the ControlType M_SEARCH_ANGLE_MODE is disabled and the search is done at 0° (no rotation). When enabled, the model is searched at angle, respecting all search control parameters.

See the Parameter associations section for possible values.

ControlValue

Specifies the value to which to set the control.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue parameters are described below.

The values below determine the range of angles to cover in the search operation; that is, (M_SEARCH_ANGLE- M_SEARCH_ANGLE_DELTA_NEG) to (M_SEARCH_ANGLE + M_SEARCH_ANGLE_DELTA_POS) inclusively, starting at an angle close to M_SEARCH_ANGLE.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_SEARCH_ANGLE |  | Sets the starting angle value for the search. Sets the starting angle value for the search ...
 | M_DEFAULT | Specifies the default value. The default value is 0.0.
 | 0.0 to 360.0 | Specifies the angle, in degrees.
Open Collapse M_SEARCH_ANGLE_DELTA_NEG |  | Sets the maximum negative delta for the search. Sets the maximum negative delta for the search ...
 | M_DEFAULT | Specifies the default value. The default value is 0.0.
 | 0.0 to 180.0 | Specifies the angle, in degrees.
Open Collapse M_SEARCH_ANGLE_DELTA_POS |  | Sets the maximum positive delta for the search. Sets the maximum positive delta for the search ...
 | M_DEFAULT | Specifies the default value. The default value is 0.0.
 | 0.0 to 180.0 | Specifies the angle, in degrees.
Open Collapse M_SEARCH_ANGLE_MODE |  | Sets whether an angular search is enabled. Sets whether an angular search is enabled ...
 | M_DISABLE | Disables an angular search. This is the default value.
 | M_ENABLE | Enables an angular search.

The values below handle the accuracy, the type of interpolation, and the tolerance of the search.

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_SEARCH_ANGLE_ACCURACY |  | Sets the required precision of the resulting angle. Sets the required precision of the resulting angle ...
 | M_DEFAULT | Same as M_DISABLE.
 | 0.1 to 180.0 | Specifies the angle accuracy, in degrees.
 | M_DISABLE | Specifies that the angular accuracy equals the tolerance.
Open Collapse M_SEARCH_ANGLE_INTERPOLATION_MODE |  | Sets the type of interpolation used. Sets the type of interpolation used ...
 | M_DEFAULT | Same as M_NEAREST_NEIGHBOR.
 | M_BICUBIC | Specifies that bicubic interpolation is used when rotating the model.
 | M_BILINEAR | Specifies that bilinear interpolation is used when rotating the model.
 | M_NEAREST_NEIGHBOR | Specifies that nearest neighbor interpolation is used when rotating the model.
Open Collapse M_SEARCH_ANGLE_TOLERANCE |  | Sets the full range of degrees within which the pattern in the target image can be rotated from a model at a specific angle and still meet the acceptance level. Sets the full range of degrees within which the pattern in the target image can be rotated from a model at a specific angle and still meet the acceptance level ...
 | M_DEFAULT | Specifies the default value. The default value is 5.0.
 | 0.1 to 180.0 | Specifies that the given angle is the range of degrees within which the pattern in the target image can be rotated from a model at a specific angle and still meet the acceptance level. For example, if a model can tolerate the target image being offset from its search angle by ±2.5°, specify 5°. The specified tolerance determines the step angle. Note that very small tolerance values should only be used within small angular ranges, otherwise application performance can be adversely affected.

SEARCH ANGLE MODE SEARCH ANGLE SEARCH ANGLE DELTA NEG SEARCH ANGLE SEARCH ANGLE DELTA POS SEARCH ANGLE SEARCH ANGLE DEFAULT SEARCH ANGLE DELTA NEG DEFAULT SEARCH ANGLE DELTA POS DEFAULT SEARCH ANGLE MODE DISABLE ENABLE SEARCH ANGLE ACCURACY DEFAULT DISABLE SEARCH ANGLE INTERPOLATION MODE DEFAULT BICUBIC BILINEAR NEAREST NEIGHBOR SEARCH ANGLE TOLERANCE DEFAULT


MpatSetCenter

Example | Availability | MpatSetAngle | MpatSetCertainty
There are no examples containing MpatSetCenter().
Not available in MIL-Lite

Available in MIL
Synopsis
Set the reference position of a model.
Syntax
void MpatSetCenter(
MIL_ID ModelId,
double OffX,
double OffY
)
Description

This function sets the reference position of the specified model. The default reference position is equal to ((SizeX - 1) / 2.0, (SizeY - 1) / 2.0) (relative to the model origin). All positional search results are based on this defined model's reference position, relative to the top-left corner of the image in which the search is performed.

Parameters
ModelId

Specifies the identifier of the model for which to change the reference position.

OffX

Specifies the X-offset of the new model's reference position relative to the model origin. Note that the reference position need not be in the model.

OffY

Specifies the Y-offset of the new model's reference position relative to the model origin. Note that the reference position need not be in the model.


MpatSetCertainty

See Also | Example | Availability | MpatSetCenter | MpatSetDontCare
User Guide:
Search constraints

Reference:
MpatSetAcceptance
There are no examples containing MpatSetCertainty().
Not available in MIL-Lite

Available in MIL
Synopsis
Set the certainty level of a model.
Syntax
void MpatSetCertainty(
MIL_ID ModelId,
double CertaintyThreshold
)
Description

This function sets the certainty level for a match made with the specified model when it is sought in an image. If the correlation (match score) between the image and the model is equal to or greater than the certainty level, a match is assumed without looking elsewhere in the image for a better match. The default certainty level is set when the model is allocated (MpatAlloc...()).

Parameters
ModelId

Specifies the identifier of the model for which to change the certainty threshold search parameter.

CertaintyThreshold

Specifies the certainty level, as a percentage. If you set the certainty level too high (close to 100%), you slow down the search because you force the search algorithm to check the whole search region for the best match. A good certainty level is slightly lower than the expected score, so that the search can finish as soon as the match is found. However, if you set the certainty level too low, false matches might be found. Note that the certainty level must be equal to or greater than the acceptance level (MpatSetAcceptance()).


MpatSetDontCare

See Also | Example | Availability | MpatSetCertainty | MpatSetNumber
User Guide:
Steps to perform a search
Masking the model

Reference:
MpatFindModel
MpatFindMultipleModel
MpatPreprocModel
There are no examples containing MpatSetDontCare().
Not available in MIL-Lite

Available in MIL
Synopsis
Set the "don't care" pixels in a model.
Syntax
void MpatSetDontCare(
MIL_ID ModelId,
MIL_ID ImageBufId,
long OffX,
long OffY,
long Value
)
Description

This function sets pixels in the specified model to a "don't care" state. The "don't care" pixels of the model will not be considered when searching for occurrences of the model in the target image (MpatFindModel() or MpatFindMultipleModel()). To determine which model pixels to set, a region of the specified image buffer, starting at the specified offset and equal in size to the model, is compared with the specified "don't care" value. If an image pixel is equal to this value, the corresponding pixel in the model is set to "don't care".

Note, each time this function is called, a new set of "don't care" pixels is assigned to the specified model, superseding any existing set. Therefore, multiple calls to this function do not have a cumulative effect. Also, whenever the "don't care" pixels in a model change, the effect of any preprocessing of the model is undone. Therefore, if the "don't care" pixels are changed, call MpatPreprocModel() before searching for the model.

This function does not support a M_NORMALIZED + M_CIRCULAR_OVERSCAN type of model.

Parameters
ModelId

Specifies the identifier of the model in which to set "don't care" pixels.

ImageBufId

Specifies the identifier of the image buffer used to identify which pixels in the model will be set to "don't care". This buffer must be at least as large as the model.

OffX

Specifies the X-offset from the upper-left corner of the specified image buffer to the upper-left corner of the pixel-value comparison area. The size of the comparison area is determined by the size of the model.

OffY

Specifies the Y-offset from the upper-left corner of the specified image buffer to the upper-left corner of the pixel-value comparison area. The size of the comparison area is determined by the size of the model.

Value

Specifies the pixel value in the image buffer that determine the corresponding "don't care" pixels.

NORMALIZED CIRCULAR OVERSCAN


MpatSetNumber

See Also | Example | Availability | MpatSetDontCare | MpatSetPosition
User Guide:
Search constraints

Reference:
MpatFindModel
MpatFindMultipleModel
MpatSetAcceptance
MpatSetCertainty
There are no examples containing MpatSetNumber().
Not available in MIL-Lite

Available in MIL
Synopsis
Set the expected number of occurrences of a model.
Syntax
void MpatSetNumber(
MIL_ID ModelId,
long NbOccurrences
)
Description

This function sets the number of occurrences of a model for which to search when using MpatFindModel() or MpatFindMultipleModel(). Occurrences with match scores that attain/exceed the certainty level (set with MpatSetCertainty()) are returned, up to the number specified in NbOccurrences. If such occurrences are fewer than the specified number, the remaining occurrences returned are the best of those that attain/exceed the acceptance level (set with MpatSetAcceptance()). The default is 1 (that is, find only the first occurrence with a match score that attains/exceeds the certainty level).

Parameters
ModelId

Specifies the identifier of the model for which to set the expected number of occurrences.

NbOccurrences

Specifies the maximum number of occurrences for which to look in the target image. The number of occurrences should be less than or equal to the number of result buffer entries or some results may be lost.

This parameter must be set to one of the values below.

Open Collapse Value Description
Open Collapse M_ALL

 Returns all matches that attain or exceed the acceptance level.  Returns all matches that attain or exceed the acceptance level.

  Open   Collapse  Value

 Specifies the maximum number of occurrences for which to look in the target image.  Specifies the maximum number of occurrences for which to look in the target image.

  ALL


MpatSetPosition

See Also | Example | Availability | MpatSetNumber | MpatSetSearchParameter
User Guide:
Search constraints
Speeding up the search

Reference:
MpatFindModel
MpatFindMultipleModel
MpatSetCenter
There are no examples containing MpatSetPosition().
Not available in MIL-Lite

Available in MIL
Synopsis
Set the search region of a model.
Syntax
void MpatSetPosition(
MIL_ID ModelId,
long OffX,
long OffY,
long SizeX,
long SizeY
)
Description

This function sets the specified model's search region. It limits the area in the target image in which to find the reference position of the model (set with MpatSetCenter()), and consequently increases the search speed. This function is useful when the model's reference position is expected to be found in a certain area. You can change the search region at any time (for example, when tracking an object, the search region could be changed before each call to MpatFindModel() or MpatFindMultipleModel()).

If you have redefined the model's reference position (with MpatSetCenter()), make sure that the search region defined by MpatSetPosition() covers this new reference position and takes into account the angular search range of the model.

Always use this function, rather than a child buffer, to restrict the search region. Other methods result in edge effects, and if the search region is as small as or smaller than the model, other methods produce invalid results.

To change some of the search parameters set with this function without affecting others, specify M_NO_CHANGE for those you do not want to change. For example, you can change OffX and OffY to the required values and keep SizeX and SizeY as is by setting them to M_NO_CHANGE.

To reset the search region size to the full image, set OffX and OffY to zero (0), and SizeX and SizeY to M_ALL.

Note that it is valid to specify a search region (SizeX and SizeY) that is smaller than the search model since you are setting the area in which to find the model's reference position.

Parameters
ModelId

Specifies the identifier of the model for which to change the search region.

OffX

Specifies the X-coordinate of the top-left corner of the search region in the target image.

Open Collapse Value Description
Open Collapse M_ALL

 Resets the coordinate to the X-coordinate of the top-left corner of the target image to allow a search of the full image.  Resets the coordinate to the X-coordinate of the top-left corner of the target image to allow a search of the full image ...

This is the default value.

  Open   Collapse  M_NO_CHANGE

 Keeps the previous value of this coordinate as set by MpatSetCenter().  Keeps the previous value of this coordinate as set by MpatSetCenter().

  Open   Collapse  Value

 Sets the value of this coordinate to a number.  Sets the value of this coordinate to a number.

The default value is 0.

 OffY

 Specifies the Y-coordinate of the top-left corner of the search region in the target image.

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL

 Resets the coordinate to the Y-coordinate of the top left corner of the target image to allow a search of the full image.  Resets the coordinate to the Y-coordinate of the top left corner of the target image to allow a search of the full image ...

This is the default value.

  Open   Collapse  M_NO_CHANGE

 Keeps the previous value of this coordinate as set by MpatSetCenter().  Keeps the previous value of this coordinate as set by MpatSetCenter().

  Open   Collapse  Value

 Sets the value of this coordinate to a number.  Sets the value of this coordinate to a number.

The default value is 0.

 SizeX

 Specifies the width of the search region.

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL

 Resets the width of the search to that of the full image.  Resets the width of the search to that of the full image ...

This is the default value.

  Open   Collapse  M_NO_CHANGE

 Keeps the previously set value.  Keeps the previously set value.

  Open   Collapse  Value

 Sets the value of this size to a number.  Sets the value of this size to a number.

 SizeY

 Specifies the height of the search region.

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL

 Resets the height of the search to that of the full image.  Resets the height of the search to that of the full image ...

This is the default value.

  Open   Collapse  M_NO_CHANGE

 Keeps the previously set value.  Keeps the previously set value.

  Open   Collapse  Value

 Sets the value of this size to a number.  Sets the value of this size to a number.

  ALL
                         NO CHANGE   ALL
                         NO CHANGE   ALL
                         NO CHANGE   ALL
                         NO CHANGE


MpatSetSearchParameter

See Also | Example | Availability | MpatSetPosition | MpatSetSpeed
User Guide:
The pattern matching algorithm (for advanced users)

Reference:
MpatFindModel
MpatFindMultipleModel
MpatInquire
MpatPreprocModel
MpatSetAccuracy
MpatSetSpeed
There are no examples containing MpatSetSearchParameter().
Not available in MIL-Lite

Available in MIL
Synopsis
Set the internal search parameters of a model.
Syntax
void MpatSetSearchParameter(
MIL_ID PatId,
long Parameter,
double Value
)
Description

This function is for advanced users of the pattern matching module. It need not be used under most circumstances because the default settings usually provide the best results for search operations. However, if the default values do not satisfy the requirements of your application, this function can be used to set the model's internal search parameters. These internal search parameters are normally derived from the speed and accuracy settings (see MpatSetSpeed() and MpatSetAccuracy()), but this function gives the experienced user precise control over them. To gain a clearer understanding of how the search algorithm works, see Chapter 7: Pattern matching.

Note that if some of the model's search parameters are changed after a call to MpatPreprocModel(), the model must be preprocessed again. To inquire if your model is in a preprocessed state, use the MpatInquire() function with M_PREPROCESSED.

Note that the model's internal parameters are all saved and restored with the model, just like the other parameters such as search region, speed, and accuracy.

Parameters
PatId

Specifies the identifier of the model whose search parameter to change, or of the result buffer.

Parameter

Specifies the search parameter to set.

See the Parameter associations section for possible values.

Value

Specifies the value to which to set the specified parameter.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the Parameter and Value parameters are described below.

The values below are for a model identifier.

Open Collapse Parameter Description
Value
Open Collapse M_ALL

Sets all search parameters automatically from the current speed and accuracy settings. Sets all search parameters automatically from the current speed and accuracy settings ...

M_DEFAULT

Specifies all search parameters.

Open Collapse M_ALLOC_OFFSET_X

Sets the model's allocation X-offset. Sets the model's allocation X-offset ...

Value

Specifies the X-offset.

This might be useful when the original value is lost after rotating a model. You can use MpatInquire() to inquire about the current X-offset. This value can be any integer.

The default value is 0.

Open Collapse M_ALLOC_OFFSET_Y

Sets the model's allocation Y-offset. Sets the model's allocation Y-offset ...

Value

Specifies the Y-offset.

This might be useful when the original value is lost after rotating the model. You can use MpatInquire() to inquire about the current Y-offset. This value can be any integer.

The default value is 0.

Open Collapse M_COARSE_SEARCH_ACCEPTANCE

Sets the coarse search acceptance threshold level to use for rejecting candidate model peaks at low resolution levels. Sets the coarse search acceptance threshold level to use for rejecting candidate model peaks at low resolution levels ...

M_DEFAULT

Determines the coarse search acceptance threshold level automatically.

1.0 to 100.0

Specifies the coarse search acceptance threshold level.

This can speed up the search when some of the matches you request do not reach the certainty threshold, or when you request more matches than are really present in the image. The coarse search acceptance level should usually be set much lower than the search acceptance level. For example, a good level to set it to is about 20% to 30%. Note that if it is too low, you will not see any increase in speed. However, if it is too high, you risk rejecting real match peaks. Note that the coarse search acceptance threshold level is not saved and restored with the model. So, if you always want to use your own coarse search acceptance level, you should set it each time after restoring your model and before calling MpatFindModel(). Otherwise, the default coarse search acceptance level is used.

Open Collapse M_EXTRA_CANDIDATES

Sets the number of extra candidates to consider. Sets the number of extra candidates to consider ...

Value

Specifies the number of extra candidates. This value can be any integer.

Normally, the search algorithm considers only a limited number of (best) scores as possible candidates to match when proceeding at the most sub-sampled stage. This parameter allows you to add robustness to the algorithm, by considering more candidates, without compromising too heavily on search speed.

The default value is 0.

Open Collapse M_FAST_FIND

Sets whether to use fast peak finding. Sets whether to use fast peak finding ...

M_DEFAULT

Preprocessing decides if fast peak finding is appropriate.

M_DISABLE

Specifies no fast peak finding.

The initial search (at the resolution level determined by M_FIRST_LEVEL) computes the correlation at every position in the search region. This guarantees that the biggest match peak will be found, and that it will be investigated first.

M_ENABLE

Specifies fast peak finding.

The search algorithm attempts to find the peaks without checking every point. This is safe in most cases, but can cause matches to be missed for models that produce very narrow peaks.

Open Collapse M_FIRST_LEVEL

Sets the resolution level for the initial stage (lowest resolution) of the search. Sets the resolution level for the initial stage (lowest resolution) of the search ...

Note that level 0 is the original target image and each higher level is half the size (and resolution) of the previous one. If the specified level is not supported by the search algorithm, the highest possible level will be used. A higher first level speeds up the initial search but makes it less reliable, because the model might not retain enough distinctive features at such a low resolution. Use MpatInquire() with M_PROC_FIRST_LEVEL to inquire about the default value of the lowest resolution level.

M_DEFAULT

Specifies the first level automatically.

0 to 7

Specifies the first level.

Open Collapse M_LAST_LEVEL

Sets the resolution level for the final stage (highest resolution) of the search. Sets the resolution level for the final stage (highest resolution) of the search ...

Note that if the specified level is not supported by the search algorithm, the highest acceptable level will be used. Search score can also be less reliable for levels above 0, depending on the characteristics of the model. Use MpatInquire() with M_PROC_LAST_LEVEL to inquire about the default value of the highest resolution level.

M_DEFAULT

Specifies the last level automatically.

0 to 7

Specifies the last level.

Open Collapse M_MIN_SPACING_X

Sets the minimum spacing (in X) between two models in order for them to be considered distinct. Sets the minimum spacing (in X) between two models in order for them to be considered distinct ...

M_DEFAULT

Defaults to 75% of the model width (SizeX of MpatAlloc...()).

1.0 to 100.0

Specifies the minimum spacing.

Open Collapse M_MIN_SPACING_Y

Sets the minimum spacing (in Y) between two models in order for them to be considered distinct. Sets the minimum spacing (in Y) between two models in order for them to be considered distinct ...

M_DEFAULT

Defaults to 75% of the model height (SizeY of MpatAlloc...()).

1.0 to 100.0

Specifies the minimum spacing.

Open Collapse M_MODEL_STEP

Sets whether all or every second pixel in the model is used in the correlation during the high resolution stage of the search. Sets whether all or every second pixel in the model is used in the correlation during the high resolution stage of the search ...

M_DEFAULT

Specifies the model step automatically.

1

Specifies all model pixels.

2

Specifies every second model pixel (in both the X and Y directions).

This speeds up the last (high resolution) stage of the search, particularly for large models. The match score can be affected if the model has many fine features, but will tend not to be affected if the model has mainly coarse features.

The values below are for a result buffer identifier.

Open Collapse Parameter Description
Value
Open Collapse M_TARGET_CACHING

Sets whether the pyramidal representation of the buffer is called or kept in the result buffer. Sets whether the pyramidal representation of the buffer is called or kept in the result buffer ...

M_DISABLE

Specifies that the pyramidal representation of the buffer is generated each time MpatFindModel() or MpatFindMultipleModel() is called.

This is the default value.
M_ENABLE

Specifies that the pyramidal representation of the buffer (generated when MpatFindModel() or MpatFindMultipleModel() is called) is kept in the result buffer.

This pyramidal representation is re-used by consecutive calls to MpatFindModel() and MpatFindMultipleModel() as long as the same result buffer is used and the image, search region, and model size are not modified.

PREPROCESSED FIRST LEVEL PROC FIRST LEVEL PROC LAST LEVEL ALL DEFAULT ALLOC OFFSET X ALLOC OFFSET Y COARSE SEARCH ACCEPTANCE DEFAULT EXTRA CANDIDATES FAST FIND DEFAULT DISABLE ENABLE FIRST LEVEL DEFAULT LAST LEVEL DEFAULT MIN SPACING X DEFAULT MIN SPACING Y DEFAULT MODEL STEP DEFAULT TARGET CACHING DISABLE ENABLE


MpatSetSpeed

See Also | Example | Availability | MpatSetSearchParameter | MpatWrite
User Guide:
Search constraints
Speeding up the search
The pattern matching algorithm (for advanced users)

Reference:
MpatFindModel
MpatFindMultipleModel
MpatPreprocModel
dtkobjecttracking.c
mmodeltracking.c
mpat.c
Not available in MIL-Lite

Available in MIL
Synopsis
Set search speed of a model.
Syntax
void MpatSetSpeed(
MIL_ID ModelId,
long SpeedFactor
)
Description

This function specifies the required search speed when using MpatFindModel() or MpatFindMultipleModel(). At a higher speed, the search takes all reasonable short cuts; therefore, the search should be performed faster than at lower settings. Generally, the high speed setting should be used for better quality images or when using a simple model. Note, the high speed setting reduces positional accuracy very slightly. Try the low speed settings only if your image quality is particularly poor and you have encountered problems at higher speeds. Also, whenever the search speed parameter setting of a model changes, the effect of any preprocessing of the model is undone. Therefore, if the search speed is changed, call MpatPreprocModel() before searching for the model.

Parameters
ModelId

Specifies the identifier of the model for which to change the speed parameter.

SpeedFactor

Specifies the search speed. Set this parameter to one of the values below.

Open Collapse Value Description
Open Collapse M_HIGH

 Specifies a high search speed.  Specifies a high search speed.

  Open   Collapse  M_LOW

 Specifies a low search speed.  Specifies a low search speed.

  Open   Collapse  M_MEDIUM

 Specifies a medium search speed.  Specifies a medium search speed.

  Open   Collapse  M_VERY_HIGH

 Specifies a very high search speed.  Specifies a very high search speed.

  Open   Collapse  M_VERY_LOW

 Specifies a very low search speed.  Specifies a very low search speed.

  VERY HIGH HIGH MEDIUM
 LOW VERY LOW


MpatWrite

See Also | Example | Availability | MpatSetSpeed
Reference:
MpatRead
There are no examples containing MpatWrite().
Not available in MIL-Lite

Available in MIL
Synopsis
Write a pattern matching model to an open file.
Syntax
void MpatWrite(
FILE *FileHandle,
MIL_ID ModelId
)
Description

This function writes all the information about the previously allocated model to the current file position of an open file, including all of the model's current search parameter values and any effects of preprocessing. This information can later be reloaded with MpatRead().

Parameters
FileHandle

Specifies the handle of the file (opened with the standard C function fopen()). The file handle must be compatible with MIL. To achieve this, link your project with the multi-threaded DLL run-time library. For example, in the Microsoft Visual C++.NET development environment, select Properties from the Project menu. On the C/C++ page, select Code Generation as a category and Multi-threaded DLL as the run-time library to use.

The model is written starting at the current file position. After writing, the file remains open and is positioned immediately after the model just written.

ModelId

Specifies the identifier of the model to save.


str

Mstr functions

Example | Availability
There are no examples containing str().
Not available in MIL-Lite

Available in MIL
Synopsis
The String Reader module performs Optical Character Recognition (OCR) using feature based technology. The module is invariant to changes in scale, aspect ratio, and contrast. String Reader also offers considerable tolerance towards variations in perspective and angle. In addition, String Reader supports multiple user-defined grammar rules and multi-font definition in a single context, and it features a powerful Graphical User Interface (GUI) for easy font definition. All this makes the String Reader module the ideal tool for writing seemingly complex applications, such as Automatic Number Plate Recognition (ANPR) programs.
Functions
  • MstrAlloc
  • MstrAllocResult
  • MstrControl
  • MstrDraw
  • MstrEditFont
  • MstrFree
  • MstrGetResult
  • MstrInquire
  • MstrPreprocess
  • MstrRead
  • MstrRestore
  • MstrSave
  • MstrSetConstraint
  • MstrStream


MstrAlloc

See Also | Example | Availability | MstrAllocResult
User Guide:
Steps to reading a string in an image
Creating and customizing the fonts

Reference:
MstrFree
MsysAlloc
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocates a String Reader context.
Syntax
MIL_ID MstrAlloc(
MIL_ID SystemId,
long ContextType,
long ControlFlag,
MIL_ID *ObjectIdPtr
)
Description

This function allocates a String Reader context on the specified system. A String Reader context contains the read parameters, the list of fonts, and the list of string models. When the String Reader context is no longer required, you should release its memory, using MstrFree().

Parameters
SystemId

Specifies the system on which to allocate the String Reader context.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ContextType

 Specifies the type of String Reader context.  This parameter must be set to the value below.

  Open   Collapse  Value
Description

  Open   Collapse  M_FEATURE_BASED

 Specifies a feature based string reader.  Specifies a feature based string reader.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 ObjectIdPtr

 Specifies the address of the variable in which to write the String Reader context identifier.  Since the MstrAlloc() function also returns the String Reader context identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the String Reader context's identifier. If allocation fails, M_NULL is returned.

 DEFAULT HOST   FEATURE BASED


MstrAllocResult

See Also | Example | Availability | MstrAlloc | MstrControl
User Guide:
Steps to reading a string in an image

Reference:
MstrFree
MstrRead
MsysAlloc
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Allocate a String Reader result buffer.
Syntax
MIL_ID MstrAllocResult(
MIL_ID SystemId,
long ControlFlag,
MIL_ID *ObjectIdPtr
)
Description

This function allocates a String Reader result buffer, on the specified system, to store results obtained from an MstrRead() operation. When the String Reader result buffer is no longer required, release its memory, using MstrFree().

Parameters
SystemId

Specifies the system on which to allocate the String Reader result buffer.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 ObjectIdPtr

 Specifies the address of the variable in which to write the String Reader result buffer identifier.  Since the MstrAllocResult() function also returns the String Reader result buffer identifier, you can set this parameter to M_NULL.

Return value

 The returned value is the String Reader result buffer identifier. If allocation fails, M_NULL is returned.

 DEFAULT HOST


MstrControl

See Also | Example | Availability | MstrAllocResult | MstrDraw
User Guide:
Steps to reading a string in an image
Creating and customizing the fonts
Adding and deleting string models to the context
Space
Number of strings to read
Degrees of freedom
Global context settings
Scores and acceptances
Retrieving results and annotation

Reference:
MstrAlloc
MstrAllocResult
MstrDraw
MstrEditFont
MstrGetResult
MstrInquire
MstrPreprocess
MstrRead
MstrSetConstraint
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Control a String Reader context, a specific string model, a specific font, or a String Reader result buffer.
Syntax
void MstrControl(
MIL_ID ContextOrResultID,
long Index,
long ControlType,
double ControlValue
)
Description

This function sets the specified control for a String Reader context, for one (or all) of the specified string models or fonts contained therein, or for a String Reader result buffer. These settings control the execution of MstrRead() operations. All the control type settings can be inquired using MstrInquire().

Changing certain control type settings might require preprocessing the String Reader context again, using MstrPreprocess(). To know if the String Reader context needs to be preprocessed, call MstrInquire() with M_PREPROCESSED.

Parameters
ContextOrResultID

Specifies the String Reader context or String Reader result buffer whose settings you want to modify. The String Reader context or result buffer must have been previously allocated on the system using MstrAlloc() or MstrAllocResult(), respectively.

Index

Specifies that the String Reader context, a specific font, a specific string model, or a String Reader result buffer is controlled. Set this parameter to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default value.  Specifies the default value ...

 For a String Reader context, the default value is the same as M_CONTEXT.

 For a String Reader result, the default value is the same as M_GENERAL.

  Open   Collapse  M_FONT_INDEX(
long FontIndex

          )

 Specifies that the control settings will be applied to a font. This value is only applicable for a String Reader context.  Specifies that the control settings will be applied to a font ...

Parameters

FontIndex

 This parameter specifies the index of the font. You can set this parameter to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL

 Specifies that the control settings will be applied to all fonts.  Specifies that the control settings will be applied to all fonts ...

  Open   Collapse  Value >= 0

 Specifies the index of the individual font to which the control settings will be applied.  Specifies the index of the individual font to which the control settings will be applied ...

  Open   Collapse  M_STRING_INDEX(
long StringIndex

          )

 Specifies that the control settings will be applied to a string. This value is only applicable for a String Reader context.  Specifies that the control settings will be applied to a string ...

Parameters

StringIndex

 This parameter specifies the index of the string. You can set this parameter to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_ALL

 Specifies that the control settings will be applied to all strings.  Specifies that the control settings will be applied to all strings ...

 Note that to apply control settings to all strings, the ControlType and ControlValue parameters must be supported by all the string models.

  Open   Collapse  Value >= 0

 Specifies the index of the individual string to which the control settings will be applied.  Specifies the index of the individual string to which the control settings will be applied ...

  Open   Collapse  M_CONTEXT

 Controls a general setting of a String Reader context. This value is only applicable for a String Reader context.  Controls a general setting of a String Reader context ...

  Open   Collapse  M_GENERAL

 Controls a general setting of a String Reader result buffer. This value is only applicable for a String Reader result.  Controls a general setting of a String Reader result buffer ...

 ControlType

 Specifies the setting to change.

See the Parameter associations section for possible values.

 ControlValue

 Specifies the setting's new value.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue
         parameters are described below.

 The following ControlType and corresponding ControlValue settings can be specified for either the String Reader context (M_CONTEXT) or each specific string in the String Reader context (M_STRING_INDEX()):

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_STRING_NUMBER

 Sets either the maximum (total) number of all strings that can be read with a String Reader context (M_CONTEXT), or the maximum number of a specific string (M_STRING_INDEX()) that can be read with a String Reader context.  Sets either the maximum (total) number of all strings that can be read with a String Reader context (M_CONTEXT), or the maximum number of a specific string (M_STRING_INDEX()) that can be read with a String Reader context ...

 M_DEFAULT

Specifies the default value. The default value is 1.

 M_ALL

 Specifies that all strings will be read.

 Note that this setting can increase the read time; always set M_STRING_NUMBER to a specific number whenever possible.

 Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

 Value

 Specifies the maximum number of strings that can be read.

 For M_CONTEXT, this value specifies the maximum (total) number of strings that can be read. Any value greater than or equal to 1 can be set.

 Note that if you have MIL 8.0 installed without Processing Pack 1, the only valid value is 1.

 For M_STRING_INDEX(), this value specifies the maximum number of a specific string model that can be read. Any value greater than or equal to 0 can be set.

 Note that if you have MIL 8.0 installed without Processing Pack 1, the only valid values are 0 and 1.

 The possible ControlType and corresponding ControlValue settings for M_CONTEXT are:

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_ENCODING

 Sets the type of character encoding used by the String Reader context.  Sets the type of character encoding used by the String Reader context ...

 All functions that accept a string of characters as a parameter use character encoding to determine the type of the pointer.

 M_DEFAULT

Same as M_ASCII.

 M_ASCII

 Specifies an 8-bit ASCII standard.

  Open   Collapse   M_MINIMUM_CONTRAST

 Sets the minimum contrast between a character in the target image and its background, in order for the character to be read by MstrRead().  Sets the minimum contrast between a character in the target image and its background, in order for the character to be read by MstrRead() ...

 Increasing the minimum contrast will typically speed up the read operation, particularly in presence of noise; however, if the minimum contrast is higher than the contrast of an actual character, that character will be lost.

 M_DEFAULT

Specifies the default value. The default value is 15.

 1 to 255

 Specifies the minimum contrast.

  Open   Collapse   M_SEARCH_CHAR_ANGLE

 Sets whether to perform calculations specific to angular-range search strategies.  Sets whether to perform calculations specific to angular-range search strategies ...

 The read algorithm is naturally robust to variations in a character's angle. Therefore, a character might still be read correctly, even if M_SEARCH_CHAR_ANGLE is disabled.

 Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

 M_DEFAULT

Same as M_DISABLE.

 M_DISABLE

 Disables calculations specific to angular-range search strategies.

 M_ENABLE

 Enables calculations specific to angular-range search strategies.

  Open   Collapse   M_SEARCH_SKEW_ANGLE

 Sets whether to perform calculations specific to angular-range skew search strategies.  Sets whether to perform calculations specific to angular-range skew search strategies ...

 The read algorithm is naturally robust to variations in a character's skew. Therefore, a character might still be read correctly, even if M_SEARCH_SKEW_ANGLE is disabled.

 Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

 M_DEFAULT

Same as M_DISABLE.

 M_DISABLE

 Disables calculations specific to angular-range skew search strategies.

 M_ENABLE

 Enables calculations specific to angular-range skew search strategies.

  Open   Collapse   M_SPACE_CHARACTER

 Sets the character value to use as a space character within the formatted text that will be read.  Sets the character value to use as a space character within the formatted text that will be read ...

 The space character will be inserted in the formatted string results (MstrGetResult() with M_FORMATTED_STRING) every time the distance between 2 characters exceeds the space width (MstrControl() with M_SPACE_WIDTH). Note that the space character must be set before the text is read.

 M_DEFAULT

Specifies the default value. The default value is numerical ASCII code 32.

 M_NONE

 Specifies no space character.

 Value

 Specifies the space character, as its numerical ASCII code. For example, 10 results in a new line character, 32 results in a space character. Note that the character value must be cast to a double.

  Open   Collapse   M_SPEED

 Sets the search and read speed of the MstrRead() operation. Note that increasing the speed can decrease the robustness of MstrRead() Sets the search and read speed of the MstrRead() operation ...

 M_DEFAULT

Same as M_MEDIUM.

 M_MEDIUM

 Sets the speed to medium.

  Open   Collapse   M_STRING_SEPARATOR

 Sets the character value to use as a string separator within the formatted text that will be read.  Sets the character value to use as a string separator within the formatted text that will be read ...

 The string separator character will be inserted between each string when getting the entire text (MstrGetResult() with M_TEXT). Note that the string separator character must be set before the string is read.

 M_DEFAULT

Specifies the default value. The default value is numerical ASCII code 10.

 M_NONE

 Specifies no separator character.

 Value

 Specifies the separator character, as its numerical ASCII code. For example, 10 results in a new line character, 32 results in a space character. Note that the character value must be cast to a double.

  Open   Collapse   M_TIMEOUT

 Sets the maximum read time for MstrRead(), in msec. If the read operation times out, the strings read up to that point will be returned as a result.  Sets the maximum read time for MstrRead(), in msec ...

 Note that the actual maximum read time might vary slightly from the time that you set.

 M_DEFAULT

Specifies the default value. The default value is 2000.0 msec.

 M_DISABLE

 Specifies an infinite amount of read time.

 Value > = 0

 Specifies the maximum read time, in msec.

 The possible ControlType and corresponding ControlValue settings for operations done with M_CONTEXT are:

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_FONT_ADD |  | Adds an empty font to the String Reader context. The maximum number of fonts in a String Reader context is 255. Adds an empty font to the String Reader context ... To edit the font, use MstrEditFont().
 | M_DEFAULT | Same as M_USER_DEFINED.
 | M_USER_DEFINED | Specifies an empty font. You must use MstrEditFont() to add characters to it.
Open Collapse M_FONT_DELETE |  | Deletes a font from the String Reader context. Deletes a font from the String Reader context ...
 | M_DEFAULT | Same as M_ALL.
 | M_ALL | Specifies that all fonts will be deleted.
 | Value > = 0 | Specifies the index of the font to delete.
Open Collapse M_STRING_ADD |  | Adds a string to the String Reader context. Adds a string to the String Reader context ... The maximum number of strings in a String Reader context is 255.
 | M_DEFAULT | Same as M_USER_DEFINED.
 | M_USER_DEFINED | Specifies a user-defined string. Initially, a user-defined string does not have any constraints, does not use any checksum error detection, and all its parameters are set to their default value.
Open Collapse M_STRING_DELETE |  | Deletes a string from the String Reader context. Deletes a string from the String Reader context ...
 | M_DEFAULT | Same as M_ALL.
 | M_ALL | Specifies that all strings will be deleted.
 | Value > = 0 | Specifies the index of the string to delete.

 The possible ControlType and corresponding ControlValue settings for M_STRING_INDEX() are:

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_CHAR_ACCEPTANCE

 Sets the acceptance level for the character score.  Sets the acceptance level for the character score ...

 The character's score quantifies the similarity between the character in the target and the character in the font; it also quantifies the similarity between the character in the target and the other characters of the string in the target.

 To be accepted as part of the string, the character's score (MstrGetResult() with M_CHAR_SCORE) must be greater than or equal to M_CHAR_ACCEPTANCE.

 M_DEFAULT

Specifies the default value. The default value is 50.0 percent.

 0.0 to 100.0

 Specifies an acceptable score, as a percentage.

  Open   Collapse   M_CHAR_ASPECT_RATIO_MAX_FACTOR

 Sets the factor used to determine the upper limit of the aspect ratio for the characters in the string. This value is relative to the found string aspect ratio. That is, UpperLimit = FoundStringAspectRatio x M_CHAR_ASPECT_RATIO_MAX_FACTOR.  Sets the factor used to determine the upper limit of the aspect ratio for the characters in the string ...

 This value sets the possible increasing aspect ratio variation for the characters in the string. Characters with an aspect ratio outside the aspect ratio range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 1.1.

 1.0 to 2.0

 Specifies the factor that determines the maximum aspect ratio of the characters in the string.

  Open   Collapse   M_CHAR_ASPECT_RATIO_MIN_FACTOR

 Sets the factor used to determine the lower limit of the aspect ratio for the characters in the string. This value is relative to the found string aspect ratio. That is, LowerLimit = FoundStringAspectRatio x M_CHAR_ASPECT_RATIO_MIN_FACTOR.  Sets the factor used to determine the lower limit of the aspect ratio for the characters in the string ...

 This value sets the possible decreasing aspect ratio variation for the characters in the string. Characters with an aspect ratio outside the aspect ratio range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 0.9.

 0.5 to 1.0

 Specifies the factor that determines the minimum aspect ratio of the characters in the string.

  Open   Collapse   M_CHAR_HOMOGENEITY_ACCEPTANCE

 Sets the acceptance level for the character's homogeneity score.  Sets the acceptance level for the character's homogeneity score ...

 The character's homogeneity score quantifies the similarity between the character in the target and the other characters of the string in the target.

 To be accepted as part of the string, the character's homogeneity score (MstrGetResult() with M_CHAR_HOMOGENEITY_SCORE) must be greater than or equal to M_CHAR_HOMOGENEITY_ACCEPTANCE.

 M_DEFAULT

Specifies the default value. The default value is 50.0 percent.

 0.0 to 100.0

 Specifies an acceptable score, as a percentage.

  Open   Collapse   M_CHAR_MAX_BASELINE_DEVIATION

 Sets the maximum deviation that a character's baseline can have from the string's baseline. This value is a percentage of the character's height (size-Y) at the scale of the string (median character scale).  Sets the maximum deviation that a character's baseline can have from the string's baseline ...

 The string's baseline is determined by the median position of all character baselines in the string. Characters with no baseline are ignored. The deviation of a character is the distance between the character's baseline and the string's baseline. The maximum deviation is given as a percentage of the character's height (size Y). For example, 10 means that the character cannot deviate from the string reference line by more than 10% of its height (size Y), at the scale of the string found.

 For more information, refer to M_CHAR_BASELINE in MstrEditFont().

 M_DEFAULT

Specifies the default value. The default value is 10.

 0 to 100

 Specifies the character's maximum deviation.

  Open   Collapse   M_CHAR_SCALE_MAX_FACTOR

 Sets the factor used to determine the upper limit (maximum permitted scale) of the scale range for the characters in the string. This value is relative to the found string scale. That is, UpperLimit = FoundStringScale x M_CHAR_SCALE_MAX_FACTOR.  Sets the factor used to determine the upper limit (maximum permitted scale) of the scale range for the characters in the string ...

 This value sets the possible increasing scale variation for the characters in the string. Characters with a scale outside the scale range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 1.1.

 1.0 to 2.0

 Specifies the factor that determines the maximum scale of the characters in the string.

  Open   Collapse   M_CHAR_SCALE_MIN_FACTOR

 Sets the factor used to determine the lower limit (minimum permitted scale) of the scale range for the characters in the string. This value is relative to the found string scale. That is, LowerLimit = FoundStringScale x M_CHAR_SCALE_MIN_FACTOR.  Sets the factor used to determine the lower limit (minimum permitted scale) of the scale range for the characters in the string ...

 This value sets the possible decreasing scale variation for the characters in the string. Characters with a scale outside the scale range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 0.9.

 0.5 to 1.0

 Specifies the factor that determines the minimum scale of the characters in the string.

  Open   Collapse   M_CHAR_SIMILARITY_ACCEPTANCE

 Sets the acceptance level for the character's similarity score.  Sets the acceptance level for the character's similarity score ...

 The character's similarity score quantifies the similarity between the character in the target and the character in the font.

 To be accepted as part of the string, the character's similarity score (MstrGetResult() with M_CHAR_SIMILARITY_SCORE) must be greater than or equal to M_CHAR_SIMILARITY_ACCEPTANCE.

 M_DEFAULT

Specifies the default value. The default value is 50.0 percent.

 0.0 to 100.0

 Specifies an acceptable score, as a percentage.

  Open   Collapse   M_FOREGROUND_VALUE

 Sets the foreground color of the string.  Sets the foreground color of the string ...

 M_DEFAULT

Same as M_FOREGROUND_BLACK.

 M_FOREGROUND_BLACK

 Specifies that black is the foreground color of the string.

 M_FOREGROUND_BLACK_OR_WHITE

 Specifies that the foreground color of the string can be either black or white.

 Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

 M_FOREGROUND_WHITE

 Specifies that white is the foreground color of the string.

  Open   Collapse   M_SPACE_MAX_CONSECUTIVE

 Sets the maximum number of consecutive space characters allowed in the string.  Sets the maximum number of consecutive space characters allowed in the string ...

 Together with the space width (MstrControl() with M_SPACE_WIDTH), M_SPACE_MAX_CONSECUTIVE determines the maximum distance between 2 adjacent characters of the same string. If the distance between two characters is greater than the maximum distance, then they are considered to be part of 2 different strings.

 M_DEFAULT

Specifies the default value. The default value is 3.

 Value > = 0

 Specifies the maximum number of consecutive space characters.

  Open   Collapse   M_STRING_ACCEPTANCE

 Sets the acceptance level for the string score.  Sets the acceptance level for the string score ...

 The string score is the average score of the characters in the string.

 To be accepted as part of the string, the string's score (MstrGetResult() with M_STRING_SCORE) must be greater than or equal to M_STRING_ACCEPTANCE.

 M_DEFAULT

Specifies the default value. The default value is 50.0 percent.

 0.0 to 100.0

 Specifies an acceptable score, as a percentage.

  Open   Collapse   M_STRING_ANGLE

 Sets the nominal angle of the string.  Sets the nominal angle of the string ...

 M_DEFAULT

 Specifies the default value. The default value is 0.0°.

  Open   Collapse   M_STRING_ANGLE_DELTA_NEG

 Sets the lower limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE). That is, LowerLimit = M_STRING_ANGLE - M_STRING_ANGLE_DELTA_NEG.  Sets the lower limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE) ...

 This value sets the possible clockwise angular variation of the string. Strings with angles outside the angular range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 10.0 °.

 0.0 to 10.0

 Specifies the lower limit of the angular range, in degrees.

  Open   Collapse   M_STRING_ANGLE_DELTA_POS

 Sets the upper limit of the angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE). That is, UpperLimit = M_STRING_ANGLE  + M_STRING_ANGLE_DELTA_POS.  Sets the upper limit of the angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE) ...

 This value sets the possible counter-clockwise angular variation of the string. Strings with angles outside the angular range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 10.0 °.

 0.0 to 10.0

 Specifies the lower limit of the angular range, in degrees.

  Open   Collapse   M_STRING_ASPECT_RATIO

 Sets the nominal aspect ratio of the string.  Sets the nominal aspect ratio of the string ...

 The aspect ratio of the string is the median aspect ratio of all the characters in the string, while the aspect ratio of a character is the ratio of its scale in X by its scale in Y. This indicates how the width and the height of the characters in the string vary relative to the characters in the font.

 M_DEFAULT

Specifies the default value. The default value is 1.0.

 0.5 to 2.0

 Specifies the pixel width/pixel height of the target.

  Open   Collapse   M_STRING_ASPECT_RATIO_MAX_FACTOR

 Sets the factor used to determine the upper limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl() with M_STRING_ASPECT_RATIO). That is, UpperLimit = M_STRING_ASPECT_RATIO  x M_STRING_ASPECT_RATIO_MAX_FACTOR.  Sets the factor used to determine the upper limit of the string's aspect ratio ...

 This value sets the possible increasing aspect ratio variation for the string. Strings with an aspect ratio outside the aspect ratio range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 1.25.

 1.0 to 2.0

 Specifies the factor that determines the maximum aspect ratio of the string.

  Open   Collapse   M_STRING_ASPECT_RATIO_MIN_FACTOR

 Sets the factor used to determine the lower limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl() with M_STRING_ASPECT_RATIO). That is, LowerLimit = M_STRING_ASPECT_RATIO  x M_STRING_ASPECT_RATIO_MIN_FACTOR.  Sets the factor used to determine the lower limit of the string's aspect ratio ...

 This value sets the possible decreasing aspect ratio variation for the string. Strings with an aspect ratio outside the aspect ratio range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 0.8.

 0.5 to 1.0

 Specifies the factor that determines the minimum aspect ratio of the string.

  Open   Collapse   M_STRING_SCALE

 Sets the nominal scale of the string.  Sets the nominal scale of the string ...

 The scale of the string is the median scale in the X-direction of all the characters in the string.

 M_DEFAULT

Specifies the default value. The default value is 1.0.

 0.25 to 4.0

 Specifies the value of the scale.

  Open   Collapse   M_STRING_SCALE_MAX_FACTOR

 Sets the factor used to determine the upper limit (maximum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl() with M_STRING_SCALE). That is, UpperLimit = M_STRING_SCALE  x M_STRING_SCALE_MAX_FACTOR.  Sets the factor used to determine the upper limit (maximum permitted scale) of the string's scale range ...

 This value sets the possible increasing scale variation for the string. Strings with a scale outside the scale range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 2.0.

 1.0 to 2.0

 Specifies the factor that determines the minimum scale of the string.

  Open   Collapse   M_STRING_SCALE_MIN_FACTOR

 Sets the factor used to determine the lower limit (minimum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl() with M_STRING_SCALE). That is, LowerLimit = M_STRING_SCALE  x M_STRING_SCALE_MIN_FACTOR.  Sets the factor used to determine the lower limit (minimum permitted scale) of the string's scale range ...

 This value sets the possible decreasing scale variation for the string. Strings with a scale outside the scale range will not be returned as results.

 M_DEFAULT

Specifies the default value. The default value is 0.5.

 0.5 to 1.0

 Specifies the factor that determines the minimum scale of the string.

  Open   Collapse   M_STRING_SIZE_MAX

 Sets the maximum string size (number of characters) of the string model.  Sets the maximum string size (number of characters) of the string model ...

 The space characters are not counted in the string size. The maximum string size must be greater than or equal to the minimum string size (MstrControl() with M_STRING_SIZE_MIN).

 M_DEFAULT

Same as M_INFINITE.

 M_INFINITE

 Specifies no maximum string size.

 Value > = 1

 Specifies the maximum string size.

  Open   Collapse   M_STRING_SIZE_MIN

 Sets the minimum string size (number of characters) of the string model.  Sets the minimum string size (number of characters) of the string model ...

 The space characters are not counted in the string size. The minimum string size must be lower than or equal to the maximum string size (MstrControl() with M_STRING_SIZE_MAX).

 M_DEFAULT

Specifies the default value. The default value is 1.

 Value > = 1

 Specifies the minimum string size.

 The possible ControlType and corresponding ControlValue settings for M_FONT_INDEX() are:

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_DRAW_BOX_MARGIN_X

 Sets the margin in the X-direction, between the character box and the drawing box.  Sets the margin in the X-direction, between the character box and the drawing box ...

 The character box is the bounding box of the character. The drawing box is the box used for drawing purpose. For more information, see MstrDraw().

 M_DEFAULT

Specifies the default value. The default value is 3.

 Value > = 0

 Specifies the horizontal margin.

  Open   Collapse   M_DRAW_BOX_MARGIN_Y

 Sets the margin in the Y-direction, between the character box and the drawing box.  Sets the margin in the Y-direction, between the character box and the drawing box ...

 The character box is the bounding box of the character. The drawing box is the box used for drawing purpose. For more information, see MstrDraw().

 M_DEFAULT

Specifies the default value. The default value is 3.

 Value > = 0

 Specifies the vertical margin.

  Open   Collapse   M_SPACE_WIDTH

 Sets the width of the space character of the font.  Sets the width of the space character of the font ...

 Note that the space character is not like other characters in the font. For example, you cannot set it as a constraint (MstrSetConstraint()), and it is not counted in the string size (MstrControl() with M_STRING_SIZE_MIN and M_STRING_SIZE_MAX). For more information, see MstrGetResult() with M_STRING_SIZE, M_STRING, M_FORMATTED_STRING_SIZE and M_FORMATTED_STRING.

 Together with the maximum number of consecutive space characters allowed in the string (MstrControl() with M_SPACE_MAX_CONSECUTIVE), M_SPACE_WIDTH determines the maximum distance between 2 adjacent characters of the same string. If the distance between two characters is greater than the maximum distance, then they are considered to be part of 2 different strings. M_SPACE_WIDTH also determines how to convert the distance into space characters, when getting formatted string results (MstrGetResult() with M_FORMATTED_STRING).

 M_DEFAULT

Same as M_MEAN_CHAR_WIDTH.

 M_INFINITE

 Specifies that the width of the space character is infinite.

 In this case, all characters on the same line are always part of the same string. Also, there will never be a space character in the read string since the distance can never be large enough to constitute a space character.

 M_MAX_CHAR_WIDTH

 Specifies that the width of the space character is equal to the maximum character size X of the font.

 M_MEAN_CHAR_WIDTH

 Specifies that the width of the space character is equal to the average character size X of the font.

 M_MIN_CHAR_WIDTH

 Specifies that the width of the space character is equal to the minimum character size X of the font.

 M_QUARTER_MAX_CHAR_WIDTH

 Specifies that the width of the space character is equal to a quarter of the maximum character width of the font.

M_QUARTER_MAX_CHAR_WIDTH is the closest to the typical space size of a standard font (one quarter of em squared).

 Value > = 1

 Specifies the width of the space character.

PREPROCESSED CONTEXT GENERAL CONTEXT STRING INDEX() CONTEXT STRING INDEX() CONTEXT STRING INDEX() STRING NUMBER CONTEXT SEARCH CHAR ANGLE SEARCH SKEW ANGLE FORMATTED STRING SPACE WIDTH TEXT CONTEXT STRING INDEX() CHAR SCORE CHAR ACCEPTANCE CHAR ASPECT RATIO MAX FACTOR CHAR ASPECT RATIO MIN FACTOR CHAR BASELINE CHAR HOMOGENEITY SCORE CHAR HOMOGENEITY ACCEPTANCE CHAR SCALE MAX FACTOR CHAR SCALE MIN FACTOR CHAR SIMILARITY SCORE CHAR SIMILARITY ACCEPTANCE SPACE WIDTH SPACE MAX CONSECUTIVE STRING SCORE STRING ACCEPTANCE STRING ANGLE STRING ANGLE STRING ANGLE DELTA NEG STRING ANGLE STRING ANGLE STRING ANGLE DELTA POS STRING ASPECT RATIO STRING ASPECT RATIO STRING ASPECT RATIO MAX FACTOR STRING ASPECT RATIO STRING ASPECT RATIO STRING ASPECT RATIO MIN FACTOR STRING SCALE STRING SCALE STRING SCALE MAX FACTOR STRING SCALE STRING SCALE STRING SCALE MIN FACTOR STRING SIZE MIN STRING SIZE MAX FONT INDEX() STRING SIZE MIN STRING SIZE MAX STRING SIZE STRING FORMATTED STRING SIZE FORMATTED STRING SPACE MAX CONSECUTIVE SPACE WIDTH SPACE WIDTH FORMATTED STRING QUARTER MAX CHAR WIDTH   DEFAULT CONTEXT GENERAL   ALL   ALL   STRING NUMBER DEFAULT  ALL ENCODING DEFAULT ASCII MINIMUM CONTRAST  DEFAULT SEARCH CHAR ANGLE DEFAULT DISABLE ENABLE SEARCH SKEW ANGLE DEFAULT DISABLE ENABLE SPACE CHARACTER  NONE DEFAULT SPEED DEFAULT MEDIUM STRING SEPARATOR  NONE DEFAULT TIMEOUT DEFAULT DISABLE  FONT ADD USER DEFINED DEFAULT FONT DELETE  ALL DEFAULT STRING ADD USER DEFINED DEFAULT STRING DELETE  ALL DEFAULT CHAR ACCEPTANCE DEFAULT  CHAR ASPECT RATIO MAX FACTOR DEFAULT  CHAR ASPECT RATIO MIN FACTOR DEFAULT  CHAR MAX BASELINE DEVIATION DEFAULT  CHAR HOMOGENEITY ACCEPTANCE DEFAULT  CHAR SCALE MAX FACTOR DEFAULT  CHAR SCALE MIN FACTOR DEFAULT  CHAR SIMILARITY ACCEPTANCE DEFAULT  FOREGROUND VALUE DEFAULT
                         FOREGROUND BLACK FOREGROUND WHITE FOREGROUND BLACK OR WHITE SPACE MAX CONSECUTIVE DEFAULT  STRING ACCEPTANCE DEFAULT  STRING ANGLE DEFAULT STRING ANGLE DELTA NEG DEFAULT  STRING ANGLE DELTA POS DEFAULT  STRING ASPECT RATIO DEFAULT  STRING ASPECT RATIO MAX FACTOR DEFAULT  STRING ASPECT RATIO MIN FACTOR DEFAULT  STRING SCALE DEFAULT  STRING SCALE MAX FACTOR DEFAULT  STRING SCALE MIN FACTOR DEFAULT  STRING SIZE MAX  INFINITE DEFAULT STRING SIZE MIN  DEFAULT DRAW BOX MARGIN X DEFAULT  DRAW BOX MARGIN Y DEFAULT  SPACE WIDTH DEFAULT  MIN CHAR WIDTH MEAN CHAR WIDTH MAX CHAR WIDTH QUARTER MAX CHAR WIDTH INFINITE


MstrDraw

See Also | Example | Availability | MstrControl | MstrEditFont
User Guide:
Steps to reading a string in an image
Creating and customizing the fonts
Retrieving results and annotation

Reference:
MgraAlloc
MstrAlloc
MstrAllocResult
MstrControl
MstrEditFont
MstrInquire
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Draw specific features of the String Reader context or String Reader results.
Syntax
void MstrDraw(
MIL_ID GraphContId,
MIL_ID ContextOrResultID,
MIL_ID DestImageId,
long Operation,
long Index,
void *CharList,
long ControlFlag
)
Description

This function draws specific features of the String Reader context or String Reader results in the destination image buffer.

After each drawing operation, the optimal image size that was needed for that operation is updated in M_DRAW_LAST_SIZE_X and M_DRAW_LAST_SIZE_Y (MstrInquire()). When M_NULL is passed as the destination image (DestImageId parameter), only these size constants are updated; that is, the drawing operation is not performed. This can be useful if, for example, you only want to get the optimal image buffer size for the drawing operation.

Parameters
GraphContId

Specifies the graphics context to use when drawing. The graphics context must have been previously allocated using MgraAlloc(). Set this parameter to M_DEFAULT to use the default graphics context.

ContextOrResultID

Specifies the String Reader context or String Reader result buffer from which to extract the features to draw. The String Reader context or result buffer must have been previously allocated on the system using MstrAlloc() or MstrAllocResult(), respectively.

DestImageId

Specifies the identifier of the destination image buffer in which to draw. The buffer can be any supported MIL image buffer or M_NULL. By drawing into its display's overlay buffer, you can also annotate an image non-destructively.

When this parameter is set to M_NULL, only the size constants are updated (M_DRAW_LAST_SIZE_X and M_DRAW_LAST_SIZE_Y with MstrInquire()); that is, the drawing operation is not performed.

Operation

Specifies the type of operation to perform.

The following Operation parameter value can only be set for a String Reader context.

Open Collapse Value Description
Open Collapse M_DRAW_CHAR

 Draws a character representation of the font in the destination image. Characters are drawn from left to right, and from top to bottom. Characters that fall outside the destination image are clipped.  Draws a character representation of the font in the destination image ...

 The characters are drawn according to their draw box margin, set with M_DRAW_BOX_MARGIN_X and M_DRAW_BOX_MARGIN_Y in MstrControl(). This margin will determine the amount of white space between each character that is drawn.

 The following Operation parameter values can only be set for a String Reader result buffer. Note that these values can be added together to draw multiple features at once.

  Open   Collapse  Value
Description

  Open   Collapse  M_DRAW_STRING

 Draws all the characters of the result(s) of the string(s) read. The characters of the string are drawn at the location read in the target with the correct angle, scale and aspect ratio.  Draws all the characters of the result(s) of the string(s) read ...

  Open   Collapse  M_DRAW_STRING_BOX

 Draws a box around the string that is read in the target. Note that the bounding box of the string is the bounding box of all the string's characters bounding box, including the draw margin (set with M_DRAW_BOX_MARGIN_X and M_DRAW_BOX_MARGIN_Y in MstrControl()).  Draws a box around the string that is read in the target ...

  Open   Collapse  M_DRAW_STRING_CHAR_BOX

 Draws all the character boxes of the result(s) of the string(s) read. The character boxes of the strings are drawn at the location read in the target with the correct angle, scale and aspect ratio. The character box drawn is the bounding box of the character plus the draw margin (set with M_DRAW_BOX_MARGIN_X and M_DRAW_BOX_MARGIN_Y in MstrControl()).  Draws all the character boxes of the result(s) of the string(s) read ...

  Open   Collapse  M_DRAW_STRING_CHAR_POSITION

 Draws a cross at the center of the bounding box of each string's character. Note that the angle, scale, and aspect ration of the character are taken into account.  Draws a cross at the center of the bounding box of each string's character ...

  Open   Collapse  M_DRAW_STRING_CONTOUR

 Draws the contour of all the characters of the result(s) of the string(s) read. The contour of the characters of the string are drawn at the location read in the target with the correct angle, scale and aspect ratio.  Draws the contour of all the characters of the result(s) of the string(s) read ...

 Index

 Specifies the index of the font feature or result feature to draw.

 Set this parameter to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Draws the default features for either fonts or results.  Draws the default features for either fonts or results ...

 For a String Reader context, the default value is the same as M_FONT_INDEX().

 For a String Reader result, the default value is the same as M_ALL.

  Open   Collapse  M_FONT_INDEX(
long FontIndex

          )

 Draws the features of a specific font or result.  Draws the features of a specific font or result ...

Parameters

FontIndex

 This parameter specifies the index of the font or result. Set this parameter to the following:

  Open   Collapse  Value
Description

  Open   Collapse  Value >= 0

 Specifies the index of the specific font or result.  Specifies the index of the specific font or result ...

  Open   Collapse  M_ALL

 Draws the features of either all fonts or all results.  Draws the features of either all fonts or all results.

 CharList

 Specifies an explicit list of valid characters to draw, at the specified position. This is an optional, null-terminated string.

 This parameter is not needed when drawing results and should be set to M_NULL.

 Characters will be drawn in the order given in the CharList parameter. To draw the characters on multiple lines, a space character must be inserted to separate the strings included in the null-terminated terminated string.

 The array of strings must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING). At preprocessing time, each character in an explicit character list must exist in at least one of the fonts of the constraint.

 ControlFlag

 Specifies where in the destination image buffer to draw.

 For a String Reader result, this parameter must be set to M_DEFAULT.

 For a String Reader context, set this parameter to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Draws features from the top-left corner of the destination image buffer.  Draws features from the top-left corner of the destination image buffer.

  Open   Collapse  M_ORIGINAL

 Draws characters offset from their original position in the definition image, for user-defined characters (set using M_USER_DEFINED in MstrEditFont()). Note that they are all offset to 0 for other types of characters (for example, TrueType).  Draws characters offset from their original position in the definition image, for user-defined characters (set using M_USER_DEFINED in MstrEditFont()) ...

 By drawing user-defined characters immediately after they are defined, you can ascertain where the characters are located in the definition image (for example, in the overlay on top of the definition image). For more information, refer to M_DEFINITION_OFFSET_X and M_DEFINITION_OFFSET_Y in MstrInquire().

DRAW LAST SIZE X DRAW LAST SIZE Y DRAW LAST SIZE X DRAW LAST SIZE Y DRAW BOX MARGIN X DRAW BOX MARGIN Y DRAW BOX MARGIN X DRAW BOX MARGIN Y DRAW BOX MARGIN X DRAW BOX MARGIN Y FONT INDEX() ALL ENCODING DEFAULT USER DEFINED DEFINITION OFFSET X DEFINITION OFFSET Y     DRAW CHAR DRAW STRING DRAW STRING BOX DRAW STRING CHAR BOX DRAW STRING CHAR POSITION DRAW STRING CONTOUR  ALL DEFAULT     DEFAULT ORIGINAL


MstrEditFont

See Also | Example | Availability | MstrDraw | MstrFree
User Guide:
Steps to reading a string in an image
Creating and customizing the fonts
Degrees of freedom
Global context settings

Reference:
MstrAlloc
MstrControl
MstrDraw
MstrRead
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Edit a specified font.
Syntax
void MstrEditFont(
MIL_ID ContextId,
long FontIndex,
long Operation,
long OperationMode,
long Param1,
void *Param2,
void *Param3
)
Description

This function allows you to edit a specified font. For example, you can add or remove a character from a font, as well as normalize a character in a font.

Parameters
ContextId

Specifies the String Reader context that contains the font to edit. The String Reader context must have been previously allocated on the required system using MstrAlloc().

FontIndex

Specifies the index of the font to edit.

Open Collapse Value Description
Open Collapse M_FONT_INDEX(
long FontIndex
)

Specifies that the edit settings will be applied to a font. Specifies that the edit settings will be applied to a font ...

Parameters
FontIndex

This parameter specifies the index of the font to edit. You can set this parameter to the following:

Open Collapse Value Description
Open Collapse Value >= 0

 Specifies the index of the individual font.  Specifies the index of the individual font ...

 Operation

 Specifies the operation to be performed.

See the Parameter associations section for possible values.

 OperationMode

 Specifies the mode of the operation.

See the Parameter associations section for possible values.

 Param1

 Specifies a value that is dependent on the operation and mode chosen.

See the Parameter associations section for possible values.

 Param2

 Specifies a value that is dependent on the operation and mode chosen.

See the Parameter associations section for possible values.

 Param3

 Specifies a value that is dependent on the operation and mode chosen.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the Operation, OperationMode, Param1, Param2, and Param3
         parameters are described below.

  Open   Collapse  Operation
Description

OperationMode

Param1

Param2

Param3

  Open   Collapse   M_CHAR_ADD

 Specifies that a character will be added to the font.  Specifies that a character will be added to the font ...

OperationMode

 M_SYSTEM_FONT

 Specifies that characters from a given system font (for example, TrueType and Postscript) will be added, at a specified size.

 M_USER_DEFINED

 Specifies that user-defined characters will be added from a given image to the specified font. This value can be used in combination with M_SINGLE. It can also be used in combination with either M_FOREGROUND_BLACK or M_FOREGROUND_WHITE; the default is a black foreground. For more information, see the combination constants tables below.

 The characters in the image are taken from left to right and from top to bottom and are associated to the corresponding characters given in the character list. Each character in the image must be entirely connected (except for the accentuated characters) and should not be merged with other characters or other image objects.

 It is best to provide a character definition image that is of good quality, and that ideally contains only the characters you want to add to the font (though this is not mandatory). If all the characters in the string you want to add cannot be found in the image, an error is returned. Even if the operation succeeds, you should draw the characters of the font to ensure that every character is defined as expected, using MstrDraw().

 Note that if a character you want to add already exists in the font, the new character will replace the old one. You cannot add a character that is smaller than 6x6 pixels.

Param1

 For M_SYSTEM_FONT, this parameter sets the size of the characters to add, in pixels. Note that you cannot add a character that is smaller than 6x6 pixels.

 For M_USER_DEFINED, this parameter sets the identifier of the image containing the characters to add. The characters to add in the image must all be approximately the same size.

Param2

 For M_SYSTEM_FONT, this parameter sets an optional null-terminated string for all the characters to add.

 For M_USER_DEFINED, this parameter sets a null-terminated string for all the characters to add (it is not optional). You can set this parameter to M_NULL to add the standard characters of the font (for example, A to Z, a to z, and 0 to 9).

 For both M_SYSTEM_FONT and M_USER_DEFINED, the string array must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING).

 For a multi-string definition image (for M_USER_DEFINED), the space character (ASCII 32) must be inserted to separate the strings included in this null-terminated string.

 You should use multi-strings when one (or more) of the following situations is encountered: the characters are not all on the same line, the contrast is clearly different between characters, there is clearly a horizontal space between the characters (for example, ABC DEF).

Param3

 For M_SYSTEM_FONT, this parameter sets a null-terminated string containing the TrueType file name.

 For M_USER_DEFINED, this parameter must be set to M_NULL.

  Open   Collapse   M_CHAR_BASELINE

 Specifies that the baseline of the characters in the font will be set.  Specifies that the baseline of the characters in the font will be set ...

OperationMode

 M_DEFAULT

 Specifies that the default baseline will be set.

 If you add a user-defined font (M_USER_DEFINED or M_USER_DEFINED + M_SINGLE), the baseline will be set to M_AUTO_COMPUTE, which automatically computes the baseline to an appropriate value, by default.

 If you add a system font (M_SYSTEM_FONT), the baseline will be taken from that font's file, by default.

 When using a font to read a string, the baseline of each character (that uses a baseline) is expected to be aligned together within a certain degree of tolerance (set using MstrControl() with M_CHAR_MAX_BASELINE_DEVIATION), otherwise it will not be read.

 The position of the baseline in a character is defined as a percentage of the height of the character. That is, 0 refers to the bottom of character, 100 refers to the top of the character, and 50 refers to the middle of character. For example, in "ABCD", you would typically set the baseline to 0 for all characters, while in "pobq", you would typically set the baseline to 0 for "ob" and approximately 25 for "pq".

Param1

 Sets the baseline value as a percentage of the character's height.

 You can set any value between -1000 and 1000. You can also set this parameter to M_NONE to have no baseline, or to M_AUTO_COMPUTE to automatically compute the baseline to an appropriate value.

Param2

 Sets an optional null-terminated string of all the characters for which you want to set a baseline. Note that the string array must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING).

 Set this parameter to M_NULL to set the baseline of all the characters in the font.

Param3

 Must be set to M_NULL.

  Open   Collapse   M_CHAR_DELETE

 Specifies that characters will be deleted from the font.  Specifies that characters will be deleted from the font ...

OperationMode

 M_DEFAULT

 Specifies that one character, multiple characters, or all characters will be deleted from the font.

Param1

 Must be set to M_DEFAULT.

Param2

 Sets an optional null-terminated string of all the characters to delete. Note that the string array must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING).

 Set this parameter to M_NULL to delete all the characters in the font.

Param3

 Must be set to M_NULL.

  Open   Collapse   M_CHAR_NORMALIZE

 Specifies that the characters of the font will be normalized by taking either the size-X or size-Y as the reference.  Specifies that the characters of the font will be normalized by taking either the size-X or size-Y as the reference ...

OperationMode

 M_SIZE_X

 Specifies that the characters of the font are normalized by taking the size-X as the reference. That is, all the specified characters will be uniformly scaled to a given size-X. Note that size-Y is adjusted to maintain the same aspect ratio.

 M_SIZE_Y

 Specifies that the characters of the font are normalized by taking the size-Y as the reference. That is, all the specified characters will be uniformly scaled to a given size-Y. Note that size-X is adjusted to maintain the same aspect ratio.

Param1

 For M_SIZE_X, this parameter sets the reference size-X, in pixels.

 For M_SIZE_Y, this parameter sets the reference size-Y, in pixels.

 The value set for either M_SIZE_X or M_SIZE_Y must be greater than or equal to 8.

Param2

 For either M_SIZE_X or M_SIZE_Y, this parameter sets an optional null-terminated string of all the characters to normalize. Note that the string array must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING).

 To normalize all the characters in the font, set this parameter to M_NULL.

Param3

 For both M_SIZE_X or M_SIZE_Y, this parameter must be set to M_NULL.

  Open   Collapse   M_CHAR_SORT

 Specifies that characters from the font will be sorted, according to their character values.  Specifies that characters from the font will be sorted, according to their character values ...

OperationMode

 M_ASCENDING

 Specifies that characters from the font will be sorted, according to their character values, in ascending order.

 M_DESCENDING

 Specifies that characters from the font will be sorted, according to their character values, in descending order.

Param1

 Must be set to M_DEFAULT.

Param2

 Sets an optional null-terminated string of all the characters to sort. Note that the string array must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING).

 Set this parameter to M_NULL to sort all the characters in the font.

Param3

 Must be set to M_NULL.

  Open   Collapse   M_CHAR_TYPE

 Specifies the type of the characters in the font that will be set.  Specifies the type of the characters in the font that will be set ...

OperationMode

 M_DEFAULT

 Specifies that the default character type will be set. By default, the character type is M_REGULAR, which you can set with the Param1 parameter.

 Note that a string is formed by a group of regular (M_REGULAR) characters that overlap in the Y-direction, with each other regular (M_REGULAR) characters of that group.

Param1

 Set a regular (M_REGULAR) character type. This is the default.

Param2

 Sets an optional null-terminated string for all the characters for which you want to set a type. Note that the string array must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING).

 Set this parameter to M_NULL to set all the character types in the font.

Param3

 Must be set to M_NULL.

      [Combination constants]

 To specify a single user-defined character to add (M_CHAR_ADD) to the font, the following value can be added to M_USER_DEFINED:

  Open   Collapse  Value
Description

  Open   Collapse  M_SINGLE

 Specifies that a single user-defined character will be added from a given image in the specified font. This value can be used in combination with either M_FOREGROUND_BLACK or M_FOREGROUND_WHITE; the default is a black foreground. For more information, see the Combination constants table below.  Specifies that a single user-defined character will be added from a given image in the specified font ...

 If you use M_USER_DEFINED + M_SINGLE, the whole image is taken as a single character. This allows you to define special characters, which are not necessarily connected. The image is associated to the character specified by the Param2 parameter.

 It is best to provide a character definition image that is of good quality. Note that if the character you want to add already exists in the font, the new character will replace the old one. You cannot add a character that is smaller than 6x6 pixels. By default, user-defined characters have no baseline.

 If you use M_USER_DEFINED + M_SINGLE, set the following parameters accordingly:

  • Param1: Sets the identifier of the image containing the character to add.
    •

  • Param2: Sets the pointer of the character to add. The character must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING).
    •

  • Param3: Must be set to M_NULL.
    •

      [Combination constants]

 To specify the foreground of the characters in the definition image when adding (M_CHAR_ADD) user-defined characters to a font, one of the values below can be added to either M_USER_DEFINED or M_USER_DEFINED + M_SINGLE.

 Note that when a font is defined, it has no foreground. When performing a read operation (MstrRead()), the foreground the font is read with is set using M_FOREGROUND_VALUE in MstrControl(). In this case (when adding user-defined characters to a font), you are setting the foreground for the font in the definition image.

  Open   Collapse  Value
Description

  Open   Collapse  M_FOREGROUND_BLACK

 Specifies that black is the foreground color, for the definition image.  Specifies that black is the foreground color, for the definition image ...

This is the default value.

  Open   Collapse  M_FOREGROUND_WHITE

 Specifies that white is the foreground color, for the definition image.  Specifies that white is the foreground color, for the definition image.

SINGLE FOREGROUND BLACK FOREGROUND WHITE SYSTEM FONT USER DEFINED SYSTEM FONT USER DEFINED SYSTEM FONT USER DEFINED ENCODING USER DEFINED SYSTEM FONT USER DEFINED USER DEFINED USER DEFINED SINGLE SYSTEM FONT CHAR MAX BASELINE DEVIATION ENCODING ENCODING SIZE X SIZE Y SIZE X SIZE Y SIZE X SIZE Y ENCODING SIZE X SIZE Y ENCODING ENCODING CHAR ADD USER DEFINED FOREGROUND BLACK FOREGROUND WHITE USER DEFINED SINGLE USER DEFINED SINGLE ENCODING CHAR ADD USER DEFINED USER DEFINED SINGLE FOREGROUND VALUE          CHAR ADD SYSTEM FONT USER DEFINED CHAR BASELINE DEFAULT CHAR DELETE DEFAULT CHAR NORMALIZE SIZE X SIZE Y CHAR TYPE DEFAULT CHAR SORT ASCENDING DESCENDING SINGLE FOREGROUND BLACK FOREGROUND WHITE


MstrFree

See Also | Example | Availability | MstrEditFont | MstrGetResult
User Guide:
Steps to reading a string in an image

Reference:
MstrAlloc
MstrAllocResult
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Free a String Reader context or a String Reader result buffer.
Syntax
void MstrFree(
MIL_ID ObjectId
)
Description

This function deletes the specified String Reader context or String Reader result buffer identifier, and releases any memory associated with it.

All String Reader contexts and all String Reader result buffers allocated on a particular system must be freed before the system can be freed.

Parameter
ObjectId

Specifies the identifier of the String Reader context or String Reader result buffer to free. These must have been successfully allocated (with MstrAlloc() or MstrAllocResult()) prior to calling this function.


MstrGetResult

See Also | Example | Availability | MstrFree | MstrInquire
User Guide:
Steps to reading a string in an image
Creating and customizing the fonts
Adding and deleting string models to the context
Number of strings to read
Degrees of freedom
Global context settings
Scores and acceptances
Retrieving results and annotation

Reference:
MstrControl
MstrFree
MstrRead
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Get the specified type of result(s) from a String Reader result buffer.
Syntax
void MstrGetResult(
MIL_ID ResultId,
long Index,
long ResultType,
void *ResultArrayPtr
)
Description

This function retrieves the result(s) of the specified type from a String Reader result buffer. Results are only available after calling MstrRead().

All positional results are relative to the center of the top-left pixel in the target.

Parameters
ResultId

Specifies the identifier of the String Reader result buffer from which to retrieve results.

Index

Specifies where to get results. This parameter can be set to one of the following:

Open Collapse Value Description
Open Collapse M_DEFAULT

Same as M_ALL.

  Open   Collapse  0 to M_STRING_NUMBER - 1

 Specifies the index of the string from which to get results.  Specifies the index of the string from which to get results.

  Open   Collapse  M_ALL

 Specifies that the results of all strings will be retrieved.  Specifies that the results of all strings will be retrieved ...

  Open   Collapse  M_GENERAL

 Specifies that the results relating to the entire String Reader context will be retrieved.  Specifies that the results relating to the entire String Reader context will be retrieved.

 ResultType

 Specifies the type of result to retrieve.

 When retrieving a general result (M_GENERAL), the ResultType parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                a
                  double.

  Open   Collapse  Value
Description

  Open   Collapse   M_CHAR_NUMBER

 Returns the total number of characters read (all strings together).  Returns the total number of characters read (all strings together).

  Open   Collapse   M_CONTEXT_ID

 Returns the identifier of the String Reader context used by MstrRead() to obtain the results in the result buffer. Note that this identifier might not be valid if the String Reader context has been freed using MstrFree().  Returns the identifier of the String Reader context used by MstrRead() to obtain the results in the result buffer ...

  Open   Collapse   M_STRING_NUMBER

 Returns the total number of strings read.  Returns the total number of strings read.

  Open   Collapse   M_TEXT

 Retrieves the entire text. This includes all string characters, the inserted space characters, the string separators, and the null-termination character.  Retrieves the entire text ...

 Strings are ordered in the natural Latin-based reading order. The string separator can be controlled using MstrControl() with M_STRING_SEPARATOR. The inserted space characters can be controlled using MstrControl() with M_SPACE_CHARACTER.

ResultArrayPtr info

Data type:

  • array of type char
    Array size:  This array must be of size M_TEXT_SIZE.
    note:  The default data type is either char or short, depending on the encoding scheme selected (see MstrControl() with M_ENCODING).
    •

  • array of type short
    Array size:  This array must be of size M_TEXT_SIZE.
    note:  The default data type is either char or short, depending on the encoding scheme selected (see MstrControl() with M_ENCODING).
    •

  Open   Collapse   M_TEXT_ALLOC_SIZE_BYTE

 Returns the number of bytes required to retrieve M_TEXT result(s). This includes all string characters, the inserted space characters, the string separators, the null-termination character, and takes the encoding bit size into account (MstrControl() with M_ENCODING). Note that the size returned is always the number of bytes, not the number of characters.  Returns the number of bytes required to retrieve M_TEXT result(s) ...

  Open   Collapse   M_TEXT_SIZE

 Returns the total number of characters in the text. This includes all strings characters, the inserted space characters, and the string separators. Note that this does not include the null-termination character. The string separator can be controlled using MstrControl() with M_STRING_SEPARATOR. The inserted space characters can be controlled using MstrControl() with M_SPACE_CHARACTER.  Returns the total number of characters in the text. This includes all strings characters, the inserted space characters, and the string separators. Note that this does not include the null-termination character. The string separator can be controlled using MstrControl() with M_STRING_SEPARATOR ...

  Open   Collapse   M_TIMEOUT_END

 Returns whether the timeout limit was reached. You can set the timeout limit using MstrControl() with M_TIMEOUT.  Returns whether the timeout limit was reached ...

ResultArrayPtr info

Return values:
M_FALSE | Specifies that the timeout limit has not been reached.
M_TRUE | Specifies that the timeout limit has been reached.

 When retrieving individual string results, the ResultType parameter can be set to one of the following values. Results can be retrieved for a specific string, or for all strings (M_ALL). Note that strings are ordered by their position in the image (increasing in order of M_STRING_POSITION_Y, then increasing in order of M_STRING_POSITION_X).

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                a
                    double (when retrieving a specific string)
                   or an
                    array of type double (when retrieving all results (M_ALL))
                   with a size of M_STRING_NUMBER.

  Open   Collapse  Value
Description

  Open   Collapse   M_CHAR_ANGLE

 Returns the angle of the characters in the string, in degrees. The angle is the same for all the characters in the string; different angles for individual characters within a string are not supported. The characters' angle is not necessarily equal to the string's angle.  Returns the angle of the characters in the string, in degrees. The angle is the same for all the characters in the string; different angles for individual characters within a string are not supported ...

 Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

  Open   Collapse   M_FORMATTED_STRING

 Returns the formatted string. This includes all strings characters, the inserted space characters and the null-termination character.  Returns the formatted string ...

 A space character is inserted in the formatted string each time the distance between 2 adjacent characters exceeds the space width, at the scale of the string read. The space width can be set using MstrControl() with M_SPACE_WIDTH. The inserted space character can be set using MstrControl() with M_SPACE_CHARACTER.

 Strings are ordered in the natural Latin-based reading order. The string separator can be controlled using MstrControl() with M_STRING_SEPARATOR.

ResultArrayPtr info

Data type:

  • array of type char
    Array size:  This array must be of size M_FORMATTED_STRING_SIZE.
    note:  The default data type is either char or short, depending on the encoding scheme selected (see MstrControl() with M_ENCODING).
    •

  • array of type short
    Array size:  This array must be of size M_FORMATTED_STRING_SIZE.
    note:  The default data type is either char or short, depending on the encoding scheme selected (see MstrControl() with M_ENCODING).
    •

  Open   Collapse   M_FORMATTED_STRING_SIZE

 Returns the number of characters in the formatted string. This includes string characters and the inserted space characters. This does not include the null-termination character.  Returns the number of characters in the formatted string ...

 A space character is inserted in the formatted string each time the distance between 2 adjacent characters exceeds the M_SPACE_WIDTH value, which you can set with MstrControl(). Note that the inserted space characters can be controlled using MstrControl() with M_SPACE_CHARACTER.

  Open   Collapse   M_SKEW_ANGLE

 Returns the angle of the characters' skew in the string, in degrees. The angle is the same for all the characters in the string; different angles for individual characters within a string are not supported.  Returns the angle of the characters' skew in the string, in degrees ...

 Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

  Open   Collapse   M_STRING

 Returns the null-terminated string found during the read operation. The string does not contain any space characters.  Returns the null-terminated string found during the read operation ...

M_STRING cannot be used to retrieve results for all strings (M_ALL).

 Refer to M_CHAR_VALUE to retrieve all characters of all strings without the null-termination separators. Refer to M_FORMATTED_STRING to retrieve all strings with their space characters and null-termination separators.

ResultArrayPtr info

Data type:

  • array of type char
    Array size:  This array must be of size M_STRING_ALLOC_SIZE_BYTE.
    note:  The default data type is either char or short, depending on the encoding scheme selected (see MstrControl() with M_ENCODING).
    •

  • array of type short
    Array size:  This array must be of size M_STRING_ALLOC_SIZE_BYTE.
    note:  The default data type is either char or short, depending on the encoding scheme selected (see MstrControl() with M_ENCODING).
    •

  Open   Collapse   M_STRING_ALLOC_SIZE_BYTE

 Returns the number of bytes required to retrieve M_STRING result(s). This includes the null-termination character, and takes the encoding bit size into account (MstrControl() with M_ENCODING). M_STRING_ALLOC_SIZE_BYTE is typically used when retrieving all results (M_ALL), and will return an array of string size byte (1 element for each string). Note that the size is always the number of bytes, not the number of characters.  Returns the number of bytes required to retrieve M_STRING result(s) ...

  Open   Collapse   M_STRING_ANGLE

 Returns the angle of the string, in degrees.  Returns the angle of the string, in degrees.

  Open   Collapse   M_STRING_ASPECT_RATIO

 Returns the aspect ratio of the string. The aspect ratio of the string is the median aspect ratio of all the characters in the string.  Returns the aspect ratio of the string ...

  Open   Collapse   M_STRING_CHAR_SCORE_MAX

 Returns the maximum character score of the string.  Returns the maximum character score of the string.

  Open   Collapse   M_STRING_CHAR_SCORE_MIN

 Returns the minimum character score of the string.  Returns the minimum character score of the string.

  Open   Collapse   M_STRING_MODEL_INDEX

 Returns the index of the string model read.  Returns the index of the string model read.

  Open   Collapse   M_STRING_POSITION_X

 Returns the X-position of the string. The position of the string is the position of its first character. For more information, see M_CHAR_POSITION_X.  Returns the X-position of the string. The position of the string is the position of its first character ...

  Open   Collapse   M_STRING_POSITION_Y

 Returns the Y-position of the string. The position of the string is the position of its first character. For more information, see M_CHAR_POSITION_Y.  Returns the Y-position of the string. The position of the string is the position of its first character ...

  Open   Collapse   M_STRING_SCALE

 Returns the scale of the string. The scale of the string is the median scale in the X-direction of all the characters in the string.  Returns the scale of the string ...

  Open   Collapse   M_STRING_SCORE

 Returns the string score calculated during the read operation for the entire string. The string score is the average score of the characters in the string.  Returns the string score calculated during the read operation for the entire string ...

  Open   Collapse   M_STRING_SIZE

 Returns the size of the string. This does not include the null-termination character. Space characters are not counted in the string size.  Returns the size of the string. This does not include the null-termination character ...

 When retrieving results for individual characters of a string, the ResultType parameter can be set to one of the following values. Results can be returned for characters of a specific string or for characters of all (M_ALL) strings. However, an array of results is always returned. Note that characters in the string are ordered by their index position in the string.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                an
                    array of type double (when retrieving a specific string)
                   with a size of  M_STRING_SIZE (of that specific string). or an
                    array of type double (when retrieving all strings (M_ALL))
                   with a size of M_CHAR_NUMBER..

  Open   Collapse  Value
Description

  Open   Collapse   M_CHAR_ASPECT_RATIO

 Returns the aspect ratio of the character. The aspect ratio of the character is the ratio of its scale in the X-direction and in the Y-direction.  Returns the aspect ratio of the character ...

  Open   Collapse   M_CHAR_CONSECUTIVE_SPACE

 Returns the number of consecutive spaces that can be inserted between this character and the following one in the string. For more information, refer to M_SPACE_WIDTH and M_SPACE_MAX_CONSECUTIVE in MstrControl().  Returns the number of consecutive spaces that can be inserted between this character and the following one in the string ...

  Open   Collapse   M_CHAR_FONT

 Returns the index of the font of each individual character within the string(s). The index returned is that of the character's font at the moment the MstrRead() operation was performed.  Returns the index of the font of each individual character within the string(s) ...

  Open   Collapse   M_CHAR_HOMOGENEITY_SCORE

 Returns the homogeneity score of each individual character within the string(s). The character's homogeneity score quantifies the similarity between the character in the target and the other characters of the string in the target.  Returns the homogeneity score of each individual character within the string(s) ...

  Open   Collapse   M_CHAR_INDEX

 Returns the index of the character in the font for each individual character within the string(s). The index returned is that of the index of the character in its font at the moment the MstrRead() operation was performed.  Returns the index of the character in the font for each individual character within the string(s) ...

  Open   Collapse   M_CHAR_POSITION_X

 Returns the X-position of the character. The position of a character is the position of the center of its bounding box.  Returns the X-position of the character ...

  Open   Collapse   M_CHAR_POSITION_Y

 Returns the Y-position of the character. The position of a character is the position of the center of its bounding box.  Returns the Y-position of the character ...

  Open   Collapse   M_CHAR_SCALE

 Returns the scale of the character. The scale of the character is its scale in the X-direction.  Returns the scale of the character ...

  Open   Collapse   M_CHAR_SCORE

 Returns the score of each individual character within the string(s). The character's score quantifies the similarity between the character in the target and the character in the font; it also quantifies the similarity between the character in the target and the other characters of the string in the target.  Returns the score of each individual character within the string(s) ...

  Open   Collapse   M_CHAR_SIMILARITY_SCORE

 Returns the similarity score of each individual character within the string(s). The character's similarity score quantifies the similarity between the character in the target and the character in the font.  Returns the similarity score of each individual character within the string(s) ...

  Open   Collapse   M_CHAR_VALUE

 Returns the value of each character read.  Returns the value of each character read ...

ResultArrayPtr info

Data type:

  • array of type char
    Array size:  This array must be of size M_STRING_SIZE (for one string) or M_CHAR_NUMBER (for all strings).
    note:  The default data type is either char or short, depending on the encoding scheme selected (see MstrControl() with M_ENCODING).
    •

  • array of type short
    Array size:  This array must be of size M_STRING_SIZE (for one string) or M_CHAR_NUMBER (for all strings).
    note:  The default data type is either char or short, depending on the encoding scheme selected (see MstrControl() with M_ENCODING).
    •

 When retrieving transformation coefficient results for individual characters of a string, the ResultType parameter can be set to one of the following values.

 Transformation coefficients allow you to transform any point from the character image to its found position in the target image (forward) or from the found position in the target image to the corresponding position in the character image (reverse). This is done using the following equations:

 xd = axs + bys
                + c

 yd= dxs + eys
                + f

 where a, b, c, d, e and f are the transformation coefficients (forward or reverse); x s and y s specify the source coordinates (character image for forward transformation or target image for reverse transformation); and, x d and y d specify the destination coordinates (target image for forward transformation or character image for reverse transformation).

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of
                an
                    array of type double (when retrieving a specific string)
                   with a size of  M_STRING_SIZE (of that specific string). or an
                    array of type double (when retrieving all strings (M_ALL))
                   with a size of M_CHAR_NUMBER..

Open Collapse Value | Description
Open Collapse M_A_FORWARD | Returns the forward transformation coefficient A. Returns the forward transformation coefficient A.
Open Collapse M_A_REVERSE | Returns the reverse transformation coefficient A. Returns the reverse transformation coefficient A.
Open Collapse M_B_FORWARD | Returns the forward transformation coefficient B. Returns the forward transformation coefficient B.
Open Collapse M_B_REVERSE | Returns the reverse transformation coefficient B. Returns the reverse transformation coefficient B.
Open Collapse M_C_FORWARD | Returns the forward transformation coefficient C. Returns the forward transformation coefficient C.
Open Collapse M_C_REVERSE | Returns the reverse transformation coefficient C. Returns the reverse transformation coefficient C.
Open Collapse M_D_FORWARD | Returns the forward transformation coefficient D. Returns the forward transformation coefficient D.
Open Collapse M_D_REVERSE | Returns the reverse transformation coefficient D. Returns the reverse transformation coefficient D.
Open Collapse M_E_FORWARD | Returns the forward transformation coefficient E. Returns the forward transformation coefficient E.
Open Collapse M_E_REVERSE | Returns the reverse transformation coefficient E. Returns the reverse transformation coefficient E.
Open Collapse M_F_FORWARD | Returns the forward transformation coefficient F. Returns the forward transformation coefficient F.
Open Collapse M_F_REVERSE | Returns the reverse transformation coefficient F. Returns the reverse transformation coefficient F.

      [Combination constants]

 The following values can be added to the ResultType parameter to determine whether a result is either available or supported.

  Open   Collapse  Value
Description

  Open   Collapse   M_AVAILABLE

 Returns whether a result is available for a general result, string model, or font.  Returns whether a result is available for a general result, string model, or font ...

ResultType info

Return values:
M_NULL | The result is not available to be retrieved.
Value <> 0 | The result is available to be retrieved.

  Open   Collapse   M_SUPPORTED

 Returns whether a result is supported for a general result, string model, or font.  Returns whether a result is supported for a general result, string model, or font ...

ResultType info

Return values:
M_NULL | The result is not supported.
Value <> 0 | The result is supported.

      [Combination constants]

 The following values can be added to the ResultType parameter to cast the requested results to a required data type.

  Open   Collapse  Value
Description

  Open   Collapse   M_TYPE_CHAR

 Casts the requested results to a char.  Casts the requested results to a char ...

ResultArrayPtr info

Data type:

  • char
    •

  • array of type char
    Array size:  Size depends on the contents of the array.
    •

  Open   Collapse   M_TYPE_DOUBLE

 Casts the requested results to a double.  Casts the requested results to a double ...

This is the default value.

ResultArrayPtr info

Data type:

  • double
    •

  • array of type double
    Array size:  Size depends on the contents of the array.
    •

  Open   Collapse   M_TYPE_FLOAT

 Casts the requested results to a float.  Casts the requested results to a float ...

ResultArrayPtr info

Data type:

  • float
    •

  • array of type float
    Array size:  Size depends on the contents of the array.
    •

  Open   Collapse   M_TYPE_LONG

 Casts the requested results to a long.  Casts the requested results to a long ...

ResultArrayPtr info

Data type:

  • long
    •

  • array of type long
    Array size:  Size depends on the contents of the array.
    •

  Open   Collapse   M_TYPE_MIL_ID

 Casts the requested results to a MIL_ID.  Casts the requested results to a MIL_ID ...

ResultArrayPtr info

Data type:

  • MIL_ID
    •

  • array of type MIL_ID
    Array size:  Size depends on the contents of the array.
    •

  Open   Collapse   M_TYPE_SHORT

 Casts the requested results to a short.  Casts the requested results to a short ...

ResultArrayPtr info

Data type:

  • short
    •

  • array of type short
    Array size:  Size depends on the contents of the array.
    •

  Open   Collapse   M_TYPE_TEXT_CHAR

 Casts the requested results to a MIL_TEXT_CHAR.  Casts the requested results to a MIL_TEXT_CHAR ...

ResultArrayPtr info

Data type:

  • MIL_TEXT_CHAR
    •

  • array of type MIL_TEXT_CHAR
    Array size:  Size depends on the contents of the array.
    •

 ResultArrayPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type char
    •

  • array of type double
    •

  • array of type float
    •

  • array of type long
    •

  • array of type short
    •

  • array of type MIL_ID
    •

  • array of type MIL_TEXT_CHAR
    •

  • char
    •

  • double
    •

  • float
    •

  • long
    •

  • short
    •

  • MIL_ID
    •

  • MIL_TEXT_CHAR
    •

 Specifies the address in which to write results.

GENERAL STRING SEPARATOR SPACE CHARACTER ENCODING TEXT SIZE ENCODING TEXT SIZE TEXT ENCODING STRING SEPARATOR SPACE CHARACTER TIMEOUT ALL ALL STRING POSITION Y STRING POSITION X SPACE WIDTH SPACE CHARACTER STRING SEPARATOR ENCODING FORMATTED STRING SIZE ENCODING FORMATTED STRING SIZE SPACE WIDTH SPACE CHARACTER STRING ALL CHAR VALUE FORMATTED STRING ENCODING STRING ALLOC SIZE BYTE ENCODING STRING ALLOC SIZE BYTE STRING ENCODING STRING ALLOC SIZE BYTE ALL CHAR POSITION X CHAR POSITION Y STRING SIZE ALL CHAR NUMBER ALL SPACE WIDTH SPACE MAX CONSECUTIVE ENCODING STRING SIZE CHAR NUMBER ENCODING STRING SIZE CHAR NUMBER STRING SIZE ALL CHAR NUMBER   DEFAULT STRING NUMBER - 1 ALL GENERAL  CHAR NUMBER CONTEXT ID STRING NUMBER TEXT TEXT ALLOC SIZE BYTE TEXT SIZE TIMEOUT END FORMATTED STRING FORMATTED STRING SIZE SKEW ANGLE STRING STRING ALLOC SIZE BYTE STRING ANGLE STRING ASPECT RATIO CHAR ANGLE STRING CHAR SCORE MIN STRING CHAR SCORE MAX STRING MODEL INDEX STRING SCALE STRING POSITION X STRING POSITION Y STRING SCORE STRING SIZE CHAR ASPECT RATIO CHAR CONSECUTIVE SPACE CHAR FONT CHAR HOMOGENEITY SCORE CHAR INDEX CHAR POSITION X CHAR POSITION Y CHAR SCALE CHAR SIMILARITY SCORE CHAR SCORE CHAR VALUE A FORWARD A REVERSE B FORWARD B REVERSE C FORWARD C REVERSE D FORWARD D REVERSE E FORWARD E REVERSE F FORWARD F REVERSE AVAILABLE SUPPORTED TYPE CHAR TYPE DOUBLE TYPE FLOAT TYPE LONG TYPE MIL ID TYPE SHORT TYPE TEXT CHAR


MstrInquire

See Also | Example | Availability | MstrGetResult | MstrPreprocess
User Guide:
Creating and customizing the fonts
Space
Number of strings to read
Degrees of freedom
Rules for character placement
Global context settings
Retrieving results and annotation

Reference:
MstrAlloc
MstrAllocResult
MstrControl
MstrDraw
MstrEditFont
MstrPreprocess
MstrRead
There are no examples containing MstrInquire().
Not available in MIL-Lite

Available in MIL
Synopsis
Inquire information about a specified String Reader context, string model, font, or result buffer.
Syntax
void MstrInquire(
MIL_ID ContextOrResultId,
long Index,
long InquireType,
void *UserVarPtr
)
Description

This function inquires information about a String Reader context, the string models or fonts contained therein, or a String Reader result buffer.

If the inquired setting is set to M_DEFAULT, MstrInquire() will return M_DEFAULT, rather than the actual default value. To inquire the setting's default value, add M_DEFAULT to the inquire type.

Parameters
ContextOrResultId

Specifies the String Reader context or String Reader result buffer about which to inquire information. The String Reader context or result buffer must have been previously allocated on the required system using MstrAlloc() or MstrAllocResult(), respectively.

Index

Specifies that information will be inquired about the String Reader context, a specific font, a specific string model, or a String Reader result buffer. Set this parameter to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default value.  Specifies the default value ...

 For a String Reader context, the default value is the same as M_CONTEXT.

 For a String Reader result, the default value is the same as M_GENERAL.

  Open   Collapse  M_FONT_INDEX(
long FontIndex

          )

 Inquires information about a font. This value is only applicable for a String Reader context.  Inquires information about a font ...

Parameters

FontIndex

 This parameter specifies the index of the font. You can set this parameter to the following:

  Open   Collapse  Value
Description

  Open   Collapse  Value >= 0

 Specifies the index of the individual font you want to inquire about.  Specifies the index of the individual font you want to inquire about ...

  Open   Collapse  M_STRING_INDEX(
long StringIndex

          )

 Inquires information about a string. This value is only applicable for a String Reader context.  Inquires information about a string ...

Parameters

StringIndex

 This parameter specifies the index of the string. You can set this parameter to the following:

  Open   Collapse  Value
Description

  Open   Collapse  Value >= 0

 Specifies the index of the individual string you want to inquire about.  Specifies the index of the individual string you want to inquire about ...

  Open   Collapse  M_CONTEXT

 Inquires information about a general setting of a String Reader context. This value is only applicable for a String Reader context.  Inquires information about a general setting of a String Reader context ...

  Open   Collapse  M_GENERAL

 Inquires information about a general setting of a String Reader result buffer. This value is only applicable for a String Reader result.  Inquires information about a general setting of a String Reader result buffer ...

 InquireType

 Specifies the type of setting about which to inquire.

 For a String Reader context (M_CONTEXT), or a specific string in the String Reader context (M_STRING_INDEX()), the InquireType parameter can be set to the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

Open Collapse Value | Description
Open Collapse M_STRING_NUMBER | Returns either the maximum (total) number of all strings that can be read with a String Reader context (M_CONTEXT), or the maximum number of a specific string (M_STRING_INDEX()) that can be read with a String Reader context. Returns either the maximum (total) number of all strings that can be read with a String Reader context (M_CONTEXT), or the maximum number of a specific string (M_STRING_INDEX()) that can be read with a String Reader context ...
 |  | UserVarPtr info Return values: M_ALL, M_DEFAULT, Value (details)

 For a String Reader context (M_CONTEXT), the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

  Open   Collapse  Value
Description

  Open   Collapse   M_CONTEXT_TYPE

 Returns the type of search context allocated.  Returns the type of search context allocated ...

UserVarPtr info

Return values:
M_FEATURE_BASED (details)

  Open   Collapse   M_DRAW_LAST_SIZE_X

 Returns the last size-X of the image buffer needed by the last call to MstrDraw(). This allows you to allocate a buffer of optimal size, for the required drawing operation.  Returns the last size-X of the image buffer needed by the last call to MstrDraw() ...

 Note that when you call MstrDraw() for the first time, you can pass M_NULL as the destination image to get the size needed for the required drawing operation. For more information, see MstrDraw().

  Open   Collapse   M_DRAW_LAST_SIZE_Y

 Returns the last size-Y of the image buffer needed by the last call to MstrDraw(). This allows you to allocate a buffer of optimal size, for the required drawing operation.  Returns the last size-Y of the image buffer needed by the last call to MstrDraw() ...

 Note that when you call MstrDraw() for the first time, you can pass M_NULL as the destination image to get the size needed for the required drawing operation. For more information, see MstrDraw().

  Open   Collapse   M_ENCODING

 Returns the type of character encoding used by the String Reader context.  Returns the type of character encoding used by the String Reader context ...

UserVarPtr info

Return values:
M_ASCII, M_DEFAULT (details)

  Open   Collapse   M_MINIMUM_CONTRAST

 Returns the minimum contrast between a character in the target image and its background, in order for the character to be read by MstrRead().  Returns the minimum contrast between a character in the target image and its background, in order for the character to be read by MstrRead() ...

UserVarPtr info

Return values:
1 to 255, M_DEFAULT (details)

  Open   Collapse   M_MODIFICATION_COUNT

 Returns the current value of the modification counter. The modification counter is increased by one each time settings for the context are modified. The modification counter is initialized to a number that is unique to the String Reader context and is given its own unique range. If the context is freed, this number will not be reassigned to a new context.  Returns the current value of the modification counter. The modification counter is increased by one each time settings for the context are modified ...

 This feature can be useful when designing your application. For example, if the modification counter has changed, you can prompt the user to save before closing the application.

  Open   Collapse   M_NUMBER_OF_FONTS

 Returns the number of fonts in the context.  Returns the number of fonts in the context.

  Open   Collapse   M_NUMBER_OF_STRING_MODELS

 Returns the number of string models in the context.  Returns the number of string models in the context.

  Open   Collapse   M_OWNER_SYSTEM

 Returns the identifier of the system on which the context was allocated.  Returns the identifier of the system on which the context was allocated.

  Open   Collapse   M_PREPROCESSED

 Returns whether the String Reader context is preprocessed. This will indicate whether preprocessing (using MstrPreprocess()) is needed to prepare the context for use.  Returns whether the String Reader context is preprocessed ...

UserVarPtr info

Return values:
Value != 0 | The context is preprocessed; you should not preprocess again.
0 | The context is not preprocessed; you should preprocess again.

  Open   Collapse   M_SEARCH_CHAR_ANGLE

 Returns whether strategies specific to angular-range will be calculated.  Returns whether strategies specific to angular-range will be calculated ...

 Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_SEARCH_SKEW_ANGLE

 Returns whether strategies specific to angular-range skew will be calculated.  Returns whether strategies specific to angular-range skew will be calculated ...

 Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_SPACE_CHARACTER

 Returns the character value to use as a space character within the formatted text that will be read.  Returns the character value to use as a space character within the formatted text that will be read ...

UserVarPtr info

Return values:
M_DEFAULT, M_NONE, Value (details)

  Open   Collapse   M_SPEED

 Returns the search/read speed.  Returns the search/read speed ...

UserVarPtr info

Return values:
M_DEFAULT, M_MEDIUM (details)

  Open   Collapse   M_STRING_SEPARATOR

 Returns the character value to use as a string separator within the formatted text that will be read.  Returns the character value to use as a string separator within the formatted text that will be read ...

UserVarPtr info

Return values:
M_DEFAULT, M_NONE, Value (details)

  Open   Collapse   M_TIMEOUT

 Returns the maximum read time for MstrRead(), in msec.  Returns the maximum read time for MstrRead(), in msec ...

UserVarPtr info

Return values:
M_DEFAULT, M_DISABLE, Value > = 0 (details)

 For a specific string (M_STRING_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

Open Collapse Value | Description
Open Collapse M_CHAR_ACCEPTANCE | Returns the acceptance level for the character score. Returns the acceptance level for the character score ...
 |  | UserVarPtr info Return values: 0.0 to 100.0, M_DEFAULT (details)
Open Collapse M_CHAR_ASPECT_RATIO_MAX_FACTOR | Returns the factor used to determine the upper limit of the aspect ratio for the characters in the string. Returns the factor used to determine the upper limit of the aspect ratio for the characters in the string ...
 |  | UserVarPtr info Return values: 1.0 to 2.0, M_DEFAULT (details)
Open Collapse M_CHAR_ASPECT_RATIO_MIN_FACTOR | Returns the factor used to determine the lower limit of the aspect ratio for the characters in the string. Returns the factor used to determine the lower limit of the aspect ratio for the characters in the string ...
 |  | UserVarPtr info Return values: 0.5 to 1.0, M_DEFAULT (details)
Open Collapse M_CHAR_HOMOGENEITY_ACCEPTANCE | Returns the acceptance level for the character's homogeneity score. Returns the acceptance level for the character's homogeneity score ...
 |  | UserVarPtr info Return values: 0.0 to 100.0, M_DEFAULT (details)
Open Collapse M_CHAR_MAX_BASELINE_DEVIATION | Returns the maximum deviation that a character can have from the string's baseline. Returns the maximum deviation that a character can have from the string's baseline ...
 |  | UserVarPtr info Return values: 0 to 100, M_DEFAULT (details)
Open Collapse M_CHAR_SCALE_MAX_FACTOR | Returns the factor used to determine the upper limit (maximum permitted scale) of the scale range for the characters in the string. Returns the factor used to determine the upper limit (maximum permitted scale) of the scale range for the characters in the string ...
 |  | UserVarPtr info Return values: 1.0 to 2.0, M_DEFAULT (details)
Open Collapse M_CHAR_SCALE_MIN_FACTOR | Returns the factor used to determine the lower limit (minimum permitted scale) of the scale range for the characters in the string. Returns the factor used to determine the lower limit (minimum permitted scale) of the scale range for the characters in the string ...
 |  | UserVarPtr info Return values: 0.5 to 1.0, M_DEFAULT (details)
Open Collapse M_CHAR_SIMILARITY_ACCEPTANCE | Returns the acceptance level for the character's similarity score. Returns the acceptance level for the character's similarity score ...
 |  | UserVarPtr info Return values: 0.0 to 100.0, M_DEFAULT (details)
Open Collapse M_DEFAULT_CONSTRAINT_FONT | Returns the default valid font index. Returns the default valid font index ... This information can also be inquired using MstrInquire() with M_DEFAULT_CONSTRAINT_TYPE; however, it is encoded with other constant values (the one that was applied by default to all characters of the string model when no explicit constraint has been set to a specific position or if M_DEFAULT has been set to a specific position). M_DEFAULT_CONSTRAINT_FONT always returns a single value.
Open Collapse M_DEFAULT_CONSTRAINT_TYPE | Returns the default constraint type. Returns the default constraint type ... Returns the default constraint type (the one that was applied by default to all characters of the string model when no explicit constraint has been set to a specific position or if M_DEFAULT has been set to a specific position). M_DEFAULT_CONSTRAINT_TYPE always returns a single value.
Open Collapse M_FOREGROUND_VALUE | Returns the foreground color of the string. Returns the foreground color of the string ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_FOREGROUND_BLACK, M_FOREGROUND_BLACK_OR_WHITE, M_FOREGROUND_WHITE (details)
Open Collapse M_NUMBER_OF_CONSTRAINTS | Returns the number of constraints (set in MstrControl()) that have been set to a value other than M_DEFAULT (non-default constraints). Returns the number of constraints (set in MstrControl()) that have been set to a value other than M_DEFAULT (non-default constraints).
Open Collapse M_SPACE_MAX_CONSECUTIVE | Returns the maximum number of consecutive space characters allowed in the string. Returns the maximum number of consecutive space characters allowed in the string ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value > = 0 (details)
Open Collapse M_STRING_ACCEPTANCE | Returns the acceptance level for the string score. Returns the acceptance level for the string score ...
 |  | UserVarPtr info Return values: 0.0 to 100.0, M_DEFAULT (details)
Open Collapse M_STRING_ANGLE | Returns the nominal angle of the string. Returns the nominal angle of the string ...
 |  | UserVarPtr info Return values: M_DEFAULT (details)
Open Collapse M_STRING_ANGLE_DELTA_NEG | Returns the lower limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE). Returns the lower limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE) ...
 |  | UserVarPtr info Return values: 0.0 to 10.0, M_DEFAULT (details)
Open Collapse M_STRING_ANGLE_DELTA_POS | Returns the upper limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE). Returns the upper limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE) ...
 |  | UserVarPtr info Return values: 0.0 to 10.0, M_DEFAULT (details)
Open Collapse M_STRING_ASPECT_RATIO | Returns the nominal aspect ratio of the string. Returns the nominal aspect ratio of the string ...
 |  | UserVarPtr info Return values: 0.5 to 2.0, M_DEFAULT (details)
Open Collapse M_STRING_ASPECT_RATIO_MAX_FACTOR | Returns the factor used to determine the upper limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl() with M_STRING_ASPECT_RATIO). Returns the factor used to determine the upper limit of the string's aspect ratio ...
 |  | UserVarPtr info Return values: 1.0 to 2.0, M_DEFAULT (details)
Open Collapse M_STRING_ASPECT_RATIO_MIN_FACTOR | Returns the factor used to determine the lower limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl() with M_STRING_ASPECT_RATIO). Returns the factor used to determine the lower limit of the string's aspect ratio ...
 |  | UserVarPtr info Return values: 0.5 to 1.0, M_DEFAULT (details)
Open Collapse M_STRING_SCALE | Returns the nominal scale of the string. Returns the nominal scale of the string ...
 |  | UserVarPtr info Return values: 0.25 to 4.0, M_DEFAULT (details)
Open Collapse M_STRING_SCALE_MAX_FACTOR | Returns the factor used to determine the upper limit (maximum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl() with M_STRING_SCALE). Returns the factor used to determine the upper limit (maximum permitted scale) of the string's scale range ...
 |  | UserVarPtr info Return values: 1.0 to 2.0, M_DEFAULT (details)
Open Collapse M_STRING_SCALE_MIN_FACTOR | Returns the factor used to determine the lower limit (minimum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl() with M_STRING_SCALE). Returns the factor used to determine the lower limit (minimum permitted scale) of the string's scale range ...
 |  | UserVarPtr info Return values: 0.5 to 1.0, M_DEFAULT (details)
Open Collapse M_STRING_SIZE_MAX | Returns the maximum string size (number of characters) of the string model. Returns the maximum string size (number of characters) of the string model ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_INFINITE, Value > = 1 (details)
Open Collapse M_STRING_SIZE_MIN | Returns the minimum string size (number of characters) of the string model. Returns the minimum string size (number of characters) of the string model ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value > = 1 (details)
Open Collapse M_STRING_TYPE | Returns the type of the string model added. Returns the type of the string model added ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_USER_DEFINED (details)

 For a specific string (M_STRING_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                an
                  array of type double (with a size of M_NUMBER_OF_CONSTRAINTS results.)
                .

  Open   Collapse  Value
Description

  Open   Collapse   M_CONSTRAINT

 Returns the constraint string at the specified index. To specify the index, see the combination value below.  Returns the constraint string at the specified index ...

 Unless M_TYPE_LONG or M_TYPE_DOUBLE is explicitly added to M_CONSTRAINT, the string array must be of the right type for the encoding scheme selected (MstrInquire() with M_ENCODING). The string returned includes the terminating 0 character.

UserVarPtr info

Data type:
                  array of type double

            Array size: M_CONSTRAINT_ALLOC_SIZE characters.

  Open   Collapse   M_CONSTRAINT_ALLOC_SIZE

 Returns an array containing the allocation size needed for each non-default constraint string. The allocation size of the constraint string includes the terminating 0 of the string.  Returns an array containing the allocation size needed for each non-default constraint string ...

  Open   Collapse   M_CONSTRAINT_FONT

 Returns an array containing the valid font index of each non-default constraint in the string model. This information can also be found using MstrInquire() with M_CONSTRAINT_TYPE, but it is encoded with other values. You can inquire the position in the string model that this constraint is applied to using MstrInquire() with M_CONSTRAINT_POSITION.  Returns an array containing the valid font index of each non-default constraint in the string model ...

  Open   Collapse   M_CONSTRAINT_POSITION

 Returns an array containing the position of each non-default constraint in the string model (0, 255). The default constraint is therefore applied to all positions not returned in this array.  Returns an array containing the position of each non-default constraint in the string model (0, 255) ...

  Open   Collapse   M_CONSTRAINT_TYPE

 Returns an array containing the type of each non-default constraint in the string model (for example, M_LETTER, M_DIGIT). You can inquire the position in the string model that this constraint is applied to using MstrInquire() with M_CONSTRAINT_POSITION.  Returns an array containing the type of each non-default constraint in the string model (for example, M_LETTER, M_DIGIT) ...

  Open   Collapse   M_DEFAULT_CONSTRAINT

 Returns the default constraint string (the one that was applied by default to all characters of the string model when no explicit constraint has been set to a specific position or if M_DEFAULT has been set to a specific position).  Returns the default constraint string (the one that was applied by default to all characters of the string model when no explicit constraint has been set to a specific position or if M_DEFAULT has been set to a specific position) ...

 The string array must be large enough to contain M_DEFAULT_CONSTRAINT_ALLOC_SIZE characters. Unless M_TYPE_LONG or M_TYPE_DOUBLE is explicitly added to M_DEFAULT_CONSTRAINT, the string array must be of the right type for the encoding scheme selected (MstrInquire() with M_ENCODING). The string returned includes the terminating 0 character.

UserVarPtr info

Data type:
                  array of type double

            Array size: M_DEFAULT_CONSTRAINT_ALLOC_SIZE characters.

  Open   Collapse   M_DEFAULT_CONSTRAINT_ALLOC_SIZE

 Returns the allocation size needed to get the default constraint string. The allocation size includes the terminating 0 of the default string. M_DEFAULT_CONSTRAINT_ALLOC_SIZE always returns a single value.  Returns the allocation size needed to get the default constraint string. The allocation size includes the terminating 0 of the default string ...

UserVarPtr info

Data type:
                  double

 For a specific font (M_FONT_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  double.

Open Collapse Value | Description
Open Collapse M_DRAW_BOX_MARGIN_X | Returns the margin in the X-direction, between the character box and the drawing box. Returns the margin in the X-direction, between the character box and the drawing box ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value > = 0 (details)
Open Collapse M_DRAW_BOX_MARGIN_Y | Returns the margin in the Y-direction, between the character box and the drawing box. Returns the margin in the Y-direction, between the character box and the drawing box ...
 |  | UserVarPtr info Return values: M_DEFAULT, Value > = 0 (details)
Open Collapse M_FONT_TYPE | Returns the type of font added. Returns the type of font added ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_USER_DEFINED (details)
Open Collapse M_NUMBER_OF_CHARS | Returns number of characters in the font. Returns number of characters in the font.
Open Collapse M_SPACE_WIDTH | Returns the width of the space character of the font. Returns the width of the space character of the font ...
 |  | UserVarPtr info Return values: M_DEFAULT, M_INFINITE, M_MAX_CHAR_WIDTH, M_MEAN_CHAR_WIDTH, M_MIN_CHAR_WIDTH, M_QUARTER_MAX_CHAR_WIDTH, Value > = 1 (details)
Open Collapse M_SPACE_WIDTH_VALUE | Returns the actual width value of the space character of the font, in pixels. Returns the actual width value of the space character of the font, in pixels ... Note that this constant is only available if you have MIL 8.0 with Processing Pack 1 installed.

 For a specific font (M_FONT_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                an
                  array of type double (with a size of M_NUMBER_OF_CHARS results.)
                .

Open Collapse Value | Description
Open Collapse M_CHAR_BASELINE | Returns an array containing the baseline value for each character. For more information, see MstrEditFont(). Returns an array containing the baseline value for each character ...
Open Collapse M_CHAR_SIZE_X | Returns an array containing the size-X of each character in the font. Returns an array containing the size-X of each character in the font.
Open Collapse M_CHAR_SIZE_Y | Returns an array containing the size-Y of each character in the font. Returns an array containing the size-Y of each character in the font.
Open Collapse M_CHAR_THICKNESS | Returns an array containing the average thickness of each character in the font. Returns an array containing the average thickness of each character in the font.
Open Collapse M_CHAR_TYPE | Returns an array containing the type of each character in the font. The type of a character can only be M_REGULAR. For more information, see M_CHAR_TYPE in MstrEditFont(). Returns an array containing the type of each character in the font. The type of a character can only be M_REGULAR ...
Open Collapse M_CHAR_VALUE | Returns an array containing the character value for each character. Unless M_TYPE_LONG or M_TYPE_DOUBLE is explicitly added to M_CHAR_VALUE, the string array must be of the right type for the encoding scheme selected (MstrInquire() with M_ENCODING). Returns an array containing the character value for each character ...
Open Collapse M_DEFINITION_OFFSET_X | Returns an array containing the offset-X definition of each character in the font. The offset-X definition is the offset of the character in the character definition image for user defined characters (MstrControl() with M_USER_DEFINED). It is M_NONE for a system font (MstrEditFont() with M_SYSTEM_FONT). Returns an array containing the offset-X definition of each character in the font. The offset-X definition is the offset of the character in the character definition image for user defined characters (MstrControl() with M_USER_DEFINED) ...
Open Collapse M_DEFINITION_OFFSET_Y | Returns an array containing the offset-Y definition of each character in the font. The offset-Y definition is the offset of the character in the character definition image for user defined characters (MstrControl() with M_USER_DEFINED). It is M_NONE for a system font (MstrEditFont() with M_SYSTEM_FONT). Returns an array containing the offset-Y definition of each character in the font. The offset-Y definition is the offset of the character in the character definition image for user defined characters (MstrControl() with M_USER_DEFINED) ...

      [Combination constants]

 The following value must be added to M_CONSTRAINT to specify the index.

  Open   Collapse  Value
Description

  Open   Collapse   0 to (M_NUMBER_OF_CONSTRAINTS - 1)

 Returns the constraint string at the specified index.  Returns the constraint string at the specified index ...

 The index you provide is the index of the constraint in the list of non-default constraints, and not its actual position in the string model. You can inquire the position in the string model that this constraint string applies to by using MstrInquire() with M_CONSTRAINT_POSITION.

UserVarPtr info

Data type:
                  array of type double

            Array size: M_CONSTRAINT_ALLOC_SIZE characters.

      [Combination constants]

 To inquire the default value of an inquire type, add the value below to the specified type.

Open Collapse Value | Description
Open Collapse M_DEFAULT | Returns the actual default value of the specified inquire type. Returns the actual default value of the specified inquire type ...
 |  | UserVarPtr info Data type: double

      [Combination constants]

 To inquire if an inquire type is supported, add the value below to the specified inquire type.

  Open   Collapse  Value
Description

  Open   Collapse   M_SUPPORTED

 Returns whether the specified inquire type is supported for the String Reader context.  Returns whether the specified inquire type is supported for the String Reader context ...

UserVarPtr info

Data type:
                  double

Return values:
M_NULL | Inquire type is not supported.
Value | Inquire type is supported.

      [Combination constants]

 The values below can be added to the InquireType parameter to cast the requested information to a required data type.

  Open   Collapse  Value
Description

  Open   Collapse   M_TYPE_DOUBLE

 Casts the requested information to a double.  Casts the requested information to a double ...

This is the default value.

UserVarPtr info

Data type:

  • double
    •

  • array of type double
    Array size:  Size depends on the contents of the array
    •

  Open   Collapse   M_TYPE_LONG

 Casts the requested information to a long.  Casts the requested information to a long ...

UserVarPtr info

Data type:

  • long
    •

  • array of type long
    Array size:  Size depends on the contents of the array
    •

  Open   Collapse   M_TYPE_MIL_ID

 Casts the requested information to a MIL_ID. Note that M_TYPE_MIL_ID should only be used with M_OWNER_SYSTEM.  Casts the requested information to a MIL_ID ...

UserVarPtr info

Data type:

  • MIL_ID
    •

  • array of type MIL_ID
    Array size:  Size depends on the contents of the array
    •

 UserVarPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type double
    •

  • array of type long
    •

  • array of type MIL_ID
    •

  • double
    •

  • long
    •

  • MIL_ID
    •

 Specifies the address in which to write the requested information.  Since the MstrInquire() function also returns the requested information, you can set this parameter to M_NULL (for non-array results only).

CONTEXT GENERAL CONTEXT STRING INDEX() CONTEXT STRING INDEX() CONTEXT STRING INDEX() DEFAULT CONSTRAINT TYPE DEFAULT CONSTRAINT FONT DEFAULT CONSTRAINT TYPE STRING ANGLE STRING ANGLE STRING ASPECT RATIO STRING ASPECT RATIO STRING SCALE STRING SCALE NUMBER OF CONSTRAINTS STRING INDEX() TYPE LONG TYPE DOUBLE CONSTRAINT ENCODING CONSTRAINT ALLOC SIZE CONSTRAINT TYPE CONSTRAINT POSITION CONSTRAINT POSITION DEFAULT CONSTRAINT ALLOC SIZE TYPE LONG TYPE DOUBLE DEFAULT CONSTRAINT ENCODING DEFAULT CONSTRAINT ALLOC SIZE DEFAULT CONSTRAINT ALLOC SIZE FONT INDEX() NUMBER OF CHARS FONT INDEX() CHAR TYPE TYPE LONG TYPE DOUBLE CHAR VALUE ENCODING USER DEFINED SYSTEM FONT USER DEFINED SYSTEM FONT CONSTRAINT CONSTRAINT POSITION CONSTRAINT ALLOC SIZE TYPE MIL ID OWNER SYSTEM   DEFAULT CONTEXT GENERAL      STRING NUMBER CONTEXT TYPE DRAW LAST SIZE X DRAW LAST SIZE Y ENCODING MINIMUM CONTRAST MODIFICATION COUNT NUMBER OF FONTS NUMBER OF STRING MODELS OWNER SYSTEM PREPROCESSED SEARCH CHAR ANGLE SEARCH SKEW ANGLE SPACE CHARACTER SPEED STRING SEPARATOR TIMEOUT CHAR ACCEPTANCE CHAR ASPECT RATIO MAX FACTOR CHAR ASPECT RATIO MIN FACTOR CHAR HOMOGENEITY ACCEPTANCE CHAR MAX BASELINE DEVIATION CHAR SCALE MAX FACTOR CHAR SCALE MIN FACTOR CHAR SIMILARITY ACCEPTANCE DEFAULT CONSTRAINT FONT DEFAULT CONSTRAINT TYPE FOREGROUND VALUE NUMBER OF CONSTRAINTS SPACE MAX CONSECUTIVE STRING ACCEPTANCE STRING ANGLE STRING ANGLE DELTA NEG STRING ANGLE DELTA POS STRING ASPECT RATIO STRING ASPECT RATIO MAX FACTOR STRING ASPECT RATIO MIN FACTOR STRING SCALE STRING SCALE MAX FACTOR STRING SCALE MIN FACTOR STRING SIZE MAX STRING SIZE MIN STRING TYPE CONSTRAINT CONSTRAINT ALLOC SIZE CONSTRAINT FONT CONSTRAINT POSITION CONSTRAINT TYPE DEFAULT CONSTRAINT DEFAULT CONSTRAINT ALLOC SIZE DRAW BOX MARGIN X DRAW BOX MARGIN Y FONT TYPE NUMBER OF CHARS SPACE WIDTH SPACE WIDTH VALUE CHAR BASELINE CHAR SIZE X CHAR SIZE Y CHAR THICKNESS CHAR TYPE CHAR VALUE DEFINITION OFFSET X DEFINITION OFFSET Y NUMBER OF CONSTRAINTS - 1) DEFAULT SUPPORTED TYPE DOUBLE TYPE LONG TYPE MIL ID


MstrPreprocess

See Also | Example | Availability | MstrInquire | MstrRead
User Guide:
Steps to reading a string in an image
Degrees of freedom
Retrieving results and annotation

Reference:
MstrAlloc
MstrInquire
MstrRead
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Preprocess a String Reader context.
Syntax
void MstrPreprocess(
MIL_ID ContextId,
long ControlFlag
)
Description

This function prepares the specified String Reader context, font, and string model to be read. Essentially, MstrPreprocess() trains the system to read a string in the most efficient manner.

This function must be called before the first call to MstrRead(). Changes to control settings, the String Reader context, one of its font or string models often require you to re-preprocess the context. To inquire if you need to preprocess or re-preprocess the context, use MstrInquire() with M_PREPROCESSED.

Note that in a typical application, MstrPreprocess() is called once. Also note that, to preprocess a String Reader context without an error, the context must have at least one font, one character, and one string.

When you save the String Reader context, the preprocessing changes are not saved. Upon restoration, you must preprocess the context again.

Parameters
ContextId

Specifies the String Reader context to preprocess. The String Reader context must have been previously allocated on the system using MstrAlloc().

ControlFlag

Specifies whether to preprocess the String Reader context. Set this parameter to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Preprocesses the String Reader context.  Preprocesses the String Reader context.

  Open   Collapse  M_RESET

 Un-preprocesses the String Reader context.  Un-preprocesses the String Reader context ...

 Un-preprocessing the String Reader context can be useful if you want to conserve system memory within an application and preserve String Reader context settings.

PREPROCESSED   DEFAULT RESET


MstrRead

See Also | Example | Availability | MstrPreprocess | MstrRestore
User Guide:
Steps to reading a string in an image
Creating and customizing the fonts
Space
Number of strings to read
Degrees of freedom
Rules for character placement
Global context settings
Scores and acceptances
Retrieving results and annotation

Reference:
MstrAlloc
MstrControl
MstrEditFont
MstrGetResult
MstrPreprocess
MstrSetConstraint
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Read strings from a target image.
Syntax
void MstrRead(
MIL_ID ContextId,
MIL_ID TargetImageId,
MIL_ID ResultId
)
Description

This function reads one or more strings from the specified target image using the specified String Reader context. All specifications, such as the number of strings to read in the target image, the speed and/or robustness parameters, the constraints on the characters in the string, and the font used, depend on the settings of the String Reader context, which can be set with MstrControl(), MstrSetConstraint() and MstrEditFont(). All settings are taken into account by MstrRead(), and results are stored in the specified result buffer. Results can be read from the result buffer using the MstrGetResult() function.

For a string to be read, it must not only meet all of the restrictions placed on it by the String Reader context, but it must also obey the basic rules of a string. That is, it must be a group of regular characters that overlap, in the Y-direction, with each other regular character of the group.

The string read will be ordered in the natural Latin-based reading order. The position of a string is the position of the center of the box of its first character. The characters must be 1-band 8-bit unsigned, and cannot exceed a maximum size of 65536 x 65536 pixels.

Note that before performing a read operation, the String Reader context must have at least one font, one character, and one string; it must also be preprocessed (MstrPreprocess()).

Parameters
ContextId

Specifies the String Reader context to use for the read operation. The String Reader context must have been previously allocated on the required system using MstrAlloc(), and preprocessed using MstrPreprocess().

TargetImageId

Specifies the target image in which to read the strings.

ResultId

Specifies the result buffer in which to write the results of the read operation.


MstrRestore

See Also | Example | Availability | MstrRead | MstrSave
User Guide:
Retrieving results and annotation

Reference:
MstrPreprocess
MstrRead
MstrSave
MsysAlloc
There are no examples containing MstrRestore().
Not available in MIL-Lite

Available in MIL
Synopsis
Restore a String Reader context from disk.
Syntax
MIL_ID MstrRestore(
MIL_TEXT_PTR Filename,
MIL_ID SystemId,
long ControlFlag,
MIL_ID *ContextIdPtr
)
Description

This function restores a String Reader context that was previously saved to a file, using MstrSave(). This function restores all of the String Reader context's settings (including font and string model settings) that were in effect when the String Reader context was saved. A restored String Reader context is not preprocessed, therefore you must call MstrPreprocess() before performing a read with MstrRead().

Parameters
Filename

Specifies the file name. The function internally handles the opening and closing of the file.

SystemId

Specifies the system on which to restore the String Reader context.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 ContextIdPtr

 Specifies the address of the variable in which to write the String Reader context identifier.  Since this function also returns the String Reader context identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the String Reader context identifier. If allocation fails, M_NULL is returned.

  DEFAULT HOST


MstrSave

See Also | Example | Availability | MstrRestore | MstrSetConstraint
User Guide:
Steps to reading a string in an image
Retrieving results and annotation

Reference:
MstrRestore
There are no examples containing MstrSave().
Not available in MIL-Lite

Available in MIL
Synopsis
Save a String Reader context to a file.
Syntax
void MstrSave(
MIL_TEXT_PTR FileName,
MIL_ID ContextId,
long ControlFlag
)
Description

This function saves all the information about the previously allocated String Reader context to disk, including all of the individual font and string settings. This information can be reloaded, using MstrRestore().

When you save the String Reader context, the preprocessing changes are not saved. Upon restoration, you must preprocess the context again.

Parameters
FileName

Specifies the file name of the String Reader context. If this file already exists, it will be overwritten. The function internally handles the opening and closing of this file. It is recommended that you use the MSR file extension for easier use with other Matrox Imaging software products.

ContextId

Specifies the identifier of the String Reader context to save.

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.


MstrSetConstraint

See Also | Example | Availability | MstrSave | MstrStream
User Guide:
Steps to reading a string in an image
Rules for character placement

Reference:
MstrAlloc
MstrControl
MstrInquire
mstr.c
Not available in MIL-Lite

Available in MIL
Synopsis
Set character constraints.
Syntax
void MstrSetConstraint(
MIL_ID ContextId,
long StringIndex,
long CharPos,
long ConstraintType,
void *CharList
)
Description

This function specifies the constraint to apply to the character of a specified string.

Parameters
ContextId

Specifies the String Reader context with which to associate the constraint. The String Reader context must have been previously allocated on the required system using MstrAlloc().

StringIndex

Specifies the index of the string in the String Reader context.

Note that a new string can be added to the String Reader context using MstrControl() with M_STRING_ADD.

This parameter should be set to the following value:

Open Collapse Value Description
Open Collapse M_STRING_INDEX(
long StringIndex
)

Specifies that the constraint will be applied to a string, or to all strings. Specifies that the constraint will be applied to a string, or to all strings ...

Parameters
StringIndex

This parameter specifies the index of the string. You can set this parameter to one of the following:

Open Collapse Value Description
Open Collapse M_ALL

 Specifies that the constraint will be applied to all strings.  Specifies that the constraint will be applied to all strings ...

  Open   Collapse  Value >= 0

 Specifies the index of the individual string to which the constraint will be applied.  Specifies the index of the individual string to which the constraint will be applied ...

 CharPos

 Specifies the character position in the string for which the constraint is set.

 A constraint can be set for any position, even a position greater than the maximum number of characters in the string. Constraints set at a position greater than the minimum number of characters in the string are ignored (when the string read does not contain a character at that position).

 This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the default constraint of the string model.  Sets the default constraint of the string model ...

 The default constraint of the string model is used when no specific constraint is set to a given position.

  Open   Collapse  0 to 255

 Sets the character position in the string to which the constraint will be applied.  Sets the character position in the string to which the constraint will be applied.

 ConstraintType

 Specifies the type of constraint to set. Unless otherwise specified, the constants listed below can be added together.

 By default, all constraints allow for any font, including the CharList parameter constraints. For example M_LETTER + M_DIGIT means any letter and any digit of any font is acceptable. To restrict the constraint to a specific font, see the combination value below.

 This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the default constraint.  Sets the default constraint ...

 For a specific character position (the CharPos parameter is set to an individual value), the default is the same as the default constraint of the string model.

 For the default character position (the CharPos parameter is set to M_DEFAULT), the default is the same as M_ANY.

 You cannot add another constant to M_DEFAULT.

  Open   Collapse  M_ANY

 Sets the constraint to any character.  Sets the constraint to any character ...

 You cannot add another constant to M_ANY.

  Open   Collapse  M_DIGIT

 Sets the constraint to any digit (0 to 9).  Sets the constraint to any digit (0 to 9).

  Open   Collapse  M_LETTER

 Sets the constraint to any letter (a to z and A to Z).  Sets the constraint to any letter (a to z and A to Z) ...

 Note that M_LETTER does not differentiate between upper and lower cases. To specify the case of the letter, see the combination values below.

      [Combination constants]

 To specify the case of the constraint, one of the following values can be added to the M_LETTER setting of the CharPos parameter.

  Open   Collapse  Value
Description

  Open   Collapse  M_LOWERCASE

 Sets the constraint to any lowercase letter (a to z).  Sets the constraint to any lowercase letter (a to z).

  Open   Collapse  M_UPPERCASE

 Sets the constraint to any uppercase letter (A to Z).  Sets the constraint to any uppercase letter (A to Z).

      [Combination constants]

 To restrict the constraint to a specific font, add the following macro to the constant:

  Open   Collapse  Value
Description

  Open   Collapse  M_FONT_INDEX(
long FontIndex

          )

 Specifies that the constraint will be restricted to a specific font.  Specifies that the constraint will be restricted to a specific font ...

Parameters

FontIndex

 This parameter specifies the index of the font. You can set this parameter to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  0 to 255

 Specifies the index of the individual font from which the constraint is taken.  Specifies the index of the individual font from which the constraint is taken ...

 When setting the constraint, the font index can be the index of a font that does not currently exist. However, if the font still does not exist at preprocessing time, an error will be logged.

 CharList

 Specifies an explicit list of valid characters, at the specified position. This is an optional, null-terminated string.

 All the specified characters must be compatible with the ConstraintType parameter definition. Each character in the character list must be unique; no character repetition is allowed in the CharList parameter.

 The string array must be of the right type for the encoding scheme selected (MstrInquire() with M_ENCODING). At preprocessing time, each character in an explicit character list must exist in at least one of the fonts of the constraint.

STRING ADD LETTER DIGIT DEFAULT ANY DEFAULT ANY LETTER LETTER ENCODING     ALL  DEFAULT   DEFAULT ANY LETTER DIGIT LOWERCASE UPPERCASE


MstrStream

See Also | Example | Availability | MstrSetConstraint
Reference:
MappInquire
MstrPreprocess
MstrRead
MstrSave
MsysAlloc
There are no examples containing MstrStream().
Not available in MIL-Lite

Available in MIL
Synopsis
Load, restore, or save a String Reader context from/to a file or a memory stream.
Syntax
void MstrStream(
MIL_TEXT_PTR MemPtrOrFileName,
MIL_ID SystemId,
long Operation,
long StreamType,
double Version,
long ControlFlag,
MIL_ID *ObjectIdPtr,
long *SizeByteVarPtr
)
Description

This function can load or restore a String Reader context from a file or memory stream. All of the String Reader context settings that were in effect when the String Reader context was saved will be restored. A loaded or restored String Reader context is not preprocessed, therefore you must call MstrPreprocess() before performing a read with MstrRead().

Moreover, this function can also save a String Reader context to a file or memory stream. All information about the previously allocated String Reader context is saved, including all of the individual font and string settings. However, preprocessing changes are not saved.

To inquire the number of bytes necessary to save a String Reader context to memory stream, you should first call this function (MstrStream()) with M_INQUIRE_SIZE_BYTE.

The content saved to memory stream is equivalent to the content saved to file. In addition, any file saved with MstrSave() is equivalent to a file saved using this function.

You can use this and other MIL stream functions, for example, to save all required MIL objects, as well as any other custom data, for your application to a memory stream. Once in a memory stream, you can write the stream to a single file or transfer it over a network. You are responsible for concatenating the streams and for saving the stream to file.

Parameters
MemPtrOrFileName

Specifies the file or memory stream.

When the StreamType parameter is set to M_FILE, MemPtrOrFileName specifies the name and path of the file required for the operation. For easier use with other Matrox Imaging software products, when saving a String Reader context to a file, use the MSR file extension. The function internally handles an the opening and closing of the file. If the file already exists, it will be overwritten when M_SAVE operation is performed.

When the StreamType parameter is set to M_MEMORY, MemPtrOrFileName specifies the address of the block of memory required for the operation. The designated block must be large enough to stream the entire object. To know the required size, you should first call this function (MstrStream()) with M_INQUIRE_SIZE_BYTE.

When performing an M_INQUIRE_SIZE_BYTE operation, set this parameter to M_NULL.

SystemId

Specifies the system on which to restore the String Reader context. For M_INQUIRE_SIZE_BYTE, M_LOAD, and M_SAVE, SystemId is ignored and should be set to M_NULL.

For an M_RESTORE operation, this parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 Operation

 Specifies the operation to perform on the String Reader context.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_INQUIRE_SIZE_BYTE

 Inquires the number of bytes required to save a String Reader context to memory stream. This operation is not supported when the StreamType parameter is set to M_FILE.  Inquires the number of bytes required to save a String Reader context to memory stream ...

  Open   Collapse  M_LOAD

 Loads the content of a specified file or memory stream into a previously allocated String Reader context.  Loads the content of a specified file or memory stream into a previously allocated String Reader context.

  Open   Collapse  M_RESTORE

 Restores a String Reader context from a file or memory stream and assigns it an identifier.  Restores a String Reader context from a file or memory stream and assigns it an identifier.

  Open   Collapse  M_SAVE

 Saves a String Reader context to a specified file or memory stream.  Saves a String Reader context to a specified file or memory stream.

 StreamType

 Specifies the type of stream that holds the String Reader context.  This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_FILE

 Specifies a file stream.  Specifies a file stream.

  Open   Collapse  M_MEMORY

 Specifies a memory stream. You are responsible for allocating a block of memory for the stream.  Specifies a memory stream ...

 Version

 Specifies the MIL version of the String Reader context. For M_LOAD and M_RESTORE, this parameter must be set to M_DEFAULT.

 This parameter must be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Sets the version to current version of MIL.  Sets the version to current version of MIL.

  Open   Collapse  Value

 Sets the version to a specific version of MIL. This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.  Sets the version to a specific version of MIL ...

 The version specified must never be greater than the current MIL version, but must be greater or equal to 8.0. To know the current MIL version, call MappInquire() with M_VERSION.

 By supplying a specific version, you can control the String Reader context's accessibility. Note that a program using a higher version of MIL can access a String Reader context stream created or designated with a lower or equal version. Settings that do not exist in the lower version will be filled with default values when the file or memory stream is restored.

 ControlFlag

 Reserved for future expansion and must be set to M_DEFAULT.

 ObjectIdPtr

 Specifies the address of the variable in which to write or from which to read the identifier of the String Reader context.

 For M_INQUIRE_SIZE_BYTE and M_SAVE operations, ObjectIdPtr specifies the address of the variable from which to read the String Reader context identifier.

 For an M_LOAD operation, ObjectIdPtr specifies the address of the variable from which to read the identifier of the String Reader context where the file or memory stream content will be loaded.

 For an M_RESTORE operation, ObjectIdPtr specifies the address in which to return the identifier of the restored String Reader context. If the operation is not successful, M_NULL is returned.

 SizeByteVarPtr

 Specifies the address of the variable in which to write the size of the String Reader context, in bytes.

 If the size is not required, you can set this parameter to M_NULL.

 Note that the size of a String Reader context will vary depending on the MIL version specified.

INQUIRE SIZE BYTE FILE SAVE MEMORY INQUIRE SIZE BYTE INQUIRE SIZE BYTE INQUIRE SIZE BYTE LOAD SAVE RESTORE FILE LOAD  RESTORE DEFAULT INQUIRE SIZE BYTE SAVE VERSION INQUIRE SIZE BYTE SAVE LOAD RESTORE   DEFAULT HOST   INQUIRE SIZE BYTE LOAD RESTORE SAVE  FILE MEMORY  DEFAULT


sys

Msys functions

Example | Availability
There are no examples containing sys().
Available in MIL-Lite

Available in MIL
Synopsis
The system allocation and inquiry module supports the allocation and inquire of systems. The system control represents a physical board, most commonly an imaging frame grabber. The system control also allows you to access the graphics controller and Host CPU. The system control is used to specify which physical device you wish to access, and allows some system-wide settings to be set. Once the system control is set up, you can add other components to your application, such as a digitizer control, to control specific aspects of the device.
Functions
  • MsysAlloc
  • MsysControl
  • MsysFree
  • MsysGetHookInfo
  • MsysHookFunction
  • MsysInquire


MsysAlloc

See Also | Example | Availability | MsysControl
User Guide:
Allocating an application and its systems
Cameras and video sources

Reference:
MappAlloc
MappAllocDefault
MdigAlloc
MsysFree
channel_switch.c
dtkobjecttracking.c
mdblgrab.c
mdiggrabmultiple.c
mdigmultdestination.c
mdigmultformat.c
mdigprocessmultiple.c
mdispwindow.c
met2_1394serialbus.c
mgenlc.c
mmet2dig.c
muart.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Genesis
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Allocate a hardware system.
Syntax
MIL_ID MsysAlloc(
MIL_TEXT_PTR SystemDescriptor,
long SystemNum,
long InitFlag,
MIL_ID *SystemIdPtr
)
Description

This function allocates a hardware system (board set, Host system, and any available graphics controller) so that it can be used by subsequent MIL functions. Upon execution of this function, MIL ensures that it can open communication with the system before allocating it and generates an error if it cannot.

A system must be allocated before any buffers, displays, or digitizers can be allocated on it. Before allocating a system, an application must be allocated, using MappAlloc() or MappAllocDefault(). To use the default system, it must be allocated using M_SYSTEM_DEFAULT.

Note, upon allocation of an application, a default Host system is automatically allocated. Rather than using MsysAlloc() to allocate a Host system, you can use this default Host system, by specifying M_DEFAULT_HOST wherever a Host system identifier is required.

When you no longer need a particular system, free it using MsysFree().

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

When you have several imaging boards in one cluster, you must allocate the boards in that cluster in sequential order, starting with the first board. However, when boards are not connected together, they can be allocated in any order.

[Matrox Genesis]

For auxiliary displays, the Matrox Genesis will only use its on-board display section; however, the on-board display section of the Matrox Genesis can be used by other systems.

Parameters
SystemDescriptor

Specifies the type of system to allocate. Set this parameter to one of the following values:

Open Collapse Value Description corona-II (a) cronosplus (b) genesis (c) helios xa (d) helios xcl (e) Matrox Iris (f) met-II /1394 (g) met-II /cl (h) met-II /dig (i) met-II /mc (j) met-II /std (k) morphis (l) odyssey xa (m) odyssey xcl (n) odyssey xd (o) orion (p) solios xa (q) solios xcl (r)
Open Collapse M_SYSTEM_CORONA_II

 Allocates a Corona-II type system.  Allocates a Corona-II type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

a

  Open   Collapse  M_SYSTEM_CRONOSPLUS

 Allocates a CronosPlus type system.  Allocates a CronosPlus type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

b

  Open   Collapse  M_SYSTEM_DEFAULT

 Specifies the default system. This value is set during MIL installation and using MilConfig. Note that the end-user can always change this value.  Specifies the default system ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_SYSTEM_GENESIS

 Allocates a Genesis type system; that is, M_SYSTEM_GENESIS allocates a Matrox Genesis-LC board or a node on a Main or Processor Board.  Allocates a Genesis type system; that is, M_SYSTEM_GENESIS allocates a Matrox Genesis-LC board or a node on a Main or Processor Board ...

 This selection opens communication with the board or the specified node, and will allow MIL to use its resources, and any available graphics controller.

 When using a Matrox Genesis processor board or when using a node that cannot access Matrox Genesis's display section (without accessing the primary PCI bus), MIL will not only use the board/node's resources and Host computer memory, but also the VGA board. The VGA board has been included to allow you to display grabbed images.

c

  Open   Collapse  M_SYSTEM_HELIOS

 Allocates a Helios type system.  Allocates a Helios type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

d
e

  Open   Collapse  M_SYSTEM_HOST

 Specifies the Host type system.  Specifies the Host type system.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse  M_SYSTEM_IRIS

 Allocates an Iris type system.  Allocates an Iris type system.

f

  Open   Collapse  M_SYSTEM_METEOR_II

 Allocates a Meteor-II /Standard or a Meteor-II /Multi-Channel type system.  Allocates a Meteor-II /Standard or a Meteor-II /Multi-Channel type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

j
k

  Open   Collapse  M_SYSTEM_METEOR_II_1394

 Allocates a Meteor-II /1394 type system.  Allocates a Meteor-II /1394 type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

 To perform multiple continuous grabs, MIL allows you to allocate multiple M_SYSTEM_METEOR_II_1394 systems on a Matrox Meteor-II /1394 board. Then, use MdigAlloc() to specify which camera (digitizer) belongs to a particular system. Refer to section the Grabbing from multiple 1394 DCS-compliant cameras section in
          Chapter 6: Matrox Meteor-II for more details.

 The number of 1394-compliant cameras available is detected when MsysAlloc() function is called the first time. Warning: you cannot unplug a camera that has been detected by MsysAlloc() before freeing up the system with the MsysFree() function.

g

  Open   Collapse  M_SYSTEM_METEOR_II_CL

 Allocates a Meteor-II /Camera Link type system.  Allocates a Meteor-II /Camera Link type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

h

  Open   Collapse  M_SYSTEM_METEOR_II_DIG

 Allocates a Meteor-II /Digitial type system.  Allocates a Meteor-II /Digitial type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

i

  Open   Collapse  M_SYSTEM_MORPHIS

 Allocates a Morphis type system.  Allocates a Morphis type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

l

  Open   Collapse  M_SYSTEM_ODYSSEY

 Allocates an Odyssey type system.  Allocates an Odyssey type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

 If the Matrox Odyssey Xpro board that you allocate has a frame grabber module attached to it or any other Matrox Odyssey Xpro in the cluster, the system allocation allows you to allocate a digitizer on this system using MsysAlloc().

 When Matrox Odyssey boards are interconnected as a cluster, each board must be allocated separately. MIL will automatically detect the interconnection.

 If you have several Matrox Odyssey Xpro boards connected together to form a cluster, you must allocate the boards (device) in that cluster in sequential order, starting with board 0. When the boards are not connected together, they can be allocated in any order.

m
n
o

  Open   Collapse  M_SYSTEM_ORION

 Allocates an Orion type system.  Allocates an Orion type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

 To allocate an Orion system, your display resolution must be in an 8-bit or true color (32-bit) display mode (display depth).

p

  Open   Collapse  M_SYSTEM_SOLIOS

 Allocates a Solios type system.  Allocates a Solios type system ...

 This selection opens communication with the board and will automatically allow the system to use some Host memory, and any available graphics controller, if necessary.

q
r

 SystemNum

 Specifies the number (or rank) of the target board of the specified system type.  This parameter can be set to one of the following:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the default board.  Specifies the default board.

  Open   Collapse  M_DEVn

 Specifies the nth board of the specified system type. You can set n to one of the following values: 0 <= n <=15.  Specifies the nth board of the specified system type. You can set n to one of the following values: 0 <= n <=15 ...

 InitFlag

 Specifies the type of initialization to perform on the selected system.  This parameter can be set to one of the following.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Performs the same initialization as M_COMPLETE.  Performs the same initialization as M_COMPLETE.

  Open   Collapse  M_COMPLETE

 Performs a complete initialization of the system: initialize the system to its default state and download any required resident software. At least one complete initialization is necessary after you power-up your system.  Performs a complete initialization of the system: initialize the system to its default state and download any required resident software ...

  Open   Collapse  M_PARTIAL

 Initializes the system with its default state, but do not download any resident software (which can take a few seconds).  Initializes the system with its default state, but do not download any resident software (which can take a few seconds).

 SystemIdPtr

 Specifies the address of the variable in which to write the system identifier.  Since the MsysAlloc() function also returns the system identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

 The returned value is the system identifier. If allocation fails, M_NULL is returned.

SYSTEM DEFAULT SYSTEM GENESIS SYSTEM METEOR II 1394
                    SYSTEM CORONA II SYSTEM CRONOSPLUS SYSTEM GENESIS  SYSTEM HELIOS  SYSTEM HOST SYSTEM IRIS SYSTEM METEOR II SYSTEM METEOR II 1394 SYSTEM METEOR II CL SYSTEM METEOR II DIG SYSTEM MORPHIS SYSTEM ODYSSEY SYSTEM ORION  SYSTEM SOLIOS SYSTEM DEFAULT  DEFAULT DEVn   DEFAULT  COMPLETE  PARTIAL


MsysControl

See Also | Example | Availability | MsysAlloc | MsysFree
User Guide:
Buffer overscan region
Integrating native functions with MIL code

Reference:
MdigControl
MdigProcess
MsysAlloc
MsysHookFunction
MsysInquire
MthrControl
mgenlc.c
mmet2dig.c
mnatgen.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Control a system setting.
Syntax
void MsysControl(
MIL_ID SystemId,
long ControlType,
long ControlValue
)
Description

This function allows you to control the specified system setting.

To inquire the current value of a particular system setting, use MsysInquire().

Parameters
SystemId

Specifies the system identifier. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 ControlType

 Specifies the type of setting to control.

See the Parameter associations section for possible values.

 ControlValue

 Specifies the new value to assign to the system setting specified by the ControlType parameter.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue
         parameters are described below.

  Open   Collapse  ControlType
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

ControlValue

  Open   Collapse   M_ALLOCATION_OVERSCAN_SIZE

 Sets the size of the overscan region, added around all subsequently allocated image buffers (MbufAlloc...()). The overscan settings of previously allocated image buffers are not changed. For more information, see the Buffer overscan region section in
          Chapter 14: Specifying and managing your data buffers.  Sets the size of the overscan region, added around all subsequently allocated image buffers (MbufAlloc...()) ...

 To enable or disable the allocation of an overscan region, change the setting of M_FAST_OVERSCAN_BUFFER.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Specifies the default size of the overscan.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The default size is 8 pixels.

a
b

g
h
i
j
k
l

p

 The default size is 8 pixels when using paged memory. When using non-paged on-board memory, the default size is 16 pixels.

d
e

q
r

 The default size is 16 pixels.

c

m
n
o

 Value

 Specifies the size of the overscan, in pixels.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The size of the overscan must be at least 16 pixels.

c
d
e

m
n
o

q
r

  Open   Collapse   M_BUS_MASTER_COPY_FROM_HOST

 Sets whether a copy operation from a Host (off-board) buffer to an M_ON_BOARD buffer is driven by your imaging board (bus master) or by the Host CPU.  Sets whether a copy operation from a Host (off-board) buffer to an M_ON_BOARD buffer is driven by your imaging board (bus master) or by the Host CPU ...

c

h
i

m
n
o

 M_DEFAULT

 Specifies to use the default value.

c

h
i

m
n
o

Specifics

M_DISABLE is the default.

h
i

M_ENABLE is the default.

c

m
n
o

 For the Matrox Genesis-LC, M_DISABLE is the default.

c

 M_DISABLE

 Specifies that the copy operation is driven by the Host CPU.

c

h
i

m
n
o

 M_ENABLE

 Specifies that the copy operation is driven by your imaging board. This speeds up the copy and reduces Host intervention.

 Note that this does not accelerate calls to MbufGet...() or MbufPut...() functions.

c

h
i

m
n
o

  Open   Collapse   M_BUS_MASTER_COPY_TO_HOST

 Sets whether a copy operation from an M_ON_BOARD buffer to a Host buffer (off-board) is driven by your imaging board (bus master) or by the Host CPU.  Sets whether a copy operation from an M_ON_BOARD buffer to a Host buffer (off-board) is driven by your imaging board (bus master) or by the Host CPU ...

c

h
i

m
n
o

 M_DEFAULT

 Specifies to use the default value.

c

h
i

m
n
o

Specifics

M_DISABLE is the default.

h
i

M_ENABLE is the default.

c

m
n
o

 For the Matrox Genesis-LC, M_DISABLE is the default.

c

 M_DISABLE

 Specifies that the copy operation is driven by the Host CPU.

c

h
i

m
n
o

 M_ENABLE

 Specifies that the copy operation is driven by your imaging board. This speeds up the copy and reduces Host intervention.

 Note that this does not accelerate calls to MbufGet...() or MbufPut...() functions.

c

h
i

m
n
o

  Open   Collapse   M_DEFAULT_PITCH_BYTE

 Sets the value MIL uses to determine the pitch, in bytes, of the buffers allocated on the system. The pitch is the number of units between the beginnings of any two adjacent lines of the buffer's data.  Sets the value MIL uses to determine the pitch, in bytes, of the buffers allocated on the system ...

 The pitch, in bytes, of the buffers allocated on the system is a multiple of this value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 The default factor is 16.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 Value

 Specifies the factor MIL uses to determine the pitch, in bytes, of the buffers allocated on the system. This value must be a power of 2.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The value specified must be a power of 2, and must be greater or equal to 16.

c

m
n
o

  Open   Collapse   M_FAST_OVERSCAN_BUFFER

 Sets whether image buffers, allocated on the system, are allocated with an overscan region. The size of the overscan region is specified by M_ALLOCATION_OVERSCAN_SIZE.  Sets whether image buffers, allocated on the system, are allocated with an overscan region ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Specifies the optimal setting for the system. For a Host system, the default is M_ENABLE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

Specifics

 The default is M_DISABLE.

m
n
o

 The default is M_ENABLE.

a
b
c
d
e
f
g
h
i
j
k
l

p
q
r

 M_DISABLE

 Specifies that image buffers allocated on the system will have no overscan region.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Specifies that image buffers are allocated with an overscan region.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_MODIFIED_BUFFER_HOOK_MODE

 Sets whether to run user-defined functions hooked to a buffer modification on separate threads, up to the number of CPUs present in the computer. This is particularly useful when functions are hooked using MdigProcess().  Sets whether to run user-defined functions hooked to a buffer modification on separate threads, up to the number of CPUs present in the computer ...

d
e

l

q
r

 M_DEFAULT

Same as M_SINGLE_THREAD.

d
e

l

q
r

 M_SINGLE_THREAD

 Specifies that only one thread should be created and that all buffer modifications are run on the same thread.

d
e

l

q
r

 M_MULTI_THREAD

 Specifies to run user-defined functions hooked to a buffer modification on separate threads, up to the number of CPUs present in the computer. Processing is dispatched by the operating system to available CPUs, depending on their workload. MIL cannot guarantee the processing order of any frame on such a computer, because they are executed concurrently. Instead, use Microsoft Windows functions to synchronize the threads. See below for combination values.

d
e

l

q
r

  Open   Collapse   M_NATIVE_MODE_ENTER

 Sends a signal to MIL that the system is entering native mode.  Sends a signal to MIL that the system is entering native mode ...

c

m
n
o

 M_DEFAULT

 Implements the default behavior.

c

m
n
o

  Open   Collapse   M_NATIVE_MODE_LEAVE

 Sends a signal to MIL that the system is leaving native mode.  Sends a signal to MIL that the system is leaving native mode ...

c

m
n
o

 M_DEFAULT

 Implements the default behavior.

c

m
n
o

  Open   Collapse   M_PROCESSING_SYSTEM

 Sets the system on which to process allocated buffers.  Sets the system on which to process allocated buffers ...

 This control type forces the processing of buffers, allocated on the system specified by the SystemId parameter, to be performed by the system specified by the control value.

 Note, even when you force processing to be performed by a specific system, some operations might not execute successfully if the specific system does not completely support the requested operation. This can occur even if processing compensation is enabled.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Re-establishes the default processing system selected by MIL at system allocation.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT_HOST

 Forces the processing of buffers to be performed by the default Host system.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 MIL System identifier

 Forces the processing of buffers to be performed by the specified system.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_THREAD_MODE

 Sets the thread execution mode for all threads allocated on the particular system.  Sets the thread execution mode for all threads allocated on the particular system ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Specifies that the thread's execution mode will be returned either to its default value or to the value set using MthrControl() with M_THREAD_MODE.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_SYNCHRONOUS

 Specifies that the execution of a MIL function sent to the processor of a system must be completed (execution terminated) before returning control to the Host.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_TIMEOUT

 Sets the maximum amount of time (in secs) for the Host to wait for a synchronous function to return before generating a time-out error.  Sets the maximum amount of time (in secs) for the Host to wait for a synchronous function to return before generating a time-out error ...

c
d
e
f

l
m
n
o

q
r

 M_DEFAULT

Specifies the default value. The default value is 20 seconds.

c
d
e
f

l
m
n
o

q
r

 Value

 Specifies any amount of time, in secs.

c
d
e
f

l
m
n
o

q
r

      [Combination constants]

 The following can be added to M_MODIFIED_BUFFER_HOOK_MODE set to M_MULTI_THREAD.

  Open   Collapse  Value
Description

  Open   Collapse  Value >=1

 Specifies the number of hook threads to allocate. Note that this value cannot exceed the number of CPUs available.  Specifies the number of hook threads to allocate ...

[Matrox Helios XA, Matrox Helios XCL, Matrox Morphis, Matrox Solios XA, and Matrox Solios XCL]

 The following control types and control values specify the settings for UARTs. To specify a particular UART, see the combination value below.

[Matrox Morphis]

 UARTS are not supported on Matrox Morphis PC/104-Plus.

 Note that for other Matrox imaging boards that have a UART, but are not supported with the constants below, see MdigControl().

Open Collapse ControlType |  | Description | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
 | ControlValue
Open Collapse M_UART_DATA_LENGTH |  | Sets the number of data bits per character that are sent or received by the UART. Sets the number of data bits per character that are sent or received by the UART ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DEFAULT | Same as 8. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | 7 | Specifies that the data length is 7 bits. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | 8 | Specifies that the data length is 8 bits. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_PARITY |  | Sets whether character data is sent or received with a parity bit and how the parity bit is set. The parity bit is an extra data bit (0 or 1) that is added to each character for error checking purposes. Sets whether character data is sent or received with a parity bit and how the parity bit is set ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DEFAULT | Same as M_DISABLE. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DISABLE | Species that no extra bit is added (no parity). |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_EVEN | Specifies that the number of 1's will be even. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_ODD | Specifies that the number of 1's will be odd. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_READ_CHAR |  | Reads one character from the UART input buffer. If the input buffer is empty, the function will wait for the amount of time specified by M_UART_TIMEOUT. If a time-out occurs, the '?' character will be returned. Reads one character from the UART input buffer ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the address of the variable in which to save the character read from the UART. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_READ_STRING |  | Reads a string of incoming data from the UART. The number of characters to read can be specified with M_UART_READ_STRING_LENGTH or M_UART_STRING_DELIMITER. M_UART_TIMEOUT specifies the maximum time to wait between each byte when reading incoming data. Use MsysInquire() with M_UART_BYTES_READ to wait for the read operation to complete and retrieve the actual number of bytes read. Reads a string of incoming data from the UART ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the address of the character array in which to save the string read from the UART. The size of this array must be set to the same value as the M_UART_READ_STRING_MAXIMUM_LENGTH control type. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_READ_STRING_LENGTH |  | Sets the length of the string to read using M_UART_READ_STRING. Sets the length of the string to read using M_UART_READ_STRING ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DEFAULT | Specifies the use of M_UART_STRING_DELIMITER to delineate the end of the string to read. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the string length, in bytes. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_READ_STRING_MAXIMUM_LENGTH |  | Sets the maximum length of the string to read. This prevents global protection faults from happening when using the M_UART_READ_STRING control type. Sets the maximum length of the string to read ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the maximum length of the string, in bytes. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_SPEED |  | Sets the baud rate of the UART. Sets the baud rate of the UART ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DEFAULT | Specifies the default value. The default value is 14400. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | 300; 600; 1200; 1800; 2400; 3600; 4800; 7200; 9600; 14400; 19200; 28800; 38400; 57600; 76800; 115200; 128000; 256000 | Specifies the baud rate of the UART. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_STOP_BITS |  | Sets the number of extra data bit(s) (1 or 2) that are added to each character to indicate the end of the character. Sets the number of extra data bit(s) (1 or 2) that are added to each character to indicate the end of the character ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DEFAULT | Same as 1. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | 1 | Specifies that there is 1 stop bit. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | 2 | Specifies that there are 2 stop bits. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_STRING_DELIMITER |  | Sets the character used to terminate strings of incoming or outgoing data. The delimiter is used but not sent when writing data with M_UART_WRITE_STRING; it is read for incoming data with M_UART_READ_STRING. Sets the character used to terminate strings of incoming or outgoing data ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DEFAULT | Specifies the default value. The default value is '\0'. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the character used to terminate strings. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_TIMEOUT |  | Sets the maximum time to wait between each byte when reading incoming data. Sets the maximum time to wait between each byte when reading incoming data ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DEFAULT | Same as M_INFINITE. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_INFINITE | Waits indefinitely. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the time to wait, in msec. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_WRITE_CHAR |  | Sends one character to the UART for transmission. Sends one character to the UART for transmission ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the character to send. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_WRITE_STRING |  | Sends a string of data through the UART for transmission. The number of characters to send can be specified with M_UART_WRITE_STRING_LENGTH or M_UART_STRING_DELIMITER. Use MsysInquire() with M_UART_BYTES_WRITTEN to wait for the write operation to complete and retrieve the actual number of bytes written. Sends a string of data through the UART for transmission ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the character array. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
Open Collapse M_UART_WRITE_STRING_LENGTH |  | Sets the length of the string to be sent to the UART for transmission. Sets the length of the string to be sent to the UART for transmission ... |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | M_DEFAULT | Specifies the use of M_UART_STRING_DELIMITER to end the string. The delimiter will not be sent through the UART. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r
 | Value | Specifies the string length, in bytes. |  |  |  | d | e |  |  |  |  |  |  | l |  |  |  |  | q | r

      [Combination constants]

[Matrox Helios XA, Matrox Helios XCL, Matrox Morphis, Matrox Solios XA, and Matrox Solios XCL]

 The following value can be added to any M_UART... control value, listed above. Use MsysInquire() with M_UART_PRESENT to determine the number of UARTS on the system.

  Open   Collapse  Value
Description

  Open   Collapse  M_UART_NB(
long M_DEVn

          )

 Specifies which UART to control.  Specifies which UART to control ...

[Matrox Morphis]

 There is 1 UART available on Matrox Morphis and Matrox Morphis Quad.

[Matrox Helios XA]

 There are 4 UARTs available.

[Matrox Solios XA]

 There are 4 UARTs available on Matrox Solios XA and only 1 UART available on Matrox Solios XA single analog.

[Matrox Helios XCL and Matrox Solios XCL]

 On the dual-Base version, there are 2 UARTs available.

 On the single-Full version, there is 1 UART available.

Parameters

M_DEVn

 Specifies a UART to control, where n can be a value between 0 and 15.

[Matrox CronosPlus, Matrox Iris, and Matrox Morphis]

 The following values allow you to control user-defined signals.

 Note that the following are available on Matrox 4Sight-II and Matrox 4Sight-M, even without any additional Matrox imaging board(s), and on Matrox CronosPlus, Matrox Iris, and Matrox Morphis.

[Matrox Morphis]

 User-defined signals are not supported on Matrox Morphis PC/104-Plus. Use the user-defined signals of Matrox 4Sight-M instead.

 Note that for other Matrox imaging boards that have user-defined signals, but are not supported with the constants below, see MdigControl().

Open Collapse ControlType |  | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
 | ControlValue
Open Collapse M_USER_BIT_INTERRUPT_MODE |  | Sets the type of functional-state change upon which to generate an interrupt. Note that this only applies to user-defined input signals. Sets the type of functional-state change upon which to generate an interrupt ... Note that, to use this control type, M_USER_BIT_INTERRUPT_STATE must be enabled. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 |  |  | Specifics |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  |  | This is only available with user-defined signal 0. |  | b |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  |  | You must specify the user-defined signal to affect. See below for combination values. |  |  |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 | M_EDGE_FALLING | Specifies to generate an interrupt upon a high-to-low signal variation. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 | M_EDGE_RISING | Specifies to generate an interrupt upon a low-to-high signal variation. This is the default value. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
Open Collapse M_USER_BIT_INTERRUPT_STATE |  | Sets whether to generate an interrupt when the functional state of the user-defined signal changes. To specify whether to trigger the interrupt on the rising or falling edge, see M_USER_BIT_INTERRUPT_MODE. Note that this only applies to user-defined input signals. Sets whether to generate an interrupt when the functional state of the user-defined signal changes ... |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 |  |  | Specifics |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  |  | This is only available with user-defined signal 0. |  | b |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 |  |  | You must specify the user-defined signal to affect. See below for combination values. |  |  |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 | M_DISABLE | Disables the interrupt. This is the default value. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 | M_ENABLE | Enables the interrupt. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
Open Collapse M_USER_BIT_MODE |  | Sets the mode of the specified I/O user-defined signal(s). Note that you can only change the mode of an I/O (bidirectional) user-defined signal. Sets the mode of the specified I/O user-defined signal(s) ... You must specify the user-defined signal to affect. See below for combination values. |  |  |  |  |  |  |  |  |  |  |  |  | l |  |  |  |  |  |
 | Bit-encoded value | Specifies the mode of the specified user-defined output signals. Bits set to 1 in the bit-encoded value set their corresponding user-defined signals to output. Bits set to 0 in the bit-encoded value set their corresponding user-defined signals to input. |  |  |  |  |  |  |  |  |  |  |  |  | l |  |  |  |  |  |
 | M_INPUT | Specifies that the user-defined signal is set for input. This is the default value. |  |  |  |  |  |  |  |  |  |  |  |  | l |  |  |  |  |  |
 | M_OUTPUT | Specifies that the user-defined signal is set for output. |  |  |  |  |  |  |  |  |  |  |  |  | l |  |  |  |  |  |
Open Collapse M_USER_BIT_VALUE_OUT |  | Sets the state of the current user bit on the specified user-defined signal(s) to output. Note that, if used with a user-defined signal that can only accept input, an error will result. Sets the state of the current user bit on the specified user-defined signal(s) to output ... You must specify the user-defined signal to affect. See below for combination values. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 | Bit-encoded value | Specifies the state of the current bit on the specified user-defined signals. Bits set to 1 in the bit-encoded value set their corresponding user-defined signals to on. Bits set to 0 in the bit-encoded value set their corresponding user-defined signals to off. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 | M_OFF | Specifies that the user-defined signal is set to off. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |
 | M_ON | Specifies that the user-defined signal is set to on. This is the default value. |  |  | b |  |  |  | f |  |  |  |  |  | l |  |  |  |  |  |

      [Combination constants]

[Matrox CronosPlus, Matrox Iris, and Matrox Morphis]

 One of the following must be added to M_USER_BIT_VALUE_OUT, M_USER_BIT_MODE, or M_USER_BIT_INTERRUPT_STATE for Matrox 4Sight-II, Matrox 4Sight-M, Matrox CronosPlus, Matrox Iris, and/or Matrox Morphis.

 See the Board Specific Notes for a listing of available user-defined signals and their corresponding numbers in MIL.

  Open   Collapse  Value
Description

  Open   Collapse  M_BIT_MASK(
long Bit_encoded_value

          )

 Specifies a bit-encoded mask value to identify the group of user-defined signals to be affected.  Specifies a bit-encoded mask value to identify the group of user-defined signals to be affected ...

 Note that this value cannot can added to M_USER_BIT_INTERRUPT_MODE or M_USER_BIT_INTERRUPT_STATE.

Parameters

Bit_encoded_value

 Enabled bits in the mask value identify which user-defined signals to affect.

 Note that this value is only available when using a bit-encoded control value.

  Open   Collapse  0 < = Value

 Specifies a specific user-defined signal.  Specifies a specific user-defined signal ...

 Note that in this case, the control value cannot be set to a bit-encoded value.

[Matrox Morphis]

 The following control types and control values specify the settings for the Watchdog.

 The Watchdog is not supported on Matrox Morphis PC/104-Plus.

  Open   Collapse  ControlType
Description

ControlValue

  Open   Collapse   M_WATCHDOG_MODE

 Sets the current state of the Watchdog.  Sets the current state of the Watchdog ...

 M_DEFAULT

 Same as M_DISABLE.

 M_DISABLE

 Disables the Watchdog.

 M_ENABLE

 Enables the Watchdog. The application should be ready to reset the Watchdog and all timeouts (M_WATCHDOG_REBOOT_TIMEOUT & M_WATCHDOG_TIMEOUT) should be programmed before enabling the Watchdog.

  Open   Collapse   M_WATCHDOG_REBOOT_TIMEOUT

 Sets the timeout value of the Watchdog's reboot timer. If, during a reboot, the Host computer does not reset the Watchdog reboot timer before the specified interval expires, the Host computer is assumed to have hung. The Watchdog's reboot timer will then force the Host computer to reboot again.  Sets the timeout value of the Watchdog's reboot timer ...

 Value

 Specifies the timeout value, in msec.

  Open   Collapse   M_WATCHDOG_RESET

 Resets the Watchdog main, reboot, and warning timers.  Resets the Watchdog main, reboot, and warning timers ...

 M_DEFAULT

 Implements the default behavior.

  Open   Collapse   M_WATCHDOG_RESET_COUNTER

 Clears the "number of reboots" counter that counts the number of times the Watchdog has rebooted your Host computer. Note that this count includes both reboots caused by the reboot timer and the main timer.  Clears the "number of reboots" counter that counts the number of times the Watchdog has rebooted your Host computer ...

 M_DEFAULT

 Implements the default behavior.

  Open   Collapse   M_WATCHDOG_TIMEOUT

 Sets the timeout value of the Watchdog's main timer. If, during the course of regular operations, the Host computer does not reset the main timer before the specified interval expires, it is assumed to have hung. The Watchdog's main timer will then force the Host computer to reboot. To receive a warning before the reboot, you can set the Watchdog's warning timer, using M_WATCHDOG_WARNING_TIME.  Sets the timeout value of the Watchdog's main timer ...

 When the Watchdog's warning timer expires, an interrupt is generated to warn you to reset the Watchdog's main timer. You can hook a function to this interrupt using MsysHookFunction(). Set the Watchdog's main timer to a value greater than that of the Watchdog's warning timer to allow enough time for the interrupt to be generated.

 Value

 Specifies the timeout value, in msec.

  Open   Collapse   M_WATCHDOG_WARNING_TIME

 Sets the timeout value of the Watchdog's warning timer. If, during the course of regular operations, the Host computer does not reset the warning timer before the specified interval expires, the Host computer is assumed to have hung. The Watchdog's warning timer will then generate a warning interrupt. You can hook a function to this interrupt using MsysHookFunction().  Sets the timeout value of the Watchdog's warning timer ...

 The warning timeout value should be less than M_WATCHDOG_TIMEOUT to give the computer enough time to finish the hooked function.

 M_INFINITE

 Specifies that the Watchdog will never receive a warning.

 Value

 Specifies the warning time interval, in msec.

Remark

  •  Note that M_USER_BIT... control types are available on Matrox 4Sight-II and Matrox 4Sight-M even without any additional Matrox imaging boards, and on Matrox CronosPlus and Matrox Morphis, unless otherwise specified. For more information on user-defined signals, refer to the User-defined signals for Matrox 4Sight section in
          Chapter 11: Matrox 4Sight section of the Board Specific Notes. To see the information regarding the M_USER_BIT... control types if you have a Matrox 4Sight-II or Matrox 4Sight-M, select Matrox Morphis as your board type in the Customizing options section in
          Chapter 0: About Matrox MIL help.
    •

Example

[Matrox Morphis]

 The following example demonstrates how to change both the mode and state of one user-defined signal and a group of user-defined signals.

/* Set bit 1 to output mode */
MsysControl(MilSystem,M_USER_BIT_MODE+1, M_OUTPUT);
/* Set the functional state of bit 1 to on.*/
MsysControl(MilSystem,M_USER_BIT_VALUE_OUT+1, M_ON);
/* Set bits 2 and 3 to output mode. */
MsysControl(MilSystem,M_USER_BIT_MODE+M_BIT_MASK(0xC), 0xC);
/* Set bit 2 to on, but bit 3 to off. */
MsysControl(MilSystem,M_USER_BIT_VALUE_OUT+M_BIT_MASK(0xC), 0x4);

FAST OVERSCAN BUFFER ON BOARD DISABLE ENABLE DISABLE ON BOARD DISABLE ENABLE DISABLE ALLOCATION OVERSCAN SIZE ENABLE DISABLE ENABLE THREAD MODE MODIFIED BUFFER HOOK MODE MULTI THREAD UART TIMEOUT UART READ STRING UART STRING DELIMITER UART READ STRING UART READ STRING LENGTH UART STRING DELIMITER UART TIMEOUT UART BYTES READ UART READ STRING MAXIMUM LENGTH UART WRITE STRING UART READ STRING UART WRITE STRING LENGTH UART STRING DELIMITER UART BYTES WRITTEN UART STRING DELIMITER UART PRESENT USER BIT INTERRUPT STATE USER BIT INTERRUPT MODE USER BIT VALUE OUT USER BIT MODE USER BIT INTERRUPT STATE USER BIT INTERRUPT MODE USER BIT INTERRUPT STATE WATCHDOG REBOOT TIMEOUT WATCHDOG TIMEOUT DISABLE WATCHDOG WARNING TIME WATCHDOG TIMEOUT  DEFAULT HOST    ALLOCATION OVERSCAN SIZE DEFAULT  BUS MASTER COPY FROM HOST  DEFAULT DISABLE ENABLE BUS MASTER COPY TO HOST  DEFAULT  DISABLE ENABLE DEFAULT PITCH BYTE DEFAULT  FAST OVERSCAN BUFFER DEFAULT DISABLE ENABLE MODIFIED BUFFER HOOK MODE DEFAULT SINGLE THREAD MULTI THREAD NATIVE MODE ENTER DEFAULT NATIVE MODE LEAVE  DEFAULT  PROCESSING SYSTEM  DEFAULT DEFAULT HOST   THREAD MODE DEFAULT SYNCHRONOUS  TIMEOUT  DEFAULT   UART DATA LENGTH  DEFAULT    UART PARITY  DEFAULT  DISABLE  EVEN  ODD  UART READ CHAR   UART READ STRING LENGTH  DEFAULT   UART READ STRING MAXIMUM LENGTH   UART READ STRING   UART SPEED  DEFAULT   UART STOP BITS  DEFAULT    UART STRING DELIMITER  DEFAULT   UART TIMEOUT  DEFAULT  INFINITE   UART WRITE CHAR   UART WRITE STRING   UART WRITE STRING LENGTH  DEFAULT   DEVn USER BIT INTERRUPT MODE EDGE FALLING EDGE RISING USER BIT INTERRUPT STATE DISABLE ENABLE USER BIT MODE  INPUT  OUTPUT USER BIT VALUE OUT  ON OFF   WATCHDOG MODE DISABLE ENABLE DEFAULT WATCHDOG REBOOT TIMEOUT  WATCHDOG RESET DEFAULT WATCHDOG RESET COUNTER DEFAULT WATCHDOG TIMEOUT  WATCHDOG WARNING TIME  INFINITE


MsysFree

See Also | Example | Availability | MsysControl | MsysGetHookInfo
User Guide:
Allocating an application and its systems

Reference:
MsysAlloc
channel_switch.c
dtkobjecttracking.c
mdblgrab.c
mdiggrabmultiple.c
mdigmultformat.c
mdigprocessmultiple.c
mdispwindow.c
met2_1394serialbus.c
mgenlc.c
mmet2dig.c
muart.c
odysseymultiboard.c
Available in MIL-Lite

Available in MIL
Synopsis
Free a system.
Syntax
void MsysFree(
MIL_ID SystemId
)
Description

This function deallocates a system previously allocated with MsysAlloc().

Prior to freeing a system, ensure that all buffers, displays, and digitizers allocated on the system are freed.

Parameter
SystemId

Specifies the identifier of the system to free.


MsysGetHookInfo

See Also | Example | Availability | MsysFree | MsysHookFunction
Reference:
MsysHookFunction
There are no examples containing MsysGetHookInfo().
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Morphis
Fully supported on Matrox Iris

Not supported on:
Not supported on Matrox Corona-II
Not supported on Matrox CronosPlus
Not supported on Matrox Genesis
Not supported on Matrox Helios XA
Not supported on Matrox Helios XCL
Not supported on Matrox Meteor-II /1394
Not supported on Matrox Meteor-II /Camera Link
Not supported on Matrox Meteor-II /Digital
Not supported on Matrox Meteor-II /Multi-Channel
Not supported on Matrox Meteor-II /Standard
Not supported on Matrox Odyssey XA
Not supported on Matrox Odyssey XCL
Not supported on Matrox Orion
Not supported on Matrox Odyssey XD
Not supported on Matrox Solios XA
Not supported on Matrox Solios XCL

Always available on Matrox 4Sight-II/Matrox 4Sight-M
Synopsis
Get information about a hook event.
Syntax
long MsysGetHookInfo(
MIL_ID SystemId,
MIL_ID EventId,
long InquireType,
void *UserVarPtr
)
Description

This function allows you to get information about the event that caused the hook function to be called. MsysGetHookInfo() should only be called within the scope of a system hook-handler function (see MsysHookFunction()).

Note that functions hooked to an event execute on a distinct thread. This permits the functions to run asynchronously from the operation that fired the event and from functions hooked to other events. Although there is a small queue to permit a certain amount of overlap, hooked functions should not take longer to execute than the period in which two of their associated events can occur. You cannot determine the instance of the event that fired the function, and even if this were possible, this information would generally not be very useful. Typically, a hooked function performs the minimum number of operations required and, if necessary, performs longer processes by launching other threads.

Parameters
SystemId

Specifies the identifier of the system. This parameter must be set to M_DEFAULT_HOST.

EventId

Specifies the system event identifier received by the hook-handler function (see MsysHookFunction()).

InquireType

Specifies the type of information about which to inquire.

If the hook-handler function was called with a HookType parameter of the MsysHookFunction() set to M_USER_BIT_CHANGE, set the InquireType parameter to the value below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a long.

Open Collapse Value Description
Open Collapse M_USER_BIT

Returns the user bit that triggered the hook. If more than one user bit triggers an interrupt at the same time, then the hook-handler function (or chain of hook-handler functions) is called for each input user bit that generated an interrupt. As a result, any and all user specified function(s) hooked to M_USER_BIT_CHANGE (MsysHookFunction()) will be executed for each interrupt. Returns the user bit that triggered the hook ...

See the Board Specific Notes for a listing of available user-defined signals and their corresponding numbers in MIL.

UserVarPtr
Accepts the address of one of the following (see above for specifics on which is expected):
  • long

Specifies the address in which to write the requested information.

Return value
Returns null (M_NULL) on success, and returns a non-null (!M_NULL) value on failure, without logging any errors in the application.
USER BIT CHANGE USER BIT CHANGE USER BIT


MsysHookFunction

See Also | Example | Availability | MsysGetHookInfo | MsysInquire
Reference:
MsysAlloc
MsysControl
MsysGetHookInfo
MsysInquire
There are no examples containing MsysHookFunction().
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris

Not supported on:
Not supported on Matrox Corona-II
Not supported on Matrox Genesis
Not supported on Matrox Meteor-II /1394
Not supported on Matrox Meteor-II /Camera Link
Not supported on Matrox Meteor-II /Digital
Not supported on Matrox Meteor-II /Multi-Channel
Not supported on Matrox Meteor-II /Standard
Not supported on Matrox Orion
Not supported on Matrox Odyssey XA
Not supported on Matrox Odyssey XCL
Not supported on Matrox Odyssey XD

Always available on Matrox 4Sight-II/Matrox 4Sight-M
Synopsis
Hook a function to a system event.
Syntax
void MsysHookFunction(
MIL_ID SystemId,
long HookType,
MSYSHOOKFCTPTR HookHandlerPtr,
void *UserDataPtr
)
Description

This function allows you to attach or detach a user-defined function to a specified system event. Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.

Note that functions hooked to an event execute on a distinct thread. This permits the functions to run asynchronously from the operation that fired the event and from functions hooked to other events. Although there is a small queue to permit a certain amount of overlap, hooked functions should not take longer to execute than the period in which two of their associated events can occur. You cannot determine the instance of the event that fired the function. Typically, a hooked function performs the minimum number of operations required and, if necessary, performs longer processes by launching other threads.

You can hook more than one function to an event by making separate calls to MsysHookFunction() for each function that you want to hook. MIL automatically chains and keeps an internal list of all these hooked functions. When a function is hooked, this new function is added to the end of the list. When the event happens, all user-defined functions in the list will be executed in the same order that they were hooked to the event. You can also remove any function from the list; in this case, MIL preserves the order of the remaining functions in the list.

Parameters
SystemId

Specifies the identifier of the system on which to hook a function.

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application ...

 Note that this is only available on a Matrox 4Sight-II system.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function ...

 Note that this is only available on an allocated Matrox CronosPlus, Matrox Morphis, Matrox Helios, or Matrox Solios system.

 HookType

 Specifies the system event to which to hook the function.  This parameter can be set to one of the following values.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_UART_DATA_RECEIVED

 Calls the function when the specified UART receives data. Use MsysInquire() with M_UART_PRESENT to return the number of UARTs available.  Calls the function when the specified UART receives data ...

 Note that this value can be used in combination; see below.

d
e

l

q
r

  Open   Collapse  M_USER_BIT_CHANGE

 Calls the function only when a user-defined input signal changes in accordance with its specified interrupt mode, M_EDGE_RISING or M_EDGE_FALLING (see MsysControl()). It is prudent to verify that the appropriate user-defined signal triggered the hook-handler function. To determine which user-defined signal caused the event, call MsysGetHookInfo() from within your hook-handler function.  Calls the function only when a user-defined input signal changes in accordance with its specified interrupt mode, M_EDGE_RISING or M_EDGE_FALLING (see MsysControl()) ...

b

f

l

Specifics

 User-defined signals are not supported on Matrox Morphis PC/104-Plus. Use the user-defined signals of Matrox 4Sight-M instead.

l

  Open   Collapse  M_WATCHDOG_WARNING

 Calls the function only when the Watchdog warning timer is not reset before the specified interval expires. From within your hook-handler function, you should reset the Watchdog's main timer. If it is not reset, the Host computer will reboot.  Calls the function only when the Watchdog warning timer is not reset before the specified interval expires ...

 The Watchdog is not supported on Matrox Morphis PC/104-Plus.

l

      [Combination constants]

 The value below can be added to the HookType parameter.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse  M_UART_NB(
long M_DEVn

          )

 Specifies which UART to control. Use MsysInquire() with M_UART_PRESENT to determine the number of UARTs on the system.  Specifies which UART to control ...

 Note that this combination value can only be added to M_UART_DATA_RECEIVED.

[Matrox Morphis]

 There is 1 UART available on Matrox Morphis and Matrox Morphis Quad.

 Note that there are no UARTs available on Matrox Morphis PC/104-Plus.

[Matrox Helios XA]

 There are 4 UARTs available.

[Matrox Solios XA]

 There are 4 UARTs available on Matrox Solios XA and only 1 UART available on Matrox Solios XA single analog.

[Matrox Helios XCL and Matrox Solios XCL]

 On the dual-Base version, there are 2 UARTs available.

 On the single-Full version, there is 1 UART available.

d
e

l

q
r

Parameters

M_DEVn

 Specifies a UART to inquire, where n is from 0 to 3.

  Open   Collapse  M_UNHOOK

 Unhooks the specified function if hooked to an event.  Unhooks the specified function if hooked to an event.

b

d
e
f

l

q
r

 HookHandlerPtr

 Specifies the address of the function that should be called when the specified event occurs.  The hook-handler function must be declared as follows:

long MFTYPE HookHandler(
long HookType,

MIL_ID EventId,

void *UserDataPtr

        )

HookType

 Type of system event hooked.

EventId

 Event identifier to pass to MsysGetHookInfo() when inquiring about the hooked event.

UserDataPtr

 Specifies the user data pointer passed to MsysHookFunction().

 Upon successful completion, the hook-handler function should return M_NULL. Note, MSYSHOOKFCTPTR, MFTYPE, and MPTYPE are reserved MIL predefined types for functions and data pointers.

 UserDataPtr

 Specifies the address of the user data that you want to make available to the hook-handler function.  This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.

UART PRESENT EDGE RISING EDGE FALLING UART PRESENT UART DATA RECEIVED  DEFAULT HOST   UART DATA RECEIVED USER BIT CHANGE WATCHDOG WARNING DEVn UNHOOK


MsysInquire

See Also | Example | Availability | MsysHookFunction
User Guide:
Buffer overscan region

Reference:
MdigInquire
MsysAlloc
MsysControl
mdiggrabsequence.c
mdigmultformat.c
mdigprocessmultiple.c
mdispoverlay.c
mdispwindow.c
mgenlc.c
mnatgen.c
Available in MIL-Lite

Available in MIL

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Genesis
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Odyssey XA
Partially supported on Matrox Odyssey XCL
Partially supported on Matrox Odyssey XD
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Inquire about a system setting.
Syntax
long MsysInquire(
MIL_ID SystemId,
long InquireType,
void *UserVarPtr
)
Description

This function inquires about the specified system setting.

Note that you can use MsysControl() to control specific system settings.

Parameters
SystemId

Specifies the system identifier. This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT_HOST

 Specifies the default Host system of the current MIL application.  Specifies the default Host system of the current MIL application.

  Open   Collapse  MIL system identifier

 Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.  Specifies a valid system identifier, which you have allocated using the MsysAlloc() function.

 InquireType

 Specifies the type of system setting about which to inquire.  This parameter can be set to one of the following values:

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  long.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse   M_ACCELERATOR_PRESENT

 Returns whether the processing accelerator is present.  Returns whether the processing accelerator is present ...

d
e

m
n
o

q
r

UserVarPtr info

Return values:
M_NO | The processing accelerator is not present.
M_YES | The processing accelerator is present.

  Open   Collapse   M_ALLOCATION_OVERSCAN_SIZE

 Returns the size of the overscan region used when allocating image buffers, in pixels.  Returns the size of the overscan region used when allocating image buffers, in pixels ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
 Please see
                  MsysControl() with
                  M_ALLOCATION_OVERSCAN_SIZE.

        Note that
        M_DEFAULT is

        not returned.

  Open   Collapse   M_ASYNCHRONOUS_CALL_SUPPORT

 Returns whether the system supports asynchronous function execution or not.  Returns whether the system supports asynchronous function execution or not ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_NO | The system does not support asynchronous execution.
M_YES | The system supports asynchronous execution.

  Open   Collapse   M_BOARD_REVISION

 Returns the board revision number.  Returns the board revision number.

a
b

d
e

j
k
l

p
q
r

  Open   Collapse   M_BOARD_TYPE

 Returns the type of system board.  Returns the type of system board ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_CORONA_II | Matrox Corona-II.
M_CORONA_II_WITH_DIG_MODULE | Matrox Corona-II Digital.
M_CRONOSPLUS | Matrox CronosPlus.
M_GENESIS | Matrox Genesis.
M_GENESIS_LC | Matrox Genesis-LC.
M_GENESIS_PLUS | Matrox GenesisPlus.
M_GENESIS_PRO | Matrox GenesisPro.
M_HELIOS + M_XA + M_QHA | Matrox Helios XA quad-independent.
M_HELIOS + M_XCL + M_DBCL | Matrox Helios XCL dual-Base.
M_HELIOS + M_XCL + M_SFCL | Matrox Helios XCL single-Full.
M_IRIS + P300 | Matrox Iris P300.
M_IRIS + P700 | Matrox Iris P700.
M_IRIS + P1200 | Matrox Iris P1200.
M_METEOR_II_1394 | Matrox Meteor-II /1394.
M_METEOR_II_CL | Matrox Meteor-II /Camera Link.
M_METEOR_II_DIG | Matrox Meteor-II /Digital.
M_METEOR_II_MC | Matrox Meteor-II /Multi-channel.
M_METEOR_II_STD | Matrox Meteor-II /Standard.
M_MORPHIS + M_IO + M_J2K | Matrox Morphis with the I/O module and the JPEG2000 compression accelerator.
M_MORPHIS + M_2VD + M_IO | Matrox Morphis with two video decoders and the I/O module.
M_MORPHIS + M_2VD + M_IO + M_J2K | Matrox Morphis with two video decoders, the I/O module, and the JPEG2000 compression accelerator.
M_MORPHIS + M_4VD+ M_IO | Matrox Morphis with four video decoders and the I/O module.
M_ODYSSEY + M_XA + M_QHA | Matrox Odyssey XA quad-independent.
M_ODYSSEY + M_XCL + M_DBCL | Matrox Odyssey XCL dual-Base.
M_ODYSSEY + M_XCL + M_SFCL | Matrox Odyssey XCL single-Full.
M_ODYSSEY + M_XD + M_QD | Matrox Odyssey digital.
M_ODYSSEY + M_XPRO | Matrox Odyssey Xpro.
M_ODYSSEY + M_XPRO + M_DBCL | Matrox Odyssey Xpro with a Camera Link dual-Base module.
M_ODYSSEY + M_XPRO + M_QD | Matrox Odyssey Xpro with a Digital module.
M_ODYSSEY + M_XPRO + M_QHA | Matrox Odyssey Xpro with a quad-independent Analog module.
M_ODYSSEY + M_XPRO + M_SFCL | Matrox Odyssey Xpro with a Camera Link single-Full module.
M_ODYSSEY + M_XPRO_PLUS | Matrox Odyssey XPRO+.
M_ODYSSEY + M_XPRO_PLUS + M_QD | Matrox Odyssey Xpro+ with a Digitial module.
M_ODYSSEY + M_XPRO_PLUS + M_QHA | Matrox Odyssey Xpro+ with a quad-independent Analog module.
M_ODYSSEY + M_XPRO_PLUS + M_SFCL | Matrox Odyssey Xpro+ with a Camera Link single-Full module.
M_ODYSSEY + M_XPRO_PLUS+M_DBCL | Matrox Odyssey Xpro+ with a Camera Link dual-Base module.
M_ORION | Matrox Orion.
M_ORION_4SIGHT_II_DUAL | Matrox Orion /Dual for the 4Sight-II.
M_ORION_4SIGHT_II_RGB | Matrox Orion /RGB for the 4Sight-II.
M_ORION_4SIGHT_II_STD | Matrox Orion /Standard for the 4Sight-II.
M_SOLIOS + M_XA + M_DA | Matrox Solios XA dual analog PCI-X.
M_SOLIOS + M_XA + M_QA | Matrox Solios XA quad analog PCI-X.
M_SOLIOS + M_XA + M_SA | Matrox Solios XA single analog PCI-X.
M_SOLIOS + M_XCL + M_DBCL | Matrox Solios XCL dual-Base PCI-X Camera Link.
M_SOLIOS + M_XCL + M_SMCL | Matrox Solios XCL medium-Full PCI-X Camera Link.

  Open   Collapse   M_BUS_MASTER_COPY_FROM_HOST

 Returns whether copies from a Host buffer to an M_ON_BOARD buffer are driven by your imaging board (bus master) or by the Host CPU.  Returns whether copies from a Host buffer to an M_ON_BOARD buffer are driven by your imaging board (bus master) or by the Host CPU ...

c

h
i

m
n
o

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_BUS_MASTER_COPY_TO_HOST

 Returns whether copies from an M_ON_BOARD buffer to a Host buffer are driven by your imaging board (bus master) or by the Host CPU.  Returns whether copies from an M_ON_BOARD buffer to a Host buffer are driven by your imaging board (bus master) or by the Host CPU ...

c

h
i

m
n
o

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_COM_PORT_NUMBER

 Returns the Microsoft Windows COM port number associated with the specified UART. Note that the number of UARTs available differs, depending on the version of your board.  Returns the Microsoft Windows COM port number associated with the specified UART ...

 You must specify which COM port to inquire. See below for combination values.

d
e

l

q
r

  Open   Collapse   M_CPU_SPEED

 Returns the CPU speed of the G4 PowerPC microprocessor, in MHz.  Returns the CPU speed of the G4 PowerPC microprocessor, in MHz.

m
n
o

  Open   Collapse   M_CURRENT_THREAD_ID

 Returns the identifier of the current system thread. This identifier can be used with the thread module.  Returns the identifier of the current system thread ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Data type:
                  MIL_ID

  Open   Collapse   M_DCF_SUPPORTED

 Returns whether the system supports downloadable digitizer configuration format (DCF) files.  Returns whether the system supports downloadable digitizer configuration format (DCF) files.

a
b
c
d
e

g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_DEFAULT_PITCH_BYTE

 Returns the value MIL uses to determine the pitch, in bytes, of the buffers allocated on the system.  Returns the value MIL uses to determine the pitch, in bytes, of the buffers allocated on the system.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_DIGITAL_MODULE_PRESENT

 Returns whether the companion digital-input board is present or not.  Returns whether the companion digital-input board is present or not ...

a

UserVarPtr info

Return values:
M_FALSE | Digital module is not present.
M_TRUE | Digital module is present.

  Open   Collapse   M_DIGITIZER_NUM

 Returns the total number of possible independent acquisition paths on the system.  Returns the total number of possible independent acquisition paths on the system ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:

 0 <= Value
 The number independent acquisition paths available.

Specifics

 When dealing with a cluster of boards featuring Matrox Odyssey Xpro, the total number of independent acquisition paths available includes those of the frame grabber modules attached to any Matrox Odyssey Xpro board (or PMC board) in the cluster. The total number can be from 0 to 31. Use MsysInquire() with M_DIGITIZER_TYPE + M_DEVn to return the type of frame grabber module to which an independent acquisition path belongs.

m
n
o

  Open   Collapse   M_DIGITIZER_TYPE

 Returns the type of frame grabber(s) available to allocate a digitizer on the system. If there are multiple types, see below for combination values.  Returns the type of frame grabber(s) available to allocate a digitizer on the system ...

 When dealing with a cluster of boards featuring Matrox Odyssey Xpro, the total number of acquisition paths available includes those of the frame grabber modules attached to any Matrox Odyssey Xpro board (or PMC board) in the cluster. This total number can be from 0 to 31. Use MsysInquire() with M_DIGITIZER_NUM to return the total number of frame grabber modules in the cluster.

m
n
o

UserVarPtr info

Return values:
M_DBCL | Matrox Odyssey XCL dual-Base Camera Link.
M_QD | Matrox Odyssey XD.
M_QHA | Matrox Odyssey XA quad-independent.
M_SFCL | Matrox Odyssey XCL single-Full Camera Link.

  Open   Collapse   M_DISPLAY_OUTPUT_NUM

 Returns the number of video output controllers available on your Matrox imaging board.  Returns the number of video output controllers available on your Matrox imaging board ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:

 0 <= Value
 The number of video output controllers.

  Open   Collapse   M_FAST_MEMORY_FREE

 Returns the total amount of free on-board fast processing memory, in bytes. Note that this memory might not be contiguous.  Returns the total amount of free on-board fast processing memory, in bytes ...

m
n
o

  Open   Collapse   M_FAST_OVERSCAN_BUFFER

 Returns whether image buffers, allocated on the system, will be allocated with an overscan region.  Returns whether image buffers, allocated on the system, will be allocated with an overscan region ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_HEAP_FREE

 Returns the amount of free on-board heap space, in bytes.  Returns the amount of free on-board heap space, in bytes.

m
n
o

  Open   Collapse   M_HEAP_SIZE

 Returns the total amount of on-board memory available for things other than buffers, in bytes (for example, blob results).  Returns the total amount of on-board memory available for things other than buffers, in bytes (for example, blob results).

m
n
o

  Open   Collapse   M_INIT_FLAG

 Returns the system initialization flag.  Returns the system initialization flag ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_COMPLETE, M_DEFAULT, M_PARTIAL (details)

  Open   Collapse   M_LOCATION

 Returns the location of the specified system.  Returns the location of the specified system ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_LOCAL | Local system.
M_REMOTE | Remote system.

  Open   Collapse   M_MEMORY_FREE

 Returns the total amount of free on-board processing memory, in bytes. Note that this memory might not be contiguous.  Returns the total amount of free on-board processing memory, in bytes ...

 Note that, if the specified system is a JPEG2000 image compression/decompression accelerator, the amount of free on-board processing memory on the JPEG2000 module is returned. Otherwise, the amount of free grab memory will be returned.

d
e

l
m
n
o

  Open   Collapse   M_MEMORY_SIZE

 Returns the amount of on-board processing memory, in Mbytes.  Returns the amount of on-board processing memory, in Mbytes.

d
e

l
m
n
o

q
r

  Open   Collapse   M_MODIFIED_BUFFER_HOOK_MODE

 Returns whether to run user-defined functions hooked to a buffer modification on separate threads, up to the number of CPUs present in the computer.  Returns whether to run user-defined functions hooked to a buffer modification on separate threads, up to the number of CPUs present in the computer ...

d
e

l

q
r

UserVarPtr info

Return values:
M_MULTI_THREAD, M_SINGLE_THREAD (details)

  Open   Collapse   M_NATIVE_CLUSTER_NUMBER

 Returns the number of the cluster to which the board belongs.  Returns the number of the cluster to which the board belongs ...

m
n
o

UserVarPtr info

Return values:

 0 <= Value
 The number of the cluster.

  Open   Collapse   M_NATIVE_ID

 Returns the identifier of the Native Library device that corresponds to the given MIL system.  Returns the identifier of the Native Library device that corresponds to the given MIL system.

c

h
i

m
n
o

  Open   Collapse   M_NATIVE_THREAD_ID

 Returns the Native Library identifier of the thread currently used by MIL.  Returns the Native Library identifier of the thread currently used by MIL.

c

h
i

m
n
o

  Open   Collapse   M_NUMBER

 Returns the board number of the system.  Returns the board number of the system ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_DEFAULT, M_DEVn (details)

  Open   Collapse   M_OWNER_APPLICATION

 Returns the MIL identifier of the application on which the system has been allocated.  Returns the MIL identifier of the application on which the system has been allocated ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Data type:
                  MIL_ID

  Open   Collapse   M_PROCESSING_SYSTEM

 Returns the identifier of the system on which to process allocated buffers.  Returns the identifier of the system on which to process allocated buffers ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Data type:
                  MIL_ID

  Open   Collapse   M_PROCESSING_SYSTEM_TYPE

 Returns the type of the system (on-board or Host) used to process allocated buffers.  Returns the type of the system (on-board or Host) used to process allocated buffers ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_SYSTEM_GENESIS_TYPE | Matrox Genesis.
M_SYSTEM_HELIOS_TYPE | Matrox Helios.
M_SYSTEM_HOST_TYPE | Host.
M_SYSTEM_IRIS | Matrox Iris.
M_SYSTEM_ODYSSEY_TYPE | Matrox Odyssey.

  Open   Collapse   M_PROCESSOR_NUM

 Returns the number of processors (CPUs) available on the allocated Matrox imaging board.  Returns the number of processors (CPUs) available on the allocated Matrox imaging board ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:

 0 <= Value
 The number of processors available.

  Open   Collapse   M_SERIAL_NUMBER

 Returns the serial number of the Matrox Imaging board, as a string.  Returns the serial number of the Matrox Imaging board, as a string ...

b
c
d
e
f
g

l
m
n
o
p
q
r

UserVarPtr info

Data type:
                  array of type MIL_TEXT_CHAR

            Array size:  To determine the size of the array required to store the serial number, use MsysInquire() with M_SERIAL_NUMBER_SIZE.

  Open   Collapse   M_SERIAL_NUMBER_SIZE

 Returns the length of the string returned by M_SERIAL_NUMBER.  Returns the length of the string returned by M_SERIAL_NUMBER.

b
c
d
e
f
g

l
m
n
o
p
q
r

  Open   Collapse   M_SHARED_MEMORY_FREE

 Returns the total amount of free on-board shared memory, in bytes.  Returns the total amount of free on-board shared memory, in bytes.

d
e

m
n
o

q
r

  Open   Collapse   M_SYSTEM_DESCRIPTOR

 Returns the system descriptor set using MsysAlloc().  Returns the system descriptor set using MsysAlloc() ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Data type:
                  array of type MIL_TEXT_CHAR

            Array size:  To determine the size of the array required to store the system descriptor, use MsysInquire() with M_SYSTEM_DESCRIPTOR_SIZE.

Return values:
M_SYSTEM_CORONA_II, M_SYSTEM_CRONOSPLUS, M_SYSTEM_DEFAULT, M_SYSTEM_GENESIS, M_SYSTEM_HELIOS, M_SYSTEM_HOST, M_SYSTEM_IRIS, M_SYSTEM_METEOR_II, M_SYSTEM_METEOR_II_1394, M_SYSTEM_METEOR_II_CL, M_SYSTEM_METEOR_II_DIG, M_SYSTEM_MORPHIS, M_SYSTEM_ODYSSEY, M_SYSTEM_ORION, M_SYSTEM_SOLIOS (details)

  Open   Collapse   M_SYSTEM_DESCRIPTOR_SIZE

 Returns the length of the string returned by M_SYSTEM_DESCRIPTOR.  Returns the length of the string returned by M_SYSTEM_DESCRIPTOR.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_SYSTEM_TYPE

 Returns the type of system allocated.  Returns the type of system allocated ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_SYSTEM_CORONA_II_TYPE | Matrox Corona-II.
M_SYSTEM_CRONOSPLUS_TYPE | Matrox CronosPlus.
M_SYSTEM_GENESIS_TYPE | Matrox Genesis.
M_SYSTEM_HELIOS_TYPE | Matrox Helios.
M_SYSTEM_HOST_TYPE | Host.
M_SYSTEM_IRIS_TYPE | Matrox Iris.
M_SYSTEM_METEOR_II_1394_TYPE | Matrox Meteor-II 1394.
M_SYSTEM_METEOR_II_CL_TYPE | Matrox Meteor-II Camera Link.
M_SYSTEM_METEOR_II_DIG_TYPE | Matrox Meteor-II Digital.
M_SYSTEM_METEOR_II_TYPE | Matrox Meteor-II Standard and the Matrox Meteor-II Multi-channel.
M_SYSTEM_MORPHIS_TYPE | Matrox Morphis.
M_SYSTEM_ODYSSEY_TYPE | Matrox Odyssey.
M_SYSTEM_ORION_TYPE | Matrox Orion.
M_SYSTEM_SOLIOS_TYPE | Matrox Solios.

  Open   Collapse   M_THREAD_MODE

 Returns the thread execution mode for all threads allocated on the system.  Returns the thread execution mode for all threads allocated on the system ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

UserVarPtr info

Return values:
M_DEFAULT, M_SYNCHRONOUS (details)

  Open   Collapse   M_TIMEOUT

 Returns the maximum amount of time (in secs) for the Host to wait for a synchronous function to return before generating a time-out error.  Returns the maximum amount of time (in secs) for the Host to wait for a synchronous function to return before generating a time-out error ...

c
d
e
f

l
m
n
o

UserVarPtr info

Return values:
 Please see
                  MsysControl() with
                  M_TIMEOUT.

      [Combination constants]

[Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

 The following value can be added to M_DIGITIZER_TYPE to inquire the frame grabber(s) available to allocate a digitizer. This is useful when dealing with a cluster.

Open Collapse Value | Description
Open Collapse M_DEVn | Specifies the number of the acquisition path to inquire, where n is from 0 to 31 and represents the acquisition path number. Note that if n is greater than the number of acquisition paths available, an error is generated. Specifies the number of the acquisition path to inquire, where n is from 0 to 31 and represents the acquisition path number ...

[Matrox Helios XA, Matrox Helios XCL, Matrox Morphis, Matrox Solios XA, and Matrox Solios XCL]

 The following inquire types allow you to inquire UART settings.

[Matrox Morphis]

 UARTS are not supported on Matrox Morphis PC/104-Plus.

 Note that for other Matrox imaging boards that have a UART, but are not supported with the constants below, see MdigInquire().

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  long.

  Open   Collapse  Value
Description

  Open   Collapse   M_UART_BYTES_READ

 Waits for the UART read operation (using MsysControl() with M_UART_READ_STRING) to complete before returning the number of bytes read from the UART.  Waits for the UART read operation (using MsysControl() with M_UART_READ_STRING) to complete before returning the number of bytes read from the UART.

  Open   Collapse   M_UART_BYTES_WRITTEN

 Waits for the UART write operation (using MsysControl() with M_UART_WRITE_STRING) to complete before returning the number of bytes written to the UART.  Waits for the UART write operation (using MsysControl() with M_UART_WRITE_STRING) to complete before returning the number of bytes written to the UART.

  Open   Collapse   M_UART_DATA_LENGTH

 Returns the number of data bits per character that is sent or received by the UART.  Returns the number of data bits per character that is sent or received by the UART ...

UserVarPtr info

Return values:
7, 8 (details)

  Open   Collapse   M_UART_DATA_PENDING

 Returns whether the UART input buffer has pending data or not.  Returns whether the UART input buffer has pending data or not ...

UserVarPtr info

Return values:
M_FALSE | The UART input buffer does not have pending data.
M_TRUE | The UART input buffer has pending data.

  Open   Collapse   M_UART_INTERFACE_TYPE

 Returns the type of interface used by the UART.  Returns the type of interface used by the UART ...

UserVarPtr info

Return values:
M_RS232 | An RS-232 interface is used.
M_RS485 | An RS-485 interface is used.

  Open   Collapse   M_UART_PARITY

 Returns the UART parity setting.  Returns the UART parity setting ...

UserVarPtr info

Return values:
M_DISABLE, M_EVEN, M_ODD (details)

  Open   Collapse   M_UART_PRESENT

 Returns the number of UARTs on the system.  Returns the number of UARTs on the system.

  Open   Collapse   M_UART_READ_STRING_LENGTH

 Returns the number of bytes to read when calling MsysControl() with M_UART_READ_STRING.  Returns the number of bytes to read when calling MsysControl() with M_UART_READ_STRING ...

UserVarPtr info

Return values:
M_DEFAULT | Returns that the length is delimited by M_UART_STRING_DELIMITER.
Value | Returns the length of the string, in bytes.

  Open   Collapse   M_UART_READ_STRING_MAXIMUM_LENGTH

 Returns the maximum length of the string to be read using M_UART_READ_STRING.  Returns the maximum length of the string to be read using M_UART_READ_STRING ...

UserVarPtr info

Return values:
 Please see
                  MsysControl() with
                  M_UART_READ_STRING_MAXIMUM_LENGTH.

M_DEFAULT | Returns the maximum length of the string, in bytes.
Value | Returns the maximum length of the string, in bytes.

  Open   Collapse   M_UART_SPEED

 Returns the baud rate of the UART.  Returns the baud rate of the UART ...

UserVarPtr info

Return values:
300; 600; 1200; 1800; 2400; 3600; 4800; 7200; 9600; 14400; 19200; 28800; 38400; 57600; 76800; 115200; 128000; 256000 (details)

  Open   Collapse   M_UART_STOP_BITS

 Returns the number of extra data bit(s) that are added to each character to indicate the end of a character.  Returns the number of extra data bit(s) that are added to each character to indicate the end of a character ...

UserVarPtr info

Return values:
1, 2 (details)

  Open   Collapse   M_UART_STRING_DELIMITER

 Returns the character used to terminate strings of incoming or outgoing data. The delimiter is used but not sent when writing data with M_UART_WRITE_STRING; it is read for incoming data with M_UART_READ_STRING.  Returns the character used to terminate strings of incoming or outgoing data ...

UserVarPtr info

Return values:
 Please see
                  MsysControl() with
                  M_UART_STRING_DELIMITER.

  Open   Collapse   M_UART_TIMEOUT

 Returns the maximum time (in msec) to wait between each byte when reading incoming data.  Returns the maximum time (in msec) to wait between each byte when reading incoming data ...

UserVarPtr info

Return values:
M_INFINITE, Value (details)

  Open   Collapse   M_UART_WRITE_STRING_LENGTH

 Returns the length of the string to be sent to the UART for transmission.  Returns the length of the string to be sent to the UART for transmission ...

UserVarPtr info

Return values:
 Please see
                  MsysControl() with
                  M_UART_WRITE_STRING_LENGTH.

[Matrox Helios XA, Matrox Helios XCL, Matrox Morphis, Matrox Solios XA, and Matrox Solios XCL]

 The following value can be added to M_COM_PORT_NUMBER and any M_UART... inquire value, listed above, except M_UART_PRESENT. Use MsysInquire() with M_UART_PRESENT to determine the number of UARTS on the system.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  long.

  Open   Collapse  Value
Description

  Open   Collapse  M_UART_NB(
long DeviceToInquire

          )

 Specifies which UART should be inquired.  Specifies which UART should be inquired ...

[Matrox Morphis]

 There is 1 UART available on Matrox Mprhis and Matrox Morphis Quad.

[Matrox Helios XA]

 There are 4 UARTs available.

[Matrox Solios XA]

 There are 4 UARTs available on Matrox Solios XA and only 1 UART available on Matrox Solios XA single analog.

[Matrox Helios XCL and Matrox Solios XCL]

 On the dual-Base version, there are 2 UARTs available.

 On the single-Full version, there is 1 UART available.

Parameters

DeviceToInquire

 Specifies a device (UART) to inquire.

  Open   Collapse  Value
Description

  Open   Collapse  M_DEVn

 Specifies the device to inquire, where n can be from 0 to 15.  Specifies the device to inquire, where n can be from 0 to 15 ...

[Matrox Morphis]

 The following inquire types and inquire values specify the settings for the Watchdog.

 The Watchdog is not supported on Matrox Morphis PC/104-Plus.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  long.

  Open   Collapse  Value
Description

  Open   Collapse   M_WATCHDOG_MODE

 Returns the current state of the Watchdog.  Returns the current state of the Watchdog ...

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

  Open   Collapse   M_WATCHDOG_PRESENT

 Returns whether Watchdog circuitry is present.  Returns whether Watchdog circuitry is present ...

UserVarPtr info

Return values:
M_FALSE | Watchdog circuitry is not present.
M_TRUE | Watchdog circuitry is present.

  Open   Collapse   M_WATCHDOG_REBOOT_TIMEOUT

 Returns the timeout value of the Watchdog's reboot timer, in msec.  Returns the timeout value of the Watchdog's reboot timer, in msec ...

UserVarPtr info

Return values:
 Please see
                  MsysControl() with
                  M_WATCHDOG_REBOOT_TIMEOUT.

  Open   Collapse   M_WATCHDOG_RESET_COUNTER

 Returns the number of times the Watchdog has rebooted your computer.  Returns the number of times the Watchdog has rebooted your computer ...

UserVarPtr info

Return values:

 Value
 The number of Watchdog reboots.

  Open   Collapse   M_WATCHDOG_TIMEOUT

 Returns the timeout value of the Watchdog's main timer, in msec.  Returns the timeout value of the Watchdog's main timer, in msec ...

UserVarPtr info

Return values:
 Please see
                  MsysControl() with
                  M_WATCHDOG_TIMEOUT.

  Open   Collapse   M_WATCHDOG_WARNING_TIME

 Returns the timeout value of the Watchdog's warning timer, in msec.  Returns the timeout value of the Watchdog's warning timer, in msec ...

UserVarPtr info

Return values:
M_INFINITE, Value (details)

[Matrox CronosPlus, Matrox Iris, and Matrox Morphis]

 The following values allow you to inquire user-defined signals.

 Note that the following are available on Matrox 4Sight-II and Matrox 4Sight-M, even without any additional Matrox Imaging board(s), and on Matrox Iris, Matrox Morphis, and Matrox CronosPlus.

[Matrox Morphis]

 User-defined signals are not supported on Matrox Morphis PC/104-Plus. Use the user-defined signals of Matrox 4Sight-M instead.

 Note that for other Matrox imaging boards that are not supported with the constants below, see MdigInquire().

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of
                a
                  long.

  Open   Collapse  Value
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

  Open   Collapse   M_USER_BIT_COUNT_IN

 Returns the number of user-defined signals that can be used for input.  Returns the number of user-defined signals that can be used for input ...

 This count includes the number of input and I/O user-defined signals.

b

f

l

UserVarPtr info

Return values:

 Value
 Number of user-defined signals that can be used for input.

  Open   Collapse   M_USER_BIT_COUNT_OUT

 Returns the number of user-defined signals that can be used for output.  Returns the number of user-defined signals that can be used for output ...

 This count includes the number of output and I/O user-defined signals.

b

f

l

UserVarPtr info

Return values:

 Value
 Number of user-defined signals that can be used for output.

  Open   Collapse   M_USER_BIT_INTERRUPT_MODE

 Returns the type of functional-state change upon which to generate an interrupt. Note that this only applies to user-defined input signals.  Returns the type of functional-state change upon which to generate an interrupt ...

b

f

l

UserVarPtr info

Return values:
M_EDGE_FALLING, M_EDGE_RISING (details)

Specifics

 This is only available with user-defined signal 0.

b

 You must specify the user-defined signal to inquire. See below for combination values.

f

l

  Open   Collapse   M_USER_BIT_INTERRUPT_STATE

 Returns whether to generate an interrupt when the functional state for the user-defined signal changes. Note that this only applies to user-defined input signals.  Returns whether to generate an interrupt when the functional state for the user-defined signal changes ...

b

f

l

UserVarPtr info

Return values:
M_DISABLE, M_ENABLE (details)

Specifics

 This is only available with user-defined signal 0.

b

 You must specify the user-defined signal(s) to inquire. See below for combination values.

f

l

  Open   Collapse   M_USER_BIT_MODE

 Returns the mode of the specified I/O user-defined signal(s).  Returns the mode of the specified I/O user-defined signal(s) ...

 You must specify the user-defined signal(s) to inquire. See below for combination values.

l

UserVarPtr info

Return values:
Bit-encoded value, M_INPUT, M_OUTPUT (details)

  Open   Collapse   M_USER_BIT_VALUE_IN

 Returns the state of the current user bit on the specified user-defined signal(s).  Returns the state of the current user bit on the specified user-defined signal(s) ...

 You must specify the user-defined signal(s) to inquire. See below for combination values.

b

f

l

UserVarPtr info

Return values:
Bit-encoded value | Returns the state of the current bit on the specified user-defined signals. Bits set to 1 in the bit-encoded value set their corresponding user-defined signals to on. Bits set to 0 in the bit-encoded value set their corresponding user-defined signals to off.
M_OFF | Returns that the user-defined signal is set to off.
M_ON | Returns that the user-defined signal is set to on.

  Open   Collapse   M_USER_BIT_VALUE_OUT

 Returns the state of the current user bit on the specified user-defined signal(s). Note that if used with user-defined signal(s) specifically reserved for input, an error will be returned.  Returns the state of the current user bit on the specified user-defined signal(s) ...

 You must specify the user-defined signal(s) to inquire. See below for combination values.

b

f

l

UserVarPtr info

Return values:
Bit-encoded value, M_OFF, M_ON (details)

      [Combination constants]

[Matrox CronosPlus, Matrox Iris, and Matrox Morphis]

 One of the following values must be added to M_USER_BIT_VALUE_IN, M_USER_BIT_VALUE_OUT, M_USER_BIT_INTERRUPT_STATE, and M_USER_BIT_MODE for Matrox 4Sight-II, Matrox 4Sight-M, Matrox CronosPlus, Matrox Iris, and/or Matrox Morphis.

 See the Board Specific Notes for a listing of available user-defined signals and their corresponding numbers in MIL.

  Open   Collapse  Value
Description

  Open   Collapse  M_BIT_MASK(
long Bit_encoded_value

          )

 Specifies a bit-encoded mask value that identifies the group of user-defined signals to inquire.  Specifies a bit-encoded mask value that identifies the group of user-defined signals to inquire ...

 Enabled bits in the mask value identify which user-defined signals to be inquired. Note that this value is only available when using a bit-encoded inquire value.

 Note that this value cannot be added to M_USER_BIT_INTERRUPT_MODE and M_USER_BIT_INTERRUPT_STATE.

Parameters

Bit_encoded_value

 Specifies the bit-encoded value.

  Open   Collapse   0 <= Value

 Specifies a specific user-defined signal.  Specifies a specific user-defined signal ...

 Note that in this case, the inquire value cannot be set to a bit-encoded value.

 UserVarPtr

      Accepts the address of one of the following (see above for specifics on which is expected):

  • array of type MIL_TEXT_CHAR
    •

  • long
    •

  • MIL_ID
    •

 Specifies the address in which to write the requested information.  When MsysInquire() also returns the requested information, you can set this parameter to M_NULL.

Return value

 The returned value is the requested information, usually cast to a long. For inquire types which return a value cast to MIL_TEXT_CHAR, the returned value is M_NULL.

Remark

  •  Note that M_USER_BIT... inquire types are available on Matrox 4Sight-II and Matrox 4Sight-M even without any additional Matrox imaging boards, and on Matrox CronosPlus and Matrox Morphis, unless otherwise specified. For more information on user-defined signals, refer to the User-defined signals for Matrox 4Sight section in
          Chapter 11: Matrox 4Sight section of the Board Specific Notes. To see the information regarding the M_USER_BIT... inquire types if you have a Matrox 4Sight-II or Matrox 4Sight-M, select Matrox Morphis as your board type in the the Customizing options section in
          Chapter 0: About Matrox MIL help.
    •

DIGITIZER TYPE DEVn DIGITIZER NUM SERIAL NUMBER SIZE SERIAL NUMBER SYSTEM DESCRIPTOR SIZE SYSTEM DESCRIPTOR DIGITIZER TYPE UART READ STRING UART WRITE STRING UART READ STRING UART STRING DELIMITER UART READ STRING UART WRITE STRING UART READ STRING COM PORT NUMBER UART PRESENT UART PRESENT USER BIT VALUE IN USER BIT VALUE OUT USER BIT INTERRUPT STATE USER BIT MODE USER BIT INTERRUPT MODE USER BIT INTERRUPT STATE  DEFAULT HOST   ACCELERATOR PRESENT ALLOCATION OVERSCAN SIZE ASYNCHRONOUS CALL SUPPORT BOARD REVISION BOARD TYPE BUS MASTER COPY FROM HOST BUS MASTER COPY TO HOST COM PORT NUMBER CPU SPEED CURRENT THREAD ID DCF SUPPORTED DEFAULT PITCH BYTE DIGITAL MODULE PRESENT  DIGITIZER NUM DIGITIZER TYPE DISPLAY OUTPUT NUM  FAST MEMORY FREE FAST OVERSCAN BUFFER HEAP FREE HEAP SIZE INIT FLAG  LOCATION MEMORY FREE MEMORY SIZE MODIFIED BUFFER HOOK MODE NATIVE CLUSTER NUMBER NATIVE ID NATIVE THREAD ID NUMBER OWNER APPLICATION  PROCESSING SYSTEM  PROCESSING SYSTEM TYPE  PROCESSOR NUM SERIAL NUMBER SERIAL NUMBER SIZE SHARED MEMORY FREE SYSTEM DESCRIPTOR  SYSTEM DESCRIPTOR SIZE SYSTEM TYPE THREAD MODE TIMEOUT DEVn UART BYTES READ UART BYTES WRITTEN UART DATA LENGTH UART DATA PENDING UART INTERFACE TYPE UART PARITY UART PRESENT UART READ STRING LENGTH UART READ STRING MAXIMUM LENGTH UART SPEED UART STOP BITS UART STRING DELIMITER UART TIMEOUT UART WRITE STRING LENGTH  DEVn WATCHDOG MODE WATCHDOG PRESENT WATCHDOG REBOOT TIMEOUT WATCHDOG RESET COUNTER WATCHDOG TIMEOUT WATCHDOG WARNING TIME USER BIT COUNT IN USER BIT COUNT OUT USER BIT INTERRUPT MODE USER BIT INTERRUPT STATE USER BIT MODE USER BIT VALUE IN USER BIT VALUE OUT


thr

Mthr functions

Example | Availability
There are no examples containing thr().
Available in MIL-Lite

Available in MIL
Synopsis
The thread module supports allocation of MIL thread contexts and synchronization events. Using the functions of the thread module, you can also control the created MIL thread contexts and events, inquire about various settings, and synchronize execution of multiple threads.
Functions
  • MthrAlloc
  • MthrControl
  • MthrFree
  • MthrInquire
  • MthrWait


MthrAlloc

See Also | Example | Availability | MthrControl
User Guide:
Multi-threading

Reference:
MthrControl
MthrInquire
MthrWait
dtkobjecttracking.c
mdighook.c
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Allocate a MIL thread context or event.
Syntax
MIL_ID MthrAlloc(
MIL_ID SystemId,
long ObjectType,
long ControlFlag,
MTHREADFCTPTR ThreadFctPtr,
void *UserPtr,
MIL_ID *ThreadOrEventId
)
Description

This function allocates a MIL thread context or an event.

Threads are function streams, used to ensure sequential execution of operations within the same thread, while allowing simultaneous yet independent execution of operations in other threads. MthrAlloc() can allocate threads using two different methods:

  • With the first method (M_THREAD), MthrAlloc() creates a MIL thread context for the new thread, and allows you to specify a pointer to a function that will be executed by the thread. When a thread contains a function call whose target processor is an on-board processor that supports multi-threading, MIL automatically creates a corresponding thread on that system's on-board processor. The functions of the thread module allow you to synchronize threads running on the Host and/or various MIL systems.
  • With the second method, MthrAlloc() creates a selectable thread (M_SELECTABLE_THREAD). Selectable threads are threads executed on an on-board processor that supports multi-threading but can be controlled from a single corresponding thread on the Host. Use MthrControl() with M_THREAD_SELECT to send MIL functions to be executed by a selectable thread.

For more information on these two types of threads, see the Multi-threading section in Chapter 22: Using MIL with multi-processing and under multi-thread systems .

A MIL event is a synchronization marker that can signal the completion of a required set of functions in one thread to other threads. MthrAlloc() can allocate MIL events, or map a new MIL event to an existing MIL event.

To control or inquire about a MIL thread context or event, use the MthrControl() or the MthrInquire() function, respectively. To synchronize the execution of threads, use MthrWait().

Parameters
SystemId

Specifies the identifier of the system on which to allocate a MIL thread context or an event.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_ALL

 Specifies that the identifier of the allocated MIL thread context or event can be recognized by any multi-thread system allocated in your application.  Specifies that the identifier of the allocated MIL thread context or event can be recognized by any multi-thread system allocated in your application.

  Open   Collapse  MIL system identifier

 Specifies the MIL identifier of the required system.  Specifies the MIL identifier of the required system.

 ObjectType

 Specifies the type of object to allocate.  This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_EVENT

 Allocates a new synchronization event on the system specified by the SystemId parameter.  Allocates a new synchronization event on the system specified by the SystemId parameter.

  Open   Collapse  M_EVENT_CREATE

 Creates a new synchronization event on the specified system, which maps to the event specified by the ControlFlag parameter and is in the same state. The created event allows for multiple, individual on-board processors to change and read the state of the same event.  Creates a new synchronization event on the specified system, which maps to the event specified by the ControlFlag parameter and is in the same state ...

  Open   Collapse  M_SELECTABLE_THREAD

 Allocates a selectable thread on the specified multi-threaded system. This allows you to synchronize the execution of functions on an on-board processor without creating a Host thread. Note that you cannot allocate selectable threads when the SystemId parameter is set to M_ALL.  Allocates a selectable thread on the specified multi-threaded system ...

 Use MthrControl() with M_THREAD_SELECT to select the on-board thread to which to send the functions.

  Open   Collapse  M_THREAD

 Allocates a thread and associates it with a MIL thread context. If the target processor is an on-board processor of a system that supports multi-threading (such as Matrox Odyssey), MIL automatically creates, and eventually terminates, an on-board thread for each thread that sends commands to the board.  Allocates a thread and associates it with a MIL thread context ...

 ControlFlag

 Specifies the initialization state of the MIL thread context or event, or the identifier of an existing MIL event.

 This parameter should be set to one of the following values:

  Open   Collapse  Value
Description

  Open   Collapse  M_DEFAULT

 Specifies the initialization state. This is the only setting available for threads. For events, M_DEFAULT is the same as M_NOT_SIGNALED + M_AUTO_RESET.  Specifies the initialization state ...

  Open   Collapse  M_NOT_SIGNALED

 Initializes the event as not signaled.  Initializes the event as not signaled ...

 Note that this value must be used in combination with another value; see below.

  Open   Collapse  M_SIGNALED

 Initializes the event as signaled.  Initializes the event as signaled ...

 Note that this value must be used in combination with another value; see below.

  Open   Collapse  MIL event identifier

 Specifies the identifier of the user-allocated MIL event to which to map a new M_EVENT_CREATE event.  Specifies the identifier of the user-allocated MIL event to which to map a new M_EVENT_CREATE event ...

 Cannot be used with events whose identifiers can be recognized by multiple multi-thread systems (SystemId parameter set to M_ALL).

      [Combination constants]

 The values below must be added to M_SIGNALED or M_NOT_SIGNALED.

  Open   Collapse  Value
Description

  Open   Collapse  M_AUTO_RESET

 Specifies that the event is reset automatically.  Specifies that the event is reset automatically ...

 The state of this type of event is automatically reset to M_NOT_SIGNALED upon the return of a call to MthrWait() with M_EVENT_SYNCHRONIZE or M_EVENT_WAIT.

 Events that are reset automatically are useful in applications where only one thread waits on a specific event.

  Open   Collapse  M_MANUAL_RESET

 Specifies that the event is reset manually.  Specifies that the event is reset manually ...

 The state of this type of event remains unchanged until a call to MthrControl() with M_EVENT_SET is issued.

 Events that are reset manually are useful when multiple threads wait on a specific event.

 ThreadFctPtr

 Specifies the address of the function that will be executed by the new thread (M_THREAD). For all other objects, this parameter should be set to M_NULL.

 The function must include calls to all functions that you consider as being part of one thread, and be declared as follows:

unsigned long MFTYPE FunctionToCall(
void *UserDataPtr

        )

UserDataPtr

 Specifies a pointer to user data that is passed to the UserPtr parameter of MthrAlloc().

 When MthrAlloc() is called with the ObjectType parameter set to M_THREAD, UserPtr must be passed a void pointer to the user data necessary to execute the FunctionToCall() function.

 UserPtr

 Specifies the address of user data for threads (M_THREAD). For all other objects, this parameter should be set to M_NULL.

 ThreadOrEventId

 Specifies the address of the variable in which to write the MIL identifier of the created MIL thread context or event.

 Since the MthrAlloc() function also returns the requested information, you can set this parameter to M_NULL.

Return value

 The returned value is the identifier of the new MIL thread or event. If allocation fails, M_NULL is returned as the identifier.

THREAD SELECTABLE THREAD THREAD SELECT ALL THREAD SELECT DEFAULT NOT SIGNALED AUTO RESET EVENT CREATE ALL SIGNALED NOT SIGNALED NOT SIGNALED EVENT SYNCHRONIZE EVENT WAIT EVENT SET THREAD THREAD THREAD  ALL   EVENT EVENT CREATE SELECTABLE THREAD THREAD  DEFAULT SIGNALED NOT SIGNALED  AUTO RESET MANUAL RESET


MthrControl

See Also | Example | Availability | MthrAlloc | MthrFree
User Guide:
Multi-threading

Reference:
MsysAlloc
MsysControl
MsysInquire
MthrAlloc
dtkobjecttracking.c
mdiggrabsequence.c
mdighook.c
mmorphisjpeg2000.c
mthread.c
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox CronosPlus
Partially supported on Matrox Genesis
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Camera Link
Partially supported on Matrox Meteor-II /Digital
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Morphis
Partially supported on Matrox Orion
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Control MIL thread context or MIL event settings.
Syntax
void MthrControl(
MIL_ID ThreadOrEventId,
long ControlType,
double ControlValue
)
Description

This function controls MIL thread context or MIL event settings.

Parameters
ThreadOrEventId

Specifies the identifier of a user-allocated MIL thread context or event, allocated using MthrAlloc(). This parameter can also be set to the MIL identifier of a system.

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default MIL thread context identifier associated with the current Host thread.  Specifies the default MIL thread context identifier associated with the current Host thread.

  Open   Collapse  MIL thread context/event/system identifier

 Specifies the identifier of a user-allocated MIL thread context or event (MthrAlloc()), or a valid system identifier (MsysAlloc()).  Specifies the identifier of a user-allocated MIL thread context or event (MthrAlloc()), or a valid system identifier (MsysAlloc()) ...

 When the parameter is set to the MIL identifier of a system, the function controls the current thread on the particular system.

 ControlType

 Specifies the type of setting to control.

See the Parameter associations section for possible values.

 ControlValue

 Specifies the new value to assign to the setting specified by the ControlType parameter.

See the Parameter associations section for possible values.

Parameter associations

Possible values for the ControlType and ControlValue
         parameters are described below.

 The following ControlType and corresponding ControlValue settings can be specified to control MIL thread contexts:

  Open   Collapse  ControlType
Description
corona-II
       (a)
cronosplus
       (b)
genesis
       (c)
helios xa
       (d)
helios xcl
       (e)
Matrox Iris
       (f)
met-II /1394
       (g)
met-II /cl
       (h)
met-II /dig
       (i)
met-II /mc
       (j)
met-II /std
       (k)
morphis
       (l)
odyssey xa
       (m)
odyssey xcl
       (n)
odyssey xd
       (o)
orion
       (p)
solios xa
       (q)
solios xcl
       (r)

ControlValue

  Open   Collapse   M_ACCELERATOR

 Sets whether the thread uses hardware acceleration. Hardware acceleration speeds up the execution of certain functions in a thread. Use MsysInquire() with M_ACCELERATOR_PRESENT to learn if your Matrox imaging board has an accelerator.  Sets whether the thread uses hardware acceleration ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DISABLE

 Disables hardware acceleration.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ENABLE

 Enables hardware acceleration.

This is the default value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_BUS_MASTER_COPY_MODE

 Sets the synchronization mode for copy operations when they are driven by your imaging board (bus master). The current setting for M_THREAD_MODE is ignored.  Sets the synchronization mode for copy operations when they are driven by your imaging board (bus master) ...

c
d
e

h
i

l
m
n
o

q
r

Specifics

 The setting of this control is only meaningful when either M_BUS_MASTER_COPY_FROM_HOST or M_BUS_MASTER_COPY_TO_HOST (MsysControl()) is set to M_ENABLE. When M_BUS_MASTER_COPY_FROM_HOST or M_BUS_MASTER_COPY_TO_HOST is set to M_DISABLE, the synchronization mode is always synchronous for copy operations made from the Host or to the Host, respectively.

c

h
i

m
n
o

 M_DEFAULT

Specifies the default value. The default value is M_SYNCHRONOUS.

c
d
e

h
i

l
m
n
o

q
r

 M_ASYNCHRONOUS

 Specifies that when possible, control will be returned to the imaging board (bus master) immediately after a copy operation is launched.

c
d
e

h
i

l
m
n
o

q
r

 M_SYNCHRONOUS

 Specifies that the execution of a copy operation must be completed before returning control to the imaging board (bus master).

c
d
e

h
i

l
m
n
o

q
r

  Open   Collapse   M_THREAD_COMMANDS_ABORT

 Cancels all calls queued in the thread. The remainder of the application is executed.  Cancels all calls queued in the thread ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Implements the default behavior.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_THREAD_MODE

 Sets the thread execution mode.  Sets the thread execution mode ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_ASYNCHRONOUS

 Specifies that control will be returned to the Host immediately after a MIL function is sent to the processor of a system (when the system and function allow an immediate return).

This is the default value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_SYNCHRONOUS

 Specifies that the execution of a MIL function sent to the processor of a system must be completed (execution terminated) before returning control to the Host.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_THREAD_PRIORITY

 Sets the priority status of the thread.  Sets the priority status of the thread ...

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 1 to 15

 Specifies the priority status of the thread executed on a Matrox Odyssey on-board processor. 1 specifies the lowest priority.

m
n
o

 M_ABOVE_NORMAL

 Specifies that the thread is above normal priority. Only time critical threads will be executed before it.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_BELOW_NORMAL

 Specifies that the thread is below normal priority. Threads of normal, above normal, and time critical priority will be executed before it.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_IDLE

 Specifies that the thread is idle. The thread will remain idle until its priority status is changed.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_LOWEST

 Specifies that the thread is of the lowest priority. All other non-idle threads will be executed before it.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_NORMAL

 Specifies that the thread is of normal priority. Threads of above normal and time critical priority will be executed before it.

This is the default value.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_TIME_CRITICAL

 Specifies that the thread is time critical. Time critical threads will be executed before all other threads that are not time critical.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

  Open   Collapse   M_THREAD_SELECT

 Sets the selectable thread, specified by the ThreadOrEventId parameter as the destination for subsequent MIL functions. This allows MIL functions to be executed as part of a thread controlled by a system other than the Host.  Sets the selectable thread, specified by the ThreadOrEventId parameter as the destination for subsequent MIL functions ...

 To return control to the default on-board thread associated with the Host thread, call MthrControl() with this control type and the ThreadOrEventId parameter set to M_DEFAULT.

 If the ThreadOrEventId parameter is set to an identifier of a thread that is not selectable, changing the settings of this control will cause an error to be reported.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 M_DEFAULT

 Implements the default behavior.

a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r

 The following ControlType and corresponding ControlValue setting can be specified to control MIL events:

Open Collapse ControlType |  | Description
 | ControlValue
Open Collapse M_EVENT_SET |  | Sets an event to the specified state. Sets an event to the specified state ...
 | M_NOT_SIGNALED | Sets the event to the not signaled state.
 | M_SIGNALED | Sets the event to the signaled state.

ACCELERATOR PRESENT THREAD MODE BUS MASTER COPY FROM HOST BUS MASTER COPY TO HOST BUS MASTER COPY FROM HOST BUS MASTER COPY TO HOST DEFAULT  DEFAULT    ACCELERATOR DISABLE ENABLE BUS MASTER COPY MODE DEFAULT ASYNCHRONOUS SYNCHRONOUS THREAD COMMANDS ABORT DEFAULT THREAD MODE  ASYNCHRONOUS
                      SYNCHRONOUS
                      THREAD PRIORITY  TIME CRITICAL ABOVE NORMAL NORMAL BELOW NORMAL LOWEST IDLE THREAD SELECT DEFAULT EVENT SET  NOT SIGNALED SIGNALED


MthrFree

See Also | Example | Availability | MthrControl | MthrInquire
User Guide:
Multi-threading

Reference:
MthrAlloc
dtkobjecttracking.c
mdighook.c
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Free a MIL thread context or event.
Syntax
void MthrFree (
MIL_ID ThreadOrEventId
)
Description

This function deallocates a MIL thread context or event previously allocated with MthrAlloc().

In a given thread, MthrFree() must be the last MIL function called; no other MIL function can be executed in the thread after a call to this function.

Parameter
ThreadOrEventId

Specifies the identifier of the MIL thread context/event to free.


MthrInquire

See Also | Example | Availability | MthrFree | MthrWait
User Guide:
Multi-threading

Reference:
MappInquire
MsysAlloc
MsysInquire
MthrAlloc
MthrControl
dtkobjecttracking.c
Available in MIL-Lite

Available in MIL

Fully supported on:
Fully supported on Matrox Genesis
Fully supported on Matrox Meteor-II /Digital
Fully supported on Matrox Meteor-II /Camera Link
Fully supported on Matrox Odyssey XA
Fully supported on Matrox Odyssey XCL
Fully supported on Matrox Odyssey XD

Partially supported on:
Partially supported on Matrox Corona-II
Partially supported on Matrox Meteor-II /1394
Partially supported on Matrox Meteor-II /Multi-Channel
Partially supported on Matrox Meteor-II /Standard
Partially supported on Matrox Orion
Partially supported on Matrox CronosPlus
Partially supported on Matrox Helios XA
Partially supported on Matrox Helios XCL
Partially supported on Matrox Morphis
Partially supported on Matrox Solios XA
Partially supported on Matrox Solios XCL
Partially supported on Matrox Iris
Synopsis
Inquire about a MIL thread context or event setting.
Syntax
long MthrInquire (
MIL_ID ThreadOrEventId,
long InquireType,
void *InquireValue
)
Description

This function inquires about the specified MIL thread context or event setting.

Parameters
ThreadOrEventId

Specifies the identifier of a user-allocated MIL thread context or event, allocated using MthrAlloc(). This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default MIL thread context identifier associated with the current Host thread.  Specifies the default MIL thread context identifier associated with the current Host thread.

  Open   Collapse  MIL thread context/event/system identifier

 Specifies the identifier of a user-allocated MIL thread context or event (MthrAlloc()), or a valid system identifier (MsysAlloc()).  Specifies the identifier of a user-allocated MIL thread context or event (MthrAlloc()), or a valid system identifier (MsysAlloc()) ...

 When the parameter is set to the MIL identifier of a system, the function inquires about the current thread on the particular system.

 InquireType

 Specifies the type of information about which to inquire.  This parameter can be set to one of the values below. See MthrControl() for more information about these values.

 The following InquireType settings can be specified to inquire about MIL thread contexts:

Unless otherwise specified, the following values require that you pass the InquireValue parameter the address of
                a
                  long.

Open Collapse Value | Description |  | corona-II (a) | cronosplus (b) | genesis (c) | helios xa (d) | helios xcl (e) | Matrox Iris (f) | met-II /1394 (g) | met-II /cl (h) | met-II /dig (i) | met-II /mc (j) | met-II /std (k) | morphis (l) | odyssey xa (m) | odyssey xcl (n) | odyssey xd (o) | orion (p) | solios xa (q) | solios xcl (r)
Open Collapse M_ACCELERATOR | Returns whether the thread uses hardware acceleration. Returns whether the thread uses hardware acceleration ... |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
 |  | InquireValue info Return values: M_DISABLE, M_ENABLE (details)
Open Collapse M_BUS_MASTER_COPY_MODE | Returns the synchronization mode for copy operations when they are driven by your imaging board (bus master). Returns the synchronization mode for copy operations when they are driven by your imaging board (bus master) ... |  | a | b | c | d | e |  | g | h | i | j | k | l | m | n | o | p | q | r
 |  | InquireValue info Return values: M_ASYNCHRONOUS, M_SYNCHRONOUS (details)
Open Collapse M_THREAD_MODE | Returns the thread execution mode. Returns the thread execution mode ... |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
 |  | InquireValue info Return values: M_ASYNCHRONOUS, M_SYNCHRONOUS (details)
Open Collapse M_THREAD_PRIORITY | Returns the priority setting of the thread. Returns the priority setting of the thread ... |  | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r
 |  | InquireValue info Return values: 1 to 15, M_ABOVE_NORMAL, M_BELOW_NORMAL, M_IDLE, M_LOWEST, M_NORMAL, M_TIME_CRITICAL (details)

 The following InquireType setting can be specified to inquire about MIL events:

Unless otherwise specified, the following values require that you pass the InquireValue parameter the address of
                a
                  long.

Open Collapse Value | Description
Open Collapse M_EVENT_MODE | Returns the reset mode of the event. Returns the reset mode of the event ...
 |  | InquireValue info Return values: M_AUTO_RESET, M_MANUAL_RESET (details)
Open Collapse M_EVENT_STATE | Returns the state of the event. Returns the state of the event ...
 |  | InquireValue info Return values: M_NOT_SIGNALED, M_SIGNALED (details)

[Matrox Genesis, Matrox Meteor-II /Camera Link, Matrox Meteor-II /Digital, Matrox Odyssey XA, Matrox Odyssey XCL, and Matrox Odyssey XD]

 The following InquireType settings can be specified to inquire about either a MIL thread context or an event:

Unless otherwise specified, the following values require that you pass the InquireValue parameter the address of
                a
                  MIL_ID.

Open Collapse Value | Description
Open Collapse M_NATIVE_ID | Returns the Native Library identifier of the selected MIL thread context or event. You cannot use M_NATIVE_ID for selectable threads (MthrAlloc() with M_SELECTABLE_THREAD). Instead, use MsysInquire() with M_NATIVE_THREAD_ID. Returns the Native Library identifier of the selected MIL thread context or event ...

 InquireValue

 Specifies the address in which to write the requested information.

 Since the MappInquire() function also returns the requested information, you can set this parameter to M_NULL.

Return value

 The returned value is the requested information cast to long.

SELECTABLE THREAD NATIVE THREAD ID  DEFAULT   ACCELERATOR BUS MASTER COPY MODE THREAD MODE THREAD PRIORITY EVENT MODE EVENT STATE NATIVE ID


MthrWait

See Also | Example | Availability | MthrInquire
User Guide:
Multiple cameras
Multi-threading

Reference:
MsysAlloc
MthrAlloc
dtkobjecttracking.c
dtksyncasyncfunctionsmain.c
mdiggrabsequence.c
mdighook.c
mmorphisjpeg2000.c
mthread.c
Available in MIL-Lite

Available in MIL
Synopsis
Perform a wait operation on a MIL thread or event.
Syntax
long MthrWait (
MIL_ID ThreadOrEventId,
long WaitOption,
long *State
)
Description

This function allows you to synchronize the execution of threads by forcing the current thread to wait for the completion of the specified thread or the change of state of the specified event.

Parameters
ThreadOrEventId

Sets the identifier of the MIL thread context or event with which to be synchronized. This parameter can also be set to the MIL identifier of a system.

This parameter should be set to one of the following values:

Open Collapse Value Description
Open Collapse M_DEFAULT

 Specifies the default MIL thread context identifier associated with the current Host thread.  Specifies the default MIL thread context identifier associated with the current Host thread.

  Open   Collapse  MIL thread context/event/system identifier

 Specifies the identifier of a user-allocated MIL thread context or event (MthrAlloc()), or a valid system identifier (MsysAlloc()).  Specifies the identifier of a user-allocated MIL thread context or event (MthrAlloc()), or a valid system identifier (MsysAlloc()).

 WaitOption

 Specifies the wait option.

 The following wait options are available for threads.

  Open   Collapse  Value
Description

  Open   Collapse  M_THREAD_END_WAIT

 Forces the current thread to wait for the end (the death) of the specified thread. The thread currently running cannot be the thread for which you are waiting. This option can only be used for a thread allocated using MthrAlloc() with M_THREAD.  Forces the current thread to wait for the end (the death) of the specified thread ...

 If the ThreadOrEventId parameter is set to a MIL system identifier, using this wait option results in an error.

 Note that this value can be used in combination with another value; see below.

  Open   Collapse  M_THREAD_WAIT

 Forces the current thread to wait for the completion of all functions in the specified thread's execution queue.  Forces the current thread to wait for the completion of all functions in the specified thread's execution queue ...

 If the ThreadOrEventId parameter was set to a MIL system identifier, the current thread waits for the completion of the current thread on the specified system.

 Note that this value can be used in combination with another value; see below.

      [Combination constants]

 The following value can be added to the WaitOption parameter for threads.

  Open   Collapse  Value
Description

  Open   Collapse  M_THREAD_TIMEOUT(n)

 Specifies the time interval after which a thread is considered to be timed out. n should be set to a specific interval, in msecs. To specify an infinitely long timeout interval, set n to 0 or M_INFINITE.  Specifies the time interval after which a thread is considered to be timed out ...

 The following wait options are available for events.

  Open   Collapse  Value
Description

  Open   Collapse  M_EVENT_SYNCHRONIZE

 Allows the current thread to continue with execution while forcing its corresponding on-board thread, located on the same board as the specified event, to wait for the specified event to be in a M_SIGNALED state.  Allows the current thread to continue with execution while forcing its corresponding on-board thread, located on the same board as the specified event, to wait for the specified event to be in a M_SIGNALED state ...

 If the specified event is allocated on a board that supports asynchronous calls, MIL issues the wait command to that board and allows the current thread to proceed executing while its corresponding thread on that board is waiting for the specified event to change to a signaled state. Any subsequent calls issued on that on-board thread are executed only after the event is signaled. If the specified event is not allocated on a board that supports asynchronous calls, M_EVENT_SYNCHRONIZE acts exactly like M_EVENT_WAIT.

 If the event is of the type that is reset automatically (M_AUTO_RESET), after the wait operation, the state of the event is reset to M_NOT_SIGNALED.

 Note that this value can be used in combination with another value; see below.

  Open   Collapse  M_EVENT_WAIT

 Forces the current thread to wait for the specified event to be in an M_SIGNALED state or for the event to be timed out. The current thread will not proceed with execution until the specified event has changed to a signaled state.  Forces the current thread to wait for the specified event to be in an M_SIGNALED state or for the event to be timed out ...

 If the event is of the type that is reset automatically (M_AUTO_RESET), after the wait operation, the state of the event is reset to M_NOT_SIGNALED.

 Note that this value can be used in combination with another value; see below.

      [Combination constants]

 The following value can be added to the WaitOption parameter for events.

  Open   Collapse  Value
Description

  Open   Collapse  M_EVENT_TIMEOUT(n)

 Specifies the time interval after which an event is considered to be timed out. n should be set to a specific interval, in msecs. To specify an infinitely long timeout interval, set n to 0 or M_INFINITE.  Specifies the time interval after which an event is considered to be timed out ...

 State

 Specifies the address to which to write the state of the specified thread or event. M_SIGNALED indicates that the specified thread has successfully completed or the state of the specified event has changed. M_TIMEOUT is returned when the thread or event on which the current thread was waiting has timed out.

 Since the MthrWait() function also returns the requested information, you can set this parameter to M_NULL.

Return value

 The returned value is M_SIGNALED if the specified thread has successfully completed or the state of the specified event has changed, or M_TIMEOUT.

THREAD SIGNALED AUTO RESET NOT SIGNALED SIGNALED EVENT SYNCHRONIZE EVENT WAIT AUTO RESET NOT SIGNALED SIGNALED SIGNALED  DEFAULT   THREAD END WAIT THREAD WAIT THREAD TIMEOUT(n) EVENT WAIT EVENT SYNCHRONIZE EVENT TIMEOUT(n)


GotoWelcome

 Loading...


Example: channel_switch.c

/* File name: channel_switch.c
 * Synopsis: This example shows how to achieve the fastest possible
 *           switching speed with a Matrox Meteor-II when connected to
 *           multiple unsynchronized inputs of the same video format.
 *
 * Note: This example assumes that you are using a Matrox Meteor-II with 12
 *       channels or a Matrox Orion. An application note on "Fast channel
 *       switching" (channel_switch.pdf) is available on the Matrox
 *       Imaging website at http://www.matrox.com/imaging/
 */

#include <stdio.h>
#include <mil.h>
#include <conio.h>

/* DCF name.
 * For grab field mode, use only DCF filenames finishing by "_fs.dcf".
 *                      Valid DCF are: rs170_fs.dcf, ntsc_fs.dcf,
 *                                     ccir_fs.dcf and pal_fs.dcf
 * When grabbing whole frames, use standard DCFs.
 * On the Matrox Orion, use standard DCFs.
 */
#define DCF_NAME    MIL_TEXT("ntsc_fs.dcf")

/* Image scaling. */
#define IMAGE_SCALE 0.5

/* Number of channels. */
#define NUM_CHANNELS 2

/* Buffer layout. */
#define NB_IMAGE_X  2
#define NB_IMAGE_Y  1

void main(void)
   {
   MIL_ID MilApplication,                           /* Application identifier.   */
          MilSystem,                                /* System identifier.        */
          MilDisplay,                               /* Display identifier.       */
          MilDigitizer,                             /* Digitizer identifier.     */
          MilImageDisp,                             /* Image buffer identifier.  */
          MilImageDispChild[NB_IMAGE_X*NB_IMAGE_Y]; /* Image buffer identifier.  */
   long   Lock;
   long   ColorDigitizer = M_FALSE;
   long   Counter = 0;
   long   NbGrab  = 0;
   long   X,Y;
   long   Channel[] = {M_CH0, M_CH1, M_CH2,  M_CH3,
                       M_CH4, M_CH5, M_CH6,  M_CH7,
                       M_CH8, M_CH9, M_CH10, M_CH11};

   long   Color[NUM_CHANNELS] = {0};
   double Wait = 0.25;
   double TimeStart,TimeEnd;
   unsigned long  AGCValue [NUM_CHANNELS];

   /* Allocate all the parameters. */
   MappAlloc(M_DEFAULT, &MilApplication);
   MsysAlloc(M_SYSTEM_METEOR_II, M_DEF_SYSTEM_NUM, M_SETUP, &MilSystem);
   MdispAlloc(MilSystem, M_DEFAULT, M_DEF_DISPLAY_FORMAT, M_DEFAULT, &MilDisplay);
   MdigAlloc(MilSystem, M_DEFAULT, DCF_NAME, M_DEFAULT, &MilDigitizer);

   /* Allocate a display buffer, clear it and display it. */
   MbufAllocColor(MilSystem,
                  MdigInquire(MilDigitizer, M_SIZE_BAND, M_NULL),
                  (long) (MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*IMAGE_SCALE*NB_IMAGE_X),
                  (long) (MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*IMAGE_SCALE*NB_IMAGE_Y),
                  8L+M_UNSIGNED,
                  M_IMAGE+M_GRAB+M_DISP,
                  &MilImageDisp);
   MbufClear(MilImageDisp, 128L);

   /* Note: Channel switching speed is increased when buffer is not selected
      on the display. */
   MdispSelect(MilDisplay, MilImageDisp);

   /* Allocate one child buffer for each input channel in the display buffer. */
   Counter = 0;
   for (Y = 0; Y < NB_IMAGE_Y; Y++)
      {
      for (X = 0; X < NB_IMAGE_X; X++)
         {
         MbufChild2d(MilImageDisp,
                     (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*IMAGE_SCALE*X),
                     (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*IMAGE_SCALE*Y),
                     (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*IMAGE_SCALE),
                     (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*IMAGE_SCALE),
                     &MilImageDispChild[Counter++]);
         }
      }

   /* Check if we are using a color dcf. */
   if(MdigInquire(MilDigitizer, M_SIZE_BAND, M_NULL) != 1)
      ColorDigitizer = M_TRUE;

   /* Read gain settings for each channel and also detect
      if the selected camera is color or monochrome.
      To do this we must temporarily disable the camera lock
      mechanism. */
   MdigControl(MilDigitizer, M_CAMERA_LOCK, M_DISABLE);
   for (Counter = 0; Counter < NUM_CHANNELS; Counter++)
      {
      MdigControl(MilDigitizer, M_GRAB_AUTOMATIC_INPUT_GAIN, M_ENABLE);
      MdigChannel(MilDigitizer, Channel[Counter]);
      MappTimer(M_TIMER_WAIT,&Wait);
      if( ColorDigitizer == M_TRUE)
         {
         /* When using a color dcf, we need to detect if the connected
            camera is color or monochrome. We do not want to wait on
            a color-lock on a monochrome camera. */
         Lock=M_FALSE;
         MdigInquire(MilDigitizer, M_CAMERA_LOCKED, &Lock);

         if(Lock == 0)
            Color[Counter]=0;       /* Camera is monochrome */
         else
            Color[Counter]=1;       /* Camera is color */
         }

      MdigControl(MilDigitizer, M_GRAB_AUTOMATIC_INPUT_GAIN, M_DISABLE);
      MdigInquire (MilDigitizer, M_GRAB_INPUT_GAIN, &AGCValue[Counter]);
      }

   /* Enable fast switching synchronisation. */
   MdigControl(MilDigitizer, M_CAMERA_LOCK, M_ENABLE);

   /* Set the lock/unlock sensitivity to default values. Switching
      speed can be increased by changing these values on the Matrox Orion.
      Please refer to board-specific documentation for more information. */
   MdigControl(MilDigitizer, M_CAMERA_LOCK_SENSITIVITY, M_DEFAULT);
   MdigControl(MilDigitizer, M_CAMERA_UNLOCK_SENSITIVITY, M_DEFAULT);

   /* Set the acquisition in synchronous mode. */
   MdigControl(MilDigitizer, M_GRAB_MODE, M_SYNCHRONOUS);

   /* Set the acquisition to start on any field. */
   MdigControl(MilDigitizer, M_GRAB_START_MODE, M_FIELD_START);

   /* Set the acquisition scaling. */
   MdigControl(MilDigitizer, M_GRAB_SCALE, IMAGE_SCALE);

   /* Set the acquisition to grab only one field. */
   MdigControl(MilDigitizer, M_GRAB_FIELD_NUM, 1);

   /* Disable automatic input gain. */
   MdigControl(MilDigitizer, M_GRAB_AUTOMATIC_INPUT_GAIN, M_DISABLE);

   /* When a key is pressed, Start. */
   printf("Press <Enter> to start grabbing.\n");
   getchar();
   printf("Press <Enter> to stop grabbing and exit.\n\n");

   /* Grab the sequence. */
   Counter = NUM_CHANNELS -1;

   /* Start the timer */
   MappTimer(M_TIMER_RESET, M_NULL);
   MappTimer(M_TIMER_READ, &TimeStart);
   while(!kbhit())
      {
      /* Select an input channel. */
      if (Counter < NUM_CHANNELS - 1)
         Counter++;
      else
         Counter = 0;

      /* Set the correct gain for this channel. */
      MdigControl(MilDigitizer, M_GRAB_INPUT_GAIN, AGCValue[Counter]);

      /* Do not wait on a color-lock if the camera is monochrome. */
      if (Color[Counter])
         MdigControl(MilDigitizer, M_CAMERA_COLOR_LOCK, M_ENABLE);
      else
         MdigControl(MilDigitizer, M_CAMERA_COLOR_LOCK, M_DISABLE);

      /* Switch and grab. Internaly the grab function will wait until
         the hardware is locked. */
      MdigChannel(MilDigitizer, Channel[Counter]);
      MdigGrab(MilDigitizer, MilImageDispChild[Counter]);

      NbGrab++;
      if((NbGrab % 100) == 0)
         {
         MappTimer(M_TIMER_READ, &TimeEnd);
         printf("%d fields grabbed at %f fps\r", NbGrab, 100/(TimeEnd-TimeStart));
         MappTimer(M_TIMER_READ, &TimeStart);
         }
      }

   /* Stop the timer. */
   MappTimer(M_TIMER_READ, &TimeEnd);

   printf("\n\n%d Total fields grabbed at an average of %f fps\n", NbGrab, NbGrab/TimeEnd);
   printf("Press <Enter> to end.\n");
   getchar();

   /* Free allocations. */
   for (Counter = 0; Counter < NB_IMAGE_X*NB_IMAGE_Y; Counter++)
      {
      MbufFree(MilImageDispChild[Counter]);
      }

   MbufFree(MilImageDisp);
   MdigFree(MilDigitizer);
   MdispFree(MilDisplay);
   MsysFree(MilSystem);
   MappFree(MilApplication);
}


Example: dtkaddconstantaltivec.c

/*****************************************************************************************/
/*
 * File name: DTKAddConstantAltiVec.c
 * Synopsis:  This example shows how to use of the MIL Function Developer's Toolkit to
 *            create a custom MIL function that adds a constant to an image using
 *            custom PowerPC AltiVec code.
 *
 *            The example creates a Master MIL function that registers all the parameters
 *            to MIL and calls the Slave function on the target system. The Slave function
 *            retrieves all the parameters and call a Target processing function that adds
 *            a constant to the source buffer and writes the result to the target image.
 *
 *            Note: For simplicity, the images are assumed to be 8-bit unsigned and of
 *            the same dimension.
 */

/* Standard MIL header. */
#include <mil.h>

/* Master, Slave and Target MIL functions declarations */
void MFTYPE AddConstantAltiVec(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);
void MFTYPE SlaveAddConstantAltiVec(MIL_ID Func);
void MFTYPE TargetAddConstantAltiVec(MIL_ID Src, MIL_ID Dst, unsigned long Constant);

/* Master MIL Function definition. */
/* ------------------------------- */

/* MIL Function number of parameters. */
#define FUNCTION_NB_PARAM    3

/* Opcode that matches the offset of the slave PA function pointer in the MfuncUserSlaveFunctions[] table. */
#define FUNCTION_OPCODE_ADD_CONST_ALTIVEC (M_USER_FUNCTION+5)

void MFTYPE AddConstantAltiVec(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant)
   {
   MIL_ID   Func;

   /* Allocate a MIL function context to call the Slave function on the Target system. */
   MfuncAlloc(MIL_TEXT("AddConstantAltiVec"),
              FUNCTION_NB_PARAM,
              M_NULL, M_NULL, M_NULL,
              FUNCTION_OPCODE_ADD_CONST_ALTIVEC,
              M_ASYNCHRONOUS_FUNCTION,
              &Func
             );

   /* Register the parameters. */
   MfuncParamId(  Func, 1, SrcImage, M_IMAGE, M_IN  + M_PROC);
   MfuncParamId(  Func, 2, DstImage, M_IMAGE, M_OUT + M_PROC);
   MfuncParamLong(Func, 3, Constant);

   /* Call the Slave function. */
   MfuncCall(Func);

   /* Free the MIL function context. */
   MfuncFree(Func);
   }

/* Compile Slave and Altivec code only on the PowerPC. */
#if M_MIL_USE_PPC

/* Slave MIL Function definition. */
/* ------------------------------ */

void MFTYPE SlaveAddConstantAltiVec(MIL_ID Func)
   {
   MIL_ID SrcImage, DstImage;
   unsigned long Constant;

   /* Now we are on the Target system and we will call the Target processing function. */

   /* Retrieve the passed parameters. */
   MfuncParamValue(Func, 1, &SrcImage);
   MfuncParamValue(Func, 2, &DstImage);
   MfuncParamValue(Func, 3, &Constant);

   /* Call the target slave function. */
   TargetAddConstantAltiVec(SrcImage, DstImage, Constant);
   }

/* Target MIL processing function definition using ALTIVEC code. */
/* ------------------------------------------------------------- */
/*
 * This function adds a constant to a MIL buffer.
 *
 * For simplicity, it assumes that the buffers are 8-bit unsigned parent
 * buffers of the same dimension. This is the default when allocating with
 * MbufAlloc2d() and this guarantees that their start addresses and pitches
 * are multiple of an Altivec vector size and that we can prefetch a least
 * one line after the buffer.
 */

/* Target function restrictions and error code. */
#define FUNCTION_SUPPORTED_IMAGE_DEPTH    (8+M_UNSIGNED)
#define FUNCTION_PARAMETER_ERROR_CODE     1

/* Utility definitions. */
#define MAX_PREFETCH_SIZE   512
#define VECTOR_SIZE         vec_step(vector unsigned char)

/* Prefetch parameters structure definition. */
typedef union
      {
      long     Value;
      struct
         {
         signed   long Stride : 16;
         unsigned long Number : 8;
         unsigned long Size   : 5;
         }Block;
      }
      PrefetchParameter;

/* Vector aligned structure definition. */
typedef union
      {
         vector unsigned char UCharVector;
          unsigned char UCharArray[16];
      } AltivecAligned;

void MFTYPE TargetAddConstantAltiVec(MIL_ID Src, MIL_ID Dst, unsigned long Constant)
   {
   vector unsigned char *vpSrc, *vpDst;
   vector unsigned char  vConstant;
   AltivecAligned        Data;
   long                  SizeX, SizeY, Pitch, x, y;
   PrefetchParameter     PrefetchParam;

   /* Read the MIL buffers informations assuming same buffer dimensions. */
   MbufInquire(Src, M_HOST_ADDRESS, &vpSrc);
   MbufInquire(Dst, M_HOST_ADDRESS, &vpDst);
   MbufInquire(Dst, M_SIZE_X,       &SizeX);
   MbufInquire(Dst, M_SIZE_Y,       &SizeY);
   MbufInquire(Dst, M_PITCH,        &Pitch);

   /* If the images have the proper type and dimensions, process them.*/
   if ((MbufInquire(Src, M_TYPE, M_NULL)   == FUNCTION_SUPPORTED_IMAGE_DEPTH) &&
       (MbufInquire(Dst, M_TYPE, M_NULL)   == FUNCTION_SUPPORTED_IMAGE_DEPTH) &&
       (MbufInquire(Src, M_SIZE_X, M_NULL) == SizeX) &&
       (MbufInquire(Src, M_SIZE_Y, M_NULL) == SizeY)
      )
      {
      /* Calculate the data block prefetch parameters. */
      PrefetchParam.Block.Number = ((SizeX + VECTOR_SIZE) + (MAX_PREFETCH_SIZE-1)) / MAX_PREFETCH_SIZE;
      PrefetchParam.Block.Size   = ((SizeX + VECTOR_SIZE) / PrefetchParam.Block.Number) / VECTOR_SIZE;
      PrefetchParam.Block.Stride = PrefetchParam.Block.Size * VECTOR_SIZE;

      /* Convert SizeX and Pitch from pixel to vector. */
      SizeX = SizeX/VECTOR_SIZE;
      Pitch = Pitch/VECTOR_SIZE;

      /* Replicate the constant in a vector. */
      Data.UCharArray[0] = (unsigned char)Constant;
      vConstant = vec_splat(Data.UCharVector, 15);

      /* Adds the constant. */
      for(y = 0; y < SizeY; y++)
         {
         /* Prefetch a line in the source buffer to increase I/O efficiency. */
         vec_dst(vpSrc, PrefetchParam.Value, 0);

         /* Process a line. */
         for(x = 0; x < SizeX; x++)
            {
            vpDst[x] = vec_add(vpSrc[x], vConstant);
            }

         /* Go to next line. */
         vpSrc += Pitch;
         vpDst += Pitch;
         }

      /* Notify MIL that the buffers were accessed directly using pointers and are now in cache. */
      MbufControl(Src, M_CACHE_CONTROL, M_IN_CACHE);
      MbufControl(Dst, M_CACHE_CONTROL, M_IN_CACHE);

      /* Signal MIL that the destination buffer has been modified. */
      MbufControl(Dst, M_MODIFIED, M_DEFAULT);
      }
   else
      {
      /* Report a MIL error. */
      MfuncErrorReport(M_DEFAULT, M_FUNC_ERROR+FUNCTION_PARAMETER_ERROR_CODE,
                       MIL_TEXT("Invalid parameter."),
                       MIL_TEXT("Images must have the same dimensions and must be 8-bit unsigned."),
                       M_NULL,
                       M_NULL
                      );
      }

   }
#endif /* M_MIL_USE_PPC */


Example: dtkaddconstantc.c

/*****************************************************************************************/
/*
 * File name: DTKAddConstantC.c
 * Synopsis:  This example shows how to use of the MIL Function Developer's Toolkit to
 *            create a custom MIL function that adds a constant to an image using
 *            custom C code.
 *
 *            The example creates a Master MIL function that registers all the parameters
 *            to MIL and calls the Slave function on the target system. The Slave function
 *            retrieves all the parameters and call a Target processing function that adds
 *            a constant to the source buffer and writes the result to the target image.
 *
 *            Note: For simplicity, the images are assumed to be 8-bit unsigned and of
 *            the same dimensions.
 */

/* Standard MIL header. */
#include <mil.h>

/* Master, Slave and Target MIL functions declarations */
void MFTYPE AddConstantC(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);
void MFTYPE SlaveAddConstantC(MIL_ID Func);
void MFTYPE TargetAddConstantC(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);

/* Master MIL Function definition. */
/* ------------------------------- */

/* Number of parameters of the MIL function. */
#define FUNCTION_NB_PARAM    3

/* Opcode that matches the offset of the slave PA function pointer in the MfuncUserSlaveFunctions[] table. */
#define FUNCTION_OPCODE_ADD_CONST_C (M_USER_FUNCTION+4)

void MFTYPE AddConstantC(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant)
   {
   MIL_ID   Func;

   /* Allocate a MIL function context to call the Slave function on the Target system. */
   MfuncAlloc(MIL_TEXT("AddConstantC"),
              FUNCTION_NB_PARAM,
              SlaveAddConstantC, M_NULL, M_NULL,
              FUNCTION_OPCODE_ADD_CONST_C,
              M_ASYNCHRONOUS_FUNCTION,
              &Func
             );

   /* Register the parameters. */
   MfuncParamId(  Func, 1, SrcImage, M_IMAGE, M_IN  + M_PROC);
   MfuncParamId(  Func, 2, DstImage, M_IMAGE, M_OUT + M_PROC);
   MfuncParamLong(Func, 3, Constant);

   /* Call the Slave function. */
   MfuncCall(Func);

   /* Free the MIL function context. */
   MfuncFree(Func);
   }

/* Slave MIL Function definition. */
/* ------------------------------ */

void MFTYPE SlaveAddConstantC(MIL_ID Func)
   {
   MIL_ID SrcImage, DstImage;
   unsigned long Constant;

   /* Now we are on the Target system and we will call the Target processing function. */

   /* Retrieve the function parameters. */
   MfuncParamValue(Func, 1, &SrcImage);
   MfuncParamValue(Func, 2, &DstImage);
   MfuncParamValue(Func, 3, &Constant);

   /* Call the target slave function. */
   TargetAddConstantC(SrcImage, DstImage, Constant);
   }

/* Target MIL processing function definition using C code. */
/* ------------------------------------------------------- */
/*
 * This function adds a constant to a MIL buffer.
 *
 * For simplicity, it assumes that the buffers are 8-bit unsigned
 * buffers of the same dimensions.
 */

/* Target function restrictions and error code. */
#define FUNCTION_SUPPORTED_IMAGE_DEPTH    (8+M_UNSIGNED)
#define FUNCTION_PARAMETER_ERROR_CODE     1

void MFTYPE TargetAddConstantC(MIL_ID Src, MIL_ID Dst, unsigned long Constant)
   {
   unsigned char* pSrc, *pDst;
   long           SizeX, SizeY, Pitch, x, y ;

   /* Read the MIL buffers informations assuming same buffer dimensions. */
   MbufInquire(Src, M_HOST_ADDRESS, &pSrc);
   MbufInquire(Dst, M_HOST_ADDRESS, &pDst);
   MbufInquire(Dst, M_SIZE_X,       &SizeX);
   MbufInquire(Dst, M_SIZE_Y,       &SizeY);
   MbufInquire(Dst, M_PITCH,        &Pitch);

   /* If the images have the proper type and dimensions, process them.*/
   if ((MbufInquire(Src, M_TYPE, M_NULL)   == FUNCTION_SUPPORTED_IMAGE_DEPTH) &&
       (MbufInquire(Dst, M_TYPE, M_NULL)   == FUNCTION_SUPPORTED_IMAGE_DEPTH) &&
       (MbufInquire(Src, M_SIZE_X, M_NULL) == SizeX) &&
       (MbufInquire(Src, M_SIZE_Y, M_NULL) == SizeY)
      )
      {
      /* Add the constant using C code. */
      for(y = 0; y < SizeY; y++)
         {
         for(x = 0; x < SizeX; x++)
            {
            pDst[x] = pSrc[x] + (unsigned char)Constant;
            }

         /* Go to next line. */
         pSrc += Pitch;
         pDst += Pitch;
         }

      /* Notify MIL that the buffer were accessed directly using pointers and are now in cache. */
      MbufControl(Src, M_CACHE_CONTROL, M_IN_CACHE);
      MbufControl(Dst, M_CACHE_CONTROL, M_IN_CACHE);

      /* Signal MIL that the destination buffer has been modified. */
      MbufControl(Dst, M_MODIFIED, M_DEFAULT);
      }
   else
      {
      /* Report a MIL error. */
      MfuncErrorReport(M_DEFAULT, M_FUNC_ERROR+FUNCTION_PARAMETER_ERROR_CODE,
                       MIL_TEXT("Invalid parameter."),
                       MIL_TEXT("Images must have the same dimensions and must be 8-bit unsigned."),
                       M_NULL,
                       M_NULL
                      );
      }
   }


Example: dtkaddconstantmain.c

/*****************************************************************************************/
/*
 * File name: DTKAddConstantMain.c
 *
 * Synopsis:  This file contains the main program to test and time the different
 *            versions of a custom add constant MIL function MIL created with
 *            the MIL Function Developer's Toolkit (DTK).
 */

/* Standard headers. */
#include <mil.h>
#include <conio.h>

/* Target image file name */
#define IMAGE_FILE   M_IMAGE_PATH MIL_TEXT("board.mim")

/* Timing loop iterations. */
#define NB_LOOP 100

/* Defines for the different versions of the target function to run on the Odyssey. */
#define USE_C           0 /* Target C function C.                 */
#define USE_ALTIVEC     1 /* Target AltiVec function.             */
#define USE_ONL_ALTIVEC 2 /* Target ONL AltiVec block processing. */
#define USE_PA          3 /* Target function Native PA code.      */
#define USE_MIL         4 /* Target function MIL.                 */
#define NB_VERSIONS     5 /* Number of different versions to call. */
static char *VersionName[] = {"C", "Altivec", "ONL Altivec", "PA", "MIL"};

/* Master functions prototypes: */
/* Custom C function (See DTKAddConstantC.c) */
void MFTYPE AddConstantC(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);
/* Custom AltiVec function (See DTKAddConstantAltiVec.c) */
void MFTYPE AddConstantAltiVec(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);
/* Custom ONL AltiVec Block Processing function (See DTKAddConstantONLAltiVec.c) */
void MFTYPE AddConstantONLAltiVec(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);
/* Custom PA unction (See DTKAddConstantPAMaster.c) */
void MFTYPE AddConstantPA(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);

/* Main to test the AddConstant functions. */
/* --------------------------------------- */

void main(void)
   {
   MIL_ID MilApplication,        /* Application Identifier.  */
          MilSystem,             /* System Identifier.       */
          MilDisplay,            /* Display Identifier.      */
          MilImageDisp,          /* Image buffer Identifier. */
          MilImageSrc,           /* Image buffer Identifier. */
          MilImageDst;           /* Image buffer Identifier. */
   int    Version, n;            /* Loop variables.          */
   double Time;                  /* Processing time.         */

   /* Allocate default application, system, display and image. */
   MappAllocDefault(M_COMPLETE, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore the source image into one display buffer and 2 processing buffers. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImageDisp);
   MbufRestore(IMAGE_FILE, MilSystem, &MilImageSrc);
   MbufRestore(IMAGE_FILE, MilSystem, &MilImageDst);

   /* Display the source image. */
   MdispSelect(MilDisplay, MilImageDisp);

   /* Pause */
   printf("\nMIL DTK:\n");
   printf("--------\n\n");
   printf("This example tests and times different versions of a custom\n");
   printf("asynchronous MIL function that adds a constant to an image.\n");
   printf("Press a key to continue.\n\n");
   getch();

   /* Process the image using the C version of the custom MIL function. */
   AddConstantC(MilImageSrc, MilImageDisp, 0x40);

   /* Print comment */
   printf("A constant was added to the image using a user-made MIL function.\n\n");

   /* Call and time all the versions of the add constant function.
      Do it in loop for more precision.
   */
   for (Version = 0; Version < NB_VERSIONS; Version++)
      {
      for (n= 0; n < NB_LOOP+1; n++)
         {
         /* Don't time the first iteration (avoid DLL load time, ...). */
         if (n == 1)
            MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

         /* Call the proper version */
         switch(Version)
            {
            case USE_C:
                 AddConstantC(MilImageSrc, MilImageDst, 0x40);
                 break;

            case USE_ALTIVEC:
                 AddConstantAltiVec(MilImageSrc, MilImageDst, 0x40);
                 break;

            case USE_ONL_ALTIVEC:
                 AddConstantONLAltiVec(MilImageSrc, MilImageDst, 0x40);
                 break;

            case USE_PA:
                 /* Process the image with the custom MIL function (C version). */
                 AddConstantPA(MilImageSrc, MilImageDst, 0x40);
                 break;

            case USE_MIL:
                 MimArith(MilImageSrc, 0x40, MilImageDst, M_ADD_CONST);
                 break;
            }
         }

      /* Read and print the time.*/
      MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);
      printf("Add constant time (%s version): %.3f ms.\n", VersionName[Version], Time*1000/NB_LOOP);
      }

   /* Pause */
   printf("Press a key to terminate.\n\n");
   getch();

   /* Free all allocations. */
   MbufFree(MilImageSrc);
   MbufFree(MilImageDst);
   MbufFree(MilImageDisp);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   }


Example: dtkaddconstantonlaltivec.c

/*****************************************************************************************/
/*
 * File name: DTKAddConstantONLAltiVec.c
 * Synopsis:  This example shows how to use of the MIL Function Developer's Toolkit to
 *            create a custom MIL function that adds a constant to an image using
 *            custom ONL AltiVec Block Processing code.
 *
 *            The example creates a Master MIL function that registers all the parameters
 *            to MIL and calls the Slave function on the target system. The Slave function
 *            retrieves all the parameters and call a Target processing function that adds
 *            a constant to the source buffer and writes the result to the target image.
 *
 *            Note: For simplicity, the images are assumed to be 8-bit unsigned and of
 *            the same dimensions.
 */

/* MIL header. */
#include <mil.h>

/* Master, Slave and Target MIL functions declarations */
void MFTYPE AddConstantONLAltiVec(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);
void MFTYPE SlaveAddConstantONLAltiVec(MIL_ID Func);
void MFTYPE TargetAddConstantONLAltiVec(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);

/* Master MIL Function definition. */
/* ------------------------------- */

/* Number of parameters of the MIL function. */
#define FUNCTION_NB_PARAM    3

/* Opcode that matches the offset of the slave PA function pointer in the MfuncUserSlaveFunctions[] table. */
#define FUNCTION_OPCODE_ADD_CONST_ONL_ALTIVEC (M_USER_FUNCTION+6)

void MFTYPE AddConstantONLAltiVec(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant)
   {
   MIL_ID   Func;

   /* Allocate a MIL function context to call the Slave function on the Target system. */
   MfuncAlloc(MIL_TEXT("AddConstantONLAltiVec"),
              FUNCTION_NB_PARAM,
              M_NULL, M_NULL, M_NULL,
              FUNCTION_OPCODE_ADD_CONST_ONL_ALTIVEC,
              M_ASYNCHRONOUS_FUNCTION,
              &Func
             );

   /* Register the parameters. */
   MfuncParamId(  Func, 1, SrcImage, M_IMAGE, M_IN  + M_PROC);
   MfuncParamId(  Func, 2, DstImage, M_IMAGE, M_OUT + M_PROC);
   MfuncParamLong(Func, 3, Constant);

   /* Call the Slave function. */
   MfuncCall(Func);

   /* Free the MIL function context. */
   MfuncFree(Func);
   }

/* Compile Slave and ONL code only on the PowerPC. */
#if M_MIL_USE_PPC

/* Slave MIL Function definition. */
/* ------------------------------ */

void MFTYPE SlaveAddConstantONLAltiVec(MIL_ID Func)
   {
   MIL_ID SrcImage, DstImage;
   unsigned long Constant;

   /* Now we are on the Target system and we will call the Target processing function. */

   /* Retrieve the passed parameters. */
   MfuncParamValue(Func, 1, &SrcImage);
   MfuncParamValue(Func, 2, &DstImage);
   MfuncParamValue(Func, 3, &Constant);

   /* Calls the target slave function. */
   TargetAddConstantONLAltiVec(SrcImage, DstImage, Constant);
   }

/* Target MIL processing function definition using ONL AltiVec block processing. */
/* ----------------------------------------------------------------------------- */
/*
 * This function adds a constant to a MIL buffer using ONL DTK and its
 * block processing function set.
 *
 * For simplicity, it assumes that the buffers are 8-bit unsigned
 * buffers allocated with MbufAlloc2d().
 */

/* ONL DTK header */
#include <image2.h>

/* Target function restrictions and error code. */
#define FUNCTION_SUPPORTED_IMAGE_DEPTH    (8+M_UNSIGNED)
#define FUNCTION_PARAMETER_ERROR_CODE     1

void MFTYPE TargetAddConstantONLAltiVec(MIL_ID Src, MIL_ID Dst, unsigned long Constant)
   {
    long        SrcOnlId,   DstOnlId;
   MP_BUF_ST  *SrcOnlPtr, *DstOnlPtr;
   MP_BLOCK1D_ST BlockSrc, BlockDst;
   MP_RESOURCE_ST *Resource;
   MP_VECTOR vConstant;
   long SizeX, SizeY;
   long MaxPix, NumPix, Block, NumBlock;
   long (*NextSrc)(MP_BLOCK1D_ST *, void *);
   void (*NextDst)(MP_BLOCK1D_ST *, void *);
   unsigned char  *TmpBuf;

   /* If the images have the proper type and dimensions, process them.*/
   if ((MbufInquire(Src, M_TYPE, M_NULL)   == FUNCTION_SUPPORTED_IMAGE_DEPTH) &&
       (MbufInquire(Dst, M_TYPE, M_NULL)   == FUNCTION_SUPPORTED_IMAGE_DEPTH)
      )
      {
      /* Inquire the ONL ID of the buffers */
      MbufInquire(Src, M_NATIVE_ID, &SrcOnlId);
      MbufInquire(Dst, M_NATIVE_ID, &DstOnlId );

      /* Inquire the buffers ONL MP_BUF_ST. */
      SrcOnlPtr = mp_buf_pointer(SrcOnlId);
      DstOnlPtr = mp_buf_pointer(DstOnlId );

      /* Determine size to process */
      mp_util_min_size(SrcOnlPtr, DstOnlPtr, NULL, NULL, &SizeX, &SizeY);

      /* Make a vector version of the constant */
      mp_util_replicate(Constant, IM_UBYTE, &vConstant);

      /* Inquire the ONL resource for the current thread. */
      Resource = mp_thr_thread_resource(mp_thr_thread_descriptor(mp_sys_this_thread()));

      /* Need one 8-bit tmp buffer. Use the suggested total tmp size */
      MaxPix = mp_res_tmp_size(Resource);

      /* Find the appropriate I/O function for each buffer */
      NextSrc = mp_1d_set_src(&BlockSrc, SrcOnlPtr, 0, SizeX, SizeY, 8, MaxPix, IM_DEFAULT);
      NextDst = mp_1d_set_dst(&BlockDst, DstOnlPtr, 0, SizeX, SizeY, 8, MaxPix, IM_DEFAULT);

      /* "Allocate" a temporary buffer of the proper size */
      TmpBuf = (unsigned char *)mp_res_tmp_address(Resource);

      /* Number of blocks to process. */
      NumBlock = mp_1d_num_blocks(&BlockSrc);

      /* Process each block */
      for (Block = 0; Block < NumBlock; Block++)
         {
         /* Read and align a block of source pixels */
         NumPix = NextSrc(&BlockSrc, TmpBuf);

         /* Process the aligned pixels */
         mp_1d_addc_8(TmpBuf, vConstant, TmpBuf, NumPix);

         /* Align and store the results */
         NextDst(&BlockDst, TmpBuf);
         }

      /* Make sure no buffer remain cached */
      mp_util_dl1_flush();

      /* Signal MIL that the destination buffer has been modified. */
      MbufControl(Dst, M_MODIFIED, M_DEFAULT);
      }
   else
      {
      /* Report a MIL error. */
      MfuncErrorReport(M_DEFAULT, M_FUNC_ERROR+FUNCTION_PARAMETER_ERROR_CODE,
                       MIL_TEXT("Invalid parameter."),
                       MIL_TEXT("Images must be 8-bit unsigned."),
                       M_NULL,
                       M_NULL
                      );
      }
   }
#endif /* M_MIL_USE_PPC */


Example: dtkaddconstantpamaster.c

/*****************************************************************************************/
/*
 * File name: DTKAddConstantPAMaster.c
 *
 * Synopsis:  This example shows how to use of the MIL Function Developer's Toolkit to
 *            create a custom MIL function that adds a constant to an image using
 *            custom Native PA code.
 *
 *            This file contains only the Master function. See DTKAddConstantPASlave.C
 *            for the Slave function with the Native PA code.
 *
 *            The example creates a Master MIL function that registers all the parameters
 *            to MIL and calls the Slave function on the target system. The Slave function
 *            retrieves all the parameters, adds a constant to the source buffer
 *            and writes the result to the target image using the OASIS ASIC PA.
 *
 */

/* Master MIL Function definition. */
/* ------------------------------- */

/* Standard MIL header. */
#include <mil.h>

/* Master MIL function declaration */
void MFTYPE AddConstantPA(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant);

/* Number of parameters of the user-defined MIL Function. */
#define FUNCTION_NB_PARAM    3

/* Opcode that must match the offset of the Slave PA function pointer
   in the MfuncUserPASlaveFunctions[] table.
*/
#define FUNCTION_OPCODE_ADD_CONST_PA  (M_USER_PA_FUNCTION+1)

/* PA function restrictions and error code. */
#define FUNCTION_SUPPORTED_IMAGE_DEPTH    (8+M_UNSIGNED)
#define FUNCTION_PARAMETER_ERROR_CODE     1

void MFTYPE AddConstantPA(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Constant)
   {
   MIL_ID   Func;

   /* Allocate a MIL function context to call the Slave function on the Target system. */
   MfuncAlloc(MIL_TEXT("AddConstantPA"),
              FUNCTION_NB_PARAM,
              M_NULL, M_NULL, M_NULL,
              FUNCTION_OPCODE_ADD_CONST_PA,
              M_ASYNCHRONOUS_FUNCTION,
              &Func
             );

   /* Register the parameters. */
   MfuncParamId(  Func, 1, SrcImage, M_IMAGE, M_IN  + M_PROC);
   MfuncParamId(  Func, 2, DstImage, M_IMAGE, M_OUT + M_PROC);
   MfuncParamLong(Func, 3, Constant);

   /* If the images have the proper type and dimensions, process them.
      Note that to be portable any MIL function call (such as MbufInquire())
      must be done here before calling the PA slave function because the
      PA function can be executed in kernel mode where only Native PA functions
      are allowed.
   */
   if ((MbufInquire(SrcImage, M_TYPE, M_NULL)   == FUNCTION_SUPPORTED_IMAGE_DEPTH) &&
       (MbufInquire(DstImage, M_TYPE, M_NULL)   == FUNCTION_SUPPORTED_IMAGE_DEPTH)
      )
      {
      /* Call the PA Slave function. */
      MfuncCall(Func);
      }
   else
      {
      /* Report a MIL error. */
      MfuncErrorReport(Func,M_FUNC_ERROR+FUNCTION_PARAMETER_ERROR_CODE,
                       MIL_TEXT("Invalid parameter."),
                       MIL_TEXT("Images must be 8-bit unsigned."),
                       M_NULL,
                       M_NULL
                      );
      }

   /* Free the MIL function context. */
   MfuncFree(Func);
   }


Example: dtkaddconstantpaslave.c

/*****************************************************************************************/
/*
 * File name: DTKAddConstantPASlave.c
 *
 * Synopsis:  This example shows how to use of the MIL Function Developer's Toolkit to
 *            create a custom MIL function that adds a constant to an image using
 *            custom Native PA code.
 *
 *            The example creates a Master MIL function that registers all the parameters
 *            to MIL and calls the Slave function on the target system. The Slave function
 *            retrieves all the parameters, adds a constant to the source buffer
 *            and writes the result to the target image using the OASIS ASIC PA.
 *
 *            This file contains only the Slave function. See DTKAddConstantPAMaster.C
 *            for the Master function that should be used to call this Native PA function.
 *
 *            Note: For simplicity, the images are assumed to be 8-bit unsigned.
 */

/* Slave Native PA processing function. */
/* ------------------------------------ */
/*
 * This function adds a constant to a MIL buffer using the Pixel Accelerator (PA)
 * and the Native PA DTK. The pointer to this function must be entered at the
 * index corresponding to its Opcode in the PA function table before it can be
 * called with MfuncCall().
 *
 * For simplicity, the function assumes that the buffers are monochrome 8-bit unsigned
 * buffers allocated using MbufAlloc2d() and residing on the board so that they are properly
 * located and aligned for PA operations.
 *
 * Note that to be portable, no regular MIL function can be used in a Native PA function.
 */

/* Compile Native PA code only on the PowerPC or in Host kernel mode PA DLL. */
#if (M_MIL_USE_PPC || M_MIL_USE_PA_CODE_ONLY)

/* Headers for Native PA functions development. */
#include <milpa.h>

/* Precompiled custom PA nanocode generated with PACL. */
#include "DTKPAAddConstantNanocode.h"

/* Function error code value. */
#define ADD_CONSTANT_PARAMETER_ERROR_CODE   1

/* Slave function code. */
void MFTYPE SlaveAddConstantPA(MIL_ID Func);

void MFTYPE SlaveAddConstantPA(MIL_ID Func)
   {
   MIL_ID SrcImage;
   MIL_ID DstImage;
   unsigned long Constant, SrcNativeBufId, DstNativeBufId;
   MP_BUF_ST    *SrcNativeBufPtr, *DstNativeBufPtr;
   MP_RESOURCE_ST *Resource;
   long SizeX, SizeY;
   long Block, NumBlock;
   long AllocatedPA = 0;
   PA_REGISTER_ST PA;

   /* The function is now executing in the Native PA environment on the target processing system.
      No regular MIL functions are available in a Native PA slave function. Only the Mfunc..()
      and mp_..() functions documented in the MIL Native PA DTK manual can be used.
   */

   /* Retrieve the parameters. */
   MfuncParamValue(Func, 1, &SrcImage);
   MfuncParamValue(Func, 2, &DstImage);
   MfuncParamValue(Func, 3, &Constant);

   /* Inquire the native buffers identifiers and PA resource. */
   SrcNativeBufId = mp_mil_buf_inquire(SrcImage, M_NATIVE_ID, 0);
   DstNativeBufId = mp_mil_buf_inquire(DstImage, M_NATIVE_ID, 0);
   Resource       = mp_mil_func_resource(Func);

   /* Inquire the buffers Native MP_BUF_ST structure. */
   SrcNativeBufPtr = mp_buf_pointer(SrcNativeBufId);
   DstNativeBufPtr = mp_buf_pointer(DstNativeBufId);

   /* If the buffers are not accessible to the PA or the PA is disabled,
      log a MIL error and return immediately.
    */
   if((!mp_pa_valid(SrcNativeBufPtr) || !mp_pa_valid(DstNativeBufPtr)) ||
      (mp_thr_accelerator(mp_sys_this_thread()) == IM_DISABLE))
       {
       MfuncErrorReport(Func, M_FUNC_ERROR+ADD_CONSTANT_PARAMETER_ERROR_CODE,
                      "Invalid parameters.",
                      "Images not accessible by the PA or PA processing disabled.",
                      M_NULL,
                      M_NULL
                     );
       return;
       }

   /* Determine size to process. */
   mp_util_min_size(SrcNativeBufPtr, DstNativeBufPtr, NULL, NULL, &SizeX, &SizeY);

   /* Initialize for a point operation with one Src and one Dst. */
   mp_pa_set_mode(&PA, IM_OP_POINT, 1, 1, IM_SINGLE, IM_DISABLE);

   /* Program the source (must be src 3). */
   mp_pa_set_src(&PA, 3, SrcNativeBufPtr, 0, SizeX, SizeY, IM_DEFAULT);

   /* Program the destination (must be dst 0). */
   mp_pa_set_dst(&PA, 0, DstNativeBufPtr, 0, SizeX, SizeY, IM_DEFAULT);

   /* Specify the nanocode location in the PA. */
   mp_pa_set_nanocode_start(&PA, 0);

   /* Set constants. */
   mp_pa_set_constant(&PA, 0, Constant);

   /* Determine the number of blocks needed to cover the image. */
   NumBlock = mp_pa_set_block_size(&PA, IM_DEFAULT, IM_DEFAULT, IM_DEFAULT);

   /* Allocate the PA if not already done. */
   if(!mp_res_use_pa(Resource))
      {
      AllocatedPA = 1;
      mp_res_alloc_pa(Resource);
      }

   /* Load precompiled nanocode sequence. */
   mp_pa_load_nanocode(Resource, &PA,
                       NanocodePAAddConstant+PA_START_PAADDCONSTANT_CODE,
                       0, PA_SIZE_PAADDCONSTANT_CODE
                      );

   /* Loop through all blocks. */
   for(Block = 0; Block < NumBlock; Block++)
       {
       /* Load all required PA registers. */
       mp_pa_load_regs(Resource, &PA, IM_DEFAULT);

       /* Start the PA. */
       mp_res_start_pa(Resource);

       /* Wait for it to finish. */
       mp_res_wait_pa(Resource);
       }

   /* Free the PA if allocated. */
   if(AllocatedPA)
      mp_res_free_pa(Resource);
   }


Example: dtkobjecttracking.c

/**********************************************************************************/
/*
 *  File name: DTKObjectTracking.c
 *
 *  Synopsis:  This example uses the MIL Odyssey DTK to create and autonomous processing
 *             loop that runs directly on the Odyssey target system. The processing loop
 *             does object tracking.
 *
 *             To optimize the processing and free the Host cpu, the function will run
 *             completely on the target system and do the complete grab and model search
 *             job in real time instead of sending each individual commands from the Host.
 *             The results of each search will be returned in lot at each processing loop
 *             in a shared Data Exchange structure copied from the Target system to the Host.
 *
 *             The example will first do a grab controlled from the Host to define the model.
 *             After it will start the autonomous procressing function to follow the model on
 *             the target Odyssey system while printing the results and displaying the
 *             annotated images on the Host.
 */

/* MIL Header. */
#include <mil.h>

/* Specify which pattern matching type to use (choose one). */
#define GEOMETRIC        0
#define GRAYSCALE        1
#define PATTERN_MATCHING_METHOD  GRAYSCALE

/* Specify where the Slave processing loop will be run (choose one). */
#define TARGET_PLATFORM      M_NULL   /* Automatic choice.           */
//#define TARGET_PLATFORM    M_LOCAL  /* Force Slave to run on Host. */
//#define TARGET_PLATFORM    M_REMOTE /* Force Slave to on PowerPC.  */

/* Flag to update the display and draw the position found while processing. */
#define DISPLAY_UPDATE        M_YES

/* Target model specifications. */
#define MODEL_WIDTH           128L
#define MODEL_HEIGHT          128L
#define MODEL_POS_X_INIT      320L
#define MODEL_POS_Y_INIT      240L
#define MODEL_MIN_MATCH_SCORE 50.0

/* Processing functions prototypes. */
long MFTYPE PatternMatchingLoop(MIL_ID *MilDataExchangeBuffer);
void MFTYPE SlavePatternMatchingLoop(MIL_ID Func);

/* Data Exchange structure between Host and Target processors. */
typedef struct
   {
   MIL_ID MilSystem;
   MIL_ID MilDisplay;
   MIL_ID MilDigitizer;
   MIL_ID MilImageDisp;
   MIL_ID MilDataExchangeBuffer;
   MIL_ID MilThread;
   MIL_ID MilModelPositionOkEvent;
   MIL_ID MilDataExchangeBufferReadyEvent;
   MIL_ID MilStopProcessingEvent;
   long   PatternMatchingMethod;
   long   DisplayUpdateFlag;
   long   Found;
   double PosX;
   double PosY;
   double Score;
   double Time;
   long   NbFindDone;
   long   Error;
   } DataExchangeStruct;

/* On the HOST, compile the main() and the data exchange buffer hook function. */
#if !M_MIL_USE_PPC

/* Standard I/O Header. */
#include <conio.h>

/* Host Hook function prototype. */
long MFTYPE DataExchangeBufferModified(long, MIL_ID, void MPTYPE *);

/******************************************************************************/
/* main function. */
void main(void)
{
   /* Variables declaration */
   MIL_ID MilApplication;
   DataExchangeStruct DataEx;
   long   i=0, Error = 0;
   long   NbGrab     = 0;
   double Time       = 0.0;

   /* Allocate MIL objects. */
   MappAlloc(M_DEFAULT, &MilApplication);
   MsysAlloc("M_DEFAULT", M_DEFAULT, M_DEFAULT, &DataEx.MilSystem);
   MdispAlloc(DataEx.MilSystem, M_DEFAULT, "M_DEFAULT", M_DEFAULT, &DataEx.MilDisplay);
   MdigAlloc(DataEx.MilSystem, M_DEFAULT, "M_DEFAULT", M_DEFAULT, &DataEx.MilDigitizer);
   MbufAlloc2d(DataEx.MilSystem,
               MdigInquire(DataEx.MilDigitizer, M_SIZE_X, M_NULL),
               MdigInquire(DataEx.MilDigitizer, M_SIZE_Y, M_NULL),
               8L+M_UNSIGNED,
               M_IMAGE+M_PROC+M_DISP+M_GRAB, &DataEx.MilImageDisp);
   MthrAlloc(DataEx.MilSystem, M_EVENT, M_NOT_SIGNALED+M_AUTO_RESET,
             M_NULL, M_NULL, &DataEx.MilModelPositionOkEvent);
   MthrAlloc(DataEx.MilSystem, M_EVENT, M_NOT_SIGNALED+M_AUTO_RESET,
             M_NULL, M_NULL, &DataEx.MilStopProcessingEvent);
   MthrAlloc(DataEx.MilSystem, M_EVENT, M_SIGNALED    +M_AUTO_RESET,
             M_NULL, M_NULL, &DataEx.MilDataExchangeBufferReadyEvent);

   /* Initialize the display */
   MbufClear(DataEx.MilImageDisp, 0x0);
   MdispSelect(DataEx.MilDisplay, DataEx.MilImageDisp);

   /* Allocate a MIL array buffer for the Data Exchange structure with the Target
      system. This data will include the Target processing results which will be
      read in a single faster MbufGet() operation.
   */
   MbufAlloc1d(DataEx.MilSystem, sizeof(DataExchangeStruct),
               8L+M_UNSIGNED, M_ARRAY, &DataEx.MilDataExchangeBuffer);

   /* Specify to update the display with the model position found. */
   DataEx.DisplayUpdateFlag = DISPLAY_UPDATE;

   /* Specify which type of pattern matching to perform. */
   DataEx.PatternMatchingMethod = PATTERN_MATCHING_METHOD;

   /* Initialize the MIL Data Exchange buffer with the structure. */
   MbufPut(DataEx.MilDataExchangeBuffer, &DataEx);

   /* Hook a callback function to the Data Exchange buffer modification
      to get the result on the Host.
   */
   MbufHookFunction(DataEx.MilDataExchangeBuffer, M_MODIFIED_BUFFER,
                    DataExchangeBufferModified, &DataEx.MilDataExchangeBuffer);

   /* START THE TARGET PROCESSING PROCEDURE:
      This function will allocate and start an autonomous thread on the Host and
      on the Odyssey that will run the pattern matching loop on the target system.
   */
   MthrAlloc(M_DEFAULT, M_THREAD, M_DEFAULT, PatternMatchingLoop,
             &DataEx.MilDataExchangeBuffer, &DataEx.MilThread);

   /* Here the Host is free to do any other task. The processing loop is running
      autonomously, grabbing and waiting for the Host to signal that the
      Target Model is properly positionned to define the model and start
      the processing.
   */

   /* Print a user message and wait for good model position. */
   printf("\nMIL DTK:\n");
   printf("--------\n\n");
   printf("On-board object tracking:\n\n");
   printf("Place the rectangle on the model to be found.\n");
   printf("Press a key to continue.\n\n");
   getch();

   /* Print a user message to announce the processing loop. */
   printf("Finding the model using an autonomous user-defined function.\n");
   printf("Press a key to stop processing.\n\n");

   /* Set the Model Position Ok Event to allocate model and start the procesing loop. */
   MthrControl(DataEx.MilModelPositionOkEvent, M_EVENT_SET, M_SIGNALED);

   /* Here the Host is free to do any other task again. The processing loop
      is running autonomously and passing the necessary results to the Host via the data
      exchange buffer. The host is called in a separate thread via its hook function
      each time new results are written by the processing loop. The hook
      function prints the results and statistics.
   */

   /* Wait for a key. */
   getch();

   /* Stop the processing loop. */
   MthrControl(DataEx.MilStopProcessingEvent, M_EVENT_SET, M_SIGNALED);

   /* Wait for processing thread to be completed before freeing the MIL objects. */
   MthrWait(DataEx.MilThread, M_THREAD_END_WAIT, M_NULL);

   /* Unhook the Data exchange buffer modifications */
   MbufHookFunction(DataEx.MilDataExchangeBuffer, M_MODIFIED_BUFFER+M_UNHOOK,
                    DataExchangeBufferModified, &DataEx.MilDataExchangeBuffer);

   /* Free allocations. */
   MthrFree(DataEx.MilDataExchangeBufferReadyEvent);
   MthrFree(DataEx.MilStopProcessingEvent);
   MthrFree(DataEx.MilModelPositionOkEvent);
   MthrFree(DataEx.MilThread);
   MbufFree(DataEx.MilDataExchangeBuffer);
   MbufFree(DataEx.MilImageDisp);
   MdispFree(DataEx.MilDisplay);
   MdigFree(DataEx.MilDigitizer);
   MsysFree(DataEx.MilSystem);
   MappFree(MilApplication);
}

/******************************************************************************
 * Data Modified hook function:
 *      - This function is used to print the position of the model found. It gets
 *        called each time new results are written in the Data Exchange Buffer.
 *
 *  Note: Time spend in the hook function should be minimal. External
 *        thread waiting on an event should be used to do long processing
 *        otherwise the processing loop will be waiting to continue.
 */
long MFTYPE DataExchangeBufferModified(long HookType, MIL_ID EventId, void MPTYPE *DataExchangeIdPtr)
{
   /* Variables declaration. */
   DataExchangeStruct DataEx;

   /* Get the pattern matching results by reading the Data Exchange structure. */
   MbufGet(*(MIL_ID *)DataExchangeIdPtr, &DataEx);

   /* Set the Buffer Ready event to signal to the Target system that the results were read. */
   MthrControl(DataEx.MilDataExchangeBufferReadyEvent, M_EVENT_SET, M_SIGNALED);

   /* Print the model search results and processing statistics. */
   if (DataEx.Found)
      {
      printf("Search #%ld: X=%-6.2f, Y=%-6.2f, Score=%5.1f %%, Frame rate=%.1f fps. \r",
              DataEx.NbFindDone, DataEx.PosX, DataEx.PosY, DataEx.Score, DataEx.NbFindDone/DataEx.Time);
      }
   else
      {
      printf("Search #%ld: Model not found: Score<%5.1f %%, Frame rate=%.1f fps.    \r",
              DataEx.NbFindDone, MODEL_MIN_MATCH_SCORE, DataEx.NbFindDone/DataEx.Time);
      }

   /* return successful completion status */
   return(M_NULL);
}

#endif /* !M_MIL_USE_PPC */

/******************************************************************************
 *  Master MIL function:
 *      - This function is used to launch the execution of a group of MIL
 *        functions on a Target system. This function grabs and processes
 *        in double buffering mode on the Target system without sending every
 *        MIL command individually from the Host computer. This has the great
 *        advantages of reducing the Host and Target CPU usage, the command
 *        send and result get overhead, the processing time and latency.
 *
 *        Although it can be called directly, we defined the function prototype
 *        to be compatible with MappControlThead(..., M_THREAD_CREATE, ...) to
 *        be able to start it in a separate thread on the Host and on the Odyssey.
 */

/* Function Parameters */
#define PATTERN_MATCHING_LOOP     (M_USER_FUNCTION+7)
#define NB_PARAMETERS             1

/* Error codes */
#define PATTERN_MATCHING_LOOP_ERROR_CODE 2

long MFTYPE PatternMatchingLoop(MIL_ID *MilDataExchangeBuffer)
   {
   /* Variables declaration */
   MIL_ID  Func;

   /* Allocate a Custom MIL function that will call a Target work function
      to do the real processing job on the Target computer.
   */
   MfuncAlloc(MT("PatternMatchingLoop"),
                  NB_PARAMETERS,
                  SlavePatternMatchingLoop, M_NULL, M_NULL,
                  PATTERN_MATCHING_LOOP,
                  M_SYNCHRONOUS_FUNCTION+TARGET_PLATFORM,
                  &Func
                );

   /* Register the function parameters. */
   MfuncParamId(Func, 1, *MilDataExchangeBuffer, M_ARRAY, M_IN+M_OUT);

   /* Call the Slave processing function on the Target system. */
   MfuncCall(Func);

   /* Mark the end of the function. */
   MfuncFree(Func);

   /* Thread return value. */
   return(M_TRUE);
}

/******************************************************************************
 *  Slave function:
 *      - This slave function does grab and processing in a loop and signals
 *        when results are available to the controling computer.
 *        This prevents the controling computer from having to send each MIL command
 *        individually, reducing the inter-computer overhead, and it permits to return
 *        all the results at the same time.
 */

/* Number of grab images. */
#define NB_TARGET_IMAGES 2

void MFTYPE SlavePatternMatchingLoop(MIL_ID Func)
{
   /* Variable declarations */
  MIL_ID MilDataExchangeBuffer;
  MIL_ID MilImage[NB_TARGET_IMAGES];
  MIL_ID MilModel;
  MIL_ID MilResult;
  long   TargetImageIndex;
  DataExchangeStruct DataEx;
  long  *ErrorReturnValuePtr = M_NULL;

  /* Read the parameter. */
  MfuncParamValue(Func, 1, &MilDataExchangeBuffer);

  /* Read the Data Exchange structure. */
  MbufGet(MilDataExchangeBuffer, &DataEx);

  /* Allocate 2 buffers for double buffering grab. */
  MbufAlloc2d(DataEx.MilSystem,
              MdigInquire(DataEx.MilDigitizer, M_SIZE_X, M_NULL),
              MdigInquire(DataEx.MilDigitizer, M_SIZE_Y, M_NULL),
              8L+M_UNSIGNED,
              M_IMAGE+M_GRAB+M_PROC, &MilImage[0]);
  MbufAlloc2d(DataEx.MilSystem,
              MdigInquire(DataEx.MilDigitizer, M_SIZE_X, M_NULL),
              MdigInquire(DataEx.MilDigitizer, M_SIZE_Y, M_NULL),
              8L+M_UNSIGNED,
              M_IMAGE+M_GRAB+M_PROC, &MilImage[1]);

  /* Initialize the buffers synchronously. */
  MdigGrab(DataEx.MilDigitizer, MilImage[0]);
  MdigGrab(DataEx.MilDigitizer, MilImage[1]);

  /* Put the digitizer in asynchronous mode. */
  MdigControl(DataEx.MilDigitizer, M_GRAB_MODE, M_ASYNCHRONOUS);

  /* Reset the target image index. */
  TargetImageIndex = 0;

  /* Grab until the ModelPositionOk event is set. */
  while(MthrInquire(DataEx.MilModelPositionOkEvent, M_EVENT_STATE, M_NULL) == M_NOT_SIGNALED)
      {
      /* Set the current image index. */
      TargetImageIndex = TargetImageIndex % 2;

      /* Grab the next buffer asynchronously while drawing in the current one. */
      MdigGrab(DataEx.MilDigitizer, MilImage[1-TargetImageIndex]);

      /* Draw a rectangle in the Overlay around the position of the model to define. */
      MgraRect(M_DEFAULT, MilImage[TargetImageIndex],
              (long)(MODEL_POS_X_INIT+0.5) - (MODEL_WIDTH/2)  - 2,
              (long)(MODEL_POS_Y_INIT+0.5) - (MODEL_HEIGHT/2) - 2,
              (long)(MODEL_POS_X_INIT+0.5) + (MODEL_WIDTH/2)  + 1,
              (long)(MODEL_POS_Y_INIT+0.5) + (MODEL_HEIGHT/2) + 1);

      /* Update the display */
      MbufCopy(MilImage[TargetImageIndex], DataEx.MilImageDisp);

      /* Increment target image index. */
      TargetImageIndex++;
      }

   /* Wait for the last grab end. */
   MdigGrabWait(DataEx.MilDigitizer, M_GRAB_END);

  /* --------------------------- */
  /* GEOMETRIC PATTERN MATCHING. */

  if (DataEx.PatternMatchingMethod == GEOMETRIC)
     {
     /* Allocate a geometric model finder context to hold the model. */
     MmodAlloc(DataEx.MilSystem, M_GEOMETRIC, M_DEFAULT, &MilModel);

     /* Define a geometric model from the last grabbed image. */
     MmodDefine(MilModel, M_IMAGE, MilImage[TargetImageIndex % 2],
                (long)(MODEL_POS_X_INIT+0.5) - (MODEL_WIDTH/2)  - 1,
                (long)(MODEL_POS_Y_INIT+0.5) - (MODEL_HEIGHT/2) - 1,
                MODEL_WIDTH, MODEL_HEIGHT);

     /* Allocate a result buffer. */
     MmodAllocResult(DataEx.MilSystem, M_DEFAULT, &MilResult);

     /* If no allocation error, set the model search parameters,
        preprocess the model and set the error state to false.
     */
     if ((MilModel    != M_NULL) && (MilResult   != M_NULL) &&
         (MilImage[0] != M_NULL) && (MilImage[1] != M_NULL)
        )
        {
        MmodControl(MilModel, M_CONTEXT, M_NUMBER, 1);
        MmodControl(MilModel, M_CONTEXT, M_SPEED, M_VERY_HIGH);
        MmodControl(MilModel, M_CONTEXT, M_ACCURACY, M_MEDIUM);
        MmodControl(MilModel, M_ALL, M_ACCEPTANCE, MODEL_MIN_MATCH_SCORE);
        MmodPreprocess(MilModel, M_DEFAULT);
        DataEx.Error = M_FALSE;
        }
     else
        {
        /* Stop the processing. */
        MthrControl(DataEx.MilStopProcessingEvent, M_EVENT_SET, M_SIGNALED);

        /* Report a MIL error. */
        MfuncErrorReport(Func, M_FUNC_ERROR+PATTERN_MATCHING_LOOP_ERROR_CODE,
                         MT("Error during target processing loop allocations."),
                         M_NULL, M_NULL, M_NULL
                        );
        DataEx.Error = M_TRUE;
        }

     /* Reset the find count. */
     DataEx.NbFindDone = 0;

     /* Grab the first buffer. */
     MdigGrab(DataEx.MilDigitizer, MilImage[0]);

     /* Process until the Continue Processing Event is reset by the Host. */
     while(MthrInquire(DataEx.MilStopProcessingEvent, M_EVENT_STATE, M_NULL) == M_NOT_SIGNALED)
         {
         /* Set the current image index. */
         TargetImageIndex = DataEx.NbFindDone % 2 ;

         /* Grab the next buffer asynchronously while searching in the current one. */
         MdigGrab(DataEx.MilDigitizer, MilImage[1-TargetImageIndex]);

         /* Synchronize and start the timer. */
         if (DataEx.NbFindDone == 0)
            MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

         /* Find model. */
         MmodFind(MilModel, MilImage[TargetImageIndex], MilResult);

         /* Increment find operation count. */
         DataEx.NbFindDone++;

         /* Copy the results in the result structure to be read by the Local system. */
         MmodGetResult(MilResult, M_DEFAULT, M_NUMBER+M_TYPE_LONG, &DataEx.Found);
         MmodGetResult(MilResult, M_DEFAULT, M_POSITION_X, &DataEx.PosX);
         MmodGetResult(MilResult, M_DEFAULT, M_POSITION_Y, &DataEx.PosY);
         MmodGetResult(MilResult, M_DEFAULT, M_SCORE,      &DataEx.Score);

         /* If required, copy the processed image with the model position drawn to the display. */
         if (DataEx.DisplayUpdateFlag)
            {
            if (DataEx.Found)
               MmodDraw(M_DEFAULT, MilResult,  MilImage[TargetImageIndex],
                        M_DRAW_POSITION+M_DRAW_BOX, M_DEFAULT, M_DEFAULT);
            else
               MgraText(M_DEFAULT, MilImage[TargetImageIndex],
                        MODEL_POS_X_INIT, MODEL_POS_Y_INIT, "  MODEL NOT FOUND ?  ");
            MbufCopy(MilImage[TargetImageIndex], DataEx.MilImageDisp);
            }

         /* Read the elapsed time. */
         MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &DataEx.Time);

         /* Wait for previous results to be read (event set).*/
         MthrWait(DataEx.MilDataExchangeBufferReadyEvent, M_EVENT_WAIT, M_NULL);

         /* Write the new results (This also triggers the MbufHookFunction() callback. */
         MbufPut(MilDataExchangeBuffer, &DataEx);
         }

     /* Wait for the last grab end. */
     MdigGrabWait(DataEx.MilDigitizer, M_GRAB_END);

     /* Free the model finder objects */
     if (MilResult != M_NULL) MmodFree(MilResult);
     if (MilModel  != M_NULL) MmodFree(MilModel);
     }

  /* --------------------------- */
  /* GRAYSCALE PATTERN MATCHING. */

  else
     {
     /* Allocate normalized grayscale type model from the last grabbed image. */
     MpatAllocModel(DataEx.MilSystem, MilImage[TargetImageIndex % 2],
                    (long)(MODEL_POS_X_INIT+0.5) - (MODEL_WIDTH/2)  - 1,
                    (long)(MODEL_POS_Y_INIT+0.5) - (MODEL_HEIGHT/2) - 1,
                    MODEL_WIDTH, MODEL_HEIGHT,
                    M_NORMALIZED, &MilModel);

     /* Allocate result. */
     MpatAllocResult(DataEx.MilSystem, 1L, &MilResult);

     /* If no allocation error, set the model search parameters,
        preprocess the Target model and set the error state to false.
     */
     if ((MilModel != M_NULL) && (MilResult != M_NULL))
        {
        MpatSetAcceptance(MilModel,MODEL_MIN_MATCH_SCORE);
        MpatSetSpeed(MilModel,M_HIGH);
        MpatSetAccuracy(MilModel,M_LOW);
        MpatPreprocModel(MilImage[0], MilModel, M_DEFAULT);
        DataEx.Error = M_FALSE;
        }
     else
        {
        /* Skip the processing. */
        MthrControl(DataEx.MilStopProcessingEvent, M_EVENT_SET, M_SIGNALED);
        /* Report a MIL error. */
        MfuncErrorReport(Func, M_FUNC_ERROR+PATTERN_MATCHING_LOOP_ERROR_CODE,
                         MT("Error during target processing loop model allocations."),
                                                            M_NULL, M_NULL, M_NULL);
        DataEx.Error = M_TRUE;
        }

     /* Reset the find count. */
     DataEx.NbFindDone = 0;

     /* Grab the first buffer. */
     MdigGrab(DataEx.MilDigitizer, MilImage[0]);

     /* Process until the Continue Processing Event is reset by the Host. */
     while(MthrInquire(DataEx.MilStopProcessingEvent, M_EVENT_STATE, M_NULL) == M_NOT_SIGNALED)
         {
         /* Set the current image index. */
         TargetImageIndex = DataEx.NbFindDone%2 ;

         /* Grab the next buffer asynchronously while searching in the current one. */
         MdigGrab(DataEx.MilDigitizer, MilImage[1-TargetImageIndex]);

         /* Synchronize and start the timer. */
         if (DataEx.NbFindDone == 0)
            MappTimer(M_TIMER_RESET, M_NULL);

         /* Find model. */
         MpatFindModel(MilImage[TargetImageIndex], MilModel, MilResult);

         /* Increment find operation count. */
         DataEx.NbFindDone++;

         /* Get the results. */
         MpatGetNumber(MilResult, &DataEx.Found);
         MpatGetResult(MilResult, M_POSITION_X, &DataEx.PosX);
         MpatGetResult(MilResult, M_POSITION_Y, &DataEx.PosY);
         MpatGetResult(MilResult, M_SCORE, &DataEx.Score);

         /* If required, update the display with the processed image and the
            model position drawn in it.
         */
         if (DataEx.DisplayUpdateFlag)
            {
            if (DataEx.Found)
               MpatDraw(M_DEFAULT, MilResult, MilImage[TargetImageIndex],
                                   M_DRAW_BOX+M_DRAW_POSITION, M_DEFAULT, M_DEFAULT);
            else
               MgraText(M_DEFAULT, MilImage[TargetImageIndex],
                        MODEL_POS_X_INIT, MODEL_POS_Y_INIT, "  MODEL NOT FOUND ?  ");
            MbufCopy(MilImage[TargetImageIndex], DataEx.MilImageDisp);
            }

         /* Read the elapsed time. */
         MappTimer(M_TIMER_READ, &DataEx.Time);

         /* Wait for previous results to be read (event set).*/
         MthrWait(DataEx.MilDataExchangeBufferReadyEvent, M_EVENT_WAIT, M_NULL);

         /* Write the new results (This also generate the MbufHookFunction() callback. */
         MbufPut(MilDataExchangeBuffer, &DataEx);
         }

     /* Wait for the last grab end. */
     MdigGrabWait(DataEx.MilDigitizer, M_GRAB_END);

     /* Free pattern matching objects */
     if (MilResult != M_NULL) MpatFree(MilResult);
     if (MilModel  != M_NULL) MpatFree(MilModel);
     }

  /* Free the grab buffers */
  MbufFree(MilImage[0]);
  MbufFree(MilImage[1]);

  /* Set the event to signal the host that the processing loop is finished. */
  MthrControl(DataEx.MilStopProcessingEvent, M_EVENT_SET, M_SIGNALED);
}


Example: dtkremap.c

/*****************************************************************************************/
/*
 * File name: DTKRemap.c
 *
 * Synopsis:  This example shows how to use of the MIL Function Developer's Toolkit to
 *            create a custom asynchronous MIL function that does a series of MIL
 *            commands on a target system in a single call from the host. The function
 *            shows how to avoid having the Host to wait for on board calculation result
 *            and also show how to reduce the overhead of sending multiple commands by
 *            grouping them in a meta MIL function.
 *
 *            The example creates a Master MIL function that register all the parameters
 *            to MIL and call the Slave function on the target system. The Slave function
 *            retrieve all the parameters, Find the Max and Min of the source buffer and
 *            remap it to have it full range (min at 0x0 and the max at 0xFF).
 *
 *            Note: For simplicity, the images are assumed to be 8-bit unsigned.
 */

/* MIL Header. */
#include <mil.h>

/* Master and Slave MIL functions declarations */
void MFTYPE CustomRemap(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Option);
void MFTYPE SlaveCustomRemap(MIL_ID Func);

/* Compile the main() on the HOST only. */
#if !M_MIL_USE_PPC

/* Standard I/0 */
#include <conio.h>

/* Target image file name */
#define IMAGE_FILE   M_IMAGE_PATH MIL_TEXT("Wafer.mim")

/* Main to test the function. */
/* -------------------------- */

void main(void)
{
   MIL_ID MilApplication,    /* Application Identifier.  */
          MilSystem,         /* System Identifier.       */
          MilDisplay,        /* Display Identifier.      */
          MilImage;          /* Image buffer Identifier. */

   /* Allocate default application, system, display and image. */
   MappAllocDefault(M_COMPLETE, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into an automatically allocated image buffer. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);

   /* Display the image. */
   MdispSelect(MilDisplay, MilImage);

   /* Pause */
   printf("\nMIL DTK:\n");
   printf("--------\n\n");
   printf("Custom asynchronous processing function:\n\n");
   printf("This example creates a custom MIL function that maximize the contrast.\n");
   printf("Press a key to continue.\n\n");
   getch();

   /* Process the image with the custom MIL function. */
   CustomRemap(MilImage, MilImage, M_DEFAULT);

   /* Pause */
   printf("A smart image remapping was done on the image using a user made MIL function.\n");
   printf("Press a key to terminate.\n\n");
   getch();

   /* Free all allocations. */
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}

#endif /* !M_MIL_USE_PPC */

/* Master MIL Function definition. */
/* ------------------------------- */

/* MIL Function specifications */
#define FUNCTION_OPCODE_REMAP   (M_USER_FUNCTION+1)
#define FUNCTION_NB_PARAM       3

void MFTYPE CustomRemap(MIL_ID SrcImage, MIL_ID DstImage, unsigned long Option)
{
   MIL_ID   Func;

   /* Allocate a MIL function context that will be used to call a target
      slave function to do the processing.
   */
   MfuncAlloc(MIL_TEXT("CustomRemap"),
              FUNCTION_NB_PARAM,
              SlaveCustomRemap, M_NULL,
              MT("CustomRemap"),
              FUNCTION_OPCODE_REMAP,
              M_ASYNCHRONOUS_FUNCTION,
              &Func
             );

   /* Register the parameters. */
   MfuncParamId(  Func, 1, SrcImage, M_IMAGE, M_IN  + M_PROC);
   MfuncParamId(  Func, 2, DstImage, M_IMAGE, M_OUT + M_PROC);
   MfuncParamLong(Func, 3, Option);

   /* Call the target Slave function. */
   MfuncCall(Func);

   /* Free the MIL function context. */
   MfuncFree(Func);
}

/* Slave MIL Function definition. */
/* ------------------------------ */

void MFTYPE SlaveCustomRemap(MIL_ID Func)
{
  MIL_ID SrcImage, DstImage, OwnerSystem, ExtremeResult, Lut;
  unsigned long Option, MinAndMax[2];

  /* Read the parameters. */
  MfuncParamValue(Func, 1, &SrcImage);
  MfuncParamValue(Func, 2, &DstImage);
  MfuncParamValue(Func, 3, &Option);

  /* Find the Owner system of the destination image. */
  MbufInquire(SrcImage, M_OWNER_SYSTEM, &OwnerSystem);

  /* Find the Minimum and Maximum values of the image. */
  MimAllocResult(OwnerSystem, 2L, M_EXTREME_LIST, &ExtremeResult);
  MimFindExtreme(SrcImage, ExtremeResult, M_MIN_VALUE+M_MAX_VALUE);
  MimGetResult(ExtremeResult, M_VALUE, MinAndMax);
  MimFree(ExtremeResult);

  /* Create a LUT to remap the values from Min to Max to 0x00-0xFF. */
  MbufAlloc1d(OwnerSystem, 256, 8+M_UNSIGNED, M_LUT, &Lut);
  MgenLutRamp(Lut, MinAndMax[0], 0x00, MinAndMax[1], 0xFF);

  /* Remap the values. */
  MimLutMap(SrcImage, DstImage, Lut);

  /* Free the Lut buffer */
  MbufFree(Lut);
}


Example: dtksyncasyncfunctionsmain.c

/*****************************************************************************************/
/*
 * File name: DTKSyncAsyncFunctionsMain.c
 *
 * Synopsis:  This example shows how to use of the MIL Function Developer ToolKit to
 *            call custom synchronous and asynchronous MIL functions.
 *
 *            It contains the main to test the SynchronousFunction() and
 *            AsynchronousFunction() master functions.
 */
#include <mil.h>
#include <conio.h>

/* Master and Slave MIL functions declarations */
long MFTYPE SynchronousFunction(MIL_ID SrcImage, MIL_ID DstImage,  long Option);
void MFTYPE AsynchronousFunction(MIL_ID SrcImage, MIL_ID DstImage, long Option);

/* Target image file name */
#define IMAGE_FILE   M_IMAGE_PATH MIL_TEXT("Wafer.mim")
#define NB_LOOP      100

/* Main to test the functions. */
/* --------------------------- */

void main(void)
{
   MIL_ID MilApplication,       /* Application Identifier.  */
          MilSystem,            /* System Identifier.       */
          MilDisplay,           /* Display Identifier.      */
          MilImage;             /* Image buffer Identifier. */
   long   ReturnValue;          /* Return Value holder.     */
   double SynchronousCallTime,  /* Timer variable.          */
          AsynchronousCallTime; /* Timer variable.          */
   int    n;                    /* Counter.                 */

   /* Allocate default application, system, display and image. */
   MappAllocDefault(M_COMPLETE, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into an automatically allocated image buffer. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);

   /* Uncomment to display the image.    */
   /* MdispSelect(MilDisplay, MilImage); */

   /* Pause */
   printf("\nMIL DTK:\n");
   printf("--------\n\n");
   printf("Custom synchronous and asynchronous MIL functions:\n\n");
   printf("This example times a synchronous and asynchronous custom function call.\n");
   printf("Press a key to continue.\n\n");
   getch();

   /* Synchronous function call. */
   /* -------------------------- */

   /* Call the function a first time for more accurate timings later (dll load, ...). */
   ReturnValue = SynchronousFunction(MilImage, MilImage, M_DEFAULT);

   /* Start the timer */
   MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

   /* Loop many times for more precise timing. */
   for (n= 0; n < NB_LOOP; n++)
      {
      /* Call the custom MIL synchronous function. */
      ReturnValue = SynchronousFunction(MilImage, MilImage, M_DEFAULT);
      }

   /* Read the timer. */
   MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &SynchronousCallTime);

   /* Print the synchronous call time. */
   printf("Synchronous  function call time: %.1f us.\n", SynchronousCallTime*1000000/NB_LOOP);

   /* Asynchronous function call. */
   /* --------------------------- */

   /* Call the function a first time for more accurate timings later (dll load, ...). */
  AsynchronousFunction(MilImage, MilImage, M_DEFAULT);
  MthrWait(M_DEFAULT, M_THREAD_WAIT, M_NULL);

   /* Start the timer */
   MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

   /* Loop many times for more precise timing. */
   for (n= 0; n < NB_LOOP; n++)
      {
      /* Call the custom MIL asynchronous function. */
      AsynchronousFunction(MilImage, MilImage, M_DEFAULT);
      }

   /* Read and print the time. */
   MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &AsynchronousCallTime);

   /* Print the asynchronous call time. */
   printf("Asynchronous function call time: %.1f us.\n", AsynchronousCallTime*1000000/NB_LOOP);
   printf("Press a key to terminate.\n\n");
   getch();

   /* Free all allocations. */
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: dtksyncasyncfunctionsmaster.c

/*************************************************************************************/
/*
 * File name: DTKSyncAsyncFunctionsMaster.c
 *
 * Synopsis:  This example shows how to use of the MIL Function Developer's Toolkit to
 *            create custom synchronous and asynchronous MIL functions.
 *
 *            It contains the SynchronousFunction() and AsynchronousFunction() master
 *            functions.
 */
#include <mil.h>

/* Slave MIL functions declarations */
long MFTYPE SynchronousFunction(MIL_ID SrcImage, MIL_ID DstImage, long Option);
void MFTYPE SlaveSynchronousFunction(MIL_ID Func);
void MFTYPE AsynchronousFunction(MIL_ID SrcImage, MIL_ID DstImage, long Option);
void MFTYPE SlaveAsynchronousFunction(MIL_ID Func);

/* Master Synchronous MIL Function definition. */
/* ------------------------------------------- */

#define SYNC_FUNCTION_OPCODE    (M_USER_FUNCTION+2)
#define SYNC_FUNCTION_NB_PARAM  4

long MFTYPE SynchronousFunction(MIL_ID SrcImage, MIL_ID DstImage, long Option)
{
   MIL_ID Func;
   long   ReturnValue;

   /* Allocate a MIL function context. */
   MfuncAlloc(MIL_TEXT("SynchronousFunction"), SYNC_FUNCTION_NB_PARAM,
              SlaveSynchronousFunction, M_NULL, M_NULL,
              SYNC_FUNCTION_OPCODE,
              M_SYNCHRONOUS_FUNCTION,
              &Func
             );

   /* Register the parameters. */
   MfuncParamId(     Func, 1, SrcImage, M_IMAGE, M_IN  + M_PROC);
   MfuncParamId(     Func, 2, DstImage, M_IMAGE, M_OUT + M_PROC);
   MfuncParamLong(   Func, 3, Option);
   MfuncParamPointer(Func, 4, &ReturnValue, sizeof(ReturnValue), M_OUT);

   /* Call the target Slave function. */
   MfuncCall(Func);

   /* Free the MIL function context. */
   MfuncFree(Func);

   /* Return the value returned by the slave function. */
   return(ReturnValue);
}

/* Master Asynchronous MIL Function definition. */
/* -------------------------------------------- */

#define ASYNC_FUNCTION_OPCODE    (M_USER_FUNCTION+3)
#define ASYNC_FUNCTION_NB_PARAM  3

void MFTYPE AsynchronousFunction(MIL_ID SrcImage, MIL_ID DstImage, long Option)
{
   MIL_ID Func;

   /* Allocate a MIL function context. */
   MfuncAlloc(MIL_TEXT("AsynchronousFunction"),
              ASYNC_FUNCTION_NB_PARAM,
              SlaveAsynchronousFunction, M_NULL, M_NULL,
              ASYNC_FUNCTION_OPCODE,
              M_ASYNCHRONOUS_FUNCTION,
              &Func
             );

   /* Register the parameters. */
   MfuncParamId(  Func, 1, SrcImage, M_IMAGE, M_IN  + M_PROC);
   MfuncParamId(  Func, 2, DstImage, M_IMAGE, M_OUT + M_PROC);
   MfuncParamLong(Func, 3, Option);

   /* Call the target Slave function. */
   MfuncCall(Func);

   /* Free the MIL function context. */
   MfuncFree(Func);
}


Example: dtksyncasyncfunctionsslave.c

/*****************************************************************************************/
/*
 * File name: DTKSyncAsyncFunctionsSlave.c
 *
 * Synopsis:  This example shows how to use of the MIL Function Developer's Toolkit to
 *            create custom synchronous and asynchronous MIL functions.
 *
 *            It contains the SlaveSynchronousFunction() and SlaveAsynchronousFunction()
 *            slave functions.
 */
#include <mil.h>

/* Slave MIL Function prototypes. */
void MFTYPE SlaveSynchronousFunction(MIL_ID Func);
void MFTYPE SlaveAsynchronousFunction(MIL_ID Func);

/* Slave Synchronous MIL Function definition. */
/* ------------------------------------------ */

void MFTYPE SlaveSynchronousFunction(MIL_ID Func)
{
  MIL_ID SrcImage, DstImage;
  unsigned long Option, *ReturnValuePtr, ValueToReturn = M_NULL;

  /* Read the parameters including pointer to the ReturnValue data. */
  MfuncParamValue(Func, 1, &SrcImage);
  MfuncParamValue(Func, 2, &DstImage);
  MfuncParamValue(Func, 3, &Option);
  MfuncParamValue(Func, 4, &ReturnValuePtr);

  /* Do the processing and calculate the value to return. */
  // ValueToReturn = ...

  /* Write the return value. */
  *ReturnValuePtr = ValueToReturn;
}

/* Slave Asynchronous MIL Function definition. */
/* ------------------------------------------- */

void MFTYPE SlaveAsynchronousFunction(MIL_ID Func)
{
  MIL_ID SrcImage, DstImage;
  unsigned long Option;

  /* Read the parameters including pointer to the ReturnValue data. */
  MfuncParamValue(Func, 1, &SrcImage);
  MfuncParamValue(Func, 2, &DstImage);
  MfuncParamValue(Func, 3, &Option);

  /* Do the processing. */
  //...
}


Example: mappstart.c

/******************************************************************************/
/*
 * File name: MAppStart.c
 *
 * Synopsis:  This program allocates a MIL application and system, then displays
 *            a welcoming message using graphics functions. It also shows how
 *            to check for errors.
 */
#include <conio.h>
#include <mil.h>

void main(void)
{
   MIL_ID MilApplication,  /* Application identifier.  */
          MilSystem,       /* System identifier.       */
          MilDisplay,      /* Display identifier.      */
          MilImage;        /* Image buffer identifier. */

   /* Allocate a default MIL application, system, display and image. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, &MilImage);

   /* If no allocation errors. */
   if (!MappGetError(M_GLOBAL, M_NULL))
      {
      /* Perform graphic operations in the display image. */
      MgraColor(M_DEFAULT, 0xF0);
      MgraFont(M_DEFAULT, M_FONT_DEFAULT_LARGE);
      MgraText(M_DEFAULT, MilImage, 160L, 230L, MIL_TEXT(" Welcome to MIL !!! "));
      MgraColor(M_DEFAULT, 0xC0);
      MgraRect(M_DEFAULT, MilImage, 100L, 150L, 530L, 340L);
      MgraRect(M_DEFAULT, MilImage, 120L, 170L, 510L, 320L);
      MgraRect(M_DEFAULT, MilImage, 140L, 190L, 490L, 300L);

      /* Print a message. */
      printf("\nSYSTEM ALLOCATION:\n");
      printf("------------------\n\n");
      printf("System allocation successful.\n\n");
      printf("     \"Welcome to MIL !!!\"\n\n");
      }
   else
      printf("System allocation error !\n\n");

   /* Wait for a key press. */
   printf("Press <Enter> to end.\n");
   getch();

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, MilImage);
}


Example: mblob.c

/*******************************************************************************/
/*
 * File name: MBlob.c
 *
 * Synopsis:  This program loads an image of some nuts, bolts and washers,
 *            determines the number of each of these, finds and marks
 *            their center of gravity using the Blob analysis module.
 */
#include <conio.h>
#include <mil.h>
#include <malloc.h>

/* Target MIL image file specifications. */
#define IMAGE_FILE            M_IMAGE_PATH MIL_TEXT("BoltsNutsWashers.mim")
#define IMAGE_THRESHOLD_VALUE 26L

/* Minimum and maximum area of blobs. */
#define MIN_BLOB_AREA         50L
#define MAX_BLOB_AREA         50000L

/* Radius of the smallest particles to keep. */
#define MIN_BLOB_RADIUS       3L

/* Minimum hole compactness corresponding to a washer. */
#define MIN_COMPACTNESS       1.5

void main(void)
{
   MIL_ID MilApplication,                 /* Application identifier.            */
          MilSystem,                      /* System identifier.                 */
          MilDisplay,                     /* Display identifier.                */
          MilImage,                       /* Image buffer identifier.           */
          MilOverlayImage,                /* Overlay image.                     */
          MilBinImage,                    /* Binary image buffer identifier.    */
          MilBlobResult,                  /* Blob result buffer identifier.     */
          MilBlobFeatureList;             /* Feature list identifier.           */
   long   TotalBlobs,                     /* Total number of blobs.             */
          BlobsWithHoles,                 /* Number of blobs with holes.        */
          BlobsWithRoughHoles,            /* Number of blobs with rough holes.  */
          n;                              /* Counter.                           */
   double *CogX,                          /* X coordinate of center of gravity. */
          *CogY;                          /* Y coordinate of center of gravity. */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into image buffer. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);

   /* Display the buffer and prepare for overlay annotations. */
   MdispSelect(MilDisplay, MilImage);
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a binary image buffer for fast processing. */
   MbufAlloc2d(MilSystem,
               MbufInquire(MilImage, M_SIZE_X, M_NULL),
               MbufInquire(MilImage, M_SIZE_Y, M_NULL),
               1+M_UNSIGNED, M_IMAGE+M_PROC, &MilBinImage);

   /* Pause to show the original image. */
   printf("\nBLOB ANALYSIS:\n");
   printf("--------------\n\n");
   printf("This program determines the number of bolts, nuts and washers\n");
   printf("in the image and finds their center of gravity.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Binarize image. */
   MimBinarize(MilImage, MilBinImage, M_GREATER_OR_EQUAL,
                                      IMAGE_THRESHOLD_VALUE, M_NULL);

   /* Remove small particles and then remove small holes. */
   MimOpen(MilBinImage, MilBinImage, MIN_BLOB_RADIUS, M_BINARY);
   MimClose(MilBinImage, MilBinImage, MIN_BLOB_RADIUS, M_BINARY);

   /* Allocate a feature list. */
   MblobAllocFeatureList(MilSystem, &MilBlobFeatureList);

   /* Enable the Area and Center Of Gravity feature calculation. */
   MblobSelectFeature(MilBlobFeatureList, M_AREA);
   MblobSelectFeature(MilBlobFeatureList, M_CENTER_OF_GRAVITY);

   /* Allocate a blob result buffer. */
   MblobAllocResult(MilSystem, &MilBlobResult);

   /* Calculate selected features for each blob. */
   MblobCalculate(MilBinImage, M_NULL, MilBlobFeatureList, MilBlobResult);

   /* Exclude blobs whose area is too small. */
   MblobSelect(MilBlobResult, M_EXCLUDE, M_AREA, M_LESS_OR_EQUAL,
                                                 MIN_BLOB_AREA, M_NULL);

   /* Get the total number of selected blobs. */
   MblobGetNumber(MilBlobResult, &TotalBlobs);
   printf("There are %ld objects ", TotalBlobs);

   /* Read and print the blob's center of gravity. */
   if ((CogX = (double *)malloc(TotalBlobs*sizeof(double))) &&
       (CogY = (double *)malloc(TotalBlobs*sizeof(double)))
      )
      {
      /* Get the results. */
      MblobGetResult(MilBlobResult, M_CENTER_OF_GRAVITY_X, CogX);
      MblobGetResult(MilBlobResult, M_CENTER_OF_GRAVITY_Y, CogY);

      /* Print the center of gravity of each blob. */
      printf("and their center of gravity are:\n");
      for(n=0; n < TotalBlobs; n++)
         printf("Blob #%ld: X=%5.1f, Y=%5.1f\n", n, CogX[n], CogY[n]);
      free(CogX);
      free(CogY);
      }
   else
      printf("\nError: Not enough memory.\n");

   /* Draw a cross at the center of gravity of each blob. */
   MgraColor(M_DEFAULT, M_COLOR_RED);
   MblobDraw(M_DEFAULT, MilBlobResult, MilOverlayImage, M_DRAW_CENTER_OF_GRAVITY,
                                                        M_INCLUDED_BLOBS, M_DEFAULT);

   /* Reverse what is considered to be the background so that
    * holes are seen as being blobs.
    */
   MblobControl(MilBlobResult, M_FOREGROUND_VALUE, M_ZERO);

   /* Add a feature to distinguish between types of holes. Since area
    * has already been added to the feature list, and the processing
    * mode has been changed, all blobs will be re-included and the area
    * of holes will be calculated automatically.
    */
   MblobSelectFeature(MilBlobFeatureList, M_COMPACTNESS);

   /* Calculate selected features for each blob. */
   MblobCalculate(MilBinImage, M_NULL, MilBlobFeatureList, MilBlobResult);

   /* Exclude small holes and large (the area around objects) holes. */
   MblobSelect(MilBlobResult, M_EXCLUDE, M_AREA, M_OUT_RANGE,
                                         MIN_BLOB_AREA, MAX_BLOB_AREA);

   /* Get the number of blobs with holes. */
   MblobGetNumber(MilBlobResult, &BlobsWithHoles);

   /* Exclude blobs whose holes are compact (i.e. nuts). */
   MblobSelect(MilBlobResult, M_EXCLUDE, M_COMPACTNESS, M_LESS_OR_EQUAL,
                                                        MIN_COMPACTNESS, M_NULL);

   /* Get the number of blobs with holes that are NOT compact. */
   MblobGetNumber(MilBlobResult, &BlobsWithRoughHoles);

   /* Print results. */
   printf("\nIdentified objects:\n");
   printf("%ld bolts\n", TotalBlobs-BlobsWithHoles);
   printf("%ld nuts\n", BlobsWithHoles - BlobsWithRoughHoles);
   printf("%ld washers\n\n", BlobsWithRoughHoles);
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free all allocations. */
   MblobFree(MilBlobResult);
   MblobFree(MilBlobFeatureList);
   MbufFree(MilBinImage);
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mbufbayercolorfilter.c

/************************************************************************************/
/*
 * File name: MBufBayerColorFilter.c
 *
 * Synopsis:  This program shows how to perform Bayer-to-Color conversion.
 */

#include "mil.h"
#include "conio.h"
void main(void)
{
MIL_ID MilApplication,
MilSystem,
MilDigitizer,
MilDisplay,
MilWBCoefficients,
MilImageDisp,
MilImageGrab;

/* User array for white balance coefficients. */
float WBCoefficients[3];
/* Specify the Bayer pattern of your camera. */
long ConversionType = M_BAYER_GR;
/* Buffer characteristics. */
long XSize;
long YSize;

/* Allocate an application. */
MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay,
&MilDigitizer, M_NULL);
XSize = MdigInquire(MilDigitizer, M_SIZE_X, M_NULL);
YSize = MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL);
/* Allocate a display buffer. */
MbufAllocColor(MilSystem, 3, XSize, YSize, 8L+M_UNSIGNED, M_PROC+M_IMAGE,
&MilImageDisp);
/* Allocate a grab buffer. */
MbufAllocColor(MilSystem, 1, XSize, YSize, 8L+M_UNSIGNED,
M_IMAGE+M_DISP+M_GRAB+M_PROC, &MilImageGrab);
/* Allocate an array for the white balance coefficients. */
MbufAlloc1d(MilSystem, 3, 32+M_FLOAT, M_ARRAY, &MilWBCoefficients);

/* Display the image. */
MbufClear(MilImageDisp, M_RGB888(0, 0, 0));
MdispSelect(MilDisplay, MilImageDisp);
/* Ask the user for a white image for white balance. */
printf("Place a white paper in front of the camera and " \
"press <ENTER> when ready.\n");
do
{
/* Grab a white Bayer image. */
MdigGrab(MilDigitizer, MilImageGrab);
/* Convert the white Bayer image to color without white balance. */
MbufBayer(MilImageGrab, MilImageDisp, M_DEFAULT, ConversionType);
}
while (!kbhit());
getch();
/* Determine the white balance coefficients. */
MbufBayer(MilImageGrab, MilImageDisp, MilWBCoefficients,
ConversionType+M_WHITE_BALANCE_CALCULATE);
/* Print the computed coefficients. */
MbufGet(MilWBCoefficients, (void *) &WBCoefficients[0]);
printf("\nWhite balance correction coefficients : %f, %f, %f\n\n",
WBCoefficients[0], WBCoefficients[1], WBCoefficients[2]);
/* Grab a new Bayer image with white balance correction. */
printf("Press <ENTER> to grab an image\n");
getchar();
do
{
/* Grab a Bayer image. */
MdigGrab(MilDigitizer, MilImageGrab);
/* Convert the Bayer image to color. */
MbufBayer(MilImageGrab, MilImageDisp, MilWBCoefficients, ConversionType);
}
while (!kbhit());
getch();
printf("Press <ENTER> to end\n");
getchar();

/* Terminate and free everything. */
MbufFree(MilImageGrab);
MbufFree(MilImageDisp);
MbufFree(MilWBCoefficients);
MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, M_NULL);


Example: mbufcolor.c

/**********************************************************************************/
/*
 * File name: MBufColor.c
 *
 * Synopsis:  This program demonstrates color buffer manipulations. It allocates
 *            a displayable color image buffer, displays it, and loads a color
 *            image into its left part. After that, color annotations are done
 *            in each band of the color buffer. If image processing is available,
 *            it converts the image to Hue, Luminance and Saturation (HLS), adds
 *            a certain offset to the luminance component and converts
 *            the image back to Red, Green, Blue (RGB) to display the result.
 *
 *            The example also demonstrates how to display multiple images
 *            in a single display using child buffers.
 */
#include <mil.h>
#include <conio.h>

/* Source MIL image file specifications. */
#define IMAGE_FILE              M_IMAGE_PATH MIL_TEXT("Bird.mim")

/* Luminance offset to add to the image. */
#define IMAGE_LUMINANCE_OFFSET  40L

/* Main function. */
void main(void)
{
   MIL_ID MilApplication,       /* Application identifier.  */
          MilSystem,            /* System identifier.       */
          MilDisplay,           /* Display identifier.      */
          MilImage,             /* Image buffer identifier. */
          MilLeftSubImage,      /* Sub-image buffer identifier for original image. */
          MilRightSubImage,     /* Sub-image buffer identifier for processed image.*/
          MilLumSubImage=0,     /* Sub-image buffer identifier for luminance.      */
          MilRedBandSubImage,   /* Sub-image buffer identifier for red component.  */
          MilGreenBandSubImage, /* Sub-image buffer identifier for green component.*/
          MilBlueBandSubImage;  /* Sub-image buffer identifier for blue component. */
   long   SizeX, SizeY, SizeBand, Type;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Allocate a color display buffer twice the size of the source image and display it. */
   MbufAllocColor(MilSystem,
                  MbufDiskInquire(IMAGE_FILE, M_SIZE_BAND, &SizeBand),
                  MbufDiskInquire(IMAGE_FILE, M_SIZE_X, &SizeX) * 2,
                  MbufDiskInquire(IMAGE_FILE, M_SIZE_Y, &SizeY),
                  MbufDiskInquire(IMAGE_FILE, M_TYPE,   &Type),
                  M_IMAGE+M_DISP+M_PROC, &MilImage);
   MbufClear(MilImage, 0L);
   MdispSelect(MilDisplay, MilImage);

   /* Define 2 child buffers that maps to the left and right part of the display
      buffer, to put the source and destination color images.
    */
   MbufChild2d(MilImage, 0L, 0L, SizeX, SizeY, &MilLeftSubImage);
   MbufChild2d(MilImage, SizeX, 0L, SizeX, SizeY, &MilRightSubImage);

   /* Load the color source image on the left. */
   MbufLoad(IMAGE_FILE, MilLeftSubImage);

   /* Define child buffers that map to the red, green and blue components
      of the source image.
    */
   MbufChildColor(MilLeftSubImage, M_RED,   &MilRedBandSubImage);
   MbufChildColor(MilLeftSubImage, M_GREEN, &MilGreenBandSubImage);
   MbufChildColor(MilLeftSubImage, M_BLUE,  &MilBlueBandSubImage);

   /* Write color text annotations to show access in each individual band of the image.

      Note that this is typically simplified by using:
      MgraColor(M_DEFAULT, M_RGB(0xFF,0x90,0x00));
      MgraText(M_DEFAULT, MilLeftSubImage, ...);
    */
   MgraColor(M_DEFAULT, 0xFF);
   MgraText(M_DEFAULT, MilRedBandSubImage,   SizeX/16, SizeY/8, MIL_TEXT(" TOUCAN "));
   MgraColor(M_DEFAULT, 0x90);
   MgraText(M_DEFAULT, MilGreenBandSubImage, SizeX/16, SizeY/8, MIL_TEXT(" TOUCAN "));
   MgraColor(M_DEFAULT, 0x00);
   MgraText(M_DEFAULT, MilBlueBandSubImage,  SizeX/16, SizeY/8, MIL_TEXT(" TOUCAN "));

   /* Print a message. */
   printf("\nCOLOR OPERATIONS:\n");
   printf("-----------------\n\n");
   printf("A color source image was loaded on the left and color text\n");
   printf("annotations were written in it.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /*  If Image Processing module is available, augment the image luminance. */
   #if (!M_MIL_LITE)
      {
      /* Convert image to Hue, Luminance, Saturation color space (HLS). */
      MimConvert(MilLeftSubImage, MilRightSubImage, M_RGB_TO_HLS);

      /* Create a child buffer that maps to the luminance component. */
      MbufChildColor(MilRightSubImage, M_LUMINANCE, &MilLumSubImage);

      /* Add an offset to the luminance component. */
      MimArith(MilLumSubImage, IMAGE_LUMINANCE_OFFSET, MilLumSubImage, M_ADD_CONST+M_SATURATION);

      /* Convert image back to Red, Green, Blue color space (RGB) for display. */
      MimConvert(MilRightSubImage, MilRightSubImage, M_HLS_TO_RGB);

      /* Free the luminance band child buffer. */
      MbufFree(MilLumSubImage);

      /* Print a message. */
      printf("Luminance was increased using color image processing.\n");
      }
   #else
      {
      /* Copy the color source image. */
      MbufCopy(MilLeftSubImage, MilRightSubImage);

      /* Print a message. */
      printf("The image was copied to the right.\n");
      }
   #endif

   /* Print a message. */
   printf("Press <Enter> to end.\n");
   getch();

   /* Release sub-images and color image buffer. */
   MbufFree(MilRedBandSubImage);
   MbufFree(MilGreenBandSubImage);
   MbufFree(MilBlueBandSubImage);
   MbufFree(MilRightSubImage);
   MbufFree(MilLeftSubImage);
   MbufFree(MilImage);

   /* Release defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mcal.c

/*******************************************************************************/
/*
 * File name: MCal.c
 *
 * Synopsis:  This program uses the Calibration module to calibrate a high
 *            distortion camera with an image of a grid. Then, an image of
 *            a board grabbed with the same camera is loaded and some
 *            measurements are done in real world calibrated units. Finally
 *            the distorted board image is corrected using the same camera
 *            calibration.
 */
#include <mil.h>
#include <conio.h>

/* Source image files specification. */
#define GRID_IMAGE_FILE        M_IMAGE_PATH MIL_TEXT("CalGrid.mim")
#define BOARD_IMAGE_FILE       M_IMAGE_PATH MIL_TEXT("CalBoard.mim")

/* World description of the calibration grid. */
#define GRID_OFFSET_X          0
#define GRID_OFFSET_Y          0
#define GRID_OFFSET_Z          0
#define GRID_ROW_SPACING       1
#define GRID_COLUMN_SPACING    1
#define GRID_ROW_NUMBER       18
#define GRID_COLUMN_NUMBER    25

/* Measurement boxes specification. */
#define MEAS_BOX_POS_X1       55
#define MEAS_BOX_POS_Y1       24
#define MEAS_BOX_WIDTH1        7
#define MEAS_BOX_HEIGHT1     425

#define MEAS_BOX_POS_X2      225
#define MEAS_BOX_POS_Y2       11
#define MEAS_BOX_WIDTH2        7
#define MEAS_BOX_HEIGHT2     450

/* Specification of the stripes' constraints. */
#define WIDTH_APPROXIMATION  425
#define WIDTH_WEIGHT_FACTOR   98

/*  Main function. */
void main(void)
{
   MIL_ID  MilApplication,    /* Application identifier.        */
           MilSystem,         /* System identifier.             */
           MilDisplay,        /* Display identifier.            */
           MilImage,          /* Image buffer identifier.       */
           MilOverlayImage,   /* Overlay image.                 */
           MilCalibration,    /* Calibration identifier.        */
           MeasMarker1,       /* Measurement marker identifier. */
           MeasMarker2;       /* Measurement marker identifier. */
   double  WorldDistance1,  WorldDistance2;
   double  PixelDistance1,  PixelDistance2;
   double  PosX1, PosY1, PosX2, PosY2, PosX3, PosY3, PosX4, PosY4;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into an automatically allocated image buffer. */
   MbufRestore(GRID_IMAGE_FILE, MilSystem, &MilImage);

   /* Display the image buffer. */
   MdispSelect(MilDisplay, MilImage);

   /* Prepare for overlay annotation. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Pause to show the original image. */
   printf("\nCALIBRATION:\n");
   printf("------------\n\n");
   printf("The displayed grid has been grabbed with a high distortion\n");
   printf("camera and will be used to calibrate the camera.\n");
   printf("Press <Enter> to continue.\n\n");
   getchar();

   /* Allocate a camera calibration object. */
   McalAlloc(MilSystem, M_DEFAULT, M_DEFAULT, &MilCalibration);

   /* Calibrate the camera with the image of the grid and its world description. */
   McalGrid(MilCalibration, MilImage,
            GRID_OFFSET_X, GRID_OFFSET_Y, GRID_OFFSET_Z,
            GRID_ROW_NUMBER, GRID_COLUMN_NUMBER,
            GRID_ROW_SPACING, GRID_COLUMN_SPACING,
            M_DEFAULT, M_DEFAULT);

   /* Perform a first image transformation with the calibration grid. */
   McalTransformImage(MilImage, MilImage, MilCalibration,
                      M_BILINEAR|M_OVERSCAN_CLEAR, M_DEFAULT, M_DEFAULT);

   /* Pause to show the corrected image of the grid. */
   printf("The camera has been calibrated and the image of the grid\n");
   printf("has been transformed to remove its distortions.\n");
   printf("Press <Enter> to continue.\n\n");
   getchar();

   /* Read the image of the board and associate the calibration to the image. */
   MbufLoad(BOARD_IMAGE_FILE, MilImage);
   McalAssociate(MilCalibration, MilImage, M_DEFAULT);

   /* Allocate the measurement markers. */
   MmeasAllocMarker(MilSystem, M_STRIPE, M_DEFAULT, &MeasMarker1);
   MmeasAllocMarker(MilSystem, M_STRIPE, M_DEFAULT, &MeasMarker2);

   /* Set the markers' measurement boxes. */
   MmeasSetMarker(MeasMarker1, M_BOX_ORIGIN, MEAS_BOX_POS_X1, MEAS_BOX_POS_Y1);
   MmeasSetMarker(MeasMarker1, M_BOX_SIZE, MEAS_BOX_WIDTH1, MEAS_BOX_HEIGHT1);
   MmeasSetMarker(MeasMarker2, M_BOX_ORIGIN, MEAS_BOX_POS_X2, MEAS_BOX_POS_Y2);
   MmeasSetMarker(MeasMarker2, M_BOX_SIZE, MEAS_BOX_WIDTH2, MEAS_BOX_HEIGHT2);

   /* Set markers' orientation. */
   MmeasSetMarker(MeasMarker1, M_ORIENTATION, M_HORIZONTAL, M_NULL);
   MmeasSetMarker(MeasMarker2, M_ORIENTATION, M_HORIZONTAL, M_NULL);

   /* Set marker's approximate width and the associated weight factor. */
   MmeasSetMarker(MeasMarker1, M_WIDTH, WIDTH_APPROXIMATION, M_NULL);
   MmeasSetMarker(MeasMarker2, M_WIDTH, WIDTH_APPROXIMATION, M_NULL);
   MmeasSetMarker(MeasMarker1, M_WEIGHT_FACTOR+M_WIDTH, WIDTH_WEIGHT_FACTOR, M_NULL);
   MmeasSetMarker(MeasMarker2, M_WEIGHT_FACTOR+M_WIDTH, WIDTH_WEIGHT_FACTOR, M_NULL);

   /* Find and measure the position and width of the board. */
   MmeasFindMarker(M_DEFAULT, MilImage, MeasMarker1, M_WIDTH+M_POSITION);
   MmeasFindMarker(M_DEFAULT, MilImage, MeasMarker2, M_WIDTH+M_POSITION);

   /* Get the world width of the two markers. */
   MmeasGetResult(MeasMarker1, M_WIDTH, &WorldDistance1, M_NULL);
   MmeasGetResult(MeasMarker2, M_WIDTH, &WorldDistance2, M_NULL);

   /* Get the pixel width of the two markers. */
   McalControl(MilCalibration, M_OUTPUT_COORDINATE_SYSTEM, M_PIXEL);
   MmeasGetResult(MeasMarker1, M_WIDTH, &PixelDistance1, M_NULL);
   MmeasGetResult(MeasMarker2, M_WIDTH, &PixelDistance2, M_NULL);

   /* Get the edges position in pixel to draw the annotations. */
   MmeasGetResult(MeasMarker1, M_POSITION+M_EDGE_FIRST,  &PosX1, &PosY1);
   MmeasGetResult(MeasMarker1, M_POSITION+M_EDGE_SECOND, &PosX2, &PosY2);
   MmeasGetResult(MeasMarker2, M_POSITION+M_EDGE_FIRST,  &PosX3, &PosY3);
   MmeasGetResult(MeasMarker2, M_POSITION+M_EDGE_SECOND, &PosX4, &PosY4);

   /* Draw the measurement indicators on the image.  */
   MgraColor(M_DEFAULT, M_COLOR_YELLOW);
   MmeasDraw(M_DEFAULT, MeasMarker1, MilOverlayImage, M_DRAW_WIDTH, M_DEFAULT, M_RESULT);
   MmeasDraw(M_DEFAULT, MeasMarker2, MilOverlayImage, M_DRAW_WIDTH, M_DEFAULT, M_RESULT);

   MgraBackColor(M_DEFAULT, M_COLOR_BLACK);
   MgraText(M_DEFAULT, MilOverlayImage, (long)(PosX1+0.5-40),
                       (long)((PosY1+0.5)+((PosY2 - PosY1)/2.0)), MIL_TEXT(" Distance 1 "));
   MgraText(M_DEFAULT, MilOverlayImage, (long)(PosX3+0.5-40),
                       (long)((PosY3+0.5)+((PosY4 - PosY3)/2.0)), MIL_TEXT(" Distance 2 "));

   /* Pause to show the original image and the measurement results. */
   printf("A distorted image grabbed with the same camera was loaded and\n");
   printf("calibrated measurements were done to evaluate the board dimensions.\n");
   printf("\n========================================================\n");
   printf("                      Distance 1          Distance 2 \n");
   printf("--------------------------------------------------------\n");
   printf(" Calibrated unit:   %8.2lf cm           %6.2lf cm    \n", WorldDistance1
                                                                   , WorldDistance2);
   printf(" Uncalibrated unit: %8.2lf pixels       %6.2lf pixels\n", PixelDistance1
                                                                   , PixelDistance2);
   printf("========================================================\n\n");
   printf("Press <Enter> to continue.\n\n");
   getchar();

   /* Clear the display overlay. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Read the image of the PCB. */
   MbufLoad(BOARD_IMAGE_FILE, MilImage);

   /* Transform the image of the board. */
   McalTransformImage(MilImage, MilImage, MilCalibration,
                      M_BILINEAR+M_OVERSCAN_CLEAR, M_DEFAULT, M_DEFAULT);

   /* Pause to show the transformed image of the board. */
   printf("The image was corrected to remove its distortions.\n");
   printf("Press <Enter> to end.\n\n");
   getchar();

   /* Free all allocations. */
   MmeasFree(MeasMarker1);
   MmeasFree(MeasMarker2);
   McalFree(MilCalibration);
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mcode.c

/**************************************************************************************/
/*
 * File name: MCode.c
 *
 * Synopsis:  This program decodes a 1D Code 39 linear Barcode and a 2D DataMatrix code.
 */
#include <conio.h>
#include <mil.h>

/* Target image character specifications. */
#define IMAGE_FILE                    M_IMAGE_PATH MIL_TEXT("Code.mim")

/* Regions around 1D code. */
#define BARCODE_REGION_TOP_LEFT_X     256L
#define BARCODE_REGION_TOP_LEFT_Y      80L
#define BARCODE_REGION_SIZE_X         290L
#define BARCODE_REGION_SIZE_Y          60L

/* Regions around 2D code. */
#define DATAMATRIX_REGION_TOP_LEFT_X    8L
#define DATAMATRIX_REGION_TOP_LEFT_Y  312L
#define DATAMATRIX_REGION_SIZE_X      118L
#define DATAMATRIX_REGION_SIZE_Y      105L

/* Maximum length of the string to read. */
#define STRING_LENGTH_MAX              64L

void main(void)
{
   MIL_ID MilApplication,        /* Application identifier.         */
          MilSystem,             /* System identifier.              */
          MilDisplay,            /* Display identifier.             */
          MilImage,              /* Image buffer identifier.        */
          MilOverlayImage,       /* Image buffer identifier.        */
          DataMatrixRegion,      /* Child containing DataMatrix.    */
          DataMatrixCode,        /* DataMatrix 2D code identifier.  */
          BarCodeRegion,         /* Child containing Code39         */
          Barcode;               /* Code39 barcode identifier.      */
   long   BarcodeStatus;         /* Decoding status.                */
   long   DataMatrixStatus;      /* Decoding status.                */
   long   AnnotationColor = M_COLOR_GREEN, AnnotationBackColor = M_COLOR_GRAY, n;
   MIL_TEXT_CHAR OutputString    [STRING_LENGTH_MAX]; /* Array of characters to draw. */
   MIL_TEXT_CHAR BarcodeString   [STRING_LENGTH_MAX]; /* Array of characters read.    */
   MIL_TEXT_CHAR DataMatrixString[STRING_LENGTH_MAX]; /* Array of characters read.    */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into an automatically allocated image buffer. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);

   /* Display the image buffer. */
   MdispSelect(MilDisplay, MilImage);

   /* Prepare for overlay annotations. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

    /* Pause to show the original image. */
   printf("\n1D and 2D CODE READING:\n");
   printf("-----------------------\n\n");
   printf("This program will decode a linear Code 39 and a DataMatrix code.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* 1D BARCODE READING: */

   /* Create a read region around the code to speedup reading. */
   MbufChild2d(MilImage, BARCODE_REGION_TOP_LEFT_X, BARCODE_REGION_TOP_LEFT_Y,
               BARCODE_REGION_SIZE_X, BARCODE_REGION_SIZE_Y, &BarCodeRegion);

   /* Allocate CODE objects. */
   McodeAlloc(MilSystem, M_CODE39, M_DEFAULT, &Barcode);

   /* Read codes from image. */
   McodeRead(Barcode, BarCodeRegion, M_DEFAULT);

   /* Get decoding status. */
   McodeGetResult(Barcode, M_STATUS+M_TYPE_LONG, &BarcodeStatus);

   /* Check if decoding was successful. */
   if (BarcodeStatus == M_STATUS_OK)
      {
      /* Get decoded string. */
      McodeGetResult(Barcode, M_STRING, BarcodeString);

      /* Draw the decoded strings and read region in the overlay image. */
      MgraColor(M_DEFAULT, AnnotationColor);
      MgraBackColor(M_DEFAULT, AnnotationBackColor);
      MOs_sprintf(OutputString, MIL_TEXT("\"%s\""), BarcodeString);
      MgraText(M_DEFAULT, MilOverlayImage, BARCODE_REGION_TOP_LEFT_X+10,
               BARCODE_REGION_TOP_LEFT_Y+80, MIL_TEXT(" 1D linear 39 bar code:           "));
      MgraText(M_DEFAULT, MilOverlayImage, BARCODE_REGION_TOP_LEFT_X+200,
               BARCODE_REGION_TOP_LEFT_Y+80, OutputString);
      MgraRect(M_DEFAULT, MilOverlayImage,
               BARCODE_REGION_TOP_LEFT_X, BARCODE_REGION_TOP_LEFT_Y,
               BARCODE_REGION_TOP_LEFT_X+BARCODE_REGION_SIZE_X,
               BARCODE_REGION_TOP_LEFT_Y+BARCODE_REGION_SIZE_Y);
      }

   /* Free objects. */
   McodeFree(Barcode);
   MbufFree(BarCodeRegion);

   /* 2D CODE READING: */

   /* Create a read region around the code to speedup reading. */
   MbufChild2d(MilImage, DATAMATRIX_REGION_TOP_LEFT_X, DATAMATRIX_REGION_TOP_LEFT_Y,
               DATAMATRIX_REGION_SIZE_X, DATAMATRIX_REGION_SIZE_Y, &DataMatrixRegion);

   /* Allocate CODE objects. */
   McodeAlloc(MilSystem, M_DATAMATRIX, M_DEFAULT, &DataMatrixCode);

   /* Set the foreground value for the DataMatrix since it is different from the default value. */
   McodeControl(DataMatrixCode, M_FOREGROUND_VALUE, M_FOREGROUND_WHITE);

   /* Read codes from image. */
   McodeRead(DataMatrixCode, DataMatrixRegion, M_DEFAULT);

   /* Get decoding status. */
   McodeGetResult(DataMatrixCode, M_STATUS + M_TYPE_LONG, &DataMatrixStatus);

   /* Check if decoding was successful. */
   if (DataMatrixStatus == M_STATUS_OK)
      {
      /* Get decoded string. */
      McodeGetResult(DataMatrixCode, M_STRING, DataMatrixString);

      /* Draw the decoded strings and read region in the overlay image. */
      MgraColor(M_DEFAULT, AnnotationColor);
      MgraBackColor(M_DEFAULT, AnnotationBackColor);
      for (n=0; DataMatrixString[n] != '\0'; n++) /* Replace non printable characters with space.*/
          if ((DataMatrixString[n] < '0') || (DataMatrixString[n] > 'Z'))
              DataMatrixString[n] = ' ';
      MOs_sprintf(OutputString, MIL_TEXT("\"%s\" "), DataMatrixString);
      MgraText(M_DEFAULT, MilOverlayImage, DATAMATRIX_REGION_TOP_LEFT_X,
               DATAMATRIX_REGION_TOP_LEFT_Y+120, MIL_TEXT(" 2D Data Matrix code:                  "));
      MgraText(M_DEFAULT, MilOverlayImage, DATAMATRIX_REGION_TOP_LEFT_X+200,
               DATAMATRIX_REGION_TOP_LEFT_Y+120, OutputString);
      MgraRect(M_DEFAULT, MilOverlayImage,
               DATAMATRIX_REGION_TOP_LEFT_X, DATAMATRIX_REGION_TOP_LEFT_Y,
               DATAMATRIX_REGION_TOP_LEFT_X+DATAMATRIX_REGION_SIZE_X,
               DATAMATRIX_REGION_TOP_LEFT_Y+DATAMATRIX_REGION_SIZE_Y);
      }

   /* Free objects. */
   McodeFree(DataMatrixCode);
   MbufFree(DataMatrixRegion);

   /* Pause to show the results. */
   if ( (DataMatrixStatus == M_STATUS_OK) && (BarcodeStatus == M_STATUS_OK) )
      printf("Decoding was successful and the strings were written under each code.\n");
   else
      printf("Decoding error found.\n");
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free other allocations. */
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mdblgrab.c

/* File name: DoubleGrab.c
 * Synopsis:  This program shows how to Grab with two different cameras at the same time with two
 *            continuous grabs. if two continuous grags are not supported, the program simulates a
 *            continuous grab using many simple grabs
 *
 *     Thread usage:
 *      - The main thread starts a processing thread in each of the 4 different
 *        quarters of a display buffer. The main thread then waits for a key to
 *        be pressed to stop them.
 *      - The top-left and bottom-left threads work in a loop, as follows: the
 *        top-left thread draws a rectangle in its buffer (in a size
 *        different from the previous rectangle), then sends an event to the
 *        bottom-left thread. The bottom-left thread waits for the event from
 *        the top-left thread, copies the contents of the top-left buffer into
 *        its buffer, draws a circle in the rectangle, then sends an event to
 *        the top-left thread. When the top-left thread receives the event, the
 *        loop continues.
 *      - The top-right and bottom-right threads work exactly the same way as the
 *        top-left and bottom-left threads.
 *
 *      Note that the top and bottom threads (of each half) could be set to do
 *      something else while waiting for each other.
 */

/* headers */
#include <stdio.h>
#include <mil.h>

/* Main function: */
/* -------------- */
void main(void)
{
   MIL_ID MilApplication,        /* Application identifier.                   */
          MilSystem,             /* System identifier.                        */
          MilDisplay,            /* Display identifier.                       */
          MilImage,              /* Image buffer identifiers.                 */
          MilDigitizer,          /* Digitizer identifier.    */
          MilSystem2,
          MilDisplay2,           /* Display identifier.      */
          MilDigitizer2,         /* Digitizer identifier.    */
          MilImage2;

   /* Allocate defaults*/
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                             &MilDisplay, &MilDigitizer, &MilImage);

   /* Allocate everything that is needed for the second digitizer. */
   MsysAlloc(M_SYSTEM_SETUP, M_DEFAULT, M_COMPLETE, &MilSystem2);
   MdispAlloc(MilSystem2, M_DEV1, "M_DEFAULT", M_WINDOWED, &MilDisplay2);
   MdigAlloc(MilSystem2, M_DEV1, "M_DEFAULT", M_DEFAULT, &MilDigitizer2);
   MbufAllocColor(MilSystem2,
                  MbufInquire(MilImage, M_SIZE_BAND, M_NULL),
                  MbufInquire(MilImage, M_SIZE_X, M_NULL),
                  MbufInquire(MilImage, M_SIZE_Y, M_NULL),
                  MbufInquire(MilImage, M_TYPE, M_NULL),
                  MbufInquire(MilImage, M_ATTRIBUTE, M_NULL),
                  &MilImage2);
   MdispSelect(MilDisplay2, MilImage2);

   /* Start continuous grabs.*/
   MdigGrabContinuous(MilDigitizer, MilImage );
   MdigGrabContinuous(MilDigitizer2, MilImage2 );
   printf("Press any key to end grab\n");
   getchar();

   /* Stop continuous grabs. */
   MdigHalt(MilDigitizer );
   MdigHalt(MilDigitizer2 );

   /*Free the second digitizer*/
   MbufFree(MilImage2);
   MdispFree(MilDisplay2);
   MdigFree(MilDigitizer2);
   MsysFree(MilSystem2);

   /* Release defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilImage);
   }


Example: mdigautofocus.c

/*****************************************************************************/
/*
 * File name: MdigAutoFocus.c
 *
 * Synopsis:  This program performs an autofocus operation using the
 *            MdigFocus() function. Since the way to move a motorized
 *            camera lens is device-specific, we will not include real
 *            lens movement control and image grab but will simulate
 *            the lens focus with a smooth operation.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

/* Source MIL image file specification. */
#define IMAGE_FILE                     M_IMAGE_PATH MIL_TEXT("BaboonMono.mim")

/* Lens mechanical characteristics. */
#define FOCUS_MAX_NB_POSITIONS         100
#define FOCUS_MIN_POSITION             0
#define FOCUS_MAX_POSITION             (FOCUS_MAX_NB_POSITIONS - 1)
#define FOCUS_START_POSITION           10

/* Autofocus search properties. */
#define FOCUS_MAX_POSITION_VARIATION   M_DEFAULT
#define FOCUS_MODE                     M_SMART_SCAN
#define FOCUS_SENSITIVITY              1

/* User Data structure definition. */
typedef struct
{  MIL_ID      SourceImage;
   MIL_ID      FocusImage;
   MIL_ID      Display;
   long        Iteration;
}  DigHookUserData;

/* Autofocus callback function responsible for moving the lens. */
long MFTYPE MoveLensHookFunction(long HookType, long position, void MPTYPE *UserDataHookPtr);

/* Simulate a grab from a camera at different lens positions. */
void SimulateGrabFromCamera(MIL_ID SourceImage, MIL_ID FocusImage, long Iteration, MIL_ID AnnotationDisplay);

/* Draw position of the lens. */
void DrawCursor(MIL_ID AnnotationImage, long Position);

/*****************************************************************************/
/*  Main application function.                                               */
void main(void)
{
   MIL_ID MilApplication,                   /* Application identifier.       */
          MilSystem,                        /* System identifier.            */
          MilDisplay,                       /* Display identifier.           */
          MilSource,                        /* Source image                  */
          MilCameraFocus;                   /* Focus simulated image         */
   long   FocusPos;                         /* Best focus position           */
   DigHookUserData UserData;                /* User data passed to the hook  */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Load the source image. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilSource);
   MbufRestore(IMAGE_FILE, MilSystem, &MilCameraFocus);
   MbufClear(MilCameraFocus, 0);

   /* Select image on the display. */
   MdispSelect(MilDisplay, MilCameraFocus);

   /* Simulate the first image grab. */
   SimulateGrabFromCamera(MilSource, MilCameraFocus, FOCUS_START_POSITION, MilDisplay);

   /* Initialize user data needed within the hook function. */
   UserData.SourceImage = (long)MilSource;
   UserData.FocusImage  = (long)MilCameraFocus;
   UserData.Iteration   = (long)0L;
   UserData.Display     = (long)MilDisplay;

   /* Pause to show the original image. */
   printf("\nAUTOFOCUS:\n");
   printf("----------\n\n");
   printf("Automatic focusing operation will be done on this image.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();
   printf("Autofocusing...\n\n");

   /* Perform Autofocus.
      Since lens movement is hardware specific, no digitizer is used here.
      We simulate the lens movement with by smoothing the image data in
      the hook function instead.
   */
   MdigFocus(M_NULL,
             MilCameraFocus,
             M_DEFAULT,
             MoveLensHookFunction,
             &UserData,
             FOCUS_MIN_POSITION,
             FOCUS_START_POSITION,
             FOCUS_MAX_POSITION,
             FOCUS_MAX_POSITION_VARIATION,
             FOCUS_MODE + FOCUS_SENSITIVITY,
             &FocusPos);

   /* Print the best focus position and number of iterations. */
   printf("The best focus position is %d.\n", FocusPos);
   printf("The best focus position found in %d iterations.\n\n", UserData.Iteration);
   printf("Press <Enter> to end.\n");
   getch();

  /* Free all allocations. */
   MbufFree(MilSource);
   MbufFree(MilCameraFocus);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}

/********************************************************************************/
/* Autofocus hook function responsible to move the lens.                        */

long MFTYPE MoveLensHookFunction(long HookType, long Position,  void MPTYPE *UserDataHookPtr)
{
 DigHookUserData *UserData = (DigHookUserData *)UserDataHookPtr;

   /* Here, the lens position must be changed according to the Position parameter.
      In that case, we simulate the lens position change followed by a grab.
   */
   if(HookType == M_CHANGE || HookType == M_ON_FOCUS)
      {
      SimulateGrabFromCamera( UserData->SourceImage,
                              UserData->FocusImage,
                              Position,
                              UserData->Display
                              );
      UserData->Iteration++;
      }

   return 0;
}

/***********************************************************************************/
/* Utility function to simulate a grab from a camera at different lens position    */
/* by smoothing the original image. It should be replaced with a true camera grab. */

/* Lens simulation characteristics. */
#define FOCUS_BEST_POSITION            (FOCUS_MAX_NB_POSITIONS/2)

void SimulateGrabFromCamera(MIL_ID SourceImage, MIL_ID FocusImage,
                            long Iteration, long AnnotationDisplay)
{
   long NbSmoothNeeded;      /* Number of smooths needed          */
   long BufType;             /* Buffer type                       */
   long BufSizeX;            /* Buffer size X                     */
   long BufSizeY;            /* Buffer size Y                     */
   long Smooth;              /* Smooth index                      */
   MIL_ID TempBuffer;        /* Temporary buffer                  */
   MIL_ID SourceOwnerSystem; /* Owner system of the source buffer */

   /* Compute number of smooths needed to simulate focus. */
   NbSmoothNeeded = abs(Iteration - FOCUS_BEST_POSITION);

   /* Buffer inquires. */
   BufType        = MbufInquire(FocusImage, M_TYPE,   M_NULL);
   BufSizeX       = MbufInquire(FocusImage, M_SIZE_X, M_NULL);
   BufSizeY       = MbufInquire(FocusImage, M_SIZE_Y, M_NULL);

   if(NbSmoothNeeded == 0)
      {
      /* Directly copy image source to destination. */
      MbufCopy(SourceImage, FocusImage);
      }
   else if(NbSmoothNeeded == 1)
      {
      /* Directly convolve image from source to destination. */
      MimConvolve(SourceImage, FocusImage, M_SMOOTH);
      }
   else
      {
      SourceOwnerSystem = MbufInquire(SourceImage, M_OWNER_SYSTEM, M_NULL);

      /* Allocate temporary buffer. */
      MbufAlloc2d(SourceOwnerSystem, BufSizeX, BufSizeY,
                  BufType, M_IMAGE+M_PROC, &TempBuffer);

      /* Perform first smooth. */
      MimConvolve(SourceImage, TempBuffer, M_SMOOTH);

      /* Perform smooths. */
      for(Smooth=1;Smooth<NbSmoothNeeded-1;Smooth++)
         {
         MimConvolve(TempBuffer, TempBuffer, M_SMOOTH);
         }

      /* Perform last smooth. */
      MimConvolve(TempBuffer, FocusImage, M_SMOOTH);

      /* Free temporary buffer. */
      MbufFree(TempBuffer);
      }

   /* Draw position cursor. */
   DrawCursor(AnnotationDisplay, Iteration);
}

/****************************************************************/
/* Draw position of the focus lens.                             */

/* Cursor specifications. */
#define CURSOR_POSITION                ((BufSizeY*7)/8)
#define CURSOR_SIZE                    14
#define CURSOR_COLOR                   M_COLOR_GREEN

void DrawCursor(MIL_ID AnnotationDisplay, long Position)
{
   MIL_ID AnnotationImage;
   long CursorColor, BufSizeX, BufSizeY, n;

   /* Prepare for overlay annotations. */
   MdispControl(AnnotationDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(AnnotationDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(AnnotationDisplay, M_OVERLAY_ID, &AnnotationImage);
   MbufInquire(AnnotationImage, M_SIZE_X, &BufSizeX);
   MbufInquire(AnnotationImage, M_SIZE_Y, &BufSizeY);
   CursorColor = CURSOR_COLOR;
   MgraColor(M_DEFAULT, CursorColor);

   /* Write annotations. */
   n = (BufSizeX/FOCUS_MAX_NB_POSITIONS);
   MgraLine(M_DEFAULT, AnnotationImage, 0, CURSOR_POSITION+CURSOR_SIZE,
                                        BufSizeX-1, CURSOR_POSITION+CURSOR_SIZE);
   MgraLine(M_DEFAULT, AnnotationImage, Position*n, CURSOR_POSITION+CURSOR_SIZE,
                                        Position*n-CURSOR_SIZE, CURSOR_POSITION);
   MgraLine(M_DEFAULT, AnnotationImage, Position*n, CURSOR_POSITION+CURSOR_SIZE,
                                        Position*n+CURSOR_SIZE, CURSOR_POSITION);
   MgraLine(M_DEFAULT, AnnotationImage, Position*n-CURSOR_SIZE, CURSOR_POSITION,
                                        Position*n+CURSOR_SIZE, CURSOR_POSITION);
}


Example: mdigdoublebuffering.c

/************************************************************************/
/*
 * File name: MDigDoubleBuffering.c
 *
 * Synopsis:  This program performs a double-buffering grab,
 *            times the processing, and displays some statistics.
 *
 *     Note:  The double buffering method is not recommended for real-time
 *            processing when the CPU usage is high. For more
 *            robust real-time behavior, use the MdigProcess() function.
 *            See MDigProcess.c for a complete example.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

/* Main function. */
void main(void)
{
   MIL_ID   MilApplication;
   MIL_ID   MilSystem     ;
   MIL_ID   MilDigitizer  ;
   MIL_ID   MilDisplay    ;
   MIL_ID   MilImage[2]   ;
   MIL_ID   MilImageDisp  ;
   long     NbProc = 0, n = 0;
   double   Time = 0.0;
   MIL_TEXT_CHAR Text[10] = MIL_TEXT("0");

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay,
                                              &MilDigitizer, &MilImageDisp);

   /* Allocate 2 grab buffers. */
   for (n=0; n<2; n++)
       MbufAlloc2d(MilSystem,
                   MdigInquire(MilDigitizer, M_SIZE_X, M_NULL),
                   MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL),
                   8L+M_UNSIGNED,
                   M_IMAGE+M_GRAB+M_PROC, &MilImage[n]);

   /* Print a message. */
   printf("\nDOUBLE BUFFERING ACQUISITION:\n");
   printf("-----------------------------\n\n");
   printf("Press <Enter> to start.\n\n");

   /* Grab continuously on display and wait for a key press. */
   MdigGrabContinuous(MilDigitizer,MilImageDisp);
   getch();

   /* Halt continuous grab. */
   MdigHalt(MilDigitizer);
   printf("Press <Enter> to stop.\n\n");

   /* Put the digitizer in asynchronous mode to be able to process while grabbing. */
   MdigControl(MilDigitizer, M_GRAB_MODE, M_ASYNCHRONOUS);

   /* Grab the first buffer. */
   MdigGrab(MilDigitizer, MilImage[0]);

   /* Process one buffer while grabbing the other. */
   n=0;
   do {
      /* Grab the other buffer while processing previous one. */
      MdigGrab(MilDigitizer, MilImage[1-n]);

      /* Synchronize and start the timer. */
      if (NbProc == 0)
         MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

      /* Write the frame counter. */
      MOs_ltoa(NbProc+1, Text, 10);
      MgraText(M_DEFAULT, MilImage[n], 32, 32, Text);

      /* Process the first buffer already grabbed.  */
      #if (!M_MIL_LITE)
      MimArith(MilImage[n], M_NULL, MilImageDisp, M_NOT);
      #else
      MbufCopy(MilImage[n], MilImageDisp);
      #endif

      /* Count processed buffers. */
      NbProc++;

      /* Toggle grab buffers. */
      n = 1-n;
      }
   while(!kbhit());
   getch();

   /* Wait until the end of the last grab and stop timer. */
   MdigGrabWait(MilDigitizer, M_GRAB_END);

   /* Print statistics. */
   MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);
   printf("%ld frames grabbed, at a frame rate of %.2f frames/sec (%.2f ms/frame).\n",
                                             NbProc, NbProc/Time, 1000.0*Time/NbProc);
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free allocations. */
   for (n=0; n<2; n++)
       MbufFree(MilImage[n]);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilImageDisp);
}


Example: mdiggrab.c

/********************************************************************************/
/*
 * File name: MDigGrab.c
 *
 * Synopsis:  This program demonstrates how to grab from a camera in
 *            continuous and monoshot mode.
 */
#include <mil.h>
#include <conio.h>

void main(void)
{
   MIL_ID MilApplication,  /* Application identifier.  */
          MilSystem,       /* System identifier.       */
          MilDisplay,      /* Display identifier.      */
          MilDigitizer,    /* Digitizer identifier.    */
          MilImage;        /* Image buffer identifier. */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                             &MilDisplay, &MilDigitizer, &MilImage);

   /* Grab continuously. */
   MdigGrabContinuous(MilDigitizer, MilImage);

   /* When a key is pressed, halt. */
   printf("\nDIGITIZER ACQUISITION:\n");
   printf("----------------------\n\n");
   printf("Continuous image grab in progress.\n");
   printf("Press <Enter> to stop.\n\n");
   getch();

   /* Stop continuous grab. */
   MdigHalt(MilDigitizer);

   /* Pause to show the result. */
   printf("Continuous grab stopped.\n\n");
   printf("Press <Enter> to do a single image grab.\n\n");
   getch();

   /* Monoshot grab. */
   MdigGrab(MilDigitizer, MilImage);

   /* Pause to show the result. */
   printf("Displaying the grabbed image.\n");
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilImage);
}


Example: mdiggrabmultiple.c

/**************************************************************************/
/*
 * File name: MDigGrabMultiple.c
 *
 * Synopsis: This example performs 2 continuous grabs using the 2 digitizers
 *           of a system.
 */
/* Headers. */
#include <mil.h>
#include <conio.h>

/* Grab scale. */
#define GRAB_SCALE  1.0

/* Main function. */
void main(void)
{
   MIL_ID   MilApplication;
   MIL_ID   MilSystem     ;
   MIL_ID   MilDigitizer[2];
   MIL_ID   MilDisplay[2] ;
   MIL_ID   MilImageDisp[2];

   /* Allocations. */
   MappAlloc(M_DEFAULT, &MilApplication);
   MsysAlloc("M_DEFAULT", M_DEFAULT, M_DEFAULT, &MilSystem);
   MdigAlloc(MilSystem,  M_DEV0, "M_DEFAULT", M_DEFAULT, &MilDigitizer[0]);
   MdigAlloc(MilSystem,  M_DEV1, "M_DEFAULT", M_DEFAULT, &MilDigitizer[1]);
   MdispAlloc(MilSystem, M_DEV0, "M_DEFAULT", M_DEFAULT, &MilDisplay[0]);
   MdispAlloc(MilSystem, M_DEV1, "M_DEFAULT", M_DEFAULT, &MilDisplay[1]);

   /* Allocate 2 display buffers and clear them. */
   MbufAlloc2d(MilSystem,
               (long)(MdigInquire(MilDigitizer[0], M_SIZE_X, M_NULL)*GRAB_SCALE),
               (long)(MdigInquire(MilDigitizer[0], M_SIZE_Y, M_NULL)*GRAB_SCALE),
               8L+M_UNSIGNED,
               M_IMAGE+M_GRAB+M_PROC+M_DISP, &MilImageDisp[0]);
   MbufClear(MilImageDisp[0], 0x0);
   MbufAlloc2d(MilSystem,
               (long)(MdigInquire(MilDigitizer[1], M_SIZE_X, M_NULL)*GRAB_SCALE),
               (long)(MdigInquire(MilDigitizer[1], M_SIZE_Y, M_NULL)*GRAB_SCALE),
               8L+M_UNSIGNED,
               M_IMAGE+M_GRAB+M_PROC+M_DISP, &MilImageDisp[1]);
   MbufClear(MilImageDisp[1], 0x80);

   /* Display the buffers. */
   MdispSelect(MilDisplay[0], MilImageDisp[0]);
   MdispSelect(MilDisplay[1], MilImageDisp[1]);

   /* Grab continuously on displays at the specified scale. */
   MdigControl(MilDigitizer[0], M_GRAB_SCALE, GRAB_SCALE);
   MdigGrabContinuous(MilDigitizer[0],MilImageDisp[0]);
   MdigControl(MilDigitizer[1], M_GRAB_SCALE, GRAB_SCALE);
   MdigGrabContinuous(MilDigitizer[1],MilImageDisp[1]);

   /* Print a message. */
   printf("Press <Enter> to stop continuous grab.\n");
   getchar();

   /* Halt continuous grab. */
   MdigHalt(MilDigitizer[0]);
   MdigHalt(MilDigitizer[1]);

   /* Print a message. */
   printf("Press <Enter> to end.\n");
   getchar();

   /* Free allocations. */
   MbufFree(MilImageDisp[0]);
   MbufFree(MilImageDisp[1]);
   MdispFree(MilDisplay[0]);
   MdispFree(MilDisplay[1]);
   MdigFree(MilDigitizer[0]);
   MdigFree(MilDigitizer[1]);
   MsysFree(MilSystem);
   MappFree(MilApplication);
}


Example: mdiggrabsequence.c

/********************************************************************************/
/*
 * File name: MDigGrabSequence.c
 *
 * Synopsis:  This example shows how to grab a sequence, archive it, and play
 *            it back in real time from an AVI file. It supports compressed
 *            or uncompressed sequences and parallelized compression/decompression
 *            with disk access to optimize the use of hardware resources
 *            when possible. If this is not necessary, the example can be simplified.
 *
 * NOTE:      This example assumes that the hard disk is sufficiently fast
 *            to keep up with the grab. Also, removing the sequence display or
 *            the text annotation while grabbing will reduce the CPU usage and
 *            might help if some frames are missed during acquisition.
 *            If the disk or system are not fast enough, set GRAB_SCALE to 0.5,
 *            FRAME_NUMBER_ANNOTATION to M_NO or SAVE_SEQUENCE_TO_DISK to M_NO.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

/* Sequence file name.*/
#define SEQUENCE_FILE M_IMAGE_PATH MIL_TEXT("MilSequence.avi")

/* Image acquisition scale. */
#define GRAB_SCALE   1.0

/* Quantization factor to use during the compression.
   Valid values are 1 to 99 (higher to lower quality).
*/
#define COMPRESSION_Q_FACTOR   50

/* Annotation flag. Set to M_YES to draw the frame number in the saved image. */
#define FRAME_NUMBER_ANNOTATION  M_YES

/* Archive flag. Set to M_NO to disable AVI Import/Export to disk. */
#if (!M_MIL_USE_CE)
#define SAVE_SEQUENCE_TO_DISK  M_YES
#else
#define SAVE_SEQUENCE_TO_DISK  M_NO
#endif

/* Maximum number of images for the multiple buffering grab. */
#define NB_GRAB_IMAGE_MAX  20

/* User's archive hook function prototype (called for every grabbed frame). */
long MFTYPE ArchiveFunction(long HookType, MIL_ID HookId, void MPTYPE *HookDataPtr);

/* User's archive function hook data structure. */
typedef struct
   {
   MIL_ID MilSystem;
   MIL_ID MilDisplay;
   MIL_ID MilImageDisp;
   MIL_ID *MilCompressedImage;
   long   NbGrabbedFrames;
   long   NbArchivedFrames;
   long   SaveSequenceToDisk;
   long   OnBoardAttribute;
   } HookDataStruct;

/* Main function. */
/* -------------- */
void main(void)
{
   MIL_ID  MilApplication, MilSystem, MilDigitizer, MilDisplay, MilImageDisp;
   MIL_ID  MilGrabImages[NB_GRAB_IMAGE_MAX+1];
   MIL_ID  MilCompressedImage[2] = {0, 0};
   long    CompressAttribute=0, OnBoardAttribute=0;
   long    NbFrames=0,   Selection=1,   LicenseModules=0,   n=0;
   long    FrameCount=0, FrameMissed=0, NbFramesReplayed=0, Exit=0;
   double  FrameRate=0,  TimeWait=0,    TotalReplay=0;
   double  GrabScale=GRAB_SCALE;
   long    SaveSequenceToDisk = SAVE_SEQUENCE_TO_DISK;
   HookDataStruct UserHookData;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay,
                                              &MilDigitizer, M_NULL);

   /* Allocate an image and display it. */
   MbufAllocColor(MilSystem,
                  (long) MdigInquire(MilDigitizer, M_SIZE_BAND, M_NULL),
                  (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*GrabScale),
                  (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*GrabScale),
                  8L+M_UNSIGNED,
                  M_IMAGE+M_GRAB+M_DISP+M_NON_PAGED, &MilImageDisp);
   MbufClear(MilImageDisp, 0x0);
   MdispSelect(MilDisplay, MilImageDisp);

   /* Grab continuously on display at the specified scale. */
   MdigControl(MilDigitizer, M_GRAB_SCALE, GrabScale);
   MdigGrabContinuous(MilDigitizer, MilImageDisp);

   /* Print a message */
   printf("\nSEQUENCE AQUISITION:\n");
   printf("--------------------\n\n");

   /* Inquire MIL licenses. */
   MappInquire(M_LICENSE_MODULES, &LicenseModules);
   if (MsysInquire(MilSystem, M_SYSTEM_TYPE, M_NULL) == M_SYSTEM_ODYSSEY_TYPE)
       LicenseModules = (M_LICENSE_JPEGSTD | M_LICENSE_JPEG2000);

   /* If sequence is saved to disk, select between grabbing an
      uncompressed, JPEG or JPEG2000 sequence.
   */
   if (SaveSequenceToDisk && (LicenseModules & (M_LICENSE_JPEGSTD | M_LICENSE_JPEG2000)))
      {
      printf("Choose the sequence format:\n");
      printf("1) Uncompressed images.\n" );
      if(LicenseModules & M_LICENSE_JPEGSTD)
         printf("2) Compressed images with a lossy JPEG algorithm.\n");
      if(LicenseModules & M_LICENSE_JPEG2000)
         printf("3) Compressed images with a lossy JPEG 2000 algorithm.\n");
      Selection = getch();
      }
   else
      {
      printf("Press <Enter> to record images.\n");
      Selection = '1';
      getch();
      }

   /* Set the buffer attribute. */
   switch(Selection)
      {
      case '1':
      case '\r':
         printf("\nRecording uncompressed images...\n\n");
         CompressAttribute = M_NULL;
         break;

      case '2':
         printf("\nRecording JPEG images...\n\n");
         CompressAttribute = M_COMPRESS + M_JPEG_LOSSY;
         /* If the system JPEG on-board compression use it. */
         if (MsysInquire(MilSystem, M_BOARD_TYPE, M_NULL) & M_JPEG)
             OnBoardAttribute = M_ON_BOARD;
         break;

      case '3':
         printf("\nRecording JPEG 2000 images...\n\n");
         CompressAttribute = M_COMPRESS + M_JPEG2000_LOSSY;
         /* If the system JPEG2000 on-board compression use it. */
         if (MsysInquire(MilSystem, M_BOARD_TYPE, M_NULL) & M_J2K)
             OnBoardAttribute = M_ON_BOARD;
         break;

      default:
         printf("\nInvalid selection !.\n\nUsing uncompressed images.\n\n");
         CompressAttribute = M_NULL;
         while (kbhit()) getch();
         break;
      }

   /* Allocate 2 compressed buffers if required. */
   if (CompressAttribute)
      {
      for (n=0; n<2; n++)
        {
        MbufAllocColor(MilSystem,
                       (long)MdigInquire(MilDigitizer, M_SIZE_BAND, M_NULL),
                       (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*GrabScale),
                       (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*GrabScale),
                       8L+M_UNSIGNED, M_IMAGE+CompressAttribute, &MilCompressedImage[n]);
        MbufControl(MilCompressedImage[n], M_Q_FACTOR, COMPRESSION_Q_FACTOR);
        }
      }

   /* Allocate the grab buffers to hold the sequence buffering. */
   MappControl(M_ERROR, M_PRINT_DISABLE);
   for (NbFrames=0, n=0; n<NB_GRAB_IMAGE_MAX+1; n++)
      {
      MbufAllocColor(MilSystem,
                     (long)MdigInquire(MilDigitizer, M_SIZE_BAND, M_NULL),
                     (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*GrabScale),
                     (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*GrabScale),
                     8L+M_UNSIGNED, M_IMAGE+M_GRAB+OnBoardAttribute, &MilGrabImages[n]);
      if (MilGrabImages[n])
        {
         NbFrames++;
         MbufClear(MilGrabImages[n], 0xFF);
        }
      else
         break;
      }
   MappControl(M_ERROR, M_PRINT_ENABLE);

   /* Free a buffer to leave some space for possible temporary buffer. */
   NbFrames--;
   MbufFree(MilGrabImages[NbFrames]);

   /* Halt continuous grab. */
   MdigHalt(MilDigitizer);

   /* Open the AVI file if required. */
   if (SaveSequenceToDisk)
      {
      printf("Saving the sequence to an AVI file...\n\n");
      MbufExportSequence(SEQUENCE_FILE, M_DEFAULT, M_NULL, M_NULL, M_DEFAULT, M_OPEN);
      }

   /* Initialize User's archiving function hook data structure. */
   UserHookData.MilSystem           = MilSystem;
   UserHookData.MilDisplay          = MilDisplay;
   UserHookData.MilImageDisp        = MilImageDisp;
   UserHookData.MilCompressedImage  = MilCompressedImage;
   UserHookData.SaveSequenceToDisk  = SaveSequenceToDisk;
   UserHookData.OnBoardAttribute    = OnBoardAttribute;
   UserHookData.NbGrabbedFrames     = 0;
   UserHookData.NbArchivedFrames = 0;

   /* Acquire the sequence. The processing hook function will
      be called for each image grabbed to archive and display it.
      If sequence is not saved to disk, stop after NbFrames.
   */
   MdigProcess(MilDigitizer, MilGrabImages, NbFrames,
               SaveSequenceToDisk ? M_START : M_SEQUENCE,
               M_DEFAULT, ArchiveFunction, &UserHookData);

   /* Wait for a key press. */
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Stop the sequence acquisition. */
   MdigProcess(MilDigitizer, MilGrabImages, NbFrames, M_STOP,
                             M_DEFAULT, ArchiveFunction, &UserHookData);

   /* Read and print final statistics. */
   MdigInquire(MilDigitizer, M_PROCESS_FRAME_COUNT,  &FrameCount);
   MdigInquire(MilDigitizer, M_PROCESS_FRAME_RATE,   &FrameRate);
   MdigInquire(MilDigitizer, M_PROCESS_FRAME_MISSED, &FrameMissed);
   printf("\n\n%ld frames archived (%ld missed), at %.1f frames/sec (%.1f ms/frame).\n",
                   UserHookData.NbArchivedFrames, FrameMissed, FrameRate, 1000.0/FrameRate);

   /* Sequence file closing if required. */
   if (SaveSequenceToDisk)
       MbufExportSequence(SEQUENCE_FILE, M_DEFAULT, M_NULL, M_NULL, FrameRate, M_CLOSE);

   /* Playback the sequence until a key is pressed. */
   printf("Press <Enter> to end the playback, any other key to playback again.\n\n");
   if (UserHookData.NbArchivedFrames > 0)
     do
      {
      /* If sequence must be loaded. */
      if (SaveSequenceToDisk)
         {
         /* Inquire information about the sequence. */
         printf("Restoring the sequence from the AVI file...\n\n");
         MbufDiskInquire(SEQUENCE_FILE, M_NUMBER_OF_IMAGES, &FrameCount);
         MbufDiskInquire(SEQUENCE_FILE, M_FRAME_RATE, &FrameRate);
         MbufDiskInquire(SEQUENCE_FILE, M_COMPRESSION_TYPE, &CompressAttribute);

         /* Open the sequence file. */
         MbufImportSequence(SEQUENCE_FILE, M_DEFAULT, M_NULL,
                            M_NULL, M_NULL, M_NULL, M_NULL, M_OPEN);
         }

      /* Activate asynchronous buffer copy and decompression on the system if supported. */
      MappControl(M_ERROR, M_PRINT_DISABLE);
      MthrControl(MilSystem, M_BUS_MASTER_COPY_MODE, M_ASYNCHRONOUS);
      MappControl(M_ERROR, M_PRINT_ENABLE);

      /* Copy the images to the screen respecting the sequence frame rate. */
      TotalReplay = 0.0;
      NbFramesReplayed = 0;
      for (n=0; n<FrameCount; n++)
         {
         /* Reset the time. */
         MappTimer(M_TIMER_RESET, M_NULL);

         /* If image was saved to disk uncompressed. */
         if (SaveSequenceToDisk && !CompressAttribute)
            {
            /* Load image directly in the display image. */
            MbufImportSequence(SEQUENCE_FILE, M_DEFAULT, M_LOAD,
                               M_NULL, &MilImageDisp, n, 1, M_READ);
            NbFramesReplayed++;
            printf("Frame #%d             \r", NbFramesReplayed);
            }
         else
            {
            /* If image was saved to disk in compressed format. */
            if (SaveSequenceToDisk && CompressAttribute)
                {
                /* Decompress the previous image loaded asynchronously while
                   loading the next one (if supported by the system).
                */
                if (n > 0)
                   {
                   /* Make sure any previous asynchronous operation is completed. */
                   MthrWait(M_DEFAULT, M_THREAD_WAIT, M_NULL);

                   /* Decompress a frame. */
                   MbufCopy(MilCompressedImage[1-(n&1)], MilImageDisp);
                   NbFramesReplayed++;
                   printf("Frame #%d             \r", NbFramesReplayed);
                   }
                else
                   FrameCount++;
                if (n < (FrameCount-1))
                   {
                   /* Load the next one. */
                   MbufImportSequence(SEQUENCE_FILE, M_DEFAULT, M_LOAD,
                                      M_NULL, &MilCompressedImage[n&1], n, 1, M_READ);
                   }
                }
            else
                {
                /* Copy one of the grabbeds image directly. */
                MbufCopy(MilGrabImages[n], MilImageDisp);
                NbFramesReplayed++;
                printf("Frame #%d             \r", NbFramesReplayed);
                }
            }

         /* Check for a pressed key to exit. */
         if (kbhit() && (n>=(NB_GRAB_IMAGE_MAX-1)))
            {
            getch();
            break;
            }

         /* Wait to have a proper frame rate. */
         MappTimer(M_TIMER_READ, &TimeWait);
         TotalReplay += TimeWait;
         TimeWait = (1/FrameRate) - TimeWait;
         MappTimer(M_TIMER_WAIT, &TimeWait);
         TotalReplay += (TimeWait > 0) ? TimeWait: 0.0;
         }

      /* Close the sequence file. */
      if (SaveSequenceToDisk)
         MbufImportSequence(SEQUENCE_FILE, M_DEFAULT, M_NULL,
                            M_NULL, M_NULL, M_NULL, M_NULL, M_CLOSE);

      /* Print statistics. */
      printf("\n\n%ld frames replayed, at a frame rate of %.1f frames/sec (%.1f ms/frame).\n\n",
                                          NbFramesReplayed, n/TotalReplay, 1000.0*TotalReplay/n);
      }
   while(getch() != '\r');

   /* Free all allocated buffers. */
   MbufFree(MilImageDisp);
   for (n=0; n<NbFrames; n++)
       MbufFree(MilGrabImages[n]);
   for (n=0; n<2; n++)
       if (MilCompressedImage[n])
          MbufFree(MilCompressedImage[n]);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, M_NULL);
}

/* User's archive function called each time a new buffer is grabbed. */
/* -------------------------------------------------------------------*/

/* Local defines for the annotations. */
#define STRING_LENGTH_MAX  20
#define STRING_POS_X       20
#define STRING_POS_Y       20

long MFTYPE ArchiveFunction(long HookType, MIL_ID HookId, void MPTYPE *HookDataPtr)
   {
   HookDataStruct *UserHookDataPtr = (HookDataStruct *)HookDataPtr;
   MIL_ID ModifiedImage = 0;
   long n = 0;
   MIL_TEXT_CHAR Text[STRING_LENGTH_MAX]= {'\0',};

   /* Activate hardware asynchronous copy or compression of the image if supported. */
   if (UserHookDataPtr->NbGrabbedFrames == 0)
   {
   MappControl(M_ERROR, M_PRINT_DISABLE);
   MthrControl(UserHookDataPtr->MilSystem, M_BUS_MASTER_COPY_MODE, M_ASYNCHRONOUS);
   MappControl(M_ERROR, M_PRINT_ENABLE);
   }

   /* Retrieve the MIL_ID of the grabbed buffer. */
   MdigGetHookInfo(HookId, M_MODIFIED_BUFFER+M_BUFFER_ID, &ModifiedImage);

   /* Increment the frame count. */
   UserHookDataPtr->NbGrabbedFrames++;

   /* Draw the frame count in the image if enabled and if the buffer is not on-board. */
   if((FRAME_NUMBER_ANNOTATION == M_YES) && (!UserHookDataPtr->OnBoardAttribute))
     {
     MOs_sprintf(Text, MIL_TEXT(" %ld "), UserHookDataPtr->NbGrabbedFrames);
     MgraText(M_DEFAULT, ModifiedImage,   STRING_POS_X, STRING_POS_Y, Text);
     }

   /* Compress the new image if required while archiving the previous one. */
   if (UserHookDataPtr->MilCompressedImage[0])
      {
      /* Make sure any previous asynchronous operation is completed. */
      MthrWait(M_DEFAULT, M_THREAD_WAIT, M_NULL);

      n = UserHookDataPtr->NbGrabbedFrames & 1;
      MbufCopy(ModifiedImage, UserHookDataPtr->MilCompressedImage[n]);
      if (UserHookDataPtr->NbGrabbedFrames > 1)
         {
         if (UserHookDataPtr->SaveSequenceToDisk && (UserHookDataPtr->NbGrabbedFrames > 1))
            MbufExportSequence(SEQUENCE_FILE, M_DEFAULT,
                               &UserHookDataPtr->MilCompressedImage[1-n], 1, M_DEFAULT, M_WRITE);
         UserHookDataPtr->NbArchivedFrames++;
         printf("Frame #%d               \r", UserHookDataPtr->NbArchivedFrames);
         }
      }
   else  /* Archive the new image directly if required. */
      {
      if (UserHookDataPtr->SaveSequenceToDisk)
         {
         MbufExportSequence(SEQUENCE_FILE, M_DEFAULT, &ModifiedImage, 1, M_DEFAULT, M_WRITE);
         }
       UserHookDataPtr->NbArchivedFrames++;
       printf("Frame #%d               \r", UserHookDataPtr->NbArchivedFrames);
      }

   /* Copy the new grabbed image to the display. */
   MbufCopy(ModifiedImage, UserHookDataPtr->MilImageDisp);

   return 0;
   }


Example: mdighook.c

/*************************************************************************/
/*
 * File name: MDigHook.c
 *
 * Synopsis:  This grab example shows how to use the digitizer hook functions.
 *            It grabs a sequence of images using hooks and plays it back. It
 *            also uses events to signal the end of each grab and to
 *            annotate the buffer.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

/* Number of buffers in the sequence. */
#define NB_GRAB_MAX   20

/* Hook functions prototypes. */
long MFTYPE GrabStart(long, MIL_ID, void MPTYPE *);
long MFTYPE GrabEnd(long, MIL_ID, void MPTYPE *);

/* Hook data structure. */
typedef struct
   {
   MIL_ID  *MilImage;
   MIL_ID  MilDigitizer;
   MIL_ID  GrabEndEvent;
   long    NbGrabStart;
   long    NbGrabEnd;
   long    NbFrames;
   double  Time;
   } UserDataStruct;

/* Main function. */
void main(void)
{
   MIL_ID   MilApplication;
   MIL_ID   MilSystem     ;
   MIL_ID   MilDigitizer  ;
   MIL_ID   MilDisplay    ;
   MIL_ID   MilImage[NB_GRAB_MAX];
   MIL_ID   MilImageDisp  ;
   MIL_TEXT_CHAR FrameIndex[10];
   UserDataStruct UserStruct;
   double TimeWait = 0.0;
   long NbFrames = 0;
   long n;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay,
                                              &MilDigitizer, &MilImageDisp);

   /* Allocate and clear sequence and display images. */
   MappControl(M_ERROR, M_PRINT_DISABLE);
   for (NbFrames=0; NbFrames<NB_GRAB_MAX; NbFrames++)
      {
      MbufAlloc2d(MilSystem,
               MdigInquire(MilDigitizer, M_SIZE_X, M_NULL),
               MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL),
               M_DEF_IMAGE_TYPE,
               M_IMAGE+M_GRAB, &MilImage[NbFrames]);

      if (MilImage[NbFrames])
         {
         MbufClear(MilImage[NbFrames], 0xFF);
         }
      else
         break;
      }
   MappControl(M_ERROR, M_PRINT_ENABLE);

   /* Free a buffer to leave space for possible temporary buffer. */
   NbFrames--;
   MbufFree(MilImage[NbFrames]);

   /* MIL event allocation for grab end hook. */
   MthrAlloc(MilSystem, M_EVENT, M_DEFAULT, M_NULL, M_NULL, &UserStruct.GrabEndEvent);

   /* Initialize hook structure. */
   UserStruct.MilDigitizer = MilDigitizer;
   UserStruct.MilImage     = MilImage;
   UserStruct.NbGrabStart  = -2;
   UserStruct.NbGrabEnd    = -2;
   UserStruct.NbFrames     = NbFrames;
   UserStruct.Time         =  0;

   /* Grab on display. */
   MdigGrabContinuous(MilDigitizer, MilImageDisp);

   /* Print a message, wait for a key press and stop the grab. */
   printf("\nDIGITIZER HOOK:\n");
   printf("---------------\n\n");
   printf("Press <Enter> to record the sequence using grab hook.\n\n");
   getch();
   MdigHalt(MilDigitizer);

   /* Hook functions to grab the sequence. */
   MdigHookFunction(MilDigitizer, M_GRAB_START, GrabStart, (void *)(&UserStruct));
   MdigHookFunction(MilDigitizer, M_GRAB_END,   GrabEnd,   (void *)(&UserStruct));

   /* Put digitizer in asynchronous mode. */
   MdigControl(MilDigitizer, M_GRAB_MODE, M_ASYNCHRONOUS);

   /* Start sequence with a grab in the first buffer. */
   MdigGrab(MilDigitizer, MilImage[0]);

   /* At this point the CPU is free to do other tasks and the sequence will be
    * grabbed during this time. Here, the CPU will print and draw the
    * index of the buffer grabbed before copying it to display.
    */
   while (UserStruct.NbGrabEnd < NbFrames)
     {
     long GrabEndIndex;

     /* Wait end of grab event */
     MthrWait(UserStruct.GrabEndEvent, M_EVENT_WAIT, M_NULL);

     /* Print the current grab index. */
     GrabEndIndex = UserStruct.NbGrabEnd-1;
     if (GrabEndIndex >= 0)
         {
         printf("\rBuffer #%ld grabbed.   ",GrabEndIndex);
         MOs_ltoa(GrabEndIndex, FrameIndex, 10);
         MgraText(M_DEFAULT, MilImage[GrabEndIndex], 32, 32, FrameIndex);
         MbufCopy(MilImage[GrabEndIndex],MilImageDisp);
         }
     }

   /* Wait for end of last grab. */
   MdigGrabWait(MilDigitizer, M_GRAB_END);

   /* Print statistics. */
   printf("\n\n%ld frames grabbed, at a frame rate of %.2f frames/sec (%.2f ms/frame).\n",
          UserStruct.NbGrabStart, UserStruct.NbGrabStart/UserStruct.Time, 1000.0*UserStruct.Time/UserStruct.NbGrabStart);

   /* Play the sequence until <enter> is pressed. */
   printf("Press <enter> to end the playback.\n");
   while( !kbhit() )
      {
      /* Play the sequence. */
      for (n=0; n<NbFrames; n++)
         {
         /* Copy one image to the screen. */
         MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);
         MbufCopy(MilImage[n],MilImageDisp);
         MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &TimeWait);
         TimeWait = (UserStruct.Time/UserStruct.NbGrabStart) - TimeWait;
         MappTimer(M_TIMER_WAIT, &TimeWait);
         }
      }
   getch();

   /* Unhook functions. */
   MdigHookFunction(MilDigitizer, M_GRAB_START+M_UNHOOK, GrabStart, (void *)(&UserStruct));
   MdigHookFunction(MilDigitizer, M_GRAB_END+M_UNHOOK, GrabEnd, (void *)(&UserStruct));

   /* Free event. */
   MthrFree(UserStruct.GrabEndEvent);

   /* Free allocations. */
   for (n=0; n<NbFrames; n++)
      {
      MbufFree(MilImage[n]);
      }
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilImageDisp);
}

/* Grab Start hook function:
 *      - This function is used to queue a grab at the beginning of
 *        the each current grab.
 *      - It is also used to measure the frame rate. This is done
 *        by starting a timer at the beginning of a dummy grab and
 *        by stopping the timer at the beginning of the last grab.
 */
long MFTYPE GrabStart(long HookType, MIL_ID EventId, void MPTYPE *UserStructPtr)
{
  UserDataStruct *UserPtr=(UserDataStruct*)UserStructPtr;

  /* Increment grab start count. */
  UserPtr->NbGrabStart++;

  /* Start the timer when needed. */
  if(UserPtr->NbGrabStart == 0)
     MappTimer(M_TIMER_RESET, (double *)&UserPtr->Time);

  /* Queue a new grab or stop the timer at the end. */
  if (UserPtr->NbGrabStart < UserPtr->NbFrames)
     MdigGrab(UserPtr->MilDigitizer,
              UserPtr->MilImage[(UserPtr->NbGrabStart < 0) ? 0 : UserPtr->NbGrabStart]);
  else
     MappTimer(M_TIMER_READ, (double *)&UserPtr->Time);

  return(0);
}

/* Grab end hook function:
 *      - This function is used to signal to a waiting thread (here the main())
 *        that a grab is completed and that the data can be processed.
 *
 *  Note: Time spend in the hook function should be minimal. External
 *        thread waiting on an event should be used to do processing.
 */
long MFTYPE GrabEnd(long HookType, MIL_ID EventId, void MPTYPE *UserStructPtr)
{
  UserDataStruct *UserPtr=(UserDataStruct*)UserStructPtr;

  /* Increment grab count. */
  UserPtr->NbGrabEnd++;

  /* Signal the end of grab event to the main thread waiting. */
  MthrControl(UserPtr->GrabEndEvent, M_EVENT_SET, M_SIGNALED);

  return(0);
}


Example: mdigmultdestination.c

/* File name:  MdigMultDestination.c
 * Synopsis:   This example shows how to maintain a color continuous
 *             grab in the display and at the same time grab in
 *             a monochrome Host buffer for processing.
 *             For further information, refer to the MdigAlloc()
 *             section of the Matrox Orion Board-Specific manual.
 *
 *       Note: This example is only supported on the Matrox Orion,
 *             and the Matrox Orion for 4Sight-II.
 *             Your display depth must be in 32bpp.
*/

/* Processing operation to perform. */
#define REVERSE_IMAGE     0
#define EDGE_DETECT_IMAGE 0
#define COPY_IMAGE        1

/* Image scale. */
#define IMAGE_SCALE  0.5

#include <stdlib.h>
#include <stdio.h>
#include <conio.h>
#include "mil.h"

void main(void)
   {
   MIL_ID  MilApplication;
   MIL_ID  MilSystem;
   MIL_ID  MilDisplay;
   MIL_ID  MilDisplayContinuous;
   MIL_ID  MilDigitizer;
   MIL_ID  MilDigitizerContinuous;
   MIL_ID  MilImage[2];
   MIL_ID  MilImageDisp;
   MIL_ID  MilImageDispContinuous;
   long i=0, n=0, t=0;
   double Time = 0.0;

   /* System allocation. */
   MappAlloc(M_DEFAULT, &MilApplication);
   MsysAlloc(M_SYSTEM_ORION, M_DEF_SYSTEM_NUM, M_SETUP, &MilSystem);

   /* Allocate 2 displays, one for each digitizer. */
   MdispAlloc(MilSystem, M_DEFAULT, M_DEF_DISPLAY_FORMAT, M_DEFAULT, &MilDisplayContinuous);
   MdispAlloc(MilSystem, M_DEFAULT, M_DEF_DISPLAY_FORMAT, M_DEFAULT, &MilDisplay);
   MdispControl(MilDisplayContinuous, M_TITLE, M_PTR_TO_DOUBLE("Continuous grab on display."));
   MdispControl(MilDisplay, M_TITLE, M_PTR_TO_DOUBLE("Grab monoshot on Host and update to display."));

   /* Allocate 2 digitizers, one for the continuous grab to the display and
      one for monochrome monoshots on the Host. */
   MdigAlloc(MilSystem, M_DEV0, M_DEF_DIGITIZER_FORMAT, M_DEFAULT, &MilDigitizerContinuous);
   MdigAlloc(MilSystem, M_DEV0, M_DEF_DIGITIZER_FORMAT, M_DEFAULT, &MilDigitizer);
   MdigControl(MilDigitizer, M_GRAB_SCALE, IMAGE_SCALE);
   MdigControl(MilDigitizer, M_GRAB_MODE, M_ASYNCHRONOUS);

   /* Monoshot grab buffers. */
   MbufAllocColor(MilSystem,  1,
                  (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*IMAGE_SCALE),
                  (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*IMAGE_SCALE),
                     8L+M_UNSIGNED,
                     M_IMAGE+M_GRAB+M_PROC, &MilImage[0]);
   MbufAllocColor(MilSystem,  1,
                  (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*IMAGE_SCALE),
                  (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*IMAGE_SCALE),
                     8L+M_UNSIGNED,
                     M_IMAGE+M_GRAB+M_PROC, &MilImage[1]);
   MbufClear(MilImage[0],M_BLACK);
   MbufClear(MilImage[1],M_BLACK);

   /* Monochrome display buffer. */
   /* Note that the display update speed can be increased and CPU usage decreased
      if the display buffer is allocated in the VGA memory. Simply add
      M_DDRAW+M_ON_BOARD to the display buffer attributes. */
   MbufAllocColor(MilSystem,
                  1,
                  (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*IMAGE_SCALE),
                  (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*IMAGE_SCALE),
                  8L+M_UNSIGNED,
                  M_IMAGE+M_PROC+M_DISP+M_GRAB, &MilImageDisp);
   MbufClear(MilImageDisp,M_BLACK);

   /* Continuous grab display buffer. */
   MbufAllocColor(MilSystem,
                  (long)(MdigInquire(MilDigitizerContinuous, M_SIZE_BAND, M_NULL)),
                  (long)(MdigInquire(MilDigitizerContinuous, M_SIZE_X, M_NULL)),
                  (long)(MdigInquire(MilDigitizerContinuous, M_SIZE_Y, M_NULL)),
                  8L+M_UNSIGNED,
                  M_IMAGE+M_PROC+M_DISP+M_GRAB, &MilImageDispContinuous);
   MbufClear(MilImageDispContinuous, M_BLACK);

   MdispSelect(MilDisplay, MilImageDisp);
   MdispSelect(MilDisplayContinuous, MilImageDispContinuous);

   /* Start continuous grab on the display. */
   MdigGrabContinuous(MilDigitizerContinuous, MilImageDispContinuous);

   printf("Continuous grab in progress.\n");
   printf("Press <enter> to start monoshot grabs\n");
   printf("on Host and update to display.\n");
   getchar();

   /* Reset the timer to compute the number of actual frames
      grabbed per second by monoshot digitizer. */
   MappTimer(M_TIMER_RESET, &Time);

   /* While the continuous grab is running in the display we do
      monoshot grabs with the other digitizer and copy them on
      the second display. This is done using double-buffering
      techniques. Please refer to mdbproc.c example for further
      details about double-buffering. */
   while(!kbhit())
      {
      /* Grab a frame. */
      MdigGrab(MilDigitizer, MilImage[i]);

      /* Toggle between the 2 grab buffers. */
      i = 1-i;
      n++;t++;

      /* Print frame rate. */
      if (n==30)
         {
         MappTimer(M_TIMER_READ, &Time);
         printf("\rGrabbing and processing on Host at %2.3f frames/sec.  Total frames: %d   ",n/Time,t);
         n=0;
         MappTimer(M_TIMER_RESET, &Time);
         }

      /* Process the first buffer already grabbed.
         Note: Real time only if PC is fast enough. */
      #if REVERSE_IMAGE
      MimArith(MilImage[i], M_NULL, MilImageDisp, M_NOT);
      #endif
      #if EDGE_DETECT_IMAGE
      MimConvolve(MilImage[i], MilImageDisp, M_EDGE_DETECT);
      #endif
      #if COPY_IMAGE
      MbufCopy(MilImage[i], MilImageDisp);
      #endif
      }

   /* Wait for the last queued monoshot to finish. */
   MdigGrabWait(MilDigitizer, M_GRAB_END);
   /* Stop the continuous grab. */
   MdigHalt(MilDigitizerContinuous);

   /* Free allocations. */
   MbufFree (MilImage[0]);
   MbufFree (MilImage[1]);
   MbufFree (MilImageDisp);
   MbufFree (MilImageDispContinuous);
   MdigFree (MilDigitizer);
   MdigFree (MilDigitizerContinuous);
   MdispFree(MilDisplay);
   MdispFree(MilDisplayContinuous);
   MsysFree (MilSystem);
   MappFree (MilApplication);
   }


Example: mdigmultformat.c

/* File name:  MdigMultFormat.c
 * Synopsis:   This example shows how to grab from multiple
 *             cameras with different DCFs.
 *             In some applications, you might want to grab from multiple
 *             cameras with different DCFs that are attached to the same
 *             digitizer. This procedure normally involves allocating a
 *             digitizer, grabbing the required frame, freeing the digitizer,
 *             and then allocating the digitizer again with the second DCF;
 *             this can increase the time required for the operation. Mil can
 *             circumvent this problem by using a fast switching technique
 *             which is outlines in this example. For more information
 *             refer to the board specific manual.
 *
 *             This example is supported on the Matrox Meteor-II, Matrox
 *             Meteor-II/MC, Matrox Corona-II, Matrox CronosPlus and Matrox Orion.
 *             It is not supported if you have a JPEG module on your
 *             Matrox Meteor-IIs.
 *             It uses a RS170 camera on channel 0 and a
 *             CCIR camera on channel 1.
 *
 */

#include <conio.h>
#include <mil.h>

/* Image scale. */
#define IMAGE_SCALE        0.5

void main(void)
{
   MIL_ID   MilApplication;
   MIL_ID   MilSystem;
   MIL_ID   MilDigitizerRs170;
   MIL_ID   MilDigitizerCcir;
   MIL_ID   MilImageRs170;
   MIL_ID   MilImageCcir;
   MIL_ID   MilDisplayRs170;
   MIL_ID   MilDisplayCcir;
   double   Time;
   long     NbGrab = 0;
   long     BoardType;

   /* Allocate defaults. */
   MappAlloc(M_DEFAULT, &MilApplication);
   MsysAlloc(M_DEF_SYSTEM_TYPE, M_DEV0, M_DEFAULT, &MilSystem);

   /* Check if this example is supported on the allocated system. */
   BoardType = MsysInquire(MilSystem, M_BOARD_TYPE, M_NULL);
   if ( (BoardType != M_METEOR_II)           &&
        (BoardType != M_METEOR_II_MC)        &&
        (BoardType != M_ORION)               &&
        (BoardType != M_CRONOS_PLUS)         &&
        (BoardType != M_CORONA_II)           &&
        (BoardType != M_CORONA_II_WITH_DIG_MODULE))
      {
      printf("\nSorry this example is not supported on the allocated system.\n");
      printf("\nSupported boards are:\n");
      printf("Matrox Meteor-II.\n");
      printf("Matrox Meteor-II/MC.\n");
      printf("Matrox Corona-II.\n");
      printf("Matrox CronosPlus.\n");
      printf("Matrox Orion.\n");
      printf("Matrox Orion for 4Sight-II.\n");
      MsysFree(MilSystem);
      MappFree(MilApplication);
      return;
      }

   printf("\nThis example shows how to grab from multiple\n");
   printf("cameras with different DCFs.\n");
   printf("\nBe sure you have a RS170 camera on channel 0 and\n");
   printf("an a CCIR camera on channel 1.\n\n");
   printf("Press Enter to begin.\n");
   getchar();

   /* Allocate multiple digitizers on M_DEV0 with different DCFs.*/
   MdigAlloc(MilSystem, M_DEV0, MIL_TEXT("M_RS170"), M_DEFAULT, &MilDigitizerRs170);
   MdigAlloc(MilSystem, M_DEV0, MIL_TEXT("M_CCIR"), M_DEFAULT, &MilDigitizerCcir);

   /* A history of all calls to MdigControl, MdigChannel, MdigReference and
      MdigHookFunction are maintained for each allocated digitizer. It is
      therefore not necessary to redo these calls after a digitizer context
      switch, the restore is done automatically by the driver. */
   MdigControl(MilDigitizerRs170, M_GRAB_SCALE, IMAGE_SCALE);

   /* Enable camera lock, this is done to make shure we are locked on the new
      camera signal after a digitizer context switch.
      Note: changing M_CAMERA_LOCK_SENSITIVITY, and M_CAMERA_UNLOCK_SENSITIVITY
      will affect frame rate performance and grab stability, The user should
      be aware that he may need to change these values for his specific camera
      combination. A lower value of lock and unlock sentivity gives a higher locking/
      unlocking speed but might result in grab sync-lost error messages. */

   MdigControl(MilDigitizerRs170, M_CAMERA_LOCK, M_ENABLE);
   MdigControl(MilDigitizerRs170, M_CAMERA_LOCK_SENSITIVITY, M_DEFAULT);
   MdigControl(MilDigitizerRs170, M_CAMERA_UNLOCK_SENSITIVITY, M_DEFAULT);
   MdigChannel(MilDigitizerRs170, M_CH0);

   MdigControl(MilDigitizerCcir, M_GRAB_SCALE, IMAGE_SCALE);
   MdigControl(MilDigitizerCcir, M_CAMERA_LOCK, M_ENABLE);
   MdigControl(MilDigitizerCcir, M_CAMERA_LOCK_SENSITIVITY, M_DEFAULT);
   MdigControl(MilDigitizerCcir, M_CAMERA_UNLOCK_SENSITIVITY, M_DEFAULT);
   MdigChannel(MilDigitizerCcir, M_CH1);

   MbufAllocColor(MilSystem,
                  (long)MdigInquire(MilDigitizerRs170, M_SIZE_BAND, M_NULL),
                  (long)(MdigInquire(MilDigitizerRs170, M_SIZE_X, M_NULL)*IMAGE_SCALE),
                  (long)(MdigInquire(MilDigitizerRs170, M_SIZE_Y, M_NULL)*IMAGE_SCALE),
                  8L+M_UNSIGNED,
                  M_IMAGE+M_GRAB+M_DISP,
                  &MilImageRs170);
   MbufAllocColor(MilSystem,
                  (long)MdigInquire(MilDigitizerCcir, M_SIZE_BAND, M_NULL),
                  (long)(MdigInquire(MilDigitizerCcir, M_SIZE_X, M_NULL)*IMAGE_SCALE),
                  (long)(MdigInquire(MilDigitizerCcir, M_SIZE_Y, M_NULL)*IMAGE_SCALE),
                  8L+M_UNSIGNED,
                  M_IMAGE+M_GRAB+M_DISP,
                  &MilImageCcir);
   MbufClear(MilImageRs170, 128L);
   MbufClear(MilImageCcir, 128L);

   MdispAlloc(MilSystem, M_DEFAULT, M_DEF_DISPLAY_FORMAT, M_DEFAULT, &MilDisplayRs170);
   MdispAlloc(MilSystem, M_DEFAULT, M_DEF_DISPLAY_FORMAT, M_DEFAULT, &MilDisplayCcir);
   MdispControl(MilDisplayRs170, M_WINDOW_TITLE_NAME, (long)MIL_TEXT("Rs170 Display"));
   MdispControl(MilDisplayCcir,  M_WINDOW_TITLE_NAME, (long)MIL_TEXT("Ccir Display"));
   MdispSelect(MilDisplayRs170, MilImageRs170);
   MdispSelect(MilDisplayCcir,  MilImageCcir);

   MappTimer(M_TIMER_RESET, M_NULL);
   while(!kbhit())
      {
      /* Here a digitizer context switch is made at every loop:
         the new digitizer state is restored along with all controls. */
      /* Note: For faster digitizer switching time the user should
               create custom DCF's with the channel already selected,
               the user should also remove the call to MdigChannel
               at the initialisation phase of this example. You can
               create these DCF's using Matrox Intellicam. */
      if((NbGrab % 2) == 0)
         MdigGrab(MilDigitizerRs170, MilImageRs170);
      else
         MdigGrab(MilDigitizerCcir, MilImageCcir);

      NbGrab++;
      if((NbGrab % 30) == 0)
         {
         MappTimer(M_TIMER_READ, &Time);
         printf("\r%d\tframes grabbed at %f fps.", NbGrab, 30/Time);
         MappTimer(M_TIMER_RESET, M_NULL);
         }
      }
   getchar();

   /* Free all allocated buffers. */
   MdispFree(MilDisplayRs170);
   MdispFree(MilDisplayCcir);
   MdigFree(MilDigitizerRs170);
   MdigFree(MilDigitizerCcir);
   MbufFree(MilImageRs170);
   MbufFree(MilImageCcir);

   MsysFree(MilSystem);
   MappFree(MilApplication);

   return;
}


Example: mdigprocess.c

/*************************************************************************************/
/*
 * File name: MDigProcess.c
 *
 * Synopsis:  This program shows the use of the MdigProcess() function to do perform
 *            real-time processing.
 *
 *            The user's processing code is written in a hook function that
 *            will be called for each frame grabbed (see ProcessingFunction()).
 *
 *      Note: The average processing time must be shorter than the grab time or
 *            some frames will be missed. Also, if the processing results are not
 *            displayed and the frame count is not drawn or printed, the
 *            CPU usage is reduced significantly.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

 /* Number of images in the buffering grab queue.
    Generally, increasing this number gives better real-time grab.
  */
#define BUFFERING_SIZE_MAX 20

/* User's processing function prototype. */
long MFTYPE ProcessingFunction(long HookType, MIL_ID HookId, void MPTYPE *HookDataPtr);

/* User's processing function hook data structure. */
typedef struct
   {
   MIL_ID  MilImageDisp;
   long    ProcessedImageCount;
   } HookDataStruct;

/* Main function. */
/* ---------------*/

void main(void)
{
   MIL_ID MilApplication;
   MIL_ID MilSystem     ;
   MIL_ID MilDigitizer  ;
   MIL_ID MilDisplay    ;
   MIL_ID MilImageDisp  ;
   MIL_ID MilGrabBufferList[BUFFERING_SIZE_MAX] = { 0 };
   long   MilGrabBufferListSize;
   long   ProcessFrameCount  = 0;
   long   NbFrames           = 0;
   double ProcessFrameRate   = 0;
   HookDataStruct UserHookData;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay,
                                              &MilDigitizer, &MilImageDisp);

   /* Allocate the grab buffers and clear them. */
   MappControl(M_ERROR, M_PRINT_DISABLE);
   for(MilGrabBufferListSize = 0; MilGrabBufferListSize<BUFFERING_SIZE_MAX; MilGrabBufferListSize++)
      {
      MbufAlloc2d(MilSystem,
                  MdigInquire(MilDigitizer, M_SIZE_X, M_NULL),
                  MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL),
                  M_DEF_IMAGE_TYPE,
                  M_IMAGE+M_GRAB+M_PROC,
                  &MilGrabBufferList[MilGrabBufferListSize]);

      if (MilGrabBufferList[MilGrabBufferListSize])
         {
         MbufClear(MilGrabBufferList[MilGrabBufferListSize], 0xFF);
         }
      else
         break;
      }
   MappControl(M_ERROR, M_PRINT_ENABLE);

   /* Free a buffer to leave space for possible temporary buffer. */
   MilGrabBufferListSize--;
   MbufFree(MilGrabBufferList[MilGrabBufferListSize]);

   /* Print a message. */
   printf("\nMULTIPLE BUFFERED PROCESSING.\n");
   printf("-----------------------------\n\n");
   printf("Press <Enter> to start.\n\n");

   /* Grab continuously on the display and wait for a key press. */
   MdigGrabContinuous(MilDigitizer, MilImageDisp);
   getch();

   /* Halt continuous grab. */
   MdigHalt(MilDigitizer);

   /* Initialize the User's processing function data structure. */
   UserHookData.MilImageDisp        = MilImageDisp;
   UserHookData.ProcessedImageCount = 0;

   /* Start the processing. The processing function is called for every frame grabbed. */
   MdigProcess(MilDigitizer, MilGrabBufferList, MilGrabBufferListSize,
                             M_START, M_DEFAULT, ProcessingFunction, &UserHookData);

   /* NOTE: Now the main() is free to perform other tasks while the processing is executing. */
   /* --------------------------------------------------------------------------------- */

   /* Print a message and wait for a key press after a minimum number of frames. */
   printf("Press <Enter> to stop.\n\n");
   getch();

   /* Stop the processing. */
   MdigProcess(MilDigitizer, MilGrabBufferList, MilGrabBufferListSize,
               M_STOP, M_DEFAULT, ProcessingFunction, &UserHookData);

   /* Print statistics. */
   MdigInquire(MilDigitizer, M_PROCESS_FRAME_COUNT,  &ProcessFrameCount);
   MdigInquire(MilDigitizer, M_PROCESS_FRAME_RATE,   &ProcessFrameRate);
   printf("\n\n%ld frames grabbed at %.1f frames/sec (%.1f ms/frame).\n",
                          ProcessFrameCount, ProcessFrameRate, 1000.0/ProcessFrameRate);
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free the grab buffers. */
   while(MilGrabBufferListSize > 0)
      MbufFree(MilGrabBufferList[--MilGrabBufferListSize]);

   /* Release defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilImageDisp);
}

/* User's processing function called every time a grab buffer is modified. */
/* -----------------------------------------------------------------------*/

/* Local defines. */
#define STRING_LENGTH_MAX  20
#define STRING_POS_X       20
#define STRING_POS_Y       20

long MFTYPE ProcessingFunction(long HookType, MIL_ID HookId, void MPTYPE *HookDataPtr)
   {
   HookDataStruct *UserHookDataPtr = (HookDataStruct *)HookDataPtr;
   MIL_ID ModifiedBufferId;
   MIL_TEXT_CHAR Text[STRING_LENGTH_MAX]= {'\0',};

   /* Retrieve the MIL_ID of the grabbed buffer. */
   MdigGetHookInfo(HookId, M_MODIFIED_BUFFER+M_BUFFER_ID, &ModifiedBufferId);

   /* Print and draw the frame count. */
   UserHookDataPtr->ProcessedImageCount++;
   printf("Processing frame #%d.\r", UserHookDataPtr->ProcessedImageCount);
   MOs_ltoa(UserHookDataPtr->ProcessedImageCount, Text, 10);
   MgraText(M_DEFAULT, ModifiedBufferId, STRING_POS_X, STRING_POS_Y, Text);

   /* Perform the processing and update the display. */
   #if (!M_MIL_LITE)
      MimArith(ModifiedBufferId, M_NULL, UserHookDataPtr->MilImageDisp, M_NOT);
   #else
      MbufCopy(ModifiedBufferId, UserHookDataPtr->MilImageDisp);
   #endif

   return 0;
   }


Example: mdigprocessmultiple.c

/***********************************************************************************/
/*
 * File name: MDigProcessMultiple.c
 *
 * Synopsis:  This program shows how to use multiple digitizers to do processing.
 *            The main starts an independent processing job for each digitizer
 *            (one per camera) and then waits for a key to be pressed to stop them.
 *
 *     Note:  To do PA processing when using the Matrox Helios, +M_ON_BOARD
 *            attribute is added to the buffer allocations.
 *
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

/* Number of digitizer to use. */
#define DIGITIZER_NUM   2

/* Maximum number of images in the buffering grab queue of each digitizer.
   Generally, increasing the number of buffers prevents missing frames.
 */
#define BUFFERING_SIZE_MAX  30

/* Draw annotation in the Grab image buffers. This can increase CPU
   usage significantly. This is especially true for on-board buffers.
 */
#define DRAW_ANNOTATION     M_NO

/* User's processing function prototype and hook parameter structure. */
long MFTYPE ProcessingFunction(long HookType, MIL_ID HookId, void MPTYPE *HookDataPtr);
typedef struct
   {
   MIL_ID  MilImageDisp;
   long    ProcessedImageCount;
   } HookDataStruct;

/* Main function: */
/* -------------- */
void main(void)
   {
   MIL_ID MilApplication;
   MIL_ID MilSystem;
   MIL_ID MilDigitizer[DIGITIZER_NUM];
   MIL_ID MilDisplay[DIGITIZER_NUM];
   MIL_ID MilImageDisp[DIGITIZER_NUM];
   MIL_ID MilGrabBufferList[DIGITIZER_NUM][BUFFERING_SIZE_MAX];
   long   n, m, BufferLocation = M_NULL;
   long   LastAllocatedN = M_NULL;
   long   LastAllocatedM = M_NULL;
   long   MilGrabBufferListSize = M_NULL;
   long   ProcessFrameCount;
   double ProcessFrameRate;
   int    BufferAllocationSuccess = 1;
   HookDataStruct UserHookData[DIGITIZER_NUM];

   /* Allocate application and system. */
   MappAlloc(M_DEFAULT, &MilApplication);
   MsysAlloc(M_DEF_SYSTEM_TYPE, M_DEFAULT, M_DEFAULT, &MilSystem);

   /* Allocate digitizers using the default DCF. */
   for(n=0; n<DIGITIZER_NUM; n++)
       MdigAlloc(MilSystem, n, "M_DEFAULT", M_DEFAULT, &MilDigitizer[n]);

   /* Allocate displays. */
   for(n=0; n<DIGITIZER_NUM; n++)
       MdispAlloc(MilSystem, M_DEV0, "M_DEFAULT", M_DEFAULT, &MilDisplay[n]);

   /* If the system is a Matrox Helios, allocate the buffer on-board to benefit from Oasis PA processing. */
   if (MsysInquire(MilSystem, M_SYSTEM_TYPE, M_NULL) == M_SYSTEM_HELIOS_TYPE)
      BufferLocation = M_ON_BOARD;

   /* Allocate display buffers and clear them. */
   for(n=0; n<DIGITIZER_NUM; n++)
       {
       MbufAlloc2d(MilSystem,
                   MdigInquire(MilDigitizer[n], M_SIZE_X, M_NULL),
                   MdigInquire(MilDigitizer[n], M_SIZE_Y, M_NULL),
                   8+M_UNSIGNED, M_IMAGE+M_GRAB+M_PROC+M_DISP+BufferLocation,
                   &MilImageDisp[n]);
       MbufClear(MilImageDisp[n], 0);
       }

   /* Allocate the grab buffers for each digitizer and clear them. */
    MappControl(M_ERROR, M_PRINT_DISABLE);

    /* Init table. */
    for(n = 0; n < DIGITIZER_NUM; n++)
       for(m = 0; m < BUFFERING_SIZE_MAX; m++)
          MilGrabBufferList[n][m] = M_NULL;

    /* Try to allocate as many buffers as possible */
    for(m = M_NULL; m < BUFFERING_SIZE_MAX; m++)
      {
      for(n = M_NULL; n < DIGITIZER_NUM; n++)
         {
         /* Try to allocate a buffer. */
         MbufAlloc2d(MilSystem,
                     MdigInquire(MilDigitizer[n], M_SIZE_X, M_NULL),
                     MdigInquire(MilDigitizer[n], M_SIZE_Y, M_NULL),
                     MdigInquire(MilDigitizer[n], M_TYPE, M_NULL),
                     M_IMAGE+M_GRAB+M_PROC+BufferLocation,
                     &MilGrabBufferList[n][m]);

         /* If allocation is successful, clear the buffer. */
         if (MilGrabBufferList[n][m])
            {
            MbufClear(MilGrabBufferList[n][m], 0xFF);

            /* Keep index in table, in case it is the last allocated buffer. */
            LastAllocatedN = n;
            LastAllocatedM = m;
          }

         /* Allocation failed, stop immediately. */
         else
            {
            BufferAllocationSuccess = 0;
            break;
            }

         }

      /* If allocation worked on all digitizers, increase the number of buffers per digitizer. */
      if(BufferAllocationSuccess)
         MilGrabBufferListSize++;

      /* Allocation failed, stop immediately. */
      else
         break;
      }
   MappControl(M_ERROR, M_PRINT_ENABLE);

   /* Free the last allocated buffer to leave space for possible temporary buffer. */
   MbufFree(MilGrabBufferList[LastAllocatedN][LastAllocatedM]);
   MilGrabBufferList[LastAllocatedN][LastAllocatedM] = M_NULL;

   /* If other digitizers have a buffer allocated at same index, delete them for symmetry. */
   for(n = 0; n < DIGITIZER_NUM; n++)
      {
      if(MilGrabBufferList[n][LastAllocatedM])
         {
         MbufFree(MilGrabBufferList[n][LastAllocatedM]);
         MilGrabBufferList[n][LastAllocatedM] = M_NULL;
         }
      }
    MilGrabBufferListSize--;

    /* Start processing jobs. */
   for(n = 0; n < DIGITIZER_NUM; n++)
      {
      /* Display the target image. */
       MdispSelect(MilDisplay[n], MilImageDisp[n]);

       /* Grab continuously on the display and wait for a key press. */
       MdigGrabContinuous(MilDigitizer[n], MilImageDisp[n]);

       /* Print a message. */
       printf("\nPROCESSING #%ld: Multiple buffered processing (%ld buffers).\n", n+1, MilGrabBufferListSize);
       printf("---------------------------------------------------------\n\n");
       printf("Press <Enter> to start.\r");
       getch();
       printf("Processing started...  \n\n");

       /* Halt continuous grab. */
       MdigHalt(MilDigitizer[n]);

       /* Initialize the User processing function data structure. */
       UserHookData[n].MilImageDisp        = MilImageDisp[n];
       UserHookData[n].ProcessedImageCount = 0;

       /* Start the processing. The processing function is called for every grabbed frame. */
       MdigProcess(MilDigitizer[n], MilGrabBufferList[n], MilGrabBufferListSize,
                                 M_START, M_DEFAULT, ProcessingFunction, &UserHookData[n]);
       }

   /* NOTE: Now the main is free to do other tasks while the processing is executing. */
   /* ------------------------------------------------------------------------------- */

   /* Report that the threads are started and wait for a key press. */
   printf("\nMAIN: Processing task(s) running...\n");
   printf("-----------------------------------\n\n");
   printf("Press <Enter> to stop.\n\n");
   getch();

   /* Stop the processing jobs. */
   for(n=0; n<DIGITIZER_NUM; n++)
       {
       /* Stop the processing. */
       MdigProcess(MilDigitizer[n], MilGrabBufferList[n], MilGrabBufferListSize,
                   M_STOP, M_DEFAULT, ProcessingFunction, &UserHookData[n]);

       /* Print statistics. */
       MdigInquire(MilDigitizer[n], M_PROCESS_FRAME_COUNT,  &ProcessFrameCount);
       MdigInquire(MilDigitizer[n], M_PROCESS_FRAME_RATE,   &ProcessFrameRate);
       printf("Processing #%ld: %ld frames grabbed at %.1f frames/sec (%.1f ms/frame).\n",
                          n+1, ProcessFrameCount, ProcessFrameRate, 1000.0/ProcessFrameRate);
       }

    /* Free the grab buffers and MIL objects. */
    MappControl(M_ERROR, M_PRINT_DISABLE);
    for (n=0 ;n<DIGITIZER_NUM; n++)
       {
       for (m = 0; m < BUFFERING_SIZE_MAX; m++)
          {
          if(MilGrabBufferList[n][m])
             {
             MbufFree(MilGrabBufferList[n][m]);
             MilGrabBufferList[n][m] = 0;
             }
          }
       MbufFree(MilImageDisp[n]);
       MdispFree(MilDisplay[n]);
       MdigFree(MilDigitizer[n]);
       }

    MappControl(M_ERROR, M_PRINT_ENABLE);

   /* Wait for a key press to exit. */
   printf("\nPress <Enter> to end.\n\n");
   getch();

   /* Free buffers. */
   MsysFree(MilSystem);
   MappFree(MilApplication);
   }

/* Processing thread(s) function: */
/* ---------------------------------------------------------------- */

/* User's processing function called every time a grab buffer is modified. */
/* ------------------------------------------------------------------------*/

/* Local defines. */
#define STRING_LENGTH_MAX  20
#define STRING_POS_X       20
#define STRING_POS_Y       20

long MFTYPE ProcessingFunction(long HookType, MIL_ID HookId, void MPTYPE *HookDataPtr)
   {
   HookDataStruct *UserHookDataPtr = (HookDataStruct *)HookDataPtr;
   MIL_ID ModifiedBufferId;
   char   Text[STRING_LENGTH_MAX]= {'\0',};

   /* Retrieve the MIL_ID of the grabbed buffer. */
   MdigGetHookInfo(HookId, M_MODIFIED_BUFFER+M_BUFFER_ID, &ModifiedBufferId);

   /* Increase the frame count. */
   UserHookDataPtr->ProcessedImageCount++;

   /* Draw the frame count (if enabled). */
   if (DRAW_ANNOTATION)
      {
      MOs_ltoa(UserHookDataPtr->ProcessedImageCount, Text, 10);
      MgraText(M_DEFAULT, ModifiedBufferId, STRING_POS_X, STRING_POS_Y, Text);
      }

   /* Perform the processing and update the display. */
   #if (!M_MIL_LITE)
      MimArith(ModifiedBufferId, M_NULL, UserHookDataPtr->MilImageDisp, M_NOT);
   #else
      MbufCopy(ModifiedBufferId, UserHookDataPtr->MilImageDisp);
   #endif

   return 0;
   }


Example: mdigsubtract.c

/************************************************************************************/
/*
 * File name: MDigSubtract.c
 *
 * Synopsis:  This program grabs an image which is expected to be the constant dark
 *            background, and then subtracts this background from subsequent grabbed
 *            images.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

void main(void)
{
   MIL_ID MilApplication,  /* Application identifier.             */
          MilSystem,       /* System identifier.                  */
          MilDisplay,      /* Display identifier.                 */
          MilCamera,       /* Camera identifier.                  */
          MilImage,        /* Image buffer identifier.            */
          GrabImage,       /* Grab image buffer identifier.       */
          BackgroundImage; /* Background image buffer identifier. */
   long   CamSizeX,        /* Camera width variable.              */
          CamSizeY;        /* Camera height variable.             */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                    &MilDisplay, &MilCamera, M_NULL);

   /* Reads camera X, Y and depth dimensions. */
   MdigInquire(MilCamera, M_SIZE_X, &CamSizeX);
   MdigInquire(MilCamera, M_SIZE_Y, &CamSizeY);

   /* Allocate a first image buffer to store and display the result image. */
   MbufAlloc2d(MilSystem, CamSizeX, CamSizeY, 8+M_UNSIGNED,
               M_IMAGE+M_PROC+M_GRAB+M_DISP, &MilImage);

   /* Allocate a second image buffer to store the background image. */
   MbufAlloc2d(M_DEFAULT, CamSizeX, CamSizeY, 8+M_UNSIGNED,
               M_IMAGE+M_PROC, &BackgroundImage);

   /* Allocate a third image buffer to grab the changing image. */
   MbufAlloc2d(MilSystem, CamSizeX, CamSizeY, 8+M_UNSIGNED,
               M_IMAGE+M_PROC+M_GRAB, &GrabImage);

   /* Select the image on the display. */
   MbufClear(MilImage, 0);
   MdispSelect(MilDisplay, MilImage);

   /* Grab the background image in the display buffer. */
   MdigGrabContinuous(MilCamera, MilImage);

   /* When a key is pressed, halt. */
   printf("Point your camera at a constant dark background and adjust the focus.\n");
   printf("Press <Enter> to continue.\n");
   getchar();
   MdigHalt(MilCamera);

   /* Copy the displayed buffer into the background buffer. */
   MbufCopy(MilImage, BackgroundImage);

   /* When a key is pressed, halt. */
   printf("Continuous subtraction in progress...\n\n");
   printf("Keeping your camera in the same position, create motion with a bright\n");
   printf("object in front of the background.\n");
   printf("Press <Enter> to end.\n");

   /* Grab and subtract background in loop. */
   while (!kbhit())
      {
      MdigGrab(MilCamera, GrabImage);
      MimArith(GrabImage, BackgroundImage, MilImage, M_SUB_ABS);
      }
   getch();

   /* Release defaults and image. */
   MbufFree(GrabImage);
   MbufFree(BackgroundImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilCamera, MilImage);
}


Example: mdispoverlay.c

/*************************************************************************************/
/*
 * File name: MDispOverlay.c
 *
 * Synopsis:  This program shows how to display an image while creating
 *            text and graphics annotations on top of it using MIL
 *            graphic functions and windows GDI drawing under Windows.
 *            If the target system supports grabbing, the annotations
 *            are done on top of a continuous grab.
 *
 */
#include <mil.h>
#include <conio.h>
#include <windows.h>

/* Target image. */
#define IMAGE_FILE     M_IMAGE_PATH MIL_TEXT("Board.mim")

/* Title for the display window. */
#define WINDOW_TITLE   MIL_TEXT("Custom Title")

/* Overlay drawing function prototype. */
void OverlayDraw(MIL_ID Display);

void main(void)
   {
   MIL_ID MilApplication,            /* Application identifier. */
          MilSystem,                 /* System identifier.      */
          MilDisplay,                /* Display identifier.     */
          MilDigitizer=0,            /* Digitizer identifier.   */
          MilImage;                  /* Image identifier.       */

   /* Allocate defaults */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* If the system have a digitizer, use it. */
   if (MsysInquire(MilSystem, M_DIGITIZER_NUM, M_NULL))
      {
      MdigAlloc(MilSystem, M_DEFAULT, MIL_TEXT("M_DEFAULT"), M_DEFAULT, &MilDigitizer);
      MbufAllocColor(MilSystem,
                     MdigInquire(MilDigitizer,M_SIZE_BAND,M_NULL),
                     MdigInquire(MilDigitizer,M_SIZE_X,M_NULL),
                     MdigInquire(MilDigitizer,M_SIZE_Y,M_NULL),
                     8+M_UNSIGNED,
                     M_IMAGE+M_DISP+M_PROC+M_GRAB,
                     &MilImage);
      MbufClear(MilImage, 0);
      }
   else
      {
      /* Restore a static image. */
      MbufRestore(IMAGE_FILE, MilSystem, &MilImage);
      }

   /* Change display window title. */
   MdispControl(MilDisplay, M_TITLE, M_PTR_TO_DOUBLE(WINDOW_TITLE));

   /* Display the image buffer. */
   MdispSelect(MilDisplay, MilImage);

   /* Draw text and graphics annotations in the display overlay. */
   OverlayDraw(MilDisplay);

   /* If the system supports it, grab continuously in the displayed image. */
   if (MilDigitizer)
      MdigGrabContinuous(MilDigitizer, MilImage);

   /* Pause to show the image. */
   printf("\nOVERLAY ANNOTATIONS:\n");
   printf("--------------------\n\n");
   printf("Displaying an image with overlay annotations.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Stop the continuous grab and free digitizer if needed. */
   if (MilDigitizer)
      {
      MdigHalt(MilDigitizer);
      MdigFree(MilDigitizer);

      /* Pause to show the result. */
      printf("Displaying the last grabbed image.\n");
      printf("Press <Enter> to end.\n\n");
      getch();
      }

   /* Free image. */
   MbufFree(MilImage);

   /* Free default allocations. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   }

/* --------------------------------------------------------------- */
/* Name:      OverlayDraw
 * Synopsis:  This function draws annotations in the display overlay.
 */
void OverlayDraw(MIL_ID MilDisplay)
   {
   MIL_ID   MilOverlayImage;
   long     ImageWidth, ImageHeight;
   long     Count;
   HDC      hCustomDC;
   HPEN     hpen, hpenOld;
   MILTCHAR chText[80];

   /* Prepare overlay buffer. */
   /***************************/

   /* Enable the display of overlay annotations. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);

   /* Inquire the overlay buffer associated with the display. */
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Clear the overlay to transparent. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Disable the overlay display update to accelerate annotations. */
   MdispControl(MilDisplay, M_OVERLAY_SHOW, M_DISABLE);

   /* Inquire overlay size. */
   ImageWidth  = MbufInquire(MilOverlayImage, M_SIZE_X, M_NULL);
   ImageHeight = MbufInquire(MilOverlayImage, M_SIZE_Y, M_NULL);

   /* Draw MIL overlay annotations. */
   /*********************************/

   /* Set the graphic text background to transparent. */
   MgraControl(M_DEFAULT, M_BACKGROUND_MODE, M_TRANSPARENT);

   /* Print a white string in the overlay image buffer. */
   MgraColor(M_DEFAULT, M_COLOR_WHITE);
   MgraText(M_DEFAULT, MilOverlayImage, ImageWidth/9, ImageHeight/5,    MIL_TEXT(" -------------------- "));
   MgraText(M_DEFAULT, MilOverlayImage, ImageWidth/9, ImageHeight/5+25, MIL_TEXT(" - MIL Overlay Text - "));
   MgraText(M_DEFAULT, MilOverlayImage, ImageWidth/9, ImageHeight/5+50, MIL_TEXT(" -------------------- "));

   /* Print a green string in the overlay image buffer. */
   MgraColor(M_DEFAULT, M_COLOR_GREEN);
   MgraText(M_DEFAULT, MilOverlayImage, ImageWidth*11/18, ImageHeight/5,    MIL_TEXT(" ---------------------"));
   MgraText(M_DEFAULT, MilOverlayImage, ImageWidth*11/18, ImageHeight/5+25, MIL_TEXT(" - MIL Overlay Text - "));
   MgraText(M_DEFAULT, MilOverlayImage, ImageWidth*11/18, ImageHeight/5+50, MIL_TEXT(" ---------------------"));

   /* Re-enable the overlay display after all annotations are done. */
   MdispControl(MilDisplay, M_OVERLAY_SHOW, M_ENABLE);

   /* Draw GDI color overlay annotation */
   /*************************************/

   /* Disable error printing for the inquire might not be supported */
   MappControl(M_ERROR, M_PRINT_DISABLE);

   /* Create a device context to draw in the overlay buffer with GDI. */
   MbufControl(MilOverlayImage, M_DC_ALLOC, M_DEFAULT);

   /* Inquire the device context. */
   hCustomDC = ((HDC)MbufInquire(MilOverlayImage, M_DC_HANDLE, M_NULL));

   /* Re-enable error printing */
   MappControl(M_ERROR, M_PRINT_ENABLE);

   /* Perform operation if GDI drawing is supported. */
   if (hCustomDC)
      {
      POINT Hor[2];
      POINT Ver[2];
      SIZE  TxtSz;
      RECT  Txt;

      /* Draw a blue cross. */
      hpen=CreatePen(PS_SOLID, 1, RGB(0, 0, 255));
      hpenOld = SelectObject(hCustomDC, hpen);

      Hor[0].x = 0;
      Hor[0].y = ImageHeight/2;
      Hor[1].x = ImageWidth;
      Hor[1].y = ImageHeight/2;
      Polyline(hCustomDC, Hor,2);

      Ver[0].x = ImageWidth/2;
      Ver[0].y = 0;
      Ver[1].x = ImageWidth/2;
      Ver[1].y = ImageHeight;
      Polyline(hCustomDC, Ver,2);

      SelectObject(hCustomDC, hpenOld);
      DeleteObject(hpen);

      /* Prepare transparent text annotations. */
      SetBkMode(hCustomDC, TRANSPARENT);
      MOs_strcpy(chText, MIL_TEXT("GDI Overlay Text"));
      Count = MOs_strlen(chText);
      GetTextExtentPoint(hCustomDC, chText, Count, &TxtSz);

      /* Write red text. */
      Txt.left = ImageWidth*3/18;
      Txt.top  = ImageHeight*17/24;
      Txt.right  = Txt.left + TxtSz.cx;
      Txt.bottom = Txt.top  + TxtSz.cy;
      SetTextColor(hCustomDC,RGB(255, 0, 0));
      DrawText(hCustomDC, chText, Count, &Txt, DT_RIGHT);

      /* Write yellow text. */
      Txt.left = ImageWidth*12/18;
      Txt.top  = ImageHeight*17/24;
      Txt.right  = Txt.left + TxtSz.cx;
      Txt.bottom = Txt.top  + TxtSz.cy;
      SetTextColor(hCustomDC, RGB(255, 255, 0));
      DrawText(hCustomDC, chText, Count, &Txt, DT_RIGHT);

      /* Delete device context. */
      MbufControl(MilOverlayImage, M_DC_FREE, M_DEFAULT);

      /* Signal MIL that the overlay buffer was modified. */
      MbufControl(MilOverlayImage, M_MODIFIED, M_DEFAULT);
      }
    }


Example: mdispselect.c

/************************************************************************************/
/*
 * File name: MDispSelect.c
 *
 * Synopsis:  This program allocates a displayable image buffer, clears its contents,
 *            draws a filled circle and some text and then displays it.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

int main(void)
{
   MIL_ID MilApplication,  /* Application identifier.  */
          MilSystem,       /* System identifier.       */
          MilDisplay,      /* Display identifier.      */
          MilImage;        /* Image buffer identifier. */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Allocate an image buffer with the default dimensions to do graphics. */
   MbufAlloc2d(MilSystem, M_DEF_IMAGE_SIZE_X_MIN,M_DEF_IMAGE_SIZE_Y_MIN,
                          M_DEF_IMAGE_TYPE, M_IMAGE+M_DISP, &MilImage);

   /* Draw and display a circle */
   MbufClear(MilImage, 0L);
   MgraColor(M_DEFAULT, 255L);
   MgraArcFill(M_DEFAULT, MilImage, 256L, 240L, 100L, 100L, 0.0, 360.0);
   MgraText(M_DEFAULT, MilImage, 238L, 234L, " MIL ");

   /* Display the image buffer. */
   MdispSelect(MilDisplay, MilImage);

   /* Print a message. */
   printf("A circle was drawn in the displayed image buffer.\n");
   printf("Press <Enter> to end.\n");
   getchar();

   /* Release image buffer. */
   MbufFree(MilImage);

   /* Release defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   return 0;
}


Example: mdispwindow.c

/*****************************************************************************/
/*
 * File name: MDispWindow.c
 *
 * Synopsis:  This program displays a welcoming message in a user-defined
 *            window and grabs (if supported) in it. It uses
 *            the MIL system and the MdispSelectWindow() function
 *            to display the MIL buffer in a user-created client window.
 *
 */
#include <windows.h> /* windows.h must precede mil.h. */
#include <mil.h>

/* Window title. */
#define MIL_APPLICATION_NAME      "MIL Application"
#define MIL_APPLICATION_NAME_SIZE  128

/* Default image dimensions. */
#define DEFAULT_IMAGE_SIZE_X       640
#define DEFAULT_IMAGE_SIZE_Y       480
#define DEFAULT_IMAGE_SIZE_BAND      1

/* Background color of the window client area. */
#define BACKCOLORRED               160
#define BACKCOLORGREEN             160
#define BACKCOLORBLUE              164

/* Defines for menu. */
#define IDM_START_MAIN             100

/* Function prototypes. */
void MilApplication(HWND UserWindowHandle);
void MilApplicationPaint(HWND UserWindowHandle);

/***************************************************************************/
/*/
* Name:         MilApplication()
*
* Synopsis:     This function is the core of the MIL application that
*               is executed when the "Start" menu item of this
*               Windows program is selected. See WinMain() below
*               for the program entry point.
*
*               It uses MIL to display a welcoming message in the
*               specified user window and to grab in it (if it is supported)
*               using the target system.
*
*/

void MilApplication(HWND UserWindowHandle)
{
   /* MIL variables */
   MIL_ID MilApplication,  /* MIL Application identifier.  */
          MilSystem,       /* MIL System identifier.       */
          MilDisplay,      /* MIL Display identifier.      */
          MilDigitizer,    /* MIL Digitizer identifier.    */
          MilImage;        /* MIL Image buffer identifier. */

   long BufSizeX;
   long BufSizeY;
   long BufSizeBand;

   /* Allocate a MIL application. */
   MappAlloc(M_DEFAULT, &MilApplication);

   /* Allocate a MIL system. */
   MsysAlloc("M_DEFAULT", M_DEFAULT, M_DEFAULT, &MilSystem);

   /* Allocate a MIL display. */
   MdispAlloc(MilSystem, M_DEFAULT, "M_DEFAULT", M_WINDOWED, &MilDisplay);

   /* Allocate a MIL digitizer, if supported, and set the target image size. */
   if (MsysInquire(MilSystem, M_DIGITIZER_NUM, M_NULL) > 0)
      {
      MdigAlloc(MilSystem, M_DEFAULT, "M_DEFAULT", M_DEFAULT, &MilDigitizer);
      MdigInquire(MilDigitizer, M_SIZE_X,    &BufSizeX);
      MdigInquire(MilDigitizer, M_SIZE_Y,    &BufSizeY);
      MdigInquire(MilDigitizer, M_SIZE_BAND, &BufSizeBand);
      }
   else
      {
      MilDigitizer = M_NULL;
      BufSizeX     = DEFAULT_IMAGE_SIZE_X;
      BufSizeY     = DEFAULT_IMAGE_SIZE_Y;
      BufSizeBand  = DEFAULT_IMAGE_SIZE_BAND;
      }

   /* Do not allow example to run in auxiliary mode. */
   if(MdispInquire(MilDisplay, M_DISPLAY_MODE, M_NULL) != M_WINDOWED)
      {
      MessageBox(0,"""This example does no run in auxiliary mode.",
                   "MIL application example",
                   MB_APPLMODAL | MB_ICONEXCLAMATION );
      goto end;
      }

   /* Allocate a MIL buffer. */
   MbufAllocColor(MilSystem, BufSizeBand, BufSizeX, BufSizeY, 8+M_UNSIGNED,
                  (MilDigitizer ? M_IMAGE+M_DISP+M_GRAB : M_IMAGE+M_DISP), &MilImage);

   /* Clear the buffer. */
   MbufClear(MilImage,0);

   /* Select the MIL buffer to be displayed in the user-specified window. */
   MdispSelectWindow(MilDisplay, MilImage, UserWindowHandle);

   /* Print a string in the image buffer using MIL.
      Note: When a MIL buffer is modified using a MIL command, the display
      automatically updates the window passed to MdispSelectWindow().
   */
      MgraFont(M_DEFAULT, M_FONT_DEFAULT_LARGE);
      MgraText(M_DEFAULT, MilImage, (BufSizeX/8)*2, BufSizeY/2,
                                    MIL_TEXT(" Welcome to MIL !!! "));
      MgraRect(M_DEFAULT, MilImage, ((BufSizeX/8)*2)-60, (BufSizeY/2)-80,
                                    ((BufSizeX/8)*2)+370, (BufSizeY/2)+100);
      MgraRect(M_DEFAULT, MilImage, ((BufSizeX/8)*2)-40, (BufSizeY/2)-60,
                                    ((BufSizeX/8)*2)+350, (BufSizeY/2)+80);
      MgraRect(M_DEFAULT, MilImage, ((BufSizeX/8)*2)-20, (BufSizeY/2)-40,
                                    ((BufSizeX/8)*2)+330, (BufSizeY/2)+60);

   /* Open a message box to wait for a key press. */
   MessageBox(0,"""Welcome to MIL !!!"" was printed", "MIL application example",
                                              MB_APPLMODAL | MB_ICONEXCLAMATION);

   /* Grab in the user window if supported. */
   if (MilDigitizer)
      {
      /* Grab continuously. */
      MdigGrabContinuous(MilDigitizer, MilImage);

      /* Open a message box to wait for a key press. */
      MessageBox(0,"Continuous grab in progress", "MIL application example",
                                         MB_APPLMODAL | MB_ICONEXCLAMATION );

      /* Stop continuous grab. */
      MdigHalt(MilDigitizer);
      }

   /* Remove the MIL buffer from the display. */
   MdispSelect(MilDisplay, M_NULL);

   /* Free allocated objects. */
   MbufFree(MilImage);

end:

   if (MilDigitizer)
      MdigFree(MilDigitizer);
   MdispFree(MilDisplay);
   MsysFree(MilSystem);
   MappFree(MilApplication);
}

/***************************************************************************/
/*/
* Name:       MilApplicationPaint()
*
* synopsis:  This function can be used to complete the work done by
*            the MIL paint manager when the client window receives
*            a paint message.
*
*            This is called every time WindowProc receives a
*            WM_PAINT message
*/

void MilApplicationPaint(HWND UserWindowHandle)
{
   /* Nothing is done here because nothing gets drawn on top of
    * or around our displayed MIL buffer in the window.
    */
   UserWindowHandle = UserWindowHandle; /* line to remove warning */
}

/***************************************************************************/
/*
 * Synopsis:  The next functions lets the user to quickly create a Windows
 *            program which will call the MilApplication() function each
 *            time the Start menu item is selected. The user may also
 *            use the MilApplicationPaint() function that is called
 *            each time the window receives a paint message to
 *            complete the work already done by the MIL paint manager.
 */

/* Prototypes for Windows application */
int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int);
long WINAPI MainWndProc(HWND, UINT, WPARAM, LPARAM);
BOOL InitApplication(HINSTANCE, int);

/***************************************************************************/
/*
 *   Name:     WinMain()
 *
 *   Synopsis: Calls initialization function, processes message loop.
 */

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                                        LPSTR lpCmdLine, int nCmdShow)
{
   MSG msg;

   /* Avoid warning for the unused parameter. */
   lpCmdLine = lpCmdLine;

   /* Allow only one instance of program. */
   if (hPrevInstance)
      {
      MessageBox(0, "Sample MIL Host Windows Application already active.\n"
                    "This version sample application does not allow multiple instances.",
                    "Sample MIL Host Application - Error",
                     MB_OK | MB_ICONSTOP);
      return (FALSE);
      }

   /* Exit if unable to initialize. */
   if (!InitApplication(hInstance,nCmdShow))
      return (FALSE);

   /* Get and dispatch messages until a WM_QUIT message is received. */
   while (GetMessage(&msg,(HWND)NULL,(UINT)NULL,(UINT)NULL))
      {
      TranslateMessage(&msg);   /* Translates virtual key codes. */
      DispatchMessage(&msg);    /* Dispatches message to window. */
      }

   return (msg.wParam);    /* Returns the value from PostQuitMessage. */
}

/***************************************************************************/
/*
 *   Name:      MainWndProc()
 *
 *   Synopsis:  Processes messages:
 *              WM_COMMAND     - application menu.
 *              WM_ENDSESSION  - destroy window.
 *              WM_CLOSE       - destroy window.
 *              WM_DESTROY     - destroy window.
 */

long WINAPI MainWndProc(HWND   hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
   HMENU hAppMenu;

   switch (message)
      {
      case WM_COMMAND:     /* message: command from application menu. */
         switch(wParam)
            {
            case IDM_START_MAIN:
               hAppMenu = GetMenu(hWnd);
               EnableMenuItem(hAppMenu,MF_BYCOMMAND | IDM_START_MAIN,MF_GRAYED);
               DrawMenuBar(hWnd);
               MilApplication(hWnd);
               if (!GetWindowLong(hWnd,sizeof(LPVOID)))
                  {
                  PostQuitMessage(0);
                  }
               else
                  {
                  EnableMenuItem(hAppMenu,MF_BYCOMMAND | IDM_START_MAIN,MF_ENABLED);
                  DrawMenuBar(hWnd);
                  }
               break;
            default:
               return (DefWindowProc(hWnd, message, wParam, lParam));
            }
         break;
      case WM_PAINT:
         MilApplicationPaint(hWnd);
         return (DefWindowProc(hWnd, message, wParam, lParam));
      case WM_ENDSESSION:
      case WM_CLOSE:
         PostMessage(hWnd, WM_DESTROY, (WORD)0, (LONG)0);
         break;
      case WM_DESTROY:
         /* Free the reserved extra window LPSTR to szAppName. */
         if (GetWindowLong(hWnd,sizeof(LPVOID)))
            {
            free((char *)GetWindowLong(hWnd,sizeof(LPVOID)));
            SetWindowLong(hWnd,sizeof(LPVOID),0L);
            }
         PostQuitMessage(0);

      default:
         return (DefWindowProc(hWnd, message, wParam, lParam));
      }
   return(0L);
}

/***************************************************************************/
/*
 *   Name:     InitApplication()
 *
 *   Synopsis: Initializes window data, registers window class and
 *             creates main window.
 */

BOOL InitApplication(HINSTANCE hInstance, int nCmdShow)
{
   WNDCLASS        wc;
   HWND            hwnd;
   char            TmpName[MIL_APPLICATION_NAME_SIZE];
   char *          szAppName;

   /* Allocation and storage of application name. */
   szAppName = (LPSTR)malloc((MIL_APPLICATION_NAME_SIZE+40) * sizeof(char));
   strcpy(szAppName,MIL_APPLICATION_NAME);

   wc.style          = CS_VREDRAW | CS_HREDRAW;
   wc.lpfnWndProc    = (WNDPROC)MainWndProc;
   wc.cbClsExtra     = 0;
   wc.cbWndExtra     = sizeof(LPVOID)+sizeof(LPSTR);
   wc.hInstance      = hInstance;
   wc.hIcon          = LoadIcon(0,IDI_APPLICATION);
   wc.hCursor        = LoadCursor(0, IDC_ARROW);
   wc.hbrBackground  = CreateSolidBrush(RGB(BACKCOLORRED,
                                            BACKCOLORGREEN,
                                            BACKCOLORBLUE));
   wc.lpszMenuName   = "MILAPPLMENU";
   wc.lpszClassName  = szAppName;

   /* Register the class. */
   if (!RegisterClass(&wc))
      return (FALSE);

   /* Create the window. */
   hwnd = CreateWindow (szAppName,
                        szAppName,
                        WS_OVERLAPPEDWINDOW,
                        CW_USEDEFAULT, CW_USEDEFAULT,
                        CW_USEDEFAULT, CW_USEDEFAULT,
                        0, 0, hInstance, 0) ;
   if (!hwnd)
      return (FALSE);

   lstrcat(szAppName," - ");
   GetModuleFileName(hInstance,TmpName,MIL_APPLICATION_NAME_SIZE);
   lstrcat(szAppName,TmpName);
   SetWindowText(hwnd,szAppName);

   /* Set the reserved extra window LPVOID to NULL. */
   SetWindowLong(hwnd,0,0L);

   /* Set the reserved extra window LPSTR to szAppName. */
   SetWindowLong(hwnd,sizeof(LPVOID),(DWORD)szAppName);

   /* Display the window. */
   ShowWindow (hwnd, nCmdShow) ;
   UpdateWindow (hwnd) ;

   return (TRUE);
}


Example: mdispwindowleveling.c

/************************************************************************************/
/*
 * File name: MdispWindowLeveling.c
 *
 * Synopsis:  This MIL program shows how to display a 10-bit monochrome Medical image
 *            and applies a LUT to do interactive Window Leveling.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

/* Image file to load. */
#define IMAGE_FILE                     M_IMAGE_PATH MIL_TEXT("ArmsMono10bit.mim")

/* Visible number of bits (8, 10, 12... or ImageSizeBit (for full range). */
#define IMAGE_NUMBER_OF_VISIBLE_BITS   10

/* Draw the LUT shape (if disabled reduces CPU usage). */
#define DRAW_LUT_SHAPE                 M_YES

/* Utility functions. */
long MaxImageValue(MIL_ID MilImage, long NumberOfVisibleBits);
void DrawLutShape(MIL_ID MilDisplay, MIL_ID MilOriginalImage, MIL_ID MilImage, long Start,
             long End, long InflexionIntensity, long ImageMaxValue, long DisplayMaxValue);

void main(void)
{
   MIL_ID MilApplication,       /* Application identifier.    */
          MilSystem,            /* System identifier.         */
          MilDisplay,           /* Display identifier.        */
          MilImage,             /* Image buffer identifier.   */
          MilOriginalImage = 0, /* Image buffer identifier.   */
          MilLut;               /* Lut buffer identifier.     */
   long   ImageSizeX, ImageSizeY, ImageMaxValue;
   long   DisplaySizeBit, DisplayMaxValue;
   long   Start, End, Step, InflectionLevel;
   unsigned char Ch;

   /* Allocate the MIL Application, System and Display. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore target image from disk. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);

   /* Set the maximum value of the image to indicate to MIL
      how to initialize the default display LUT.
   */
   ImageMaxValue = MaxImageValue(MilImage, IMAGE_NUMBER_OF_VISIBLE_BITS);
   MbufControl(MilImage, M_MAX, ImageMaxValue);

   /* Display the image (to specify a user-defined window, use MdispSelectWindow()). */
   MdispSelect(MilDisplay, MilImage);

   /* Determine the maximum displayable value of the current display. */
   MdispInquire(MilDisplay, M_SIZE_BIT, &DisplaySizeBit);
   DisplayMaxValue = (1<<DisplaySizeBit)-1;

   /* Print key information. */
   printf("\nWINDOW LEVELING:\n");
   printf("----------------\n\n");

   MOs_printf("Image name : %s\n",IMAGE_FILE);

   printf("Image size : %ld x %ld\n", MbufInquire(MilImage, M_SIZE_X, &ImageSizeX), MbufInquire(MilImage, M_SIZE_Y, &ImageSizeY));
   printf("Image max  : %4ld\n",   ImageMaxValue);
   printf("Display max: %4ld\n\n", DisplayMaxValue);
   printf("Press <Enter> to do interactive Window Leveling.\n\n");
   getch();

   /* Allocate a LUT buffer according to the image maximum value and display pixel depth. */
   MbufAlloc1d(MilSystem, ImageMaxValue+1, ((DisplaySizeBit>8) ? 16 : 8)+M_UNSIGNED, M_LUT, &MilLut);

   /* Generate a LUT with a full range ramp and set its maximum value. */
   MgenLutRamp(MilLut, 0, 0, ImageMaxValue, DisplayMaxValue);
   MbufControl(MilLut, M_MAX, DisplayMaxValue);

   /* Set the display LUT. */
   MdispLut(MilDisplay, MilLut);

   /* Interactive Window Leveling using keyboard. */
   printf("Position keys : Left=move Left, Right=move Right, Down=Narrow, Up=Wider.\n");
   printf("Intensity keys: L=Lower,  U=Upper,  R=Reset.\n");
   printf("Press <Enter> to end.\n\n");

   /* Modify LUT shape according to the arrow keys and update it. */
   Ch = 0;
   Start = 0;
   End = ImageMaxValue;
   InflectionLevel = DisplayMaxValue;
   Step = (ImageMaxValue+1)/128;
   Step = max(Step,4);
   while (Ch != '\r')
      {
      switch (Ch)
         {
         /* Left arrow: Move region left. */
         case 0x4B:
            { Start-=Step; End-=Step; break; }

         /* Right arrow: Move region right. */
         case 0x4D:
            { Start+=Step; End+=Step; break; }

         /* Down arrow: Narrow region. */
         case 0x50:
            { Start+=Step; End-=Step; break; }

         /* Up arrow: Widen region. */
         case 0x48:
            { Start-=Step, End+=Step; break; }

         /* L key: Lower inflexion point. */
         case 'L':
         case 'l':
            { InflectionLevel--; break; }

         /* U key: Upper inflexion point. */
         case 'U':
         case 'u':
            { InflectionLevel++; break; }

         /* R key: Reset the LUT to full image range. */
         case 'R':
         case 'r':
            { Start=0; End=ImageMaxValue; InflectionLevel=DisplayMaxValue; break; }

         }

      /* Saturate. */
      End   = min(End,ImageMaxValue);
      Start = min(Start,End);
      End   = max(End,Start);
      Start = max(Start,0);
      End   = max(End,0);
      InflectionLevel = max(InflectionLevel, 0);
      InflectionLevel = min(InflectionLevel, DisplayMaxValue);
      printf("Inflection points: Low=(%ld,0), High=(%ld,%ld).   \r", Start, End, InflectionLevel);

      /* Generate a LUT with 3 slopes and saturated at both ends. */
      MgenLutRamp(MilLut, 0, 0, Start, 0);
      MgenLutRamp(MilLut, Start, 0, End, InflectionLevel);
      MgenLutRamp(MilLut, End, InflectionLevel, ImageMaxValue, DisplayMaxValue);

      /* Update the display LUT. */
      MdispLut(MilDisplay, MilLut);

      /* Draw the current LUT's shape in the image.
         Note: This simple annotation method requires
               significant update and CPU time.
      */
      if (DRAW_LUT_SHAPE)
         {
         if (!MilOriginalImage)
            MbufRestore(IMAGE_FILE, MilSystem, &MilOriginalImage);
         DrawLutShape(MilDisplay, MilOriginalImage, MilImage, Start, End,
                                  InflectionLevel, ImageMaxValue, DisplayMaxValue);
         }

      /* If its an arrow key, get the second code. */
      if ((Ch = getch()) == 0xE0)
           Ch = getch();
      }
   printf("\n\n");

   /* Free all allocations. */
   MbufFree(MilLut);
   MbufFree(MilImage);
   if (MilOriginalImage)
      MbufFree(MilOriginalImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}

/* Function to calculate the maximum value of an image. */
long MaxImageValue(MIL_ID MilImage, long NumberOfVisibleBits)
   {
   MIL_ID MilExtremeResult = M_NULL;
   long ImageMaxValue, ImageSizeBit = 0;

   /* Determine and set the maximum value of the image. */
   #if (M_MIL_LITE)
      {
       /* Relies on the number of bits of the user-specified image but saturates if necessary. */
       MbufInquire(MilImage, M_SIZE_BIT, &ImageSizeBit);
       NumberOfVisibleBits = min(NumberOfVisibleBits, ImageSizeBit);
       ImageMaxValue = (1<<NumberOfVisibleBits)-1;
      }
   #else
      {
      /* Dynamically calculates the maximum value of the image using processing. */
      MimAllocResult(MbufInquire(MilImage, M_OWNER_SYSTEM, M_NULL), 1L,
                                           M_EXTREME_LIST, &MilExtremeResult);
      MimFindExtreme(MilImage, MilExtremeResult, M_MAX_VALUE);
      MimGetResult(MilExtremeResult, M_VALUE, &ImageMaxValue);
      MimFree(MilExtremeResult);
      }
   #endif

    return (ImageMaxValue);
   }

/* Function to draw the current LUT's shape in the image.

   Note: This simple annotation method requires significant update
          and CPU time since it repaints the entire image every time.
*/
void DrawLutShape(MIL_ID MilDisplay, MIL_ID MilOriginalImage, MIL_ID MilImage, long Start,
             long End, long InflectionIntensity, long ImageMaxValue, long DisplayMaxValue)
   {
    double         Xstart, Xend, Xstep, Ymin, Yinf, Ymax, Ystep;
    long           ImageSizeX, ImageSizeY;
    MIL_TEXT_CHAR  String[8];

    /* Inquire image dimensions. */
    MbufInquire(MilImage, M_SIZE_X, &ImageSizeX);
    MbufInquire(MilImage, M_SIZE_Y, &ImageSizeY);

    /* Calculate the drawing parameters. */
    Xstep  = (double)ImageSizeX/(double)ImageMaxValue;
    Xstart = Start*Xstep;
    Xend   = End*Xstep;
    Ystep  = ((double)ImageSizeY/4.0)/(double)DisplayMaxValue;
    Ymin   = (ImageSizeY-2);
    Yinf   = Ymin-(InflectionIntensity*Ystep);
    Ymax   = Ymin-(DisplayMaxValue*Ystep);

    /* To increase speed, disable display update until all annotations are done. */
    MdispControl(MilDisplay, M_UPDATE, M_DISABLE);

    /* Restore the original image. */
    MbufCopy(MilOriginalImage, MilImage);

    /* Draw axis max and min values. */
    MgraColor(M_DEFAULT, ImageMaxValue);
    MgraText(M_DEFAULT, MilImage, 4, (long)Ymin-22, MIL_TEXT("0"));
    MOs_sprintf(String, MIL_TEXT("%ld"), DisplayMaxValue);
    MgraText(M_DEFAULT, MilImage, 4, (long)Ymax-16, String);
    MOs_sprintf(String, MIL_TEXT("%ld"), ImageMaxValue);
    MgraText(M_DEFAULT, MilImage, ImageSizeX-38 , (long)Ymin-22, String);

    /* Draw LUT Shape (X axis is display values and Y is image values). */
    MgraLine(M_DEFAULT, MilImage, 0, (long)Ymin, (long)Xstart, (long)Ymin);
    MgraLine(M_DEFAULT, MilImage, (long)Xstart, (long)Ymin, (long)Xend, (long)Yinf);
    MgraLine(M_DEFAULT, MilImage, (long)Xend, (long)Yinf, ImageSizeX-1, (long)Ymax);

    /* Enable display update to show the result. */
    MdispControl(MilDisplay, M_UPDATE, M_ENABLE);
   }


Example: medge.c

/*****************************************************************************/
/*
 * File name: MEdge.c
 *
 * Synopsis:  This program uses the MIL Edge Finder module to find and measure
 *            the outer diameter of good seals in a target image.
 */
#include <mil.h>
#include <conio.h>

/* Source MIL image file specifications. */
#define CONTOUR_IMAGE               M_IMAGE_PATH MIL_TEXT("Seals.mim")
#define CONTOUR_MAX_RESULTS         100
#define CONTOUR_MAXIMUM_ELONGATION  0.8
#define CONTOUR_DRAW_COLOR          M_COLOR_GREEN
#define CONTOUR_LABEL_COLOR         M_COLOR_RED

 /* Main function. */
void main(void)
   {
   MIL_ID MilApplication,                         /* Application identifier.   */
          MilSystem,                              /* System Identifier.        */
          MilDisplay,                             /* Display identifier.       */
          MilImage,                               /* Image buffer identifier.  */
          MilOverlayImage,                        /* Overlay image.            */
          MilEdgeContext,                         /* Edge context.             */
          MilEdgeResult;                          /* Edge result identifier.   */
   long   EdgeDrawColor = CONTOUR_DRAW_COLOR,     /* Edge draw color.          */
          LabelDrawColor = CONTOUR_LABEL_COLOR,   /* Text draw color.          */
          NumEdgeFound  = 0L,                     /* Number of edges found.    */
          NumResults    = 0L,                     /* Number of results found.  */
          i;                                      /* Loop variable.            */
   double MeanFeretDiameter[CONTOUR_MAX_RESULTS]; /* Edge mean Feret diameter. */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore the image and display it. */
   MbufRestore(CONTOUR_IMAGE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Prepare for overlay annotations. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Pause to show the original image. */
   printf("\nEDGE MODULE:\n");
   printf("------------\n\n");
   printf("This program determines the outer seal diameters in the displayed image \n");
   printf("by detecting and analyzing contours with the Edge Finder module.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Allocate a Edge Finder context. */
   MedgeAlloc(MilSystem, M_CONTOUR, M_DEFAULT, &MilEdgeContext);

   /* Allocate a result buffer. */
   MedgeAllocResult(MilSystem, M_DEFAULT, &MilEdgeResult);

   /* Enable features to compute. */
   MedgeControl(MilEdgeContext, M_MOMENT_ELONGATION,                M_ENABLE);
   MedgeControl(MilEdgeContext, M_FERET_MEAN_DIAMETER+M_SORT1_DOWN, M_ENABLE);

   /* Calculate edges and features. */
   MedgeCalculate(MilEdgeContext, MilImage, M_NULL, M_NULL, M_NULL, MilEdgeResult, M_DEFAULT);

   /* Get the number of edges found. */
   MedgeGetResult(MilEdgeResult, M_DEFAULT, M_NUMBER_OF_CHAINS+M_TYPE_LONG, &NumEdgeFound, M_NULL);

   /* Draw edges in the source image to show the result. */
   MgraColor(M_DEFAULT, EdgeDrawColor);
   MedgeDraw(M_DEFAULT, MilEdgeResult, MilOverlayImage, M_DRAW_EDGES, M_DEFAULT, M_DEFAULT);

   /* Pause to show the edges. */
   printf("%d edges were found in the image.\n", NumEdgeFound);
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Exclude elongated edges. */
   MedgeSelect(MilEdgeResult, M_EXCLUDE, M_MOMENT_ELONGATION, M_LESS, CONTOUR_MAXIMUM_ELONGATION, M_NULL);

   /* Exclude inner chains. */
   MedgeSelect(MilEdgeResult, M_EXCLUDE, M_INCLUDED_EDGES, M_INSIDE_BOX, M_NULL, M_NULL);

   /* Draw remaining edges and their index to show the result. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MgraColor(M_DEFAULT, EdgeDrawColor);
   MedgeDraw(M_DEFAULT, MilEdgeResult, MilOverlayImage, M_DRAW_EDGES, M_DEFAULT, M_DEFAULT);

   /* Pause to show the results. */
   printf("Elongated edges and inner edges of each seal were removed.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Get the number of edges found. */
   MedgeGetResult(MilEdgeResult, M_DEFAULT, M_NUMBER_OF_CHAINS+M_TYPE_LONG, &NumResults, M_NULL);

   /* If the right number of edges were found. */
   if ( (NumResults >= 1) && (NumResults <= CONTOUR_MAX_RESULTS) )
      {
      /* Draw the index of each edge. */
      MgraColor(M_DEFAULT, LabelDrawColor);
      MedgeDraw(M_DEFAULT, MilEdgeResult, MilOverlayImage, M_DRAW_INDEX, M_DEFAULT, M_DEFAULT);

      /* Get the mean Feret diameters. */
      MedgeGetResult(MilEdgeResult, M_DEFAULT, M_FERET_MEAN_DIAMETER, &MeanFeretDiameter, M_NULL);

      /* Print the results. */
      printf("Mean diameter of the %ld outer edges are:\n\n", NumResults);
      printf("Index   Mean diameter \n");
      for (i=0; i<NumResults; i++)
         {
         printf("%-11d%-13.2f%\n", i, MeanFeretDiameter[i]);
         }
      }
   else
      {
      printf("Edges have not been found or the number of found edges is greater than\n");
      printf("the specified maximum number of edges !\n\n");
      }

   /* Wait for a key press. */
   printf("\nPress <Enter> to end.\n");
   getch();

   /* Free MIL objects. */
   MbufFree(MilImage);
   MedgeFree(MilEdgeContext);
   MedgeFree(MilEdgeResult);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   }


Example: met2_1394serialbus.c

/************************************************************************************/
/*
 * File name: Met2_1394SerialBus.c
 *
 * Synopsis:  This program is an example of the Meteor-II bus-specific features
 */
#include "mil.h"
#include "stdio.h"
#include "string.h"
void main(void)
{
MIL_ID MilApplication, /* Application identifier. */
MilSystem,             /* System identifier. */
MilDigitizer;          /* Digitizer identifier. */
long NbFormats;
long MaxLength;
char * Strings;
long Offset;
long t;

/* Allocate defaults. */
MappAlloc(M_DEFAULT, &MilApplication);
MsysAlloc(M_SYSTEM_METEOR_II_1394, M_DEFAULT, M_SETUP, &MilSystem);
MdigAlloc(MilSystem, M_DEFAULT, "M_DEFAULT", M_DEFAULT, &MilDigitizer);

/* Inquire number of strings and length */
NbFormats = MdigInquire(MilDigitizer, M_FORMAT_SUPPORTED_NUM,
M_NULL);
MaxLength = MdigInquire(MilDigitizer, M_FORMAT_SUPPORTED_LENGTH,
M_NULL);

/* Allocate a buffer to receive the strings */
Strings = malloc(NbFormats*MaxLength*sizeof(MILTCHAR));
memset(Strings, 0, NbFormats*MaxLength*sizeof(char));

/* Inquire the strings */
MdigInquire(MilDigitizer, M_FORMAT_SUPPORTED, Strings);

Offset = 0;
for(t = 0; t < NbFormats; t++)
{
/* Print each string */
printf("%s\n", &Strings[Offset]);
Offset += MaxLength;
}
free(Strings);

printf("Press <Enter> to end.\n");
getchar();

/* Free MIL objects */
MdigFree(MilDigitizer);
MsysFree(MilSystem);
MappFree(MilApplication);


Example: mfunc.c

/*****************************************************************************************/
/*
 * File name: MFunc.c
 *
 * Synopsis:  This example shows the use of the MIL Function Developer Tool Kit and how
 *            MIL and custom code can be mixed to create a custom MIL function that
 *            accesses the data pointer of a MIL buffer directly in order to process it.
 *
 *            The example creates a Master MIL function that registers all the parameters
 *            to MIL and calls the Slave function. The Slave function retrieves all the
 *            parameters, gets the pointers to the MIL image buffers, uses them to access
 *            the data directly, and adds a constant.
 *
 *            Note: The images must be 8-bit unsigned.
 */
#include <mil.h>
#include <conio.h>

/* MIL function specifications. */
#define FUNCTION_NB_PARAM                 3
#define FUNCTION_OPCODE_ADD_CONSTANT      1
#define FUNCTION_PARAMETER_ERROR_CODE     1
#define FUNCTION_SUPPORTED_IMAGE_DEPTH    8

/* Target image file name. */
#define IMAGE_FILE   M_IMAGE_PATH MIL_TEXT("BoltsNutsWashers.mim")

/* Master and Slave MIL functions declarations. */
void AddConstant(MIL_ID SrcImageId, MIL_ID DstImageId, unsigned long ConstantToAdd);
void MFTYPE SlaveAddConstant(MIL_ID Func);

/* Master MIL Function definition. */
/* ------------------------------- */

void AddConstant(MIL_ID SrcImageId, MIL_ID DstImageId, unsigned long ConstantToAdd)
{
   MIL_ID   Func;

   /* Allocate a MIL function context that will be used to call a target
      Slave function locally on the Host to do the processing.
   */
   MfuncAlloc(MIL_TEXT("AddConstant"),
              FUNCTION_NB_PARAM,
              SlaveAddConstant, M_NULL, M_NULL,
              M_USER_MODULE_1+FUNCTION_OPCODE_ADD_CONSTANT,
              M_ASYNCHRONOUS_FUNCTION+M_LOCAL,
              &Func
             );

   /* Register the parameters. */
   MfuncParamId(  Func, 1, SrcImageId, M_IMAGE, M_IN);
   MfuncParamId(  Func, 2, DstImageId, M_IMAGE, M_OUT);
   MfuncParamLong(Func, 3, ConstantToAdd);

   /* Call the target Slave function. */
   MfuncCall(Func);

   /* Free the MIL function context. */
   MfuncFree(Func);
}

/* MIL Slave function definition. */
/* ------------------------------ */

void MFTYPE SlaveAddConstant(MIL_ID Func)
{
  MIL_ID SrcImageId, DstImageId;
  unsigned long ConstantToAdd;
  unsigned char *SrcImageDataPtr, *DstImageDataPtr;
  long   SrcImageSizeX, SrcImageSizeY, SrcImageSizeBit, SrcImagePitchByte;
  long   DstImageSizeX, DstImageSizeY, DstImageSizeBit, DstImagePitchByte;
  long   x, y, TempValue;

  /* Read the parameters. */
  MfuncParamValue(Func, 1, &SrcImageId);
  MfuncParamValue(Func, 2, &DstImageId);
  MfuncParamValue(Func, 3, &ConstantToAdd);

  /* Read image information. */
  MbufInquire(SrcImageId, M_HOST_ADDRESS, &SrcImageDataPtr);
  MbufInquire(SrcImageId, M_SIZE_X,       &SrcImageSizeX);
  MbufInquire(SrcImageId, M_SIZE_Y,       &SrcImageSizeY);
  MbufInquire(SrcImageId, M_SIZE_BIT,     &SrcImageSizeBit);
  MbufInquire(SrcImageId, M_PITCH_BYTE,   &SrcImagePitchByte);
  MbufInquire(DstImageId, M_HOST_ADDRESS, &DstImageDataPtr);
  MbufInquire(DstImageId, M_SIZE_X,       &DstImageSizeX);
  MbufInquire(DstImageId, M_SIZE_Y,       &DstImageSizeY);
  MbufInquire(SrcImageId, M_SIZE_BIT,     &DstImageSizeBit);
  MbufInquire(DstImageId, M_PITCH_BYTE,   &DstImagePitchByte);

  /* Reduce the destination area to process if necessary. */
  if (SrcImageSizeX < DstImageSizeX)   DstImageSizeX = SrcImageSizeX;
  if (SrcImageSizeY < DstImageSizeY)   DstImageSizeY = SrcImageSizeY;

  /* If images have the proper depth, perform the operation using a custom C code. */
  if ((SrcImageSizeBit == DstImageSizeBit) && (SrcImageSizeBit == FUNCTION_SUPPORTED_IMAGE_DEPTH))
     {
     /* Add the constant to the image. */
     for (y= 0; y < DstImageSizeY; y++)
        {
        for (x= 0; x < DstImageSizeX; x++)
           {
           /* Calculate the value to write. */
           TempValue = (long)SrcImageDataPtr[x] + (long)ConstantToAdd;

           /* Write the value if no overflow, else saturate. */
           if (TempValue <= 0xff)
              DstImageDataPtr[x] = (unsigned char)TempValue;
           else
              DstImageDataPtr[x] = 0xff;
           }

         /* Move pointer to the next line taking into account the image's pitch. */
         (unsigned char *)SrcImageDataPtr += SrcImagePitchByte;
         (unsigned char *)DstImageDataPtr += SrcImagePitchByte;
        }
     }
  else
     {
     /* Report a MIL error. */
     MfuncErrorReport(Func,M_FUNC_ERROR+FUNCTION_PARAMETER_ERROR_CODE,
                      MIL_TEXT("Invalid parameter."),
                      MIL_TEXT("Image type not supported"),
                      MIL_TEXT("Image depth must be 8-bit."),
                      M_NULL
                     );
     }

  /* Signal to MIL that the buffers are now in cache (required by Odyssey). */
  MbufControl(SrcImageId, M_CACHE_CONTROL, M_IN_CACHE);
  MbufControl(DstImageId, M_CACHE_CONTROL, M_IN_CACHE);

  /* Signal to MIL that the destination buffer was modified. */
  MbufControl(DstImageId, M_MODIFIED, M_DEFAULT);
}

/* Main to test the custom function. */
/* --------------------------------- */

void main(void)
{
   MIL_ID MilApplication,    /* Application identifier.  */
          MilSystem,         /* System identifier.       */
          MilDisplay,        /* Display identifier.      */
          MilImage;          /* Image buffer identifier. */

   /* Allocate default application, system, display and image. */
   MappAllocDefault(M_COMPLETE, &MilApplication, &MilSystem,
                                &MilDisplay, M_NULL, M_NULL);

   /* Load source image into a Host memory image buffer. */
   MbufAlloc2d(MilSystem,
               MbufDiskInquire(IMAGE_FILE, M_SIZE_X, M_NULL),
               MbufDiskInquire(IMAGE_FILE, M_SIZE_Y, M_NULL),
               8+M_UNSIGNED,
               M_IMAGE+M_DISP+M_HOST_MEMORY,
               &MilImage);
   MbufLoad(IMAGE_FILE, MilImage);

   /* Display the image. */
   MdispSelect(MilDisplay, MilImage);

   /* Pause. */
   printf("\nMIL FUNCTION DEVELOPER'S TOOLKIT:\n");
   printf("----------------------------------\n\n");
   printf("This example creates a custom MIL function that processes\n");
   printf("an image using its data pointer directly.\n\n");
   printf("Target image was loaded.\n");
   printf("Press a key to continue.\n\n");
   getch();

   /* Process the image directly with the custom MIL function. */
   AddConstant(MilImage, MilImage, 0x40);

   /* Pause */
   printf("The white level of the image was augmented.\n");
   printf("Press a key to terminate.\n\n");
   getch();

   /* Free all allocations. */
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mgbfocus.c

/*  File name: mGbFocus.c
 * Synopsis : This program perform an autofocus operation with a digitizer
 *            that supports the M_FOCUS control.
 */

/* Regular includes. */
#include <stdio.h>
#include <mil.h>
#include <stdlib.h>
#include <windows.h>

/* Autofocus hook function responsible for moving the lens. */
long MFTYPE FocusHookFunction(long HookType, long position, void MPTYPE *UserDataPtr);

/*  Main application function.                                  */
/****************************************************************/
void main(void)
{
    MIL_ID  MilApplication;         /* Application identifier.                   */
    MIL_ID  MilSystem;              /* System identifier.                        */
    MIL_ID   MilDisplay;            /* Display identifier.                       */
    MIL_ID  MilDigitizer;           /* Digitizer identifier.                     */
    MIL_ID   MilBuffer;             /* Source image.                             */
    long     FocusMinPosition;      /* Minimum focus position.                   */
   long     FocusStartPosition;     /* Current focus position.                   */
   long     FocusMaxPosition;       /* Maximum focus position.                   */
    long     FocusPosition;         /* Best focus position.                      */
    long     NumberOfIteration;     /* Number of iterations.                     */
    long     UserData[2];           /* Data needed within the hook function.     */

    printf("An autofocus operation will be done on a grabbed image\n\n");
    printf("Press any key to continue ...\n\n");
    getchar();

    /* Allocate defaults. */
    MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, &MilDigitizer, &MilBuffer);

    /* Testing if the system supports focus. */
    MappControl(M_ERROR, M_PRINT_DISABLE);
    MdigInquire(MilDigitizer, M_FOCUS, M_NULL);

    /* System does supports focus operations. */
    if(MappGetError(M_GLOBAL, M_NULL) == 0)
        {
        MappControl(M_ERROR, M_PRINT_ENABLE);

        /* Initializing data needed for MdigFocus function. */
        FocusMinPosition   = MdigInquire(MilDigitizer, M_FOCUS + M_MIN_VALUE, M_NULL);
        FocusMaxPosition   = MdigInquire(MilDigitizer, M_FOCUS + M_MAX_VALUE, M_NULL);
        FocusStartPosition = MdigInquire(MilDigitizer, M_FOCUS, M_NULL);

       /* Initialize user data needed within the hook function. */
      NumberOfIteration  = 1;
        UserData[0]        = (long)MilDigitizer;
        UserData[1]        = NumberOfIteration;

        /* Perform autofocus. */
        MdigFocus(MilDigitizer,
                MilBuffer,
                     M_DEFAULT,
                     FocusHookFunction,
                     UserData,
                     FocusMinPosition,
                     FocusStartPosition,
                     FocusMaxPosition,
                     M_DEFAULT,
                     M_SMART_SCAN,
                     &FocusPosition);

    /* Print the best focus position, number of iterations and time needed to focus. */
        printf("The best focus position is  : %ld\n\n", FocusPosition);
        printf("The number of iterations is : %ld\n\n", UserData[1]);
        }

    /* System does not support focus operations. */
    else
      {
        printf("Your digitizer does not support this operation.\n\n");
      }

    printf("Press a key to end ...\n");
    getchar();

    /* Free all allocations. */
    MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilBuffer);
}

/* Autofocus hook function responsible for moving the lens. */
/*****************************************************************/
long MFTYPE FocusHookFunction(long HookType, long position, void MPTYPE *UserDataPtr)
{
    long  CurrentPosition;        /* Current position of the lens. */
    long  PositionDifference;     /* Difference between current.   */
                                  /* position and next position.   */
    long  TimeForMovingLens;      /* Sleep time before grab.       */

   /* Focus position must be changed. */
   if(HookType == M_CHANGE)
      {
      /* Get current position. */
        CurrentPosition = MdigInquire( (MIL_ID)(((long*)UserDataPtr)[0]), M_FOCUS, M_NULL);

      /* Go to next position. */
        MdigControl( (MIL_ID)(((long*)UserDataPtr)[0]), M_FOCUS, (double) position);

      /* Wait for the lens to stop moving before grabbing. */
        PositionDifference = abs(CurrentPosition - position);
        TimeForMovingLens  = 5 * PositionDifference;
        Sleep(TimeForMovingLens);

      /* Increase number of iterations. */
        (((long*)UserDataPtr)[1])++;
        }

    return 0;
}


Example: mgenlc.c

/* File name: mgenlc.c
 * Synopsis:  This program allocates 2 grab buffers on the
 *            unused bands of the Genesis LC display and
 *            grabs in them.
 *            This technique can be used when experiencing
 *            grab over-runs on heavy loaded systems.
 *
 *            When the display is in monochrome mode, it
 *            uses only the blue surface and reserves the
 *            red and green surfaces.  This example shows
 *            how to access this unused memory for grabbing
 *            purposes.
 *            Note: This example will only work with a
 *            monochrome camera.
*/

/* Headers. */
#include <stdio.h>
#include <stdlib.h>
#include <conio.h>
#include <mil.h>

/* Main function. */
void main(void)
{
  MIL_ID   MilApplication;
  MIL_ID   MilSystem     ;
  MIL_ID   MilDigitizer  ;
  MIL_ID   MilDisplay    ;
  MIL_ID   MilImageOnBoard[2];
  MIL_ID   MilImageDisp;
  void     *UnderlayPhysicalAddress = NULL;

  /* Allocations. */
  MappAlloc(M_DEFAULT, &MilApplication);
  MsysAlloc(M_SYSTEM_GENESIS, M_DEF_SYSTEM_NUM, M_SETUP, &MilSystem);
  MdigAlloc(MilSystem, M_DEFAULT, M_DEF_DIGITIZER_FORMAT,
                                  M_DEFAULT, &MilDigitizer);
  MdispAlloc(MilSystem, M_DEFAULT, M_DEF_DISPLAY_FORMAT, M_DEFAULT, &MilDisplay);

  /* Force the display in monochrome mode on the blue plane. */
  MdispControl(MilDisplay, M_COLOR_MODE, M_BLUE);

  /* Allocate a display buffer. */
  MbufAlloc2d(MilSystem,
              (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)),
              (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)),
              8L+M_UNSIGNED,
              M_IMAGE+M_PROC+M_DISP+M_NON_PAGED, &MilImageDisp);
  MbufClear(MilImageDisp, 0);

  /* Inquire the base address of the underlay surface. */
  MsysInquire(MilSystem, M_PHYSICAL_ADDRESS_UNDERLAY, &UnderlayPhysicalAddress);

  /* Create a buffer on the red surface (base address). */
  MbufCreateColor(MilSystem,
                  1,
                  (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)),
                  (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)),
                  8L+M_UNSIGNED,
                  M_IMAGE+M_GRAB+M_PROC+M_ON_BOARD,
                  M_PHYSICAL_ADDRESS+M_PITCH_BYTE,
                  M_DEFAULT,
                  (void *)&(UnderlayPhysicalAddress),
                  &MilImageOnBoard[0]);

  /* Move to the green plane (base address+2MEG). */
  UnderlayPhysicalAddress = ((unsigned long) UnderlayPhysicalAddress) + 0x200000;

  MbufCreateColor(MilSystem,
                  1,
                  (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)),
                  (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)),
                  8L+M_UNSIGNED,
                  M_IMAGE+M_GRAB+M_PROC+M_ON_BOARD,
                  M_PHYSICAL_ADDRESS+M_PITCH_BYTE,
                  M_DEFAULT,
                  (void *)&(UnderlayPhysicalAddress),
                  &MilImageOnBoard[1]);

  /* Enable bus master copies from the Genesis to the Host. */
  MsysControl(MilSystem, M_BUS_MASTER_COPY_TO_HOST, M_ENABLE);

  /* Display the buffer. */
  MdispSelect(MilDisplay, MilImageDisp);

  printf("Press enter to grab into the first buffer\n");
  getchar();

  /* Grab and copy to the Host. */
  MdigGrab(MilDigitizer, MilImageOnBoard[0]);
  MbufCopy(MilImageOnBoard[0], MilImageDisp);

  printf("Press enter to grab into the second buffer\n");
  getchar();

  /* Grab and copy to the Host. */
  MdigGrab(MilDigitizer, MilImageOnBoard[1]);
  MbufCopy(MilImageOnBoard[1], MilImageDisp);

  getchar();

  /* Free allocations. */
  MbufFree(MilImageOnBoard[0]);
  MbufFree(MilImageOnBoard[1]);
  MbufFree(MilImageDisp);
  MdispFree(MilDisplay);
  MdigFree(MilDigitizer);
  MsysFree(MilSystem);
  MappFree(MilApplication);
}


Example: mgrabbayer.c

/********************************************************************************/
/*
 * File name: MDigGraBayerb.c
 *
 * Synopsis:   The following example shows how to color balance an image from
 *             a bayer camera. Depending on the lighting conditions of the
 *             subject (i.e. color temperature), converted bayer images will
 *             need to be color balanced or white balanced to accurately
 *             reproduce color. MIL includes mechanisms to compute
 *             the appropriate white balancing coefficients for converting a
 *             raw bayer image into a color image. These mechanisms rely on using
 *             a test image for computing the bayer coefficients. Ideally, the
 *             test image has a consistent neutral gray background and is free
 *             of any saturated pixels. Saturated pixels in a test image will
 *             always lead to an invalid color correction.
 *             Please consult "Correcting the white balance of your Bayer images"
 *             subsection in the MIL user guide.
 */
#include <mil.h>
#include <conio.h>

void OverlayDraw(MIL_ID MilDisplay, long *SizeX, long *SizeY, long *OffsetX, long *OffsetY);

void main(void)
{
   MIL_ID MilApplication,  /* Application identifier.  */
          MilSystem,       /* System identifier.       */
          MilDisplay,      /* Display identifier.      */
          MilDigitizer,    /* Digitizer identifier.    */
          MilRawBayer,     /* Buffer used to grab raw bayer data and from which to extract white balancing information. */
          MilRawChil,      /* Region of raw buffer used for white balancing. */
          MilWBCoeff,      /* Buffer in which the white balancing coefficients will be stored. */
          MilImage;        /* Image buffer identifier. */
   long BayerPattern,      /* Bayer pattern set in the DCF. */
        SizeX,
        SizeY,
        OffsetX,
        OffsetY;
   float Coefficients[3] = {0.0};

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                             &MilDisplay, &MilDigitizer, &MilImage);

   /* Verify that the DCF is bayer. */
   MdigInquire(MilDigitizer, M_BAYER_PATTERN, &BayerPattern);
   if(BayerPattern == M_NULL)
      {
      printf("You must have a bayer camera and a bayer enabled DCF to run this example\n");
      MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilImage);
      return;
      }

   printf("This example illustrates how to color balance an image from a bayer camera.\n");
   printf("\nPress <Enter> to continue\n\n");
   getch();

   MbufAlloc2d(MilSystem,
               (long)MdigInquire(MilDigitizer, M_SIZE_X, M_NULL),
               (long)MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL),
               8+M_UNSIGNED,
               M_IMAGE+M_GRAB+M_PROC,
               &MilRawBayer);

   printf("Grabbing and converting to color without color balancing.\n");
   printf("Press <Enter> to enable automatic white balancing.\n\n");
   MdigGrabContinuous(MilDigitizer, MilImage);
   getch();

   MdigHalt(MilDigitizer);

   /* Enable automatic white balancing. This control calculates white balancing
      coefficients that will be used to perform color correction on the
      color-converted bayer image. The coefficients are calculated from
      a grabbed image and the entire frame is used to perform the calculations. */
   MdigControl(MilDigitizer, M_WHITE_BALANCE, M_CALCULATE);

   /* Retrieve the calculated coefficients. */
   MdigInquire(MilDigitizer, M_BAYER_COEFFICIENTS_ID, &MilWBCoeff);
   MbufGet(MilWBCoeff, Coefficients);

   printf("Automatic white balancing enabled\n");
   printf("The coefficients have been calculated using the entire image.\n");
   printf("Red: %f  ", Coefficients[0]);
   printf("Green: %f  ", Coefficients[1]);
   printf("Blue: %f  ", Coefficients[2]);

   printf("\n\nPress <Enter> to continue\n\n");

   /* Grab continuously. */
   MdigGrabContinuous(MilDigitizer, MilImage);
   getch();

   /* Highlight a rectangular region that will be used to calculate the white balancing coefficients */
   OverlayDraw(MilDisplay, &SizeX, &SizeY, &OffsetX, &OffsetY);

   printf("Please place a neutral gray object filling the entire rectangle.\n");
   printf("Press <Enter> to perform white balancing using this part of the image.\n\n");
   getch();

   /* Stop displaying the rectangle. */
   MdispControl(MilDisplay, M_OVERLAY_SHOW, M_DISABLE);

   /* Stop the continuous grab. */
   MdigHalt(MilDigitizer);

   /* Grab a raw bayer image. */
   MdigControl(MilDigitizer, M_BAYER_CONVERSION, M_DISABLE);
   MdigGrab(MilDigitizer, MilRawBayer);

   /* Using the rectangular region, compute the new white balancing coefficients. */
   MbufChild2d(MilRawBayer, OffsetX, OffsetY, SizeX, SizeY, &MilRawChil);
   MbufBayer(MilRawChil, MilImage, MilWBCoeff, BayerPattern+M_WHITE_BALANCE_CALCULATE);
   MbufClear(MilImage, 0);

   printf("The newly calculated white balancing coefficients are:\n");
   MbufGet(MilWBCoeff, Coefficients);
   printf("Red: %f  ", Coefficients[0]);
   printf("Green: %f  ", Coefficients[1]);
   printf("Blue: %f  ", Coefficients[2]);

   /* Re-enable the bayer conversion. */
   MdigControl(MilDigitizer, M_BAYER_CONVERSION, M_ENABLE);

   /* Store the new coefficients for the digitizers to use. */
   MdigControl(MilDigitizer, M_BAYER_COEFFICIENTS_ID, MilWBCoeff);

   /* Resume grabbing. */
   MdigGrabContinuous(MilDigitizer, MilImage);

   /* Pause to show the result. */
   printf("\n\nPress <Enter> to stop.\n\n");
   getch();

   /* Pause to show the result. */
   printf("Displaying the last image.\n");
   printf("Press <Enter> to end.\n\n");
   getch();

   MdigHalt(MilDigitizer);

   MbufFree(MilRawChil);
   MbufFree(MilRawBayer);
   MbufFree(MilWBCoeff);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilImage);
}

/* --------------------------------------------------------------- */
/* Name:      OverlayDraw
 * Synopsis:  This function draws annotations in the display overlay.
 */
void OverlayDraw(MIL_ID MilDisplay, long *SizeX, long *SizeY, long *OffsetX, long *OffsetY)
   {
   MIL_ID   MilOverlayImage;
   long     ImageWidth, ImageHeight;

   /* Prepare overlay buffer. */
   /***************************/

   /* Enable display overlay annotations. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);

   /* Inquire the overlay buffer associated with the display. */
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Clear the overlay to transparent. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Disable the overlay display updating to accelerate annotations. */
   MdispControl(MilDisplay, M_OVERLAY_SHOW, M_DISABLE);

   /* Inquire overlay size. */
   ImageWidth  = MbufInquire(MilOverlayImage, M_SIZE_X, M_NULL);
   ImageHeight = MbufInquire(MilOverlayImage, M_SIZE_Y, M_NULL);

   *SizeX   = ImageWidth/5;
   *SizeY   = ImageHeight/5;
   *OffsetX = ImageWidth/2    - (*SizeX/2);
   *OffsetY = ImageHeight/2   - (*SizeY/2);

   if((*OffsetX) & 0x1)
      (*OffsetX)++;
   if((*OffsetY) & 0x1)
      (*OffsetY)++;

   /* Draw MIL overlay annotations. */
   /*********************************/

   /* Set graphic text to transparent background. */
   MgraControl(M_DEFAULT, M_BACKGROUND_MODE, M_TRANSPARENT);

   /* Print a green string in the overlay image buffer. */
   MgraColor(M_DEFAULT, M_COLOR_RED);
   MgraRect(M_DEFAULT, MilOverlayImage, *OffsetX, *OffsetY, (*OffsetX)+(*SizeX), (*OffsetY)+(*SizeY));

   /* Re-enable the overlay display after all annotations are done. */
   MdispControl(MilDisplay, M_OVERLAY_SHOW, M_ENABLE);


Example: mheliosconcurent.c

/************************************************************************************/
/*
 * File name: HelOutOfOrder.c
 *
 * Synopsis: This program shows how to optimize efficiently in the same
 *           thread by using Matrox Helios to best effect.
 */

#include <stdio.h>
#include <mil.h>

#define IMAGE_SIZE  2048

void main(void)
   {
   MIL_ID MilApplication = 0;  /* Application identifier.  */
   MIL_ID MilSystem      = 0;  /* System identifier.       */
   MIL_ID MilDisplay     = 0;  /* Display identifier.      */
   MIL_ID MilDigitizer   = 0;  /* Digitizer identifier.    */

   MIL_ID MilImageOnBoardA  = 0;
   MIL_ID MilImageOnBoardB  = 0;
   MIL_ID MilImageOnBoardC  = 0;
   MIL_ID MilImageOffBoardD = 0;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, &MilDigitizer, M_NULL);

   /* Allocate buffers in the on-board memory of the Matrox Helios. */
   MbufAlloc2d(MilSystem, IMAGE_SIZE, IMAGE_SIZE, 8 + M_UNSIGNED, M_IMAGE +
    M_ON_BOARD + M_PROC + M_GRAB, &MilImageOnBoardA);
   MbufAlloc2d(MilSystem, IMAGE_SIZE, IMAGE_SIZE, 8 + M_UNSIGNED, M_IMAGE +
    M_ON_BOARD + M_PROC + M_GRAB, &MilImageOnBoardB);
   MbufAlloc2d(MilSystem, IMAGE_SIZE, IMAGE_SIZE, 8 + M_UNSIGNED, M_IMAGE +
    M_ON_BOARD + M_PROC + M_GRAB, &MilImageOnBoardC);

   /* Allocate a bufffer in the Host memory, off board. */
   MbufAlloc2d(MilSystem, IMAGE_SIZE, IMAGE_SIZE, 8 + M_UNSIGNED, M_IMAGE +
    M_OFF_BOARD + M_PROC + M_GRAB + M_NON_PAGED + M_DISP, &MilImageOffBoardD);

   /* Clear Buffer */
   MbufClear(MilImageOnBoardA, 0);
   MbufClear(MilImageOnBoardB, 0);
   MbufClear(MilImageOnBoardC, 0);
   MbufClear(MilImageOffBoardD, 0);

   /* Select image to display */
   MdispSelect(MilDisplay, MilImageOffBoardD);

   /* Put digitizer in asynchronous mode. */
   MdigControl(MilDigitizer, M_GRAB_MODE, M_ASYNCHRONOUS_QUEUED);

   printf("Press <Enter> to start.\n");
   getchar();

   /* Start of out of order execution */
   MdigGrab(MilDigitizer, MilImageOnBoardA);

   /* The 3 next operations will be executed in parallel */
   MdigGrab(MilDigitizer, MilImageOnBoardB);
   MimConvolve(MilImageOnBoardA, MilImageOnBoardC, M_EDGE_DETECT+M_OVERSCAN_DISABLE);
   MbufCopy(MilImageOnBoardA, MilImageOffBoardD);

   printf("Press <Enter> to end.\n");
   getchar();

   MbufFree(MilImageOnBoardA);
   MbufFree(MilImageOnBoardB);
   MbufFree(MilImageOnBoardC);
   MbufFree(MilImageOffBoardD);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, M_NULL);


Example: mimconvolve.c

/*****************************************************************************/
/*
 * File name: MImConvolve.c
 *
 * Synopsis:  This program performs a 3x3 convolution using a custom kernel
 *            and calculates the convolution time.
 */
#include <conio.h>
#include <mil.h>

/* Target MIL image specifications. */
#define IMAGE_FILE       M_IMAGE_PATH MIL_TEXT("BaboonMono.mim")
#define ZOOM_VALUE       2

/* Kernel data definition. */
#define KERNEL_WIDTH     3L
#define KERNEL_HEIGHT    3L
#define KERNEL_DEPTH     8L
unsigned char  KernelData[KERNEL_HEIGHT][KERNEL_WIDTH] =
               { {1, 2, 1},
                 {2, 4, 2},
                 {1, 2, 1}
               };

/* Timing loop iterations. */
#define NB_LOOP 100

void main(void)
{
   MIL_ID MilApplication,  /* Application identifier.     */
          MilSystem,       /* System identifier.          */
          MilDisplay,      /* Display identifier.         */
          MilDisplayImage, /* Image buffer identifier.    */
          MilImage,        /* Image buffer identifier.    */
          MilKernel;       /* Custom kernel identifier.   */
   long   n;
   double Time;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                    &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into an automatically allocated image buffers. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);
   MbufRestore(IMAGE_FILE, MilSystem, &MilDisplayImage);

   /* Zoom display to see the result of image processing better. */
   MdispZoom(MilDisplay, ZOOM_VALUE, ZOOM_VALUE);

   /* Display the image buffer. */
   MdispSelect(MilDisplay, MilDisplayImage);

   /* Pause to show the original image. */
   printf("\nIMAGE PROCESSING:\n");
   printf("-----------------\n\n");
   printf("This program performs a convolution on the displayed image.\n");
   printf("It uses a custom smoothing kernel.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Allocate a MIL kernel. */
   MbufAlloc2d(MilSystem, KERNEL_WIDTH, KERNEL_HEIGHT,
               KERNEL_DEPTH+M_UNSIGNED, M_KERNEL, &MilKernel);

   /* Put the custom data in it. */
   MbufPut(MilKernel,KernelData);

   /* Set a normalization (divide) factor to have a kernel with
    * a sum equal to one.
    */
   MbufControlNeighborhood(MilKernel,M_NORMALIZATION_FACTOR,16L);

   /* Convolve the image using the kernel. */
   MimConvolve(MilImage, MilDisplayImage, MilKernel);

   /* Now time the convolution (MimConvolve()):
      Overscan calculation is disabled and a destination image that
      is not displayed is used to have the real convolution time. Also the
      function must be called once before the timing loop for more accurate
      time (dll load, ...).
   */
   MbufControlNeighborhood(MilKernel, M_OVERSCAN, M_DISABLE);
   MimConvolve(MilDisplayImage, MilImage, MilKernel);
   MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);
   for (n= 0; n < NB_LOOP; n++)
         MimConvolve(MilDisplayImage, MilImage, MilKernel);
   MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);

   /* Pause to show the result. */
   printf("Convolve time: %.3f ms.\n", Time*1000/NB_LOOP);
   printf("Press <Enter> to terminate.\n");
   getch();

   /* Free all allocations. */
   MbufFree(MilKernel);
   MbufFree(MilImage);
   MbufFree(MilDisplayImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mimfft.c

/************************************************************************************/
/*
 * File name: MImFFT.c
 *
 * Synopsis:  This program uses the Fast Fourier Transform to filter an image.
 */
#include <mil.h>
#include <math.h>
#include <conio.h>

/* Target image specifications. */
#define NOISY_IMAGE                    M_IMAGE_PATH MIL_TEXT("noise.mim")
#define IMAGE_WIDTH                    256
#define IMAGE_HEIGHT                   256
#define X_NEGATIVE_FREQUENCY_POSITION   63
#define X_POSITIVE_FREQUENCY_POSITION  191
#define Y_FREQUENCY_POSITION           127
#define CIRCLE_WIDTH                     9

void main(void)
{
   MIL_ID MilApplication,   /* Application identifier.                  */
          MilSystem,        /* System identifier.                       */
          MilDisplay,       /* Display identifier.                      */
          MilImage,         /* Image buffer identifier.                 */
          MilOverlayImage,  /* Overlay image buffer identifier.         */
          MilSubImage00,    /* Child buffer identifier.                 */
          MilSubImage01,    /* Child buffer identifier.                 */
          MilSubImage10,    /* Child buffer identifier.                 */
          MilSubImage11,    /* Child buffer identifier.                 */
          MilTransformReal, /* Real part of the transformed image.      */
          MilTransformIm;   /* Imaginary part of the transformed image. */

   float  ZeroVal = 0.0;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay,M_NULL, M_NULL);

   /* Allocate a display buffer and clear it. */
   MbufAlloc2d(MilSystem, IMAGE_WIDTH*2, IMAGE_HEIGHT*2,
               8+M_UNSIGNED, M_IMAGE+M_PROC+M_DISP, &MilImage);
   MbufClear(MilImage, 0L);

   /* Display the image buffer and prepare for overlay annotations. */
   MdispSelect(MilDisplay, MilImage);
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate child buffers in the 4 quadrants of the display image. */
   MbufChild2d(MilImage, 0L, 0L, IMAGE_WIDTH, IMAGE_HEIGHT, &MilSubImage00);
   MbufChild2d(MilImage, IMAGE_WIDTH, 0L,IMAGE_WIDTH, IMAGE_HEIGHT, &MilSubImage01);
   MbufChild2d(MilImage, 0L, IMAGE_HEIGHT, IMAGE_WIDTH, IMAGE_HEIGHT, &MilSubImage10);
   MbufChild2d(MilImage, IMAGE_WIDTH, IMAGE_HEIGHT, IMAGE_WIDTH, IMAGE_HEIGHT, &MilSubImage11);

   /* Allocate processing buffers. */
   MbufAlloc2d(MilSystem, IMAGE_WIDTH, IMAGE_HEIGHT, 32+M_FLOAT, M_IMAGE+M_PROC, &MilTransformReal);
   MbufAlloc2d(MilSystem, IMAGE_WIDTH, IMAGE_HEIGHT, 32+M_FLOAT, M_IMAGE+M_PROC, &MilTransformIm);

   /* Load a noisy image. */
   MbufLoad(NOISY_IMAGE, MilSubImage00);

   /* Print a message on the screen. */
   printf("\nFFT:\n");
   printf("----\n\n");
   printf("The frequency spectrum of a noisy image will be computed to remove the periodic noise.\n");
   printf("Press <Enter> to continue.\n\n");
   getchar();

   /* The image is Fourier transformed to obtain the magnitude of the
      spectrum. This result will be used to design the filter.   */
   MimTransform(MilSubImage00, M_NULL, MilTransformReal, MilTransformIm,
                M_FFT, M_FORWARD+M_CENTER+M_MAGNITUDE+M_LOG_SCALE);
   MbufCopy(MilTransformReal, MilSubImage10);

   /* Draw circles in the overlay around the points of interest. */
   MbufCopy(MilTransformReal, MilSubImage11);
   MgraColor(M_DEFAULT, M_COLOR_YELLOW);
   MgraArc(M_DEFAULT, MilOverlayImage, X_NEGATIVE_FREQUENCY_POSITION,
           Y_FREQUENCY_POSITION+IMAGE_HEIGHT, CIRCLE_WIDTH, CIRCLE_WIDTH, 0, 360);
   MgraArc(M_DEFAULT, MilOverlayImage, X_POSITIVE_FREQUENCY_POSITION,
           Y_FREQUENCY_POSITION+IMAGE_HEIGHT, CIRCLE_WIDTH, CIRCLE_WIDTH, 0, 360);
   MgraArc(M_DEFAULT, MilOverlayImage, X_NEGATIVE_FREQUENCY_POSITION+IMAGE_WIDTH,
           Y_FREQUENCY_POSITION+IMAGE_HEIGHT, CIRCLE_WIDTH, CIRCLE_WIDTH, 0, 360);
   MgraArc(M_DEFAULT, MilOverlayImage, X_POSITIVE_FREQUENCY_POSITION+IMAGE_WIDTH,
           Y_FREQUENCY_POSITION+IMAGE_HEIGHT, CIRCLE_WIDTH, CIRCLE_WIDTH, 0, 360);

   /* Put zero in the spectrum where the noise is located. */
   MbufPut2d(MilSubImage11,   X_NEGATIVE_FREQUENCY_POSITION,
                              Y_FREQUENCY_POSITION, 1, 1, &ZeroVal);
   MbufPut2d(MilSubImage11,   X_POSITIVE_FREQUENCY_POSITION,
                              Y_FREQUENCY_POSITION, 1, 1, &ZeroVal);

   /* Compute the Fast Fourier Transform of the image. */
   MimTransform(MilSubImage00, M_NULL, MilTransformReal,
                MilTransformIm, M_FFT, M_FORWARD+M_CENTER);

   /* Filter the image in the frequency domain. */
   MbufPut2d(MilTransformReal, X_NEGATIVE_FREQUENCY_POSITION,
                               Y_FREQUENCY_POSITION, 1, 1, &ZeroVal);
   MbufPut2d(MilTransformReal, X_POSITIVE_FREQUENCY_POSITION,
                               Y_FREQUENCY_POSITION, 1, 1, &ZeroVal);
   MbufPut2d(MilTransformIm, X_NEGATIVE_FREQUENCY_POSITION,
                             Y_FREQUENCY_POSITION, 1, 1, &ZeroVal);
   MbufPut2d(MilTransformIm, X_POSITIVE_FREQUENCY_POSITION,
                             Y_FREQUENCY_POSITION, 1, 1, &ZeroVal);

   /* Recover the image in the spatial domain. */
   MimTransform(MilTransformReal, MilTransformIm,
                MilSubImage01, M_NULL, M_FFT, M_REVERSE+M_CENTER);

   /* Print a message. */
   printf("The frequency components of the noise are located in the center of the circles.\n");
   printf("The noise was removed by setting these frequency components to zero.\n");
   printf("Press <Enter> to end.\n\n");
   getchar();

   /* Free buffers. */
   MbufFree(MilSubImage00);
   MbufFree(MilSubImage01);
   MbufFree(MilSubImage10);
   MbufFree(MilSubImage11);
   MbufFree(MilImage);
   MbufFree(MilTransformReal);
   MbufFree(MilTransformIm);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mimhistogram.c

/***********************************************************************************/
/*
 * File name: MImHistogram.c
 *
 * Synopsis:  This program loads an image of a tissue sample, calculates its intensity
 *            histogram and draws it.
 */
#include <conio.h>
#include <mil.h>

/* Target MIL image file specifications. */
#define IMAGE_FILE  M_IMAGE_PATH MIL_TEXT("Cell.mim")

/* Number of possible pixel intensities. */
#define HIST_NUM_INTENSITIES  256
#define HIST_SCALE_FACTOR     8
#define HIST_X_POSITION       250
#define HIST_Y_POSITION       450

/* Main function. */
void main(void)
   {
   MIL_ID MilApplication,                   /* Application identifier       */
          MilSystem,                        /* System identifier.           */
          MilDisplay,                       /* Display identifier.          */
          MilImage,                         /* Image buffer identifier.     */
          MilOverlayImage,                  /* Overlay buffer identifier.   */
          HistResult;                       /* Histogram buffer identifier. */
   long   HistValues[HIST_NUM_INTENSITIES]; /* Histogram values.            */
   long   XStart[HIST_NUM_INTENSITIES], YStart[HIST_NUM_INTENSITIES],
          XEnd[HIST_NUM_INTENSITIES],   YEnd[HIST_NUM_INTENSITIES];
   long   AnnotationColor = M_COLOR_RED, i;

   /* Allocate the default system and image buffer. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into an automatically allocated image buffer. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);

   /* Display the image buffer and prepare for overlay annotations. */
   MdispSelect(MilDisplay, MilImage);
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a histogram result buffer. */
   MimAllocResult(MilSystem, HIST_NUM_INTENSITIES, M_HIST_LIST, &HistResult);

   /* Calculate the histogram. */
   MimHistogram(MilImage, HistResult);

   /* Get the results. */
   MimGetResult(HistResult, M_VALUE, HistValues);

   /* Draw the histogram in the overlay. */
   MgraColor(M_DEFAULT, AnnotationColor);
   for(i=0; i<HIST_NUM_INTENSITIES; i++)
      {
      XStart[i] = i+HIST_X_POSITION+1,
      YStart[i] = HIST_Y_POSITION;
      XEnd[i]   = i+HIST_X_POSITION+1,
      YEnd[i] = HIST_Y_POSITION-(HistValues[i]/HIST_SCALE_FACTOR);
      }
   MgraLines(M_DEFAULT, MilOverlayImage, HIST_NUM_INTENSITIES,
                        XStart, YStart, XEnd, YEnd, M_DEFAULT);

   /* Print a message. */
   printf("\nHISTOGRAM:\n");
   printf("----------\n\n");
   printf("The histogram of the image was calculated and drawn.\n");
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free all allocations. */
   MimFree(HistResult);
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mimmorphic.c

/*******************************************************************************/
/* File name: MImMorphic.c
 *
 * Synopsis: This program loads an image of some tissue and then do opening on
 *           it using two methods to show the differences.
 */
#include <mil.h>
#include <conio.h>

/* Target MIL image file specifications. */
#define IMAGE_FILE            M_IMAGE_PATH MIL_TEXT("Cell.mim")
#define IMAGE_WIDTH           240L
#define IMAGE_HEIGHT          240L
#define IMAGE_DEPTH           8L
#define IMAGE_THRESHOLD_VALUE 128L

/* Structuring element information. */
#define STRUCT_ELEM_WIDTH     5L
#define STRUCT_ELEM_HEIGHT    5L
#define STRUCT_ELEM_DEPTH     32L

/* Small particle radius (in pixels). */
#define SMALL_PARTICLE_RADIUS 2L

main(void)
{
   MIL_ID MilApplication, /* Application identifier. */
          MilSystem,    /* System identifier.        */
          MilDisplay,   /* Display identifier.       */
          MilImage,     /* Image buffer identifier.  */
          BinImage,     /* Binary Image buffer identifier.                 */
          MilSubImage0, /* Sub-image buffer identifier for original image. */
          MilSubImage1, /* Sub-image buffer identifier for binarization.   */
          MilSubImage2, /* Sub-image buffer identifier for common open.    */
          MilSubImage3; /* Sub-image buffer identifier for customized Open.*/
   MIL_ID StructElem;   /* Structing element buffer. */

   /* Structuring element data definition. */
   long  StructArray[STRUCT_ELEM_HEIGHT][STRUCT_ELEM_WIDTH]  =
         { {M_DONT_CARE, M_DONT_CARE, 1, M_DONT_CARE, M_DONT_CARE},
           {M_DONT_CARE,           1, 1,           1, M_DONT_CARE},
           {          1,           1, 1,           1,           1},
           {M_DONT_CARE,           1, 1,           1, M_DONT_CARE},
           {M_DONT_CARE, M_DONT_CARE, 1, M_DONT_CARE, M_DONT_CARE}
         };

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Allocate an image buffer, load and displays it. */
   MbufAlloc2d(M_DEFAULT, IMAGE_WIDTH*2, IMAGE_HEIGHT*2, 8+M_UNSIGNED, M_IMAGE+M_PROC+M_DISP, &MilImage);
   MbufClear(MilImage, 0);
   MdispSelect(MilDisplay, MilImage);

   /* Allocate a binary image buffer for fast processing. */
   MbufAlloc2d(M_DEFAULT, IMAGE_WIDTH, IMAGE_HEIGHT, 1+M_UNSIGNED, M_IMAGE+M_PROC, &BinImage);

   /* Define 4 processing buffers in the display buffer, restricting the
    * regions to be processed to the top left corner of the original image.
    */
   MbufChild2d(MilImage, 0L, 0L, IMAGE_WIDTH, IMAGE_HEIGHT, &MilSubImage0);
   MbufChild2d(MilImage, IMAGE_WIDTH, 0L, IMAGE_WIDTH, IMAGE_HEIGHT, &MilSubImage1);
   MbufChild2d(MilImage, 0L, IMAGE_HEIGHT, IMAGE_WIDTH, IMAGE_HEIGHT, &MilSubImage2);
   MbufChild2d(MilImage, IMAGE_WIDTH, IMAGE_HEIGHT, IMAGE_WIDTH, IMAGE_HEIGHT, &MilSubImage3);

   /* Load source image into image buffer for original image. */
   MbufLoad(IMAGE_FILE, MilSubImage0);

   /* Allocate a structuring element. */
   MbufAlloc2d(MilSystem, STRUCT_ELEM_WIDTH, STRUCT_ELEM_HEIGHT,
               STRUCT_ELEM_DEPTH + M_SIGNED, M_STRUCT_ELEMENT, &StructElem);

   /* Load buffer with data. */
   MbufPut2d(StructElem, 0L, 0L, STRUCT_ELEM_WIDTH, STRUCT_ELEM_HEIGHT, StructArray);

   /* Pause to show the original image. */
   printf("\nThis program does the opening of an image using two different\n");
   printf("structuring elements.\nPress <Enter> to continue.\n\n");
   getch();

   /* Smooth the image to remove noise. */
   MimConvolve(MilSubImage0, MilSubImage0, M_SMOOTH);

   /* Binarize the image so that particles are represented in white and
    * the background in black placing result in subimage1 on the display.
    */
   MimBinarize(MilSubImage0, MilSubImage1, M_LESS_OR_EQUAL, IMAGE_THRESHOLD_VALUE, M_NULL);

   /* Copy the binarized image to a binary buffer for fast processing */
   MbufCopy(MilSubImage1, BinImage);

   /* Opening using common method, placing result in subimage2 on the display. */
   MimOpen(BinImage, MilSubImage2, SMALL_PARTICLE_RADIUS, M_BINARY);

   /* Opening (Erode and Dilate) using customized method, placing
    * result in subimage3 on the display.
    */
   MimMorphic(BinImage, BinImage, StructElem, M_ERODE, SMALL_PARTICLE_RADIUS/2, M_BINARY);
   MimMorphic(BinImage, MilSubImage3, StructElem, M_DILATE,  SMALL_PARTICLE_RADIUS/2, M_BINARY);

   /* Pause to show the opened particle(s). */
   printf("The top right image is the binarized source image. When \n");
   printf("opening it using the standard method, the bottom left image \n");
   printf("results, whereas when opening it using the customized method,\n");
   printf("the bottom right image results and best preserves the original\n");
   printf("shape of the objects.\nPress <Enter> to end.\n\n");
   getch();

   /* Free structuring element buffer. */
   MbufFree(StructElem);

   /* Free the allocated buffers. */
   MbufFree(MilSubImage0);
   MbufFree(MilSubImage1);
   MbufFree(MilSubImage2);
   MbufFree(MilSubImage3);
   MbufFree(BinImage);

   /* Release defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, MilImage);
}


Example: mimperimeter.c

/*******************************************************************************/
/*
 * File name: MImPerimeter.c
 *
 * Synopsis:  This program finds the exoskeletons of the  perimeters of
 *            dark objects in an image.
 */
#include <mil.h>
#include <conio.h>

/* Source MIL image file specifications. */
#define IMAGE_FILE             M_IMAGE_PATH MIL_TEXT("cell.mim")
#define IMAGE_WIDTH            512L
#define IMAGE_HEIGHT           480L
#define IMAGE_THRESHOLD_VALUE  128L

/* Small particle radius (in pixels). */
#define SMALL_PARTICLE_RADIUS    2L

main(void)
{
   MIL_ID MilApplication,  /* Application identifier.  */
          MilSystem,       /* System identifier.       */
          MilDisplay,      /* Display identifier.      */
          MilImage,        /* Image buffer identifier. */
          BinImage,        /* Binary image buffer identifier. */
          DilBinImage;     /* Dilated binary image buffer identifier. */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into an image buffer and displays it. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Allocate 2 binary image buffers for fast processing. */
   MbufAlloc2d(M_DEFAULT, IMAGE_WIDTH, IMAGE_HEIGHT, 1+M_UNSIGNED, M_IMAGE+M_PROC, &BinImage);
   MbufAlloc2d(M_DEFAULT, IMAGE_WIDTH, IMAGE_HEIGHT, 1+M_UNSIGNED, M_IMAGE+M_PROC, &DilBinImage);

   /* Pause to show the original image. */
   printf("\nThis program finds the exoskeletons of the particles in the displayed image.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Binarize the image. */
   MimBinarize(MilImage, BinImage, M_LESS_OR_EQUAL, IMAGE_THRESHOLD_VALUE, M_NULL);

   /* Remove small particles. */
   MimOpen(BinImage, BinImage, SMALL_PARTICLE_RADIUS, M_BINARY);

   /* Dilate image (adds one pixel around all objects). */
   MimDilate(BinImage, DilBinImage, 1L, M_BINARY);

   /* XOR the dilated image with the original image. */
   MimArith(BinImage, DilBinImage, BinImage, M_XOR);

   /* Convert the binary image to a visible grayscale image (0-0xFF). */
   MimBinarize(BinImage, MilImage, M_GREATER, 0, M_NULL);

   /* Pause to show the resulting image. */
   printf("Exoskeletons of the object's perimeters are being calculated.\n");
   printf("Press <Enter> to end.\n");
   getch();

   /* Free all allocations. */
   MbufFree(BinImage);
   MbufFree(DilBinImage);
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mimpolar.c

/*****************************************************************************/
/*
 * File name: MImPolar.c
 *
 * Synopsis:  This program uses the polar-to-rectangular transformation
 *            to unroll a string.
 */
#include <mil.h>
#include <conio.h>
#include <math.h>

/* Target image specifications. */
#define IMAGE_FILE              M_IMAGE_PATH MIL_TEXT("Polar.mim")

/* Points used to compute the parameters of the circle. */
#define POINT1_X   147
#define POINT1_Y   359
#define POINT2_X   246
#define POINT2_Y   404
#define POINT3_X   354
#define POINT3_Y   368

/* Polar stripe features. */
#define DELTA_RADIUS  25
#define START_ANGLE   210
#define END_ANGLE     330

/* Utility function prototype. */
void GenerateCircle ( double X1, double Y1, double X2,
                      double Y2, double X3, double Y3,
                      double *CenterX, double *CenterY,
                      double *Radius);

/* Main function. */
void main(void)
{
   MIL_ID MilApplication,     /* Application identifier.        */
          MilSystem,          /* System identifier.             */
          MilDisplay,         /* Display identifier.            */
          MilImage,           /* Image buffer identifier.       */
          MilPolarImage;      /* Destination buffer identifier. */
   double SizeRadius,SizeAngle;
   double CenterX, CenterY, Radius;
   long   OffsetX, OffsetY, SizeX, SizeY;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                             &MilDisplay, M_NULL, M_NULL);

   /* Load the source image and display it. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Calculate the parameters of the circle. */
   GenerateCircle(POINT1_X, POINT1_Y, POINT2_X, POINT2_Y,
                  POINT3_X, POINT3_Y, &CenterX, &CenterY, &Radius);

   /* Get the size of the destination buffer. */
   MimPolarTransform(MilImage, M_NULL, CenterX, CenterY,
                     Radius+DELTA_RADIUS, Radius-DELTA_RADIUS,
                     START_ANGLE, END_ANGLE, M_RECTANGULAR_TO_POLAR,
                     M_NEAREST_NEIGHBOR+M_OVERSCAN_ENABLE,
                     &SizeAngle, &SizeRadius);

   /* Allocate the destination buffer. */
   OffsetX  = (long)((MbufInquire(MilImage, M_SIZE_X, M_NULL)/2) - (SizeAngle/2));
   OffsetY  = 20;
   SizeX    = (long)SizeAngle;
   SizeY    = (long)SizeRadius;
   MbufChild2d(MilImage, OffsetX, OffsetY, SizeX, SizeY, &MilPolarImage);

   /* Print a message. */
   printf("\nPOLAR TRANSFORMATION:\n");
   printf("---------------------\n\n");
   printf("A string will be unrolled using a polar-to-rectangular transformation.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Unroll the string. */
   MimPolarTransform(MilImage, MilPolarImage, CenterX, CenterY,
                     Radius+DELTA_RADIUS, Radius-DELTA_RADIUS,
                     START_ANGLE, END_ANGLE, M_RECTANGULAR_TO_POLAR,
                     M_NEAREST_NEIGHBOR+M_OVERSCAN_ENABLE,
                     &SizeAngle, &SizeRadius);

   /* Print a message on the Host screen. */
   printf("Press <Enter> to end.\n");
   getch();

   /* Free buffers. */
   MbufFree(MilPolarImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, MilImage);
}

/* GenerateCircle() function returns the center and the radius of a circle
   defined by 3 non-collinear points.
*/
void GenerateCircle ( double X1, double Y1, double X2, double Y2, double X3, double Y3,
                                 double *CenterX, double *CenterY, double *Radius)
{
   double Slope1 = 0.0;
   double Slope2 = 0.0;
   double MidPoint1X = 0.0;
   double MidPoint1Y = 0.0;
   double MidPoint2X = 0.0;
   double MidPoint2Y = 0.0;
   double Offset1 = 0.0;
   double Offset2 = 0.0;

   /* Compute the middle points of the two segments. */
   MidPoint1X = (X1+X2)/2;
   MidPoint1Y = (Y1+Y2)/2;
   MidPoint2X = (X2+X3)/2;
   MidPoint2Y = (Y2+Y3)/2;

   /* Compute the slope between points 1 and 2, and between
      points 2 and 3. */
   if (((Y2-Y1) != 0.0) && ((Y3-Y2) != 0.0))
      {
      Slope1 = -(X2-X1)/(Y2-Y1);
      Slope2 = -(X3-X2)/(Y3-Y2);

      Offset1 = MidPoint1Y - Slope1*MidPoint1X;
      Offset2 = MidPoint2Y - Slope2*MidPoint2X;

      *CenterX = (Offset2-Offset1)/(Slope1-Slope2);
      *CenterY = Slope1*(*CenterX) + Offset1;
      }
   else if (((Y2-Y1) == 0.0) && ((Y3-Y2) != 0.0))
      {
      Slope2 = -(X3-X2)/(Y3-Y2);
      Offset2 = MidPoint2Y - Slope2*MidPoint2X;

      *CenterX = MidPoint1X;
      *CenterY = Slope2*(*CenterX) + Offset2;
      }
   else if (((Y2-Y1) != 0.0) && ((Y3-Y2) == 0.0))
      {
      Slope1 = -(X2-X1)/(Y2-Y1);
      Offset1 = MidPoint1Y - Slope1*MidPoint1X;

      *CenterX = MidPoint2X;
      *CenterY = Slope1*(*CenterX) + Offset1;
      }

   /* Compute the radius. */
   *Radius = sqrt(pow(*CenterX-X1,2) + pow(*CenterY-Y1,2));
}


Example: mimprocessing.c

/*****************************************************************************/
/*
 * File name: MImProcessing.c
 *
 * Synopsis:  This program uses different image processing primitives to
 *            determine the number of cell nuclei that are larger than
 *            a certain size in an image of a tissue sample.
 */
#include <mil.h>
#include <conio.h>

/* Target MIL image file specifications. */
#define IMAGE_FILE                     M_IMAGE_PATH MIL_TEXT("Cell.mim")
#define IMAGE_THRESHOLD_VALUE          128L
#define IMAGE_SMALL_PARTICLE_RADIUS    2L

void main(void)
{
   MIL_ID MilApplication,   /* Application identifier.  */
          MilSystem,        /* System identifier.       */
          MilDisplay,       /* Display identifier.      */
          MilImage,         /* Image buffer identifier. */
          MilExtremeResult; /* Extreme result buffer identifier. */
   long   MaxLabelNumber;   /* Highest label value. */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                             &MilDisplay, M_NULL, M_NULL);

   /* Restore source image and display it. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Pause to show the original image. */
   printf("\nIMAGE PROCESSING:\n");
   printf("-----------------\n\n");
   printf("This program counts the number of large particles in the image.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Smooth the image to remove noise. */
   MimConvolve(MilImage, MilImage, M_SMOOTH);

   /* Binarize the image so that particles are represented in white and
      the background in black.
    */
   MimBinarize(MilImage, MilImage, M_LESS_OR_EQUAL, IMAGE_THRESHOLD_VALUE, M_NULL);

   /* Remove small particles. */
   MimOpen(MilImage, MilImage, IMAGE_SMALL_PARTICLE_RADIUS, M_BINARY);

   /* Pause to show the remaining particle(s). */
   printf("These particles have been extracted from the original image.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Label the image. */
   MimLabel(MilImage, MilImage, M_DEFAULT);

   /* The largest label value corresponds to the number of particles in the image. */
   MimAllocResult(MilSystem, 1L, M_EXTREME_LIST, &MilExtremeResult);
   MimFindExtreme(MilImage, MilExtremeResult, M_MAX_VALUE);
   MimGetResult(MilExtremeResult, M_VALUE, &MaxLabelNumber);

   /* Multiply the labeling result to augment the gray level of the particles. */
   MimArith(MilImage, 256L/MaxLabelNumber, MilImage, M_MULT_CONST);

   /* Display the result in pseudo-color. */
   MdispLut(MilDisplay, M_PSEUDO);

   /* Print results. */
   printf("There were %ld large particles in the original image.\n", MaxLabelNumber);
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free all allocations. */
   MimFree(MilExtremeResult);
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mimsegment.c

/*****************************************************************************/
/*
 * File name: MImSegment.c
 *
 * Synopsis:  This program uses the watershed and the edge detection functions
 *            to remove the background of an image with a non-linear lighting.
 *            Then, the watershed and the distance functions are used to separate
 *            the touching objects.
 */
#include <mil.h>
#include <conio.h>

/* Source image specifications. */
#define IMAGE_FILE         M_IMAGE_PATH MIL_TEXT("Pills.mim")

/* Minimal distance and gradient variations for the watershed calculation. */
#define WATERSHED_MINIMAL_GRADIENT_VARIATION       45
#define WATERSHED_MINIMAL_DISTANCE_VARIATION        2

/* Position used to fetch the label of the background. */
#define M_PIXEL_FETCH_POSITION_X                2
#define M_PIXEL_FETCH_POSITION_Y                2

/*  Main function. */
void main(void)
{
   MIL_ID  MilApplication,    /* Application identifier.       */
           MilSystem,         /* System identifier.            */
           MilDisplay,        /* Display identifier.           */
           MilImage,          /* Image buffer identifier.      */
           MilImageWatershed; /* Image buffer identifier.      */
   long    lFetchedValue = 0; /* Label of the background.      */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                             &MilDisplay, M_NULL, M_NULL);

   /* Restore the source image into two automatically allocated
    * image buffers and select one of them to the display.
    */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImageWatershed);
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Pause to show the original image. */
   printf("\nSEGMENTATION:\n");
   printf("-------------\n\n");
   printf("An edge detection followed by a watershed will be used to remove\n");
   printf("the background.\nPress <Enter> to continue.\n\n");
   getch();

   /* Perform a edge detection on the original image. */
   MimEdgeDetect(MilImageWatershed, MilImageWatershed, M_NULL, M_SOBEL,
                 M_REGULAR_EDGE_DETECT, M_NULL);

   /* Find the basins of the edge detected image that have a minimal gray scale
    * variation of WATERSHED_MINIMAL_GRADIENT_VARIATION.
    */
   MimWatershed(MilImageWatershed, M_NULL, MilImageWatershed,
                WATERSHED_MINIMAL_GRADIENT_VARIATION, M_MINIMA_FILL+M_BASIN);

   /* Fetch the label of the background, clip it to zero and clip the other labels to
    * the maximum value of the buffer.
    */
   MbufGet2d(MilImageWatershed, M_PIXEL_FETCH_POSITION_X, M_PIXEL_FETCH_POSITION_Y,
                                                          1, 1, &lFetchedValue);
   MimClip(MilImageWatershed, MilImageWatershed, M_EQUAL, lFetchedValue, 0, 0, 0);
   MimClip(MilImageWatershed, MilImage, M_NOT_EQUAL, 0, 0, 0xFF, 0);

   /* Pause to show the binarized image. */
   printf("A distance transformation followed by a watershed will be used \n");
   printf("to separate the touching pills.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Perform a distance transformation on the binarized image. */
   MimDistance(MilImage, MilImageWatershed, M_CHAMFER_3_4);

   /* Find the watersheds of the image. */
   MimWatershed(MilImageWatershed, M_NULL, MilImageWatershed,
                WATERSHED_MINIMAL_DISTANCE_VARIATION,
                M_STRAIGHT_WATERSHED+M_MAXIMA_FILL+M_SKIP_LAST_LEVEL);

   /* AND the watershed image with the binarized image to separate the touching pills. */
   MimArith(MilImageWatershed, MilImage, MilImage, M_AND);

   /* Pause to show the segmented image. */
   printf("Here are the segmented pills.\n");
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free all allocations. */
   MbufFree(MilImageWatershed);
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mimwarp.c

/*****************************************************************************/
/*
 * File name: MImWarp.c
 *
 * Synopsis:  : This program performs three types of warp transformations.
 *              First the image is stretched according to four specified
 *              reference points. Then it is warped on a sinusoid, and
 *              finally, the program loops while warping the image on a
 *              sphere.
 */
#include <mil.h>
#include <conio.h>
#include <math.h>
#include <malloc.h>

/* Target image specifications. */
#define IMAGE_FILE               M_IMAGE_PATH MIL_TEXT("BaboonMono.mim")
#define FIXED_POINT_PRECISION    M_FIXED_POINT+6L
#define FLOAT_TO_FIXED_POINT(x)  (64L * (x))
#define ROTATION_STEP            2

/* Utility functions. */
void YieldToGUI();
void GenerateSphericLUT(long ImageWidth, long ImageHeight,
                        short *MilLutXPtr, short *MilLutYPtr);

/* Main function. */
/* -------------- */
void main(void)
{
   MIL_ID MilApplication,  /* Application identifier.         */
          MilSystem,       /* System identifier.              */
          MilDisplay,      /* Display identifier.             */
          MilDisplayImage, /* Image buffer identifier.        */
          MilSourceImage,  /* Image buffer identifier.        */
          Mil4CornerArray, /* Coefficients buffer identifier. */
          MilLutX,         /* Lut buffer identifier.          */
          MilLutY,         /* Lut buffer identifier.          */
          ChildWindow;     /* Child Image identifier.         */
   float  FourCornerMatrix[12] = {
          0.0,             /* X coordinate of quadrilateral's 1st corner */
          0.0,             /* Y coordinate of quadrilateral's 1st corner */
          456.0,           /* X coordinate of quadrilateral's 2nd corner */
          62.0,            /* Y coordinate of quadrilateral's 2nd corner */
          333.0,           /* X coordinate of quadrilateral's 3rd corner */
          333.0,           /* Y coordinate of quadrilateral's 3rd corner */
          100.0,           /* X coordinate of quadrilateral's 4th corner */
          500.0,           /* Y coordinate of quadrilateral's 4th corner */
            0.0,           /* X coordinate of rectangle's top-left corner */
            0.0,           /* Y coordinate of rectangle's top-left corner */
          511.0,           /* X coordinate of rectangle's bottom-right corner */
          511.0 };         /* Y coordinate of rectangle's bottom-right corner */
   long   Precision     = FIXED_POINT_PRECISION;
   long   Interpolation = M_NEAREST_NEIGHBOR;
   short *MilLutXPtr,   *MilLutYPtr;
   long   OffsetX       = 0;
   long   ImageWidth, ImageHeight, ImageType, i, j;

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore the source image. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilSourceImage);

   /* Allocate a display buffers and show the source image. */
   MbufAlloc2d(MilSystem, MbufInquire(MilSourceImage, M_SIZE_X, &ImageWidth),
                          MbufInquire(MilSourceImage, M_SIZE_Y, &ImageHeight),
                          MbufInquire(MilSourceImage, M_TYPE,   &ImageType),
                          M_IMAGE+M_PROC+M_DISP, &MilDisplayImage);
   MbufCopy(MilSourceImage, MilDisplayImage);
   MdispSelect(MilDisplay, MilDisplayImage);

   /* Allocate 2 LUT buffers. */
   MbufAlloc2d(MilSystem, ImageWidth, ImageHeight, 16L+M_SIGNED, M_LUT, &MilLutX);
   MbufAlloc2d(MilSystem, ImageWidth, ImageHeight, 16L+M_SIGNED, M_LUT, &MilLutY);

   /* Four-corner LUT warping */
   /*-------------------------*/

   /* Print a message. */
   printf("\nWARPING:\n");
   printf("--------\n\n");
   printf("The image will be warped from an arbitrary quadrilateral to a square.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Allocate the coefficient buffer. */
   MbufAlloc2d(MilSystem, 12L, 1L, 32L+M_FLOAT, M_ARRAY, &Mil4CornerArray);

   /* Put warp values into the coefficient buffer. */
   MbufPut1d(Mil4CornerArray, 0L, 12L, FourCornerMatrix);

   /* Generate LUT buffers. */
   MgenWarpParameter(Mil4CornerArray, MilLutX,   MilLutY,
                     M_WARP_4_CORNER+Precision, M_DEFAULT,
                     0.0, 0.0);

   /* Clear the destination. */
   MbufClear(MilDisplayImage,0);

   /* Warp the image. */
   MimWarp(MilSourceImage, MilDisplayImage, MilLutX, MilLutY, M_WARP_LUT+Precision,
           Interpolation);

   /* Sinusoidal LUT warping */
   /*------------------------*/

   /* Print a message. */
   printf("The image will be warped on two sinusoidal waveforms.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Allocate user-defined LUTs. */
   MilLutXPtr = (short*)malloc(sizeof(short)*ImageHeight*ImageWidth);
   MilLutYPtr = (short*)malloc(sizeof(short)*ImageHeight*ImageWidth);

   /* Fill the LUT with a sinusoidal waveforms with a 6-bit precision.*/
   for (j=0;j<ImageHeight;j++)
      {
      for (i=0;i<ImageWidth;i++)
         {
         MilLutYPtr[i+ (j*ImageWidth)] =
            (short)FLOAT_TO_FIXED_POINT(((j) + (int)((20*sin(0.03*i)))));
         MilLutXPtr[i+ (j*ImageWidth)] =
            (short)FLOAT_TO_FIXED_POINT(((i) + (int)((20*sin(0.03*j)))));
         }
      }

   /* Put the values into the LUT buffers.*/
   MbufPut2d(MilLutX, 0L, 0L, ImageWidth, ImageHeight, MilLutXPtr);
   MbufPut2d(MilLutY, 0L, 0L, ImageWidth, ImageHeight, MilLutYPtr);

   /* Clear the destination. */
   MbufClear(MilDisplayImage,0);

   /* Warp the image. */
   MimWarp(MilSourceImage,MilDisplayImage,MilLutX,MilLutY,M_WARP_LUT +Precision,
           Interpolation);

   /* Continuous spherical LUT warping */
   /*--------------------------------*/

   /* Print a message. */
   printf("The image will be continuously warped on a sphere.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Allocate temporary buffer. */
   MbufFree(MilSourceImage);
   MbufAlloc2d(MilSystem, ImageWidth*2, ImageHeight, ImageType,
                                        M_IMAGE+M_PROC, &MilSourceImage);

   /* Reload the image. */
   MbufLoad(IMAGE_FILE, MilSourceImage);

   /* Fill the LUTs with a sphere pattern with a 6-bit precision.*/
   GenerateSphericLUT(ImageWidth, ImageHeight, MilLutXPtr,MilLutYPtr);
   MbufPut2d(MilLutX, 0L, 0L, ImageWidth, ImageHeight, MilLutXPtr);
   MbufPut2d(MilLutY, 0L, 0L, ImageWidth, ImageHeight, MilLutYPtr);

   /* Duplicate the buffer to allow wrap around in the warping. */
   MbufCopy(MilSourceImage, MilDisplayImage);
   MbufChild2d(MilSourceImage, ImageWidth, 0, ImageWidth, ImageHeight, &ChildWindow);
   MbufCopy(MilDisplayImage, ChildWindow);
   MbufFree(ChildWindow);

   /* Clear the destination. */
   MbufClear(MilDisplayImage,0);

   /* Print a message. */
   printf("Press <Enter> to stop.\n\n");

   /* Warp the image continuously. */
   while (!kbhit())
      {
      /* Create a child in the buffer containing the two images. */
      MbufChild2d(MilSourceImage, OffsetX, 0, ImageWidth, ImageHeight, &ChildWindow);

      /* Warp the child in the window. */
      MimWarp(ChildWindow, MilDisplayImage, MilLutX, MilLutY,
                           M_WARP_LUT+Precision, Interpolation);

      /* Update the offset (shift the window to the right). */
      OffsetX += ROTATION_STEP;

      /* Reset the offset if the child is outside the buffer. */
      if (OffsetX>ImageWidth-1)
         OffsetX = 0;

      /* Free the child. */
      MbufFree(ChildWindow);

      YieldToGUI();
      }
   getch();

   /* Free objects. */
   free(MilLutXPtr);
   free(MilLutYPtr);
   MbufFree(MilLutX);
   MbufFree(MilLutY);
   MbufFree(Mil4CornerArray);
   MbufFree(MilSourceImage);
   MbufFree(MilDisplayImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}

/* Generate two custom LUTs used to map the image on a sphere. */
/* ----------------------------------------------------------- */
void GenerateSphericLUT(long ImageWidth, long ImageHeight,
                        short *MilLutXPtr, short *MilLutYPtr)
{
   int          i, j, k;
   double       utmp, vtmp, tmp;
   short        v;

   /* Set the radius of the sphere */
   double       Radius = 200.0;

   /* Generate the X and Y buffers */
   for (j=0; j < ImageHeight; j++ )
      {
      k = j*ImageWidth;

      /* Check that still in the sphere (in the Y axis). */
      if (fabs( vtmp = ((double)(j - (ImageHeight/2)) / Radius) ) < 1.0)
      {
      /* We scan from top to bottom, so reverse the value obtained above
         and obtain the angle. */
      vtmp = acos( -vtmp );
      if(vtmp == 0.0)
         vtmp=0.0000001;

      /* Compute the position to fetch in the source. */
      v = (short)((vtmp/3.1415926) * (double)(ImageHeight - 1) + 0.5);

      /* Compute the Y coordinate of the sphere. */
      tmp = Radius*sin(vtmp);

      for (i=0; i < ImageWidth; i++ )
         {
         /* Check that still in the sphere. */
         if ( fabs(utmp = ((double)(i - (ImageWidth/2)) / tmp)) < 1.0 )
            {
            utmp = acos( -utmp);

            /* Compute the position to fetch (fold the image in four). */
            MilLutXPtr[i + k] = (short)FLOAT_TO_FIXED_POINT(((utmp/3.1415926) *
                     (double)((ImageWidth/2) - 1) + 0.5));
            MilLutYPtr[i + k] = (short)FLOAT_TO_FIXED_POINT(v);
            }
         else
            {
            /* Default position (fetch outside the buffer to
               activate the clear overscan). */
            MilLutXPtr[i + k] = (short)FLOAT_TO_FIXED_POINT(ImageWidth);
            MilLutYPtr[i + k] = (short)FLOAT_TO_FIXED_POINT(ImageHeight);
            }
         }
      }
        else
      {
      for (i=0; i < ImageWidth ;i++ )
         {
         /* Default position (fetch outside the buffer for clear overscan). */
         MilLutXPtr[i + k] = (short)FLOAT_TO_FIXED_POINT(ImageWidth);
         MilLutYPtr[i + k] = (short)FLOAT_TO_FIXED_POINT(ImageHeight);
         }
      }
   }
}

/* Windows CE GUI Scheduling Adjustment Handling */
/* --------------------------------------------- */
/* NOTE: Under Windows CE, YieldToGUI funtion improves system responsiveness
 *       in case a normal Windows CE console application thread is processing
 *       in a while loop.
 */
void YieldToGUI()
{
   #if M_MIL_USE_CE
   Sleep(0);
   #endif
}


Example: mmeas.c

/*****************************************************************************/
/*
 * File name: MMeas.c
 *
 * Synopsis:  This program consist of 2 examples that use the Measurement module
 *            to calculate the position, width and angle of objects in an image.
 *            The first one measures the position, width and angle of a stripe
 *            in an image, and marks its center and edges. The second one measures
 *            the average position, width and angle of a row of pins on a chip.
 */
#include <conio.h>
#include <mil.h>

/* Example selection. */
#define RUN_SINGLE_MEASUREMENT_EXAMPLE      M_YES
#define RUN_MULTIPLE_MEASUREMENT_EXAMPLE    M_YES

/* Example functions declarations. */
void SingleMeasurementExample(MIL_ID MilSystem, MIL_ID MilDisplay);
void MultipleMeasurementExample(MIL_ID MilSystem, MIL_ID MilDisplay);

/*****************************************************************************
 Main.
 *****************************************************************************/
void main(void)
   {
   MIL_ID MilApplication,     /* Application identifier. */
          MilSystem,          /* System Identifier.      */
          MilDisplay;         /* Display identifier.     */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Print module name. */
   printf("\nMEASUREMENT MODULE:\n");
   printf("-------------------\n\n");

   #if (RUN_SINGLE_MEASUREMENT_EXAMPLE)
   SingleMeasurementExample(MilSystem, MilDisplay);
   #endif

   #if (RUN_MULTIPLE_MEASUREMENT_EXAMPLE)
   MultipleMeasurementExample(MilSystem, MilDisplay);
   #endif

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   }

/*****************************************************************************
 Single measurement example.
 *****************************************************************************/

/* Source MIL image file specification. */
#define MEAS_IMAGE_FILE        M_IMAGE_PATH MIL_TEXT("Lead.mim")

/* Processing region specification. */
#define MEAS_BOX_WIDTH         128
#define MEAS_BOX_HEIGHT        100
#define MEAS_BOX_POS_X         166
#define MEAS_BOX_POS_Y         130

/* Target stripe typical specifications. */
#define STRIPE_POLARITY_LEFT   M_POSITIVE
#define STRIPE_POLARITY_RIGHT  M_NEGATIVE
#define STRIPE_WIDTH           45L
#define STRIPE_WIDTH_VARIATION 10L

void SingleMeasurementExample(MIL_ID MilSystem, MIL_ID MilDisplay)
   {
   MIL_ID MilImage,                     /* Image buffer identifier. */
          MilOverlayImage,              /* Overlay image.           */
          StripeMarker;                 /* Stripe marker identifier.*/
   double StripeCenterX,                /* Stripe X center position.*/
          StripeCenterY,                /* Stripe Y center position.*/
          StripeWidth,                  /* Stripe width.            */
          StripeAngle;                  /* Stripe angle.            */
   long   CrossColor = M_COLOR_YELLOW,  /* Cross drawing color.        */
          BoxColor   = M_COLOR_RED;     /* Box drawing color.       */

   /* Restore and display the source image. */
   MbufRestore(MEAS_IMAGE_FILE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Prepare for overlay annotation. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a stripe marker. */
   MmeasAllocMarker(MilSystem, M_STRIPE, M_DEFAULT, &StripeMarker);

   /* Specify the stripe characteristics. */
   MmeasSetMarker(StripeMarker, M_POLARITY, STRIPE_POLARITY_LEFT, STRIPE_POLARITY_RIGHT);
   MmeasSetMarker(StripeMarker, M_WIDTH, STRIPE_WIDTH, M_NULL);
   MmeasSetMarker(StripeMarker, M_WIDTH_VARIATION, STRIPE_WIDTH_VARIATION, M_NULL);
   MmeasSetMarker(StripeMarker, M_BOX_ANGLE_MODE, M_ENABLE, M_NULL);

   /* Specify the search box size and position. */
   MmeasSetMarker(StripeMarker, M_BOX_ORIGIN, MEAS_BOX_POS_X, MEAS_BOX_POS_Y);
   MmeasSetMarker(StripeMarker, M_BOX_SIZE,   MEAS_BOX_WIDTH, MEAS_BOX_HEIGHT);

   /* Draw the contour of the measurement box. */
   MgraColor(M_DEFAULT, BoxColor);
   MmeasDraw(M_DEFAULT, StripeMarker, MilOverlayImage, M_DRAW_BOX, M_DEFAULT, M_MARKER);

   /* Pause to show the original image. */
   printf("Position, width and angle of the stripe in the highlighted box\n");
   printf("will be calculated and the center and edges will be marked.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Find the stripe and measure its width and angle. */
   MmeasFindMarker(M_DEFAULT, MilImage , StripeMarker, M_DEFAULT);

   /* Get the stripe position, width and angle. */
   MmeasGetResult(StripeMarker, M_POSITION, &StripeCenterX, &StripeCenterY);
   MmeasGetResult(StripeMarker, M_WIDTH,    &StripeWidth, M_NULL);
   MmeasGetResult(StripeMarker, M_ANGLE,    &StripeAngle, M_NULL);

   /* Draw the contour of the found measurement box. */
   MgraColor(M_DEFAULT, BoxColor);
   MmeasDraw(M_DEFAULT, StripeMarker, MilOverlayImage, M_DRAW_BOX, M_DEFAULT, M_RESULT);

   /* Draw a cross on the center, left edge and right edge of the found stripe. */
   MgraColor(M_DEFAULT, CrossColor);
   MmeasDraw(M_DEFAULT, StripeMarker, MilOverlayImage, M_DRAW_POSITION, M_DEFAULT, M_RESULT);
   MmeasDraw(M_DEFAULT, StripeMarker, MilOverlayImage,
             M_DRAW_POSITION+M_EDGE_FIRST+M_EDGE_SECOND, M_DEFAULT, M_RESULT);

   /* Print the result. */
   printf("The stripe in the image is at position %.2f,%.2f and\n",
                                         StripeCenterX, StripeCenterY);
   printf("is %.2f pixels wide with an angle of %.2f degrees.\n",
                                         StripeWidth, StripeAngle);
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Free all allocations. */
   MmeasFree(StripeMarker);
   MbufFree(MilImage);
   }

/*****************************************************************************
 Multiple measurement example.
 *****************************************************************************/

/* Source MIL image file specification. */
#define MULT_MEAS_IMAGE_FILE     M_IMAGE_PATH MIL_TEXT("Chip.mim")

/* Processing region specification. */
#define MULT_MEAS_BOX_WIDTH      230
#define MULT_MEAS_BOX_HEIGHT     7
#define MULT_MEAS_BOX_POS_X      220
#define MULT_MEAS_BOX_POS_Y      171

/* Target stripe specifications. */
#define MULT_STRIPES_ORIENTATION      M_VERTICAL
#define MULT_STRIPES_POLARITY_LEFT    M_POSITIVE
#define MULT_STRIPES_POLARITY_RIGHT   M_NEGATIVE
#define MULT_STRIPES_NUMBER           12

void MultipleMeasurementExample(MIL_ID MilSystem, MIL_ID MilDisplay)
{
   MIL_ID MilImage,                    /* Image buffer identifier.  */
          MilOverlayImage,             /* Overlay image.            */
          StripeMarker;                /* Stripe marker identifier. */
   double MeanAngle,                   /* Stripe mean angle.        */
          MeanWidth,                   /* Stripe mean width.        */
          MeanSpacing;                 /* Stripe mean spacing.      */
   long   CrossColor = M_COLOR_YELLOW, /* Cross drawing color.      */
          BoxColor   = M_COLOR_RED;    /* Box drawing color.        */

   /* Restore and display the source image. */
   MbufRestore(MULT_MEAS_IMAGE_FILE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Prepare for overlay annotation. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a stripe marker. */
   MmeasAllocMarker(MilSystem, M_STRIPE, M_DEFAULT, &StripeMarker);

   /* Specify the stripe characteristics. */
   MmeasSetMarker(StripeMarker, M_NUMBER, MULT_STRIPES_NUMBER, M_NULL);
   MmeasSetMarker(StripeMarker, M_POLARITY, MULT_STRIPES_POLARITY_LEFT,
                                            MULT_STRIPES_POLARITY_RIGHT);
   MmeasSetMarker(StripeMarker, M_ORIENTATION, MULT_STRIPES_ORIENTATION, M_NULL);

   /* Specify the measurement box size and position. */
   MmeasSetMarker(StripeMarker, M_BOX_ORIGIN, MULT_MEAS_BOX_POS_X, MULT_MEAS_BOX_POS_Y);
   MmeasSetMarker(StripeMarker, M_BOX_SIZE,   MULT_MEAS_BOX_WIDTH, MULT_MEAS_BOX_HEIGHT);

   /* Draw the contour of the measurement box. */
   MgraColor(M_DEFAULT, BoxColor);
   MmeasDraw(M_DEFAULT, StripeMarker, MilOverlayImage, M_DRAW_BOX, M_DEFAULT, M_MARKER);

   /* Pause to show the original image. */
   printf("The position and angle of a row of pins on a chip will be calculated.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Find the stripe and measure its width and angle. */
   MmeasFindMarker(M_DEFAULT, MilImage, StripeMarker, M_POSITION + M_ANGLE + M_WIDTH);

   /* Draw the contour of the measurement box. */
   MgraColor(M_DEFAULT, BoxColor);
   MmeasDraw(M_DEFAULT, StripeMarker, MilOverlayImage, M_DRAW_BOX, M_DEFAULT, M_RESULT);

   /* Draw a cross at the center of each stripe found. */
   MgraColor(M_DEFAULT, CrossColor);
   MmeasDraw(M_DEFAULT, StripeMarker, MilOverlayImage, M_DRAW_POSITION, M_ALL, M_RESULT);

   /* Get the stripe's width, angle and spacing. */
   MmeasGetResult(StripeMarker, M_ANGLE +   M_MEAN, &MeanAngle,   M_NULL);
   MmeasGetResult(StripeMarker, M_WIDTH +   M_MEAN, &MeanWidth,   M_NULL);
   MmeasGetResult(StripeMarker, M_SPACING + M_MEAN, &MeanSpacing, M_NULL);

   /* Print the results. */
   printf("The center and angle of each pin have been marked.\n\n");
   printf("The statistics for the pins are:\n");
   printf("Average angle   : %5.2f\n", MeanAngle);
   printf("Average width   : %5.2f\n", MeanWidth);
   printf("Average spacing : %5.2f\n\n", MeanSpacing);
   printf("Press <Enter> to end.\n");
   getch();

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Free all allocations. */
   MmeasFree(StripeMarker);
   MbufFree(MilImage);


Example: mmet2dig.c

/* File name: mmet2dig.c
 * Synopsis:  This program allocates 2 grab buffers on the
 *            on-board memory of the meteor2/Dig and then
 *            grabs in them.
 *            The data is then transferred to the HOST using
 *            the bus-master copy.
 *
 *            This technique can be used when experiencing
 *            grab overruns on heavily loaded systems.
 *
 /

/* Headers. */
#include <stdio.h>
#include <stdlib.h>
#include <conio.h>
#include <mil.h>

/* Main function. */
void main(void)
{
  MIL_ID   MilApplication;
  MIL_ID   MilSystem     ;
  MIL_ID   MilDigitizer  ;
  MIL_ID   MilDisplay    ;
  MIL_ID   MilImageOnBoard[2];
  MIL_ID   MilImageDisp;

  /* Allocations. */
  MappAlloc(M_DEFAULT, &MilApplication);
  MsysAlloc(M_SYSTEM_METEOR_II_DIG, M_DEF_SYSTEM_NUM, M_SETUP, &MilSystem);
  MdigAlloc(MilSystem, M_DEFAULT, M_DEF_DIGITIZER_FORMAT,
                                  M_DEFAULT, &MilDigitizer);
  MdispAlloc(MilSystem, M_DEFAULT, M_DEF_DISPLAY_FORMAT, M_DEFAULT, &MilDisplay);

  /* Allocate a display buffer. */
  MbufAlloc2d(MilSystem,
              (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)),
              (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)),
              8L+M_UNSIGNED,
              M_IMAGE+M_PROC+M_DISP+M_NON_PAGED+M_GRAB, &MilImageDisp);
  MbufClear(MilImageDisp, 0);

  /* Allocate 2 grab buffers on the on-board memory of the board. */
  MbufAlloc2d(MilSystem,
              (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)),
              (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)),
              8L+M_UNSIGNED,
              M_IMAGE+M_GRAB+M_PROC+M_ON_BOARD, &MilImageOnBoard[0]);

  MbufAlloc2d(MilSystem,
              (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)),
              (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)),
              8L+M_UNSIGNED,
              M_IMAGE+M_GRAB+M_PROC+M_ON_BOARD, &MilImageOnBoard[1]);

  /* Enable bus master copying from the Meteor2 to the Host. */
  MsysControl(MilSystem, M_BUS_MASTER_COPY_TO_HOST, M_ENABLE);

  /* Display the buffer. */
  MdispSelect(MilDisplay, MilImageDisp);

  printf("Press enter to grab into the first buffer\n");
  getchar();

  /* Grab and copy to the Host. */
  MdigGrab(MilDigitizer, MilImageOnBoard[0]);
  MbufCopy(MilImageOnBoard[0], MilImageDisp);

  printf("Press enter to grab into the second buffer\n");
  getchar();

  /* Grab and copy to the Host. */
  MdigGrab(MilDigitizer, MilImageOnBoard[1]);
  MbufCopy(MilImageOnBoard[1], MilImageDisp);

  getchar();

  /* Free allocations. */
  MbufFree(MilImageOnBoard[0]);
  MbufFree(MilImageOnBoard[1]);
  MbufFree(MilImageDisp);
  MdispFree(MilDisplay);
  MdigFree(MilDigitizer);
  MsysFree(MilSystem);
  MappFree(MilApplication);
}


Example: mmod.c

/*************************************************************************************/
/*
 * File name: MMod.c
 *
 * Synopsis:  This program uses the Geometric Model Finder module to define geometric
 *            models and searches for these models in a target image. A simple single model
 *            example (1 model, 1 occurrence, good search conditions) is presented first,
 *            followed by a more complex example (multiple models, multiple occurrences in a
 *            complex scene with bad search conditions).
 */
#include <mil.h>
#include <conio.h>

/* Example functions declarations. */
void SingleModelExample(MIL_ID MilSystem, MIL_ID MilDisplay);
void MultipleModelsExample(MIL_ID MilSystem, MIL_ID MilDisplay);

/*****************************************************************************/
/* Main.
******************************************************************************/
void main(void)
   {
   MIL_ID MilApplication,     /* Application identifier. */
          MilSystem,          /* System Identifier.      */
          MilDisplay;         /* Display identifier.     */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Run single model example. */
   SingleModelExample(MilSystem, MilDisplay);

   /* Run multiple model example. */
   MultipleModelsExample(MilSystem, MilDisplay);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   }

/*****************************************************************************/
/* Single model example. */

/* Source MIL image file specifications. */
#define SINGLE_MODEL_IMAGE          M_IMAGE_PATH MIL_TEXT("SingleModel.mim")

/* Target MIL image file specifications. */
#define SINGLE_MODEL_TARGET_IMAGE   M_IMAGE_PATH MIL_TEXT("SingleTarget.mim")

/* Search speed: M_VERY_HIGH for faster search, M_MEDIUM for precision and robustness. */
#define SINGLE_MODEL_SEARCH_SPEED   M_VERY_HIGH

/* Model specifications. */
#define MODEL_OFFSETX               176L
#define MODEL_OFFSETY               136L
#define MODEL_SIZEX                 128L
#define MODEL_SIZEY                 128L
#define MODEL_MAX_OCCURRENCES       16L

void SingleModelExample(MIL_ID MilSystem, MIL_ID MilDisplay)
   {
   MIL_ID MilImage,                         /* Image buffer identifier.*/
          MilOverlayImage;                  /* Overlay image.          */
   MIL_ID MilSearchContext,                 /* Search context          */
          MilResult;                        /* Result identifier.      */
   long   Model[MODEL_MAX_OCCURRENCES],     /* Model index.            */
          ModelDrawColor = M_COLOR_RED;     /* Model draw color.       */
   long   NumResults  = 0L;                 /* Number of results found.*/
   double Score[MODEL_MAX_OCCURRENCES],     /* Model correlation score.*/
          XPosition[MODEL_MAX_OCCURRENCES], /* Model X position.       */
          YPosition[MODEL_MAX_OCCURRENCES], /* Model Y position.       */
          Angle[MODEL_MAX_OCCURRENCES],     /* Model occurrence angle. */
          Scale[MODEL_MAX_OCCURRENCES],     /* Model occurrence scale. */
          Time = 0.0;                       /* Bench variable.         */
   int    i;                                /* Loop variable.          */

   /* Restore the model image and display it */
   MbufRestore(SINGLE_MODEL_IMAGE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Prepare for overlay annotation. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a Geometric Model Finder context. */
   MmodAlloc(MilSystem, M_GEOMETRIC, M_DEFAULT, &MilSearchContext);

   /* Allocate a result buffer. */
   MmodAllocResult(MilSystem, M_DEFAULT, &MilResult);

   /* Define the model. */
   MmodDefine(MilSearchContext, M_IMAGE, MilImage,
              MODEL_OFFSETX, MODEL_OFFSETY, MODEL_SIZEX, MODEL_SIZEY);

   /* Set the search speed. */
   MmodControl(MilSearchContext, M_CONTEXT, M_SPEED, SINGLE_MODEL_SEARCH_SPEED);

   /* Preprocess the search context. */
   MmodPreprocess(MilSearchContext, M_DEFAULT);

   /* Draw box and position it in the source image to show the model. */
   MgraColor(M_DEFAULT, ModelDrawColor);
   MmodDraw(M_DEFAULT, MilSearchContext, MilOverlayImage,
            M_DRAW_BOX+M_DRAW_POSITION, 0, M_ORIGINAL);

   /* Pause to show the model. */
   printf("\nGEOMETRIC MODEL FINDER:\n");
   printf("-----------------------\n\n");
   printf("A model context was defined with the model in the displayed image.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Load the single model target image. */
   MbufLoad(SINGLE_MODEL_TARGET_IMAGE, MilImage);

   /* Dummy first find operation for better function timing accuracy (model cache effet,...). */
   MmodFind(MilSearchContext, MilImage, MilResult);

   /* Reset the timer. */
   MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

   /* Find the model. */
   MmodFind(MilSearchContext, MilImage, MilResult);

   /* Read the find time. */
   MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);

   /* Get the number of models found. */
   MmodGetResult(MilResult, M_DEFAULT, M_NUMBER+M_TYPE_LONG, &NumResults);

   /* If a model was found above the acceptance threshold. */
   if ( (NumResults >= 1) && (NumResults <= MODEL_MAX_OCCURRENCES) )
      {
      /* Get the results of the single model. */
      MmodGetResult(MilResult, M_DEFAULT, M_INDEX+M_TYPE_LONG, Model);
      MmodGetResult(MilResult, M_DEFAULT, M_POSITION_X, XPosition);
      MmodGetResult(MilResult, M_DEFAULT, M_POSITION_Y, YPosition);
      MmodGetResult(MilResult, M_DEFAULT, M_ANGLE, Angle);
      MmodGetResult(MilResult, M_DEFAULT, M_SCALE, Scale);
      MmodGetResult(MilResult, M_DEFAULT, M_SCORE, Score);

      /* Print the results for each model found. */
      printf("The model was found in the target image:\n\n");
      printf("Result   Model   X Position   Y Position   Angle   Scale   Score\n\n");
      for (i=0; i<NumResults; i++)
         {
         printf("%-9d%-8d%-13.2f%-13.2f%-8.2f%-8.2f%-5.2f%%\n",
               i, Model[i], XPosition[i], YPosition[i], Angle[i], Scale[i], Score[i]);
         }
      printf("\nThe search time is %.1f ms\n\n", Time*1000.0);

      /* Draw edges, position and box over the occurrences that were found. */
      for (i=0; i<NumResults; i++)
         {
         MgraColor(M_DEFAULT, ModelDrawColor);
         MmodDraw(M_DEFAULT,  MilResult, MilOverlayImage,
                  M_DRAW_EDGES+M_DRAW_BOX+M_DRAW_POSITION, i, M_DEFAULT);
         }
      }
   else
      {
      printf("The model was not found or the number of models found is greater than\n");
      printf("the specified maximum number of occurrence !\n\n");
      }

   /* Wait for a key to be pressed. */
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Free MIL objects. */
   MbufFree(MilImage);
   MmodFree(MilSearchContext);
   MmodFree(MilResult);
   }

/*****************************************************************************
/* Multiple models example. */

/* Source MIL image file specifications. */
#define MULTI_MODELS_IMAGE          M_IMAGE_PATH MIL_TEXT("MultipleModel.mim")

/* Target MIL image file specifications. */
#define MULTI_MODELS_TARGET_IMAGE   M_IMAGE_PATH MIL_TEXT("MultipleTarget.mim")

/* Search speed:  M_VERY_HIGH for faster search, M_MEDIUM for precision and robustness. */
#define MULTI_MODELS_SEARCH_SPEED   M_VERY_HIGH

/* Number of models. */
#define NUMBER_OF_MODELS            3L
#define MODELS_MAX_OCCURRENCES     16L

/* Model 1 specifications. */
#define MODEL0_OFFSETX              34L
#define MODEL0_OFFSETY              93L
#define MODEL0_SIZEX                214L
#define MODEL0_SIZEY                76L
#define MODEL0_DRAW_COLOR           M_COLOR_RED

/* Model 2 specifications. */
#define MODEL1_OFFSETX              73L
#define MODEL1_OFFSETY              232L
#define MODEL1_SIZEX                150L
#define MODEL1_SIZEY                154L
#define MODEL1_REFERENCEX           23L
#define MODEL1_REFERENCEY           127L
#define MODEL1_DRAW_COLOR           M_COLOR_GREEN

/* Model 3 specifications. */
#define MODEL2_OFFSETX              308L
#define MODEL2_OFFSETY              39L
#define MODEL2_SIZEX                175L
#define MODEL2_SIZEY                357L
#define MODEL2_REFERENCEX           62L
#define MODEL2_REFERENCEY           150L
#define MODEL2_DRAW_COLOR           M_COLOR_BLUE

/* Models array specifications. */
#define MODELS_ARRAY_SIZE           3L
#define MODELS_OFFSETX              {MODEL0_OFFSETX, MODEL1_OFFSETX, MODEL2_OFFSETX}
#define MODELS_OFFSETY              {MODEL0_OFFSETY, MODEL1_OFFSETY, MODEL2_OFFSETY}
#define MODELS_SIZEX                {MODEL0_SIZEX, MODEL1_SIZEX, MODEL2_SIZEX}
#define MODELS_SIZEY                {MODEL0_SIZEY, MODEL1_SIZEY, MODEL2_SIZEY}
#define MODELS_DRAW_COLOR           {MODEL0_DRAW_COLOR, MODEL1_DRAW_COLOR, MODEL2_DRAW_COLOR}

void MultipleModelsExample(MIL_ID MilSystem, MIL_ID MilDisplay)
   {
   MIL_ID MilImage,                                             /* Image buffer identifier. */
          MilOverlayImage;                                      /* Overlay image.           */
   MIL_ID MilSearchContext,                                     /* Search context           */
          MilResult;                                            /* Result identifier.       */
   long   Models[MODELS_MAX_OCCURRENCES],                       /* Model indices.           */
          ModelsOffsetX[MODELS_ARRAY_SIZE] = MODELS_OFFSETX,    /* Model X offsets array.   */
          ModelsOffsetY[MODELS_ARRAY_SIZE] = MODELS_OFFSETY,    /* Model Y offsets array.   */
          ModelsSizeX[MODELS_ARRAY_SIZE]   = MODELS_SIZEX,      /* Model X sizes array.     */
          ModelsSizeY[MODELS_ARRAY_SIZE]   = MODELS_SIZEY;      /* Model Y sizes array.     */
   long   ModelsDrawColor[MODELS_ARRAY_SIZE]=MODELS_DRAW_COLOR, /* Model drawing colors.    */
          NumResults  = 0L;                                     /* Number of results found. */
   double Score[MODELS_MAX_OCCURRENCES],                        /* Model correlation scores.*/
          XPosition[MODELS_MAX_OCCURRENCES],                    /* Model X positions.       */
          YPosition[MODELS_MAX_OCCURRENCES],                    /* Model Y positions.       */
          Angle[MODELS_MAX_OCCURRENCES],                        /* Model occurrence angles. */
          Scale[MODELS_MAX_OCCURRENCES],                        /* Model occurrence scales. */
          Time = 0.0;                                           /* Time variable.           */
   int    i;                                                    /* Loop variable            */

   /* Restore the model image and display it. */
   MbufRestore(MULTI_MODELS_IMAGE, MilSystem, &MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Prepare for overlay annotation. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a geometric model finder. */
   MmodAlloc(MilSystem, M_GEOMETRIC, M_DEFAULT, &MilSearchContext);

   /* Allocate a result buffer. */
   MmodAllocResult(MilSystem, M_DEFAULT, &MilResult);

   /* Define the models. */
   for (i=0; i<NUMBER_OF_MODELS; i++)
      {
      MmodDefine(MilSearchContext, M_IMAGE, MilImage,
                 ModelsOffsetX[i], ModelsOffsetY[i], ModelsSizeX[i], ModelsSizeY[i]);
      }

   /* Set the desired search speed. */
   MmodControl(MilSearchContext, M_CONTEXT, M_SPEED, MULTI_MODELS_SEARCH_SPEED);

   /* Increase the smoothness for the edge extraction in the search context. */
   MmodControl(MilSearchContext, M_CONTEXT, M_SMOOTHNESS, 75);

   /* Modify the acceptance and the certainty for all the models that were defined. */
   MmodControl(MilSearchContext, M_DEFAULT, M_ACCEPTANCE, 40);
   MmodControl(MilSearchContext, M_DEFAULT, M_CERTAINTY,  60);

   /* Set the number of occurrences to 2 for all the models that were defined. */
   MmodControl(MilSearchContext, M_DEFAULT, M_NUMBER, 2);

   #if (NUMBER_OF_MODELS>1)
   /* Change the reference point of the second model. */
   MmodControl(MilSearchContext, 1, M_REFERENCE_X, MODEL1_REFERENCEX);
   MmodControl(MilSearchContext, 1, M_REFERENCE_Y, MODEL1_REFERENCEY);

   #if (NUMBER_OF_MODELS>2)
   /* Change the reference point of the third model. */
   MmodControl(MilSearchContext, 2, M_REFERENCE_X, MODEL2_REFERENCEX);
   MmodControl(MilSearchContext, 2, M_REFERENCE_Y, MODEL2_REFERENCEY);
   #endif
   #endif

   /* Preprocess the search context. */
   MmodPreprocess(MilSearchContext, M_DEFAULT);

   /* Draw boxes and positions in the source image to identify the models. */
   for (i=0; i<NUMBER_OF_MODELS; i++)
      {
      MgraColor(M_DEFAULT, ModelsDrawColor[i]);
      MmodDraw( M_DEFAULT, MilSearchContext, MilOverlayImage,
                M_DRAW_BOX+M_DRAW_POSITION, i, M_ORIGINAL);
      }

   /* Pause to show the models. */
   printf("A model context was defined with the models in the displayed image.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Load the complex target image. */
   MbufLoad(MULTI_MODELS_TARGET_IMAGE, MilImage);

   /* Dummy first find operation for better function timing accuracy (model cache effet,...). */
   MmodFind(MilSearchContext, MilImage, MilResult);

   /* Reset the timer. */
   MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

   /* Find the models. */
   MmodFind(MilSearchContext, MilImage, MilResult);

   /* Read the find time. */
   MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);

   /* Get the number of models found. */
   MmodGetResult(MilResult, M_DEFAULT, M_NUMBER+M_TYPE_LONG, &NumResults);

   /* If the models were found above the acceptance threshold. */
   if( (NumResults >= 1) && (NumResults <= MODELS_MAX_OCCURRENCES) )
      {
      /* Get the results for each model. */
      MmodGetResult(MilResult, M_DEFAULT, M_INDEX+M_TYPE_LONG, Models);
      MmodGetResult(MilResult, M_DEFAULT, M_POSITION_X, XPosition);
      MmodGetResult(MilResult, M_DEFAULT, M_POSITION_Y, YPosition);
      MmodGetResult(MilResult, M_DEFAULT, M_ANGLE, Angle);
      MmodGetResult(MilResult, M_DEFAULT, M_SCALE, Scale);
      MmodGetResult(MilResult, M_DEFAULT, M_SCORE, Score);

      /* Print information about the target image. */
      printf("The models were found in the target image although their is:\n");
      printf("   Full rotation\n   Small scale change\n   Contrast variation\n");
      printf("   Specular reflection\n   Occlusion\n   Multiple models\n");
      printf("   Multiple occurrences\n\n");

      /* Print the results for the found models. */
      printf("Result   Model   X Position   Y Position   Angle   Scale   Score\n\n");
      for (i=0; i<NumResults; i++)
         {
         printf("%-9d%-8d%-13.2f%-13.2f%-8.2f%-8.2f%-5.2f%%\n",
               i, Models[i], XPosition[i], YPosition[i], Angle[i], Scale[i], Score[i]);
         }
      printf("\nThe search time is %.1f ms\n\n", Time*1000.0);

      /* Draw edges and positions over the occurrences that were found. */
      for (i=0; i < NumResults; i++)
         {
         MgraColor(M_DEFAULT, ModelsDrawColor[Models[i]]);
         MmodDraw(M_DEFAULT, MilResult, MilOverlayImage,
                  M_DRAW_EDGES+M_DRAW_POSITION, i, M_DEFAULT);
         }
      }
   else
      {
      printf("The models were not found or the number of models found is greater than\n");
      printf("the defined value of maximum occurrences !\n\n");
      }

   /* Wait for a key to be pressed. */
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free MIL objects. */
   MbufFree(MilImage);
   MmodFree(MilSearchContext);
   MmodFree(MilResult);
   }


Example: mmodeltracking.c

/*********************************************************************************/
/*
 * File name: MobjectTracking.c
 *
 * Synopsis:  This program shows how to track a unique object using
 *            pattern recognition. It allocates a model in the field of
 *            view of the camera and finds it in a loop. It also prints
 *            the coordinates of the found model and draws a box around it.
 *            It searches using 2 methods, the normalized grayscale
 *            correlation (Mpat), which is very fast and with the Geometric
 *            Model Finder (Mmod), which is independent of the model rotation
 *            and scale but slower.
 *
 *            Note:  Display update and annotations drawing can require
 *                   significant CPU usage.
 */
#include <conio.h>
#include <mil.h>

/* Model specification. */
#define MODEL_WIDTH                   128L
#define MODEL_HEIGHT                  128L
#define MODEL_POS_X_INIT(TargetImage) (MbufInquire(TargetImage, M_SIZE_X, M_NULL)/2)
#define MODEL_POS_Y_INIT(TargetImage) (MbufInquire(TargetImage, M_SIZE_Y, M_NULL)/2)

/* Minimum score to consider the object found (in percent). */
#define MODEL_MIN_MATCH_SCORE       50.0

/* Drawing color */
#define DRAW_COLOR                  0xFF /* White */

/* Example selection. */
#define RUN_PAT_TRACKING_EXAMPLE    M_YES
#define RUN_MOD_TRACKING_EXAMPLE    M_YES

/* Example functions declarations. */
void MpatTrackingExample(MIL_ID MilSystem, MIL_ID MilDisplay, MIL_ID MilDigitizer,
                                           MIL_ID MilDisplayImage, MIL_ID MilModelImage);
void MmodTrackingExample(MIL_ID MilSystem, MIL_ID MilDisplay, MIL_ID MilDigitizer,
                                           MIL_ID MilDisplayImage, MIL_ID MilModelImage);
void GetModelImage(MIL_ID MilSystem, MIL_ID MilDisplay, MIL_ID MilDigitizer,
                                     MIL_ID MilDisplayImage, MIL_ID MilModelImage);

/*****************************************************************************
 Main.
 *****************************************************************************/
void main(void)
   {
   MIL_ID MilApplication,   /* Application identifier.   */
          MilSystem,        /* System identifier.        */
          MilDisplay,       /* Display identifier.       */
          MilDigitizer,     /* Digitizer identifier.     */
          MilDisplayImage,  /* Display image identifier. */
          MilModelImage;    /* Model image identifier.   */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay,
                                              &MilDigitizer, &MilDisplayImage);

   /* Allocate a model image buffer. */
   MbufAlloc2d(MilSystem,
               MbufInquire(MilDisplayImage, M_SIZE_X, M_NULL),
               MbufInquire(MilDisplayImage, M_SIZE_Y, M_NULL),
               8, M_IMAGE+M_PROC, &MilModelImage);

   printf("\nMODEL TRACKING:\n");
   printf("---------------\n\n");

   /* Get the model image. */
   GetModelImage(MilSystem, MilDisplay, MilDigitizer, MilDisplayImage, MilModelImage);

   #if (RUN_PAT_TRACKING_EXAMPLE)
   /* Finds the model using pattern matching. */
   MpatTrackingExample(MilSystem, MilDisplay, MilDigitizer, MilDisplayImage, MilModelImage);
   #endif

   #if (RUN_MOD_TRACKING_EXAMPLE)
   /* Finds the model using geometric model finder. */
   MmodTrackingExample(MilSystem, MilDisplay, MilDigitizer, MilDisplayImage, MilModelImage);
   #endif

   /* Free allocated buffers. */
   MbufFree(MilModelImage);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, MilDisplayImage);
   }

/*****************************************************************************
   Get Model Image Function.
 *****************************************************************************/

void GetModelImage(MIL_ID MilSystem, MIL_ID MilDisplay, MIL_ID MilDigitizer,
                   MIL_ID MilDisplayImage, MIL_ID MilModelImage)
   {
   MIL_ID MilOverlayImage;         /* Overlay image.      */
   long   DrawColor = DRAW_COLOR;  /* Drawing color.      */

   /* Prepare for overlay annotations. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Draw the position of the model to define in the overlay. */
   MgraColor(M_DEFAULT, DrawColor);
   MgraRect(M_DEFAULT, MilOverlayImage,
            MODEL_POS_X_INIT(MilOverlayImage) - (MODEL_WIDTH/2),
            MODEL_POS_Y_INIT(MilOverlayImage) - (MODEL_HEIGHT/2),
            MODEL_POS_X_INIT(MilOverlayImage) + (MODEL_WIDTH/2),
            MODEL_POS_Y_INIT(MilOverlayImage) + (MODEL_HEIGHT/2));

   /* Grab continuously. */
   printf("Model definition:\n\n");
   printf("Place a unique model to find in the marked rectangle.\n");
   printf("Press <Enter> to continue.\n\n");

   /* Grab a reference model image. */
   MdigGrabContinuous(MilDigitizer, MilDisplayImage);
   getch();
   MdigHalt(MilDigitizer);

   /* Copy the grabbed image to the Model image to keep it. */
   MbufCopy(MilDisplayImage, MilModelImage);

   /* Clear and disable the overlay. */
   MdispControl(MilDisplay, M_OVERLAY, M_DISABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
  }

/*****************************************************************************
   Tracking object with pattern matching module.
 *****************************************************************************/

void MpatTrackingExample(MIL_ID MilSystem,    MIL_ID MilDisplay,
                         MIL_ID MilDigitizer, MIL_ID MilDisplayImage, MIL_ID MilModelImage)
   {
   MIL_ID MilImage[2],             /* Processing image buffer identifiers. */
          Model,                   /* Model identifier.                    */
          Result;                  /* Result identifier.                   */
   long   DrawColor = DRAW_COLOR;  /* Model drawing color.                 */
   long   AllocError;              /* Allocation error variable.           */
   long   Found;                   /* Number of found models.              */
   long   NbFindDone= 0;           /* Number of loops to find model done.  */
   double OrgX =0.0, OrgY=0.0;     /* Original center of model.            */
   double x, y, Score=0.0;         /* Result variables.                    */
   double Time =0.0;               /* Timer.                               */

   /* Print a start message. */
   printf("\nGRAYSCALE PATTERN MATCHING:\n");
   printf("---------------------------\n\n");

   /* Display the model image. */
   MbufCopy(MilModelImage, MilDisplayImage);

   /* Allocate normalized grayscale type model. */
   MpatAllocModel(MilSystem, MilModelImage,
                  MODEL_POS_X_INIT(MilModelImage) - (MODEL_WIDTH/2),
                  MODEL_POS_Y_INIT(MilModelImage) - (MODEL_HEIGHT/2),
                  MODEL_WIDTH, MODEL_HEIGHT, M_NORMALIZED, &Model);

   /* Allocate result. */
   MpatAllocResult(MilSystem, 1L, &Result);

   /* Check for a successful allocations. */
   MappGetError(M_GLOBAL, &AllocError);
   if (!AllocError)
      {
      /* Draw box around the model. */
      MgraColor(M_DEFAULT, DrawColor);
      MpatDraw(M_DEFAULT, Model, MilDisplayImage, M_DRAW_BOX, M_DEFAULT, M_ORIGINAL);

      /* Set minimum acceptance for search. */
      MpatSetAcceptance(Model,MODEL_MIN_MATCH_SCORE);

      /* Set speed. */
      MpatSetSpeed(Model,M_HIGH);

      /* Set accuracy. */
      MpatSetAccuracy(Model,M_LOW);

      /* Preprocess model. */
      MpatPreprocModel(MilModelImage, Model, M_DEFAULT);

      /* Inquire about center of model. */
      MpatInquire(Model, M_ORIGINAL_X, &OrgX);
      MpatInquire(Model, M_ORIGINAL_Y, &OrgY);

      /* Print the original position. */
      printf("A Grayscale Model was defined.\n");
      printf("Model dimensions:  %ld x %ld.\n", MODEL_WIDTH, MODEL_HEIGHT);
      printf("Model center:      X=%.2f, Y=%.2f.\n", OrgX, OrgY);
      printf("Model is scale and rotation dependant.\n");
      printf("Press <Enter> to continue.\n\n");
      getch();

      /* Allocate 2 grab buffers. */
      MbufAlloc2d(MilSystem,
                  MbufInquire(MilModelImage, M_SIZE_X, M_NULL),
                  MbufInquire(MilModelImage, M_SIZE_Y, M_NULL),
                  8,
                  M_IMAGE+M_GRAB+M_PROC,
                  &MilImage[0]);
      MbufAlloc2d(MilSystem,
                  MbufInquire(MilModelImage, M_SIZE_X, M_NULL),
                  MbufInquire(MilModelImage, M_SIZE_Y, M_NULL),
                  8,
                  M_IMAGE+M_GRAB+M_PROC,
                  &MilImage[1]);

      /* Grab continuously and perform the find operation using double buffering. */
      printf("\nContinuously finding the Grayscale model.\n");
      printf("Press <Enter> to stop.\n\n");

      /* Grab a first target image into first buffer (done twice for timer reset accuracy). */
      MdigControl(MilDigitizer, M_GRAB_MODE, M_ASYNCHRONOUS);
      MdigGrab(MilDigitizer, MilImage[NbFindDone%2]);
      MdigGrab(MilDigitizer, MilImage[NbFindDone%2]);
      MappTimer(M_TIMER_RESET, &Time);

      /* Loop, processing one buffer while grabbing the other. */
      do
         {
         /* Grab a target image into the other buffer. */
         MdigGrab(MilDigitizer, MilImage[(NbFindDone+1)%2]);

         /* Read the time. */
         MappTimer(M_TIMER_READ, &Time);

         /* Find model. */
         MpatFindModel(MilImage[NbFindDone%2], Model, Result);

         /* Get results. */
         MpatGetNumber(Result, &Found);
         MpatGetResult(Result, M_POSITION_X, &x);
         MpatGetResult(Result, M_POSITION_Y, &y);
         MpatGetResult(Result, M_SCORE, &Score);

         /* Print a message based upon the score. */
         if (Found)
            {
            /* Draw a box around the model and print the results. */
            MpatDraw(M_DEFAULT, Result, MilImage[NbFindDone%2],
                     M_DRAW_BOX+M_DRAW_POSITION, M_DEFAULT, M_DEFAULT);
            printf("Found: X=%7.2f, Y=%7.2f, Score=%5.1f%% (%.2f fps).    \r",
                                              x, y, Score, (NbFindDone+1)/Time);
            }
         else
            {
            /* Print the "not found" message. */
            printf("Not found ! (score<%5.1f%%)                (%.2f fps).     \r",
                                         MODEL_MIN_MATCH_SCORE, (NbFindDone+1)/Time);
            }

         /* Copy target image to the display. */
         MbufCopy(MilImage[NbFindDone%2], MilDisplayImage);

         /* Increment find count */
         NbFindDone++;
         }
         while (!kbhit());
         getch();
         printf("\n\n");
      }
   else
      {
      printf("\nError: Allocations or model definition failed.\n");
      printf("Press <Enter> to end.\n");
      getch();
      }

   /* Wait for end of last grab. */
   MdigGrabWait(MilDigitizer, M_GRAB_END);

   /* Free all allocated objects. */
   if (Result)
       MpatFree(Result);
   if (Model)
       MpatFree(Model);
   MbufFree(MilImage[1]);
   MbufFree(MilImage[0]);
}

/*****************************************************************************
   Tracking object with Geometric Model Finder module
 *****************************************************************************/

#define MODEL_MAX_OCCURRENCES       16L

void MmodTrackingExample(MIL_ID MilSystem,    MIL_ID MilDisplay,
                         MIL_ID MilDigitizer, MIL_ID MilDisplayImage, MIL_ID MilModelImage)
   {
   MIL_ID MilImage[2],                  /* Processing image buffer identifiers. */
          SearchContext,                /* Search context identifier.           */
          Result;                       /* Result identifier.                   */
   long   DrawColor = DRAW_COLOR;       /* Model drawing color.                 */
   long   AllocError;                   /* Allocation error variable.           */
   long   Found;                        /* Number of models found.              */
   long   NbFindDone=0;                 /* Number of loops to find model done.  */
   double OrgX=0.0, OrgY=0.0;           /* Original center of model.            */
   double Score[MODEL_MAX_OCCURRENCES], /* Model correlation score.             */
          x[MODEL_MAX_OCCURRENCES],     /* Model X position.                    */
          y[MODEL_MAX_OCCURRENCES],     /* Model Y position.                    */
          Angle[MODEL_MAX_OCCURRENCES], /* Model occurrence angle.              */
          Scale[MODEL_MAX_OCCURRENCES]; /* Model occurrence scale.              */
   double Time = 0.0;                   /* Timer.                               */

   /* Print a start message. */
   printf("\nGEOMETRIC MODEL FINDER (scale and rotation independent):\n");
   printf("--------------------------------------------------------\n\n");

   /* Display model image. */
   MbufCopy(MilModelImage, MilDisplayImage);

   /* Allocate a context and define a geometric model. */
   MmodAlloc(MilSystem, M_GEOMETRIC, M_DEFAULT, &SearchContext);
   MmodDefine(SearchContext, M_IMAGE, MilModelImage,
              MODEL_POS_X_INIT(MilModelImage) - (MODEL_WIDTH/2),
              MODEL_POS_Y_INIT(MilModelImage) - (MODEL_HEIGHT/2),
              MODEL_WIDTH, MODEL_HEIGHT);

   /* Allocate result. */
   MmodAllocResult(MilSystem, M_DEFAULT, &Result);

   /* Check that allocation was successful. */
   MappGetError(M_GLOBAL, &AllocError);
   if (!AllocError)
      {
      /* Draw a box around the model. */
      MgraColor(M_DEFAULT, DrawColor);
      MmodDraw(M_DEFAULT, SearchContext, MilDisplayImage, M_DRAW_BOX, M_DEFAULT, M_ORIGINAL);

      /* Set speed to VERY HIGH for fast but less precise search. */
      MmodControl(SearchContext, M_CONTEXT, M_SPEED, M_VERY_HIGH);

      /* Set minimum acceptance for the search. */
      MmodControl(SearchContext, M_DEFAULT, M_ACCEPTANCE, MODEL_MIN_MATCH_SCORE);

      /* Preprocess model. */
      MmodPreprocess(SearchContext, M_DEFAULT);

      /* Inquire about center of model. */
      MmodInquire(SearchContext, M_DEFAULT, M_ORIGINAL_X, &OrgX);
      MmodInquire(SearchContext, M_DEFAULT, M_ORIGINAL_Y, &OrgY);

      /* Print the original position. */
      printf("The Geometric target model was defined.\n");
      printf("Model dimensions: %ld x %ld.\n", MODEL_WIDTH, MODEL_HEIGHT);
      printf("Model center:     X=%.2f, Y=%.2f.\n", OrgX, OrgY);
      printf("Model is scale and rotation independent.\n");
      printf("Press <Enter> to continue.\n\n");
      getch();

      /* Allocate 2 grab buffers. */
      MbufAlloc2d(MilSystem,
                  MbufInquire(MilModelImage, M_SIZE_X, M_NULL),
                  MbufInquire(MilModelImage, M_SIZE_Y, M_NULL),
                  8,
                  M_IMAGE+M_GRAB+M_PROC,
                  &MilImage[0]);
      MbufAlloc2d(MilSystem,
                  MbufInquire(MilModelImage, M_SIZE_X, M_NULL),
                  MbufInquire(MilModelImage, M_SIZE_Y, M_NULL),
                  8,
                  M_IMAGE+M_GRAB+M_PROC,
                  &MilImage[1]);

      /* Grab continuously grab and perform the find operation using double buffering. */
      printf("\nContinuously finding the Geometric Model.\n");
      printf("Press a <Enter> to stop.\n\n");

      /* Grab a first target image into first buffer (done twice for timer reset accuracy). */
      MdigControl(MilDigitizer, M_GRAB_MODE, M_ASYNCHRONOUS);
      MdigGrab(MilDigitizer, MilImage[NbFindDone%2]);
      MdigGrab(MilDigitizer, MilImage[NbFindDone%2]);
      MappTimer(M_TIMER_RESET, &Time);

      /* Loop, processing one buffer while grabbing the other. */
      do
         {
         /* Grab a target image into the other buffer. */
         MdigGrab(MilDigitizer, MilImage[(NbFindDone+1)%2]);

         /* Read the time. */
         MappTimer(M_TIMER_READ, &Time);

         /* Find model. */
         MmodFind(SearchContext, MilImage[NbFindDone%2], Result);

         /* Get the number of occurrences found. */
         MmodGetResult(Result, M_DEFAULT, M_NUMBER+M_TYPE_LONG, &Found);

         /* Print a message based on the score. */
         if ( (Found >= 1) && (Found < MODEL_MAX_OCCURRENCES) )
            {
            /* Get results. */
            MmodGetResult(Result, M_DEFAULT, M_POSITION_X, x);
            MmodGetResult(Result, M_DEFAULT, M_POSITION_Y, y);
            MmodGetResult(Result, M_DEFAULT, M_SCALE, Scale);
            MmodGetResult(Result, M_DEFAULT, M_ANGLE, Angle);
            MmodGetResult(Result, M_DEFAULT, M_SCORE, Score);

            /* Draw a box and a cross where the model was found and print the results. */
            MmodDraw(M_DEFAULT, Result, MilImage[NbFindDone%2],
                     M_DRAW_BOX+M_DRAW_POSITION+M_DRAW_EDGES, M_DEFAULT, M_DEFAULT);
            printf("Found: X=%6.1f, Y=%6.1f, Angle=%6.1f, Scale=%5.2f, Score=%5.1f%% (%5.2f fps).\r",
                                      x[0], y[0], Angle[0], Scale[0], Score[0], (NbFindDone+1)/Time);
            }
         else
            {
            /* Print the "not found" message. */
            printf("Not found! (score<%5.1f%%)                                          (%5.2f fps).\r",
                                                              MODEL_MIN_MATCH_SCORE, (NbFindDone+1)/Time);
            }

         /* Copy target image to the display. */
         MbufCopy(MilImage[NbFindDone%2], MilDisplayImage);

         /* Increment the counter. */
         NbFindDone++;
         }
         while (!kbhit());
         getch();
         printf("\n\n");

      }
   else
      {
      printf("\nError: Allocations or model definition failed.\n");
      printf("Press <Enter> to end.\n\n");
      getch();
      }

   /* Wait for the end of last grab. */
   MdigGrabWait(MilDigitizer, M_GRAB_END);

   /* Free all allocations. */
   if (Result)
      MmodFree(Result);
   if (SearchContext)
      MmodFree(SearchContext);
   MbufFree(MilImage[1]);
   MbufFree(MilImage[0]);
}


Example: mmorphisjpeg2000.c

/************************************************************************/
/*
 * File name: MMorphisJPEG2000.c
 *
 * Synopsis:  This program shows how to perform the following:
 *            - A simple compression/decompression.
 *            - Decompressing from a Host pointer.
 *            - Double buffering the compression of Host buffers.
 *
 *     Note that processing is generally faster if the buffer is not displayed.
 */
#include <mil.h>
#include <conio.h>
#include <stdlib.h>

/* Main function. */
void main(void)
{
   MIL_ID   MilApplication; /* Application identifier. */
   MIL_ID   MilSystem     ; /* System identifier.      */
   MIL_ID   MilDigitizer  ; /* Digitizer identifier.   */
   MIL_ID   MilDisplay    ; /* Display identifier.     */
   MIL_ID   MilImage[2];
   MIL_ID   MilImageOnBoard[2];
   MIL_ID   MilImageCompress;
   MIL_ID   MilImageCreateCompress;
   MIL_ID   MilImageDisp  ;
   char *   pJP2KCodeStream;
   double   TimeStart, TimeEnd;
   long     i = 0;
   long     SizeBand, SizeX, SizeY;

   // Allocate defaults.
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay,
                                              &MilDigitizer, M_NULL);

   SizeBand = MdigInquire(MilDigitizer, M_SIZE_BAND, M_NULL);
   SizeX    = MdigInquire(MilDigitizer, M_SIZE_X, M_NULL);
   SizeY    = MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL);

   // Allocate and select a display buffer.
   MbufAllocColor(MilSystem, SizeBand, SizeX, SizeY, 8L+M_UNSIGNED,
                   M_IMAGE + M_DISP + M_NON_PAGED, &MilImageDisp);

   MbufClear(MilImageDisp, M_BLACK);
   MdispSelect(MilDisplay, MilImageDisp);

   // Allocate grab buffers in Host memory.
   for(i = 0; i < 2; i++)
      MbufAllocColor(MilSystem, SizeBand, SizeX, SizeY, 8L+M_UNSIGNED,
                     M_IMAGE + M_GRAB, &MilImage[i]);

   // Allocate grab buffers in on-board memory.
   for(i = 0; i < 2; i++)
      MbufAllocColor(MilSystem, SizeBand, SizeX, SizeY, 8L+M_UNSIGNED,
                     M_IMAGE + M_GRAB + M_ON_BOARD, &MilImageOnBoard[i]);

   // Allocate JPEG 2000 buffer.
   MbufAllocColor(MilSystem, SizeBand, SizeX, SizeY, 8L+M_UNSIGNED,
                  M_IMAGE + M_COMPRESS + M_JPEG2000_LOSSY, &MilImageCompress);

   printf("Compressing, decompressing and displaying the grabbed image.\n");
   printf("Press Enter continue.\n");

   while(!kbhit())
      {
      // Grab in to on-board memory.
      MdigGrab(MilDigitizer, MilImageOnBoard[0]);

      // Compress the buffer.
      MbufCopy(MilImageOnBoard[0], MilImageCompress);

      // Decompresses the buffer to the display.
      MbufCopy(MilImageCompress, MilImageDisp);
      }

   ////////////////////////////////////////////////////
   // Decompressing a code stream from a Host pointer.
   //
   printf("\nDecompression from a Host pointer usually occurs when receiving\n");
   printf("compressed data through a network connection, or read from a file.\n");
   printf("Press Enter to proceed.\n");
   getchar();

   printf("Press Enter to continue.\n");

   while(!kbhit())
      {
      MappTimer(M_TIMER_READ, &TimeStart);

      // pJP2KCodeStream is a pointer to a valid jpeg2000 data.
      MbufInquire(MilImageCompress, M_HOST_ADDRESS, &pJP2KCodeStream);

      // Map a MIL buffer on the Host pointer.
      MbufCreateColor(MilSystem,  SizeBand, SizeX, SizeY, 8L+M_UNSIGNED,
                      M_IMAGE + M_COMPRESS + M_JPEG2000_LOSSY + (SizeBand == 3? M_YUV16 + M_PLANAR: 0),
                      M_HOST_ADDRESS,
                      M_DEFAULT,
                      &pJP2KCodeStream,
                      &MilImageCreateCompress);

      // Decompress the buffer.
      MbufCopy(MilImageCreateCompress, MilImageDisp);

      // Free the buffer
      MbufFree(MilImageCreateCompress);
      MappTimer(M_TIMER_READ, &TimeEnd);
      printf("\rDecompressing to display from host ptr at %3.1f frames/sec (%1.4f sec) ",1.0/(TimeEnd-TimeStart), (TimeEnd-TimeStart));
      }

   getchar();
   printf("Press Enter to end.\n");

   ////////////////////////////////////////////////////
   // How to double-buffer compressed Host images.
   printf("\nThe following demonstrates how to efficiently compress images\n");
   printf("located in Host memory.\n");
   printf("While a buffer is copied from Host to on-board memory, the\n");
   printf("previously copied image is compressed by the hardware.\n\n");

   // Grab images into Host buffers.
   for(i = 0; i < 2; i++)
      MdigGrab(MilDigitizer, MilImage[i]);

   // Set the compression to be asynchronous.
   MthrControl(MilSystem, M_BUS_MASTER_COPY_MODE, M_ASYNCHRONOUS);

   i = 0;
   MbufCopy(MilImage[i], MilImageOnBoard[i]);
   while(!kbhit())
      {
      MappTimer(M_TIMER_READ, &TimeStart);

      // Perform the compression of on-board image asynchronously.
      MbufCopy(MilImageOnBoard[i], MilImageCompress);

      // While the image is being compressed, copy the next image into on-board memory.
      i = 1 - i;
      MbufCopy(MilImage[i], MilImageOnBoard[i]);

      // Wait for the compression to terminate.
      MthrWait(MilSystem, M_THREAD_WAIT, M_NULL);

      MappTimer(M_TIMER_READ, &TimeEnd);
      printf("\rPerforming compressions of host buffers at %3.1f frames/sec (%1.4f sec) ",1.0/(TimeEnd-TimeStart),(TimeEnd-TimeStart) );
      }

   MthrControl(MilSystem, M_BUS_MASTER_COPY_MODE, M_SYNCHRONOUS);

   for(i = 0; i < 2; i++)
      {
      MbufFree(MilImageOnBoard[i]);
      MbufFree(MilImage[i]);
      }

   /* Free all allocations. */
   MbufFree(MilImageCompress);
   MbufFree(MilImageDisp);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, M_NULL);


Example: mnatfct.c

/********************************************************************/
/*
 * File name: mnatfct.c
 * Synopsis:  This shows the use of the MIL native mode programmer's kit.
 *            This example shows how the user can mix MIL code and
 *            user code to create a pseudo-MIL function.
 *            This example creates a function that find the pointer
 *            to a MIL image buffer and use it to directly access
 *            the data and adds a constant.
 *      Note: The image must be 8 bit unsigned.
 */

/* headers. */
#include <stdio.h>
#include <mil.h>

#define MAX_DEPTH       8
#define DIMENSION_ERROR 1
#define IMAGE_FILE      M_IMAGE_PATH MIL_TEXT("Board.mim")

/* Pseudo-MIL Function definition. */
void AddConstToImage(MIL_ID MilImageId, unsigned long ConstantToAdd)
{
   MIL_ID        Func;
   long          ImageSizeX, ImageSizeY, ImagePitch, x, y, TempValue;
   unsigned char *ImageDataPtr;

   /* Prepare the start of the function and register the parameters. */
   Func = MfuncAlloc(MIL_TEXT("AddConstToImage"), 2, M_NULL, M_NULL, M_NULL, M_NULL, M_DEFAULT, M_NULL);
   MfuncParamId(Func,1,MilImageId,M_IMAGE,M_IN+M_OUT);
   MfuncParamLong(Func,2,ConstantToAdd);

   /* Mark the start of the function. */
   if (MfuncStart(Func))
      {
      /* Do the operation using a custom function and check to */
      /* not exceed the supported limits if required.          */
      if ((!MfuncParamCheck(Func)) || (MbufInquire(MilImageId,M_SIZE_BIT,M_NULL) == MAX_DEPTH))
         {
         /* Read the image data pointer, size X, size Y and pitch. */
         MbufInquire(MilImageId,M_HOST_ADDRESS,&ImageDataPtr);
         MbufInquire(MilImageId,M_SIZE_X,&ImageSizeX);
         MbufInquire(MilImageId,M_SIZE_Y,&ImageSizeY);
         MbufInquire(MilImageId,M_PITCH, &ImagePitch);

         /* Add the constant to the image. */
         for (y= 0; y < ImageSizeY; y++) /* For each line */
            {
            for (x= 0; x < ImageSizeX; x++) /* for each pixel */
               {
               /* Calculate the value to write */
               TempValue = (long)ImageDataPtr[x] + (long)ConstantToAdd;

               /* Write the value if no overflow else saturate */
               if (TempValue <= 0xff)
                  ImageDataPtr[x] = (unsigned char)TempValue;
               else
                  ImageDataPtr[x] = 0xff;
               }
             /* Move pointer to the next line */
             ImageDataPtr += ImagePitch;
            }
         }
      else
         {
         /* Report a MIL error. */
         MfuncErrorReport(Func,M_FUNC_ERROR+DIMENSION_ERROR,
                          MIL_TEXT("Buffer type not supported"),
                          MIL_TEXT("Depth is not 8 bit."),
                          M_NULL,
                          M_NULL
                         );
         }
      }

   /* Signal to MIL that the image content was modified. */
   MbufControl(MilImageId, M_MODIFIED, M_DEFAULT);

   /* Mark the end of the function. */
   MfuncFreeAndEnd(Func);
}

/* Main to test the function. */
void main(void)
{
   MIL_ID MilApplication,    /* Application Identifier.  */
          MilSystem,         /* System Identifier.       */
          MilDisplay,        /* Display Identifier.      */
          MilImage;          /* Image buffer Identifier. */

   /* Allocate default application, system, display and image. */
   MappAllocDefault(M_COMPLETE, &MilApplication, &MilSystem,
                                &MilDisplay, M_NULL, M_NULL);

   /* Restore source image into an automatically allocated image buffer. */
   MbufRestore(IMAGE_FILE, MilSystem, &MilImage);

   /* Display the image. */
   MdispSelect(MilDisplay, MilImage);

   /* Pause */
   printf("This example will create a custom pseudo-MIL function that \n");
   printf("process a MIL buffer using the pointer to its raw data.\n\n");
   printf("Reference image was loaded, press a key to continue.\n");
   getchar();

   /* Process the image directly with custom Pseudo-Mil function */
   AddConstToImage(MilImage, 0x40);

   /* Pause */
   printf("The white level of the image was augmented using a user made\n");
   printf("pseudo-MIL function accessing directly the image.\n");
   printf("Press a key to terminate.\n");
   getchar();

   /* Remove the image from display. */
   MdispDeselect(MilDisplay, MilImage);

   /* Release all allocated buffers. */
   MbufFree(MilImage);

   /* Free defaults */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mnatgen.c

/* File name: mnatgen.c
 * Synopsis:  This program show how to use GENESIS native library mixed
 *            with MIL calls.
 */

/* general includes */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <mil.h>
#include <imapi.h>

/* Operation control defines */
#define ALLOCATE 1
#define PROCESS  2
#define FREE     3

/* Native functions to grab  and warp an image. */
void GrabAndWarp(MIL_ID MilSystem, MIL_ID MilDisplay, MIL_ID MilCamera,
                                   MIL_ID MilImage, long Operation);

/* Main function: */
/* -------------- */
void main(void)
{
   MIL_ID MilApplication,  /* Application identifier.  */
          MilSystem,       /* System identifier.       */
          MilDisplay,      /* Display identifier.      */
          MilCamera,       /* Camera identifier.       */
          MilImage;        /* Image buffer identifier. */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem,
                             &MilDisplay, &MilCamera, &MilImage);
   /* Make sure that the system allocated is a Genesis */
   if ((MsysInquire(MilSystem, M_SYSTEM_TYPE, M_NULL)!= M_SYSTEM_GENESIS_TYPE) ||
       (MsysInquire(MilSystem, M_BOARD_TYPE, M_NULL)!= M_GENESIS))
      {
      printf("This example only runs on a Matrox Genesis main board system.\n");
      printf("Press <Enter> to end...");
      getchar();
      goto end;
      }

   /* Allocate and initialialize work buffers */
   GrabAndWarp(MilSystem, MilDisplay, MilCamera, MilImage, ALLOCATE);

   /* Print a message on the host screen. */
   printf("Native function called in a loop...\n");
   printf("Press <Enter> to end...");

   /* Grab and warp grabbed image in a loop */
   while (!kbhit())
      {
      GrabAndWarp(MilSystem, MilDisplay, MilCamera, MilImage, PROCESS);
      }
   getchar();

   /* Free work buffers */
   GrabAndWarp(MilSystem, MilDisplay, MilCamera, MilImage, FREE);

end:

   MappFreeDefault(MilApplication, MilSystem, MilDisplay, MilCamera, MilImage);
}

/* Native function: */
/* ---------------- */
void GrabAndWarp(MIL_ID MilSystem, MIL_ID MilDisplay, MIL_ID MilCamera,
                                   MIL_ID MilImage, long Operation)
{
   /* Warp coefficients and LUT ID variables.
    * (kept in static to avoid warp coeficients caculation at each call.)
    */
   static long NativeWarpBufId       = M_NULL;
   static long NativeWarpLutXBufId   = M_NULL;
   static long NativeWarpLutYBufId   = M_NULL;
   static long NativeGrabBufId       = M_NULL;
   static long NativeWarpResultBufId = M_NULL;

   /* Inquire useful MIL informations. */
   long SizeX    = MdigInquire(MilCamera, M_SIZE_X   , M_NULL);
   long SizeY    = MdigInquire(MilCamera, M_SIZE_Y   , M_NULL);
   long SizeBand = MdigInquire(MilCamera, M_SIZE_BAND, M_NULL);

   /* Miscelanous local variables */
   double CornerX1  = 0.0;
   double CornerY1  = 0.0;
   double CornerX2  = SizeX - 1.0;
   double CornerY2  = 0.0;
   double CornerX3  = 2.0 * SizeX;
   double CornerY3  = SizeY - 1.0;
   double CornerX4  = -1.0 * SizeX;
   double CornerY4  = SizeY - 1.0;
   long   SrcXStart = 0L;
   long   SrcYStart = 0L;
   long   SrcXEnd   = SizeX - 1L;
   long   SrcYEnd   = SizeY - 1L;

   /* Inquire Genesis native Id's */
   long NativeSysThreadId = MsysInquire(MilSystem, M_NATIVE_THREAD_ID,  M_NULL);
   long NativeDigCameraId = MdigInquire(MilCamera, M_NATIVE_CAMERA_ID , M_NULL);
   long NativeDigControlId= MdigInquire(MilCamera, M_NATIVE_CONTROL_ID, M_NULL);
   long NativeDigId       = MdigInquire(MilCamera, M_NATIVE_ID        , M_NULL);
   long NativeBufId       = MbufInquire(MilImage,  M_NATIVE_ID        , M_NULL);

   /* Notify MIL that we are entering native mode. */
   MsysControl(MilSystem, M_NATIVE_MODE_ENTER, M_NULL);

   /* Do the selected operation.*/
   switch (Operation)
   {
   /* Preallocate grab and warp buffers (done once for speed). */
   case ALLOCATE:
      {
      imBufAlloc(NativeSysThreadId, SizeX, SizeY, SizeBand, IM_UBYTE, IM_PROC,
                                                      &NativeGrabBufId);
      imBufAlloc(NativeSysThreadId, SizeX, SizeY, SizeBand, IM_UBYTE, IM_PROC,
                                                      &NativeWarpResultBufId);
      imBufAlloc(NativeSysThreadId, 3L, 3L, 1L, IM_FLOAT, IM_PROC,
                                                      &NativeWarpBufId);
      imBufAlloc(NativeSysThreadId, SizeX, SizeY, 1L, IM_SHORT, IM_PROC,
                                                      &NativeWarpLutXBufId);
      imBufAlloc(NativeSysThreadId, SizeX, SizeY, 1L, IM_SHORT, IM_PROC,
                                                      &NativeWarpLutYBufId);
      if (NativeGrabBufId     && NativeWarpResultBufId && NativeWarpBufId &&
          NativeWarpLutXBufId && NativeWarpLutYBufId)
         {
         /* Calculate warp coeficients */
         imGenWarp4Corner(NativeSysThreadId, NativeWarpBufId, CornerX1,
                          CornerY1, CornerX2, CornerY2, CornerX3, CornerY3,
                          CornerX4, CornerY4, SrcXStart, SrcYStart, SrcXEnd,
                          SrcYEnd, IM_DEFAULT, 0L);
         imGenWarpLutMatrix(NativeSysThreadId, NativeWarpLutXBufId,
                            NativeWarpLutYBufId, NativeWarpBufId, 0L, 0L);
         }
      else
         {
         printf("Error allocating resources...\n");
         }

      if (SizeBand > 1)
         {
         printf("Error: only monochrome cameras are supported...\n");
         }

      break;
      }

   /* Grab and Warp buffer. */
   case PROCESS:
      {
      /* Process if allocations were sucessful */
      if ((SizeBand == 1)     &&
          NativeGrabBufId     && NativeWarpResultBufId && NativeWarpBufId &&
          NativeWarpLutXBufId && NativeWarpLutYBufId)
         {
         /* Grab the image */
         imDigGrab(NativeSysThreadId, NativeDigId, NativeDigCameraId,
                   NativeGrabBufId, 1L, NativeDigControlId, 0L);

         /* Warp the grabbed image. */
         imIntWarpLut(NativeSysThreadId, NativeGrabBufId, NativeWarpResultBufId,
                      NativeWarpLutXBufId, NativeWarpLutYBufId, 0L, 0L);

         /* Copy the result into the display buffer */
         imBufCopy(NativeSysThreadId, NativeWarpResultBufId, NativeBufId, 0L, 0L);
         }
      break;
      }

   /* Free grab and warp buffers. */
   case FREE:
      {
      if (NativeGrabBufId)
         imBufFree(NativeSysThreadId, NativeGrabBufId);
      if (NativeWarpResultBufId)
         imBufFree(NativeSysThreadId, NativeWarpResultBufId);
      if (NativeWarpBufId)
         imBufFree(NativeSysThreadId, NativeWarpBufId);
      if (NativeWarpLutXBufId)
         imBufFree(NativeSysThreadId, NativeWarpLutXBufId);
      if (NativeWarpLutYBufId)
         imBufFree(NativeSysThreadId, NativeWarpLutYBufId);
      break;
      }
   }

   /* Notify MIL that we leave native mode. */
   MsysControl(MilSystem, M_NATIVE_MODE_LEAVE, M_NULL);

   /* Notify MIL that the buffer was modified. */
   MbufControl(MilImage, M_MODIFIED, M_DEFAULT);
}


Example: mocr.c

/*****************************************************************************/
/*
 * File name: MOcr.c
 *
 * Synopsis:  This program uses the OCR module to read a SEMI font string:
 *            the example calibrates a predefined OCR font (semi font)
 *            and uses it to read a string in the image. The string read
 *            is then printed to the screen and the calibrated font is
 *            saved to disk.
 */
#include <mil.h>
#include <conio.h>

/*****************************************************************************
 OCR SEMI font read example.
 *****************************************************************************/

/* Target image character specifications. */
#define CHAR_IMAGE_FILE        M_IMAGE_PATH MIL_TEXT("OcrSemi1292.mim")
#define CHAR_SIZE_X_MIN        22.0
#define CHAR_SIZE_X_MAX        23.0
#define CHAR_SIZE_X_STEP       0.50
#define CHAR_SIZE_Y_MIN        43.0
#define CHAR_SIZE_Y_MAX        44.0
#define CHAR_SIZE_Y_STEP       0.50

/* Target reading specifications. */
#define READ_REGION_POS_X      30L
#define READ_REGION_POS_Y      40L
#define READ_REGION_WIDTH      420L
#define READ_REGION_HEIGHT     70L
#define READ_SCORE_MIN         50.0

/* Font file names. */
#define FONT_FILE_IN           M_IMAGE_PATH MIL_TEXT("Semi1292.mfo")
#define FONT_FILE_OUT          M_IMAGE_PATH MIL_TEXT("Semi1292Calibrated.mfo")

/* Length of the string to read (null terminated) */
#define STRING_LENGTH          13L
#define STRING_CALIBRATION     MIL_TEXT("M940902-MXD5")

void main(void)
   {
   MIL_ID MilApplication,               /* Application identifier.       */
          MilSystem,                    /* System identifier.            */
          MilDisplay,                   /* Display identifier.           */
          MilImage,                     /* Image buffer identifier.      */
          MilSubImage,                  /* Sub-image buffer identifier.  */
          MilFontSubImage,              /* Font display sub image.       */
          MilOverlayImage,              /* Overlay image.                */
          OcrFont,                      /* OCR font identifier.          */
          OcrResult;                    /* OCR result buffer identifier. */
   MIL_TEXT_CHAR String[STRING_LENGTH]; /* Array of characters to read.  */
   double Score;                        /* Reading score.                */
   long   SizeX, SizeY, Type;           /* Source image dimensions.      */

   printf("\nOCR MODULE (SEMI font reading):\n");
   printf("-------------------------------\n\n");

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Load and display the source image into a new image buffer. */
   MbufAlloc2d(MilSystem,
               MbufDiskInquire(CHAR_IMAGE_FILE, M_SIZE_X, &SizeX),
               MbufDiskInquire(CHAR_IMAGE_FILE, M_SIZE_Y, &SizeY)*3/2,
               MbufDiskInquire(CHAR_IMAGE_FILE, M_TYPE,   &Type),
               M_IMAGE+M_PROC+M_DISP,
               &MilImage);
   MbufClear(MilImage, 0);
   MbufLoad(CHAR_IMAGE_FILE, MilImage);
   MdispSelect(MilDisplay, MilImage);

   /* Restrict the region of the image where to read the string. */
   MbufChild2d(MilImage, READ_REGION_POS_X, READ_REGION_POS_Y,
               READ_REGION_WIDTH, READ_REGION_HEIGHT, &MilSubImage);

   /* Define the bottom of the image as the region where to copy the font representation.*/
   MbufChild2d(MilImage, 50, SizeY+10, SizeX-100, (SizeY/3)-10, &MilFontSubImage);

   /* Restore the OCR character font from disk. */
   MocrRestoreFont(FONT_FILE_IN, M_RESTORE, MilSystem, &OcrFont);

   /* Show the font representation. */
   MocrCopyFont(MilFontSubImage, OcrFont, M_COPY_FROM_FONT+M_ALL_CHAR, M_NULL );

   /* Pause to show the original image. */
   printf("The SEMI string at the top will be read using the font displayed at the bottom.\n\n");
   printf("Calibrating SEMI font...\n\n");

   /* Calibrate the OCR font. */
   MocrCalibrateFont(MilSubImage, OcrFont, STRING_CALIBRATION,
                     CHAR_SIZE_X_MIN, CHAR_SIZE_X_MAX, CHAR_SIZE_X_STEP,
                     CHAR_SIZE_Y_MIN, CHAR_SIZE_Y_MAX, CHAR_SIZE_Y_STEP,
                     M_DEFAULT);

   /* Set the user-specific character constraints for each string position.  */
   MocrSetConstraint(OcrFont, 0,  M_LETTER, M_NULL);        /* A to Z only   */
   MocrSetConstraint(OcrFont, 1,  M_DIGIT,  MIL_TEXT("9")); /* 9      only   */
   MocrSetConstraint(OcrFont, 2,  M_DIGIT,  M_NULL);        /* 0 to 9 only   */
   MocrSetConstraint(OcrFont, 3,  M_DIGIT,  M_NULL);        /* 0 to 9 only   */
   MocrSetConstraint(OcrFont, 4,  M_DIGIT,  M_NULL);        /* 0 to 9 only   */
   MocrSetConstraint(OcrFont, 5,  M_DIGIT,  M_NULL);        /* 0 to 9 only   */
   MocrSetConstraint(OcrFont, 6,  M_DIGIT,  M_NULL);        /* 0 to 9 only   */
   MocrSetConstraint(OcrFont, 7,  M_DEFAULT,MIL_TEXT("-")); /* -      only   */
   MocrSetConstraint(OcrFont, 8,  M_LETTER, MIL_TEXT("M")); /* M      only   */
   MocrSetConstraint(OcrFont, 9,  M_LETTER, MIL_TEXT("X")); /* X      only   */
   MocrSetConstraint(OcrFont, 10, M_LETTER, MIL_TEXT("ABCDEFGH")); /* SEMI checksum */
   MocrSetConstraint(OcrFont, 11, M_DIGIT,  MIL_TEXT("01234567")); /* SEMI checksum */

   /* Pause before the read operation. */
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Allocate an OCR result buffer. */
   MocrAllocResult(MilSystem, M_DEFAULT, &OcrResult);

   /* Read the string. */
   MocrReadString(MilSubImage, OcrFont, OcrResult);

   /* Get the string and its reading score. */
   MocrGetResult(OcrResult, M_STRING, String);
   MocrGetResult(OcrResult, M_STRING_SCORE,  &Score);

   /* Print the result. */
   MOs_printf(MIL_TEXT("\nThe string read is: \"%s\" (score: %.1f%%).\n\n"), String, Score);

   /* Draw the string in the overlay under the reading region. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);
   MgraFont(M_DEFAULT, M_FONT_DEFAULT_LARGE);
   MgraColor(M_DEFAULT, M_COLOR_YELLOW);
   MgraText(M_DEFAULT, MilOverlayImage, READ_REGION_POS_X+(READ_REGION_WIDTH/4),
                                        READ_REGION_POS_Y+READ_REGION_HEIGHT+50, String);

   /* Save the calibrated font if the reading score was sufficiently high. */
   if (Score > READ_SCORE_MIN)
      {
      MocrSaveFont(FONT_FILE_OUT, M_SAVE, OcrFont);
      printf("Read successful, calibrated OCR font was saved to disk.\n");
      }
   else
      {
      printf("Error: Read score too low, calibrated OCR font not saved.\n");
      }
   printf("Press <Enter> to continue.\n\n\n");
   getch();

   /* Clear the overlay. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Free all allocations. */
   MocrFree(OcrFont);
   MocrFree(OcrResult);
   MbufFree(MilSubImage);
   MbufFree(MilFontSubImage);
   MbufFree(MilImage);
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
}


Example: mpat.c

/***************************************************************************************/
/*
 * File name: MPat.c
 *
 * Synopsis:  This program contains 3 examples of the pattern matching module:
 *
 *            The first example defines a model and then searches for it in a shifted
 *            version of the image (without rotation).
 *
 *            The second example defines a model and then searches for it in a
 *            rotated version of the image.
 *
 *            The third example automatically allocates a model in a wafer image and finds
 *            its horizontal and vertical displacement.
 */
#include <mil.h>
#include <conio.h>
#include <math.h>

/* Example functions declarations. */
void SearchModelExample(MIL_ID MilSystem, MIL_ID MilDisplay);
void SearchRotatedModelExample(MIL_ID MilSystem, MIL_ID MilDisplay);
void AutoAllocationModelExample(MIL_ID MilSystem, MIL_ID MilDisplay);

/*****************************************************************************
 Main.
 *****************************************************************************/
void main(void)
   {
   MIL_ID MilApplication,     /* Application identifier. */
          MilSystem,          /* System identifier.      */
          MilDisplay;         /* Display identifier.     */

   printf("\nGRAYSCALE PATTERN MATCHING:\n");
   printf("---------------------------\n\n");

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Run the search at 0 degree example. */
   SearchModelExample(MilSystem, MilDisplay);

   /* Run the search over 360 degrees example. */
   SearchRotatedModelExample(MilSystem, MilDisplay);

   /* Run the automatic model allocation example. */
   AutoAllocationModelExample(MilSystem, MilDisplay);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   }

/*****************************************************************************/
/* Find model in shifted version of the image example. */

/* Source image file name. */
#define FIND_IMAGE_FILE    M_IMAGE_PATH MIL_TEXT("CircuitsBoard.mim")

/* Model position and size. */
#define FIND_MODEL_X_POS   153L
#define FIND_MODEL_Y_POS   132L
#define FIND_MODEL_WIDTH   128L
#define FIND_MODEL_HEIGHT  128L
#define FIND_MODEL_X_CENTER   (FIND_MODEL_X_POS+(FIND_MODEL_WIDTH -1)/2.0)
#define FIND_MODEL_Y_CENTER   (FIND_MODEL_Y_POS+(FIND_MODEL_HEIGHT-1)/2.0)

/* Target image shifting values. */
#define FIND_SHIFT_X        4.5
#define FIND_SHIFT_Y        7.5

/* Minimum match score to determine acceptability of model (default). */
#define FIND_MODEL_MIN_MATCH_SCORE 70.0

/* Minimum accuracy for the search. */
#define FIND_MODEL_MIN_ACCURACY    0.1

/* Absolute value macro. */
#define Absolute(x) (((x) < 0.0) ? -(x) : (x))

void SearchModelExample(MIL_ID MilSystem, MIL_ID MilDisplay)
{
   MIL_ID MilImage,                /* Image buffer identifier.  */
          MilOverlayImage,         /* Overlay image.            */
          Model,                   /* Model identifier.         */
          Result;                  /* Result identifier.        */
   double XOrg  = 0.0, YOrg = 0.0; /* Original model position.  */
   double x     = 0.0, y    = 0.0; /* Model position.           */
   double ErrX  = 0.0, ErrY = 0.0; /* Model error position.     */
   double Score = 0.0;             /* Model correlation score.  */
   double Time  = 0.0;             /* Model search time.        */
   long   AnnotationColor = M_COLOR_RED; /* Drawing color.      */

   /* Restore source image into an automatically allocated image buffer. */
   MbufRestore(FIND_IMAGE_FILE, MilSystem, &MilImage);

   /* Display the image buffer. */
   MdispSelect(MilDisplay, MilImage);

   /* Prepare for overlay annotations. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a normalized grayscale model. */
   MpatAllocModel(MilSystem, MilImage, FIND_MODEL_X_POS, FIND_MODEL_Y_POS,
                  FIND_MODEL_WIDTH, FIND_MODEL_HEIGHT, M_NORMALIZED, &Model);

   /* Set the search accuracy to high. */
   MpatSetAccuracy(Model, M_HIGH);

   /* Set the search model speed to high. */
   MpatSetSpeed(Model, M_HIGH);

   /* Preprocess the model. */
   MpatPreprocModel(MilImage, Model, M_DEFAULT);

   /* Draw a box around the model in the model image. */
   MgraColor(M_DEFAULT, AnnotationColor);
   MpatDraw(M_DEFAULT, Model, MilOverlayImage, M_DRAW_BOX+M_DRAW_POSITION,
                                                          M_DEFAULT, M_ORIGINAL);

   /* Pause to show the original image and model position. */
   printf("\nA %ldx%ld model was defined in the source image.\n",
                                 FIND_MODEL_WIDTH, FIND_MODEL_HEIGHT);
   printf("It will be found in an image shifted by %.2f in X and %.2f in Y.\n",
                                                         FIND_SHIFT_X, FIND_SHIFT_Y);
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Translate the image on a subpixel level. */
   MimTranslate(MilImage, MilImage, FIND_SHIFT_X, FIND_SHIFT_Y, M_DEFAULT);

   /* Allocate result buffer. */
   MpatAllocResult(MilSystem, 1L, &Result);

   /* First, perform a dummy find operation for better function timing accuracy
      (model cache effect,...) and reset the timer.
    */
   MpatFindModel(MilImage, Model, Result);
   MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

   /* Find the model in the target buffer. */
   MpatFindModel(MilImage, Model, Result);

   /* Read the time spent in MpatFindModel. */
   MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);

   /* If one model was found above the acceptance threshold. */
   if (MpatGetNumber(Result, M_NULL) == 1L)
      {
      /* Read results and draw a box around the model occurrence. */
      MpatGetResult(Result, M_POSITION_X, &x);
      MpatGetResult(Result, M_POSITION_Y, &y);
      MpatGetResult(Result, M_SCORE, &Score);
      MgraColor(M_DEFAULT, AnnotationColor);
      MpatDraw(M_DEFAULT, Result, MilOverlayImage, M_DRAW_BOX+M_DRAW_POSITION,
                                                              M_DEFAULT, M_DEFAULT);

      /* Calculate the position errors in X and Y and inquire original model position. */
      ErrX = fabs((FIND_MODEL_X_CENTER+FIND_SHIFT_X) - x);
      ErrY = fabs((FIND_MODEL_Y_CENTER+FIND_SHIFT_Y) - y);
      MpatInquire(Model, M_ORIGINAL_X, &XOrg);
      MpatInquire(Model, M_ORIGINAL_Y, &YOrg);

      /* Print out the search result of the model in the original image. */
      printf("Search results:\n");
      printf("---------------------------------------------------\n");
      printf("The model was found to have been shifted by\tX:%.2f, Y:%.2f.\n", x-XOrg, y-YOrg);
      printf("The model position error is \t\tX:%.2f, Y:%.2f\n", ErrX, ErrY);
      printf("The model match score is \t\t%.1f\n", Score);
      printf("The search time is \t\t\t%.3f ms\n\n", Time*1000.0);

      /* Verify the results. */
      if (
          (Absolute((x - XOrg) - FIND_SHIFT_X) > FIND_MODEL_MIN_ACCURACY) ||
          (Absolute((y - YOrg) - FIND_SHIFT_Y) > FIND_MODEL_MIN_ACCURACY) ||
          (Score                              < FIND_MODEL_MIN_MATCH_SCORE)
         )
         printf("Results verification error !\n");
      }
   else
      printf("Model not found !\n");

   /* Wait for a key to be pressed. */
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Free all allocations. */
   MpatFree(Result);
   MpatFree(Model);
   MbufFree(MilImage);
}

/*****************************************************************************/
/* Find rotated model example. */

/* Source image file name. */
#define ROTATED_FIND_IMAGE_FILE      M_IMAGE_PATH MIL_TEXT("CircuitsBoard.mim")

/* Image rotation values. */
#define ROTATED_FIND_ROTATION_DELTA_ANGLE  10
#define ROTATED_FIND_ROTATION_ANGLE_STEP   1
#define ROTATED_FIND_RAD_PER_DEG           0.01745329251

/* Model position and size. */
#define ROTATED_FIND_MODEL_X_POS           153L
#define ROTATED_FIND_MODEL_Y_POS           132L
#define ROTATED_FIND_MODEL_WIDTH           128L
#define ROTATED_FIND_MODEL_HEIGHT          128L

#define ROTATED_FIND_MODEL_X_CENTER           ROTATED_FIND_MODEL_X_POS+ \
                                             (ROTATED_FIND_MODEL_WIDTH -1)/2.0
#define ROTATED_FIND_MODEL_Y_CENTER           ROTATED_FIND_MODEL_Y_POS+ \
                                             (ROTATED_FIND_MODEL_HEIGHT-1)/2.0

/* Minimum accuracy for the search position. */
#define ROTATED_FIND_MIN_POSITION_ACCURACY     0.10

/* Minimum accuracy for the search angle. */
#define ROTATED_FIND_MIN_ANGLE_ACCURACY        0.25

/* Angle range to search. */
#define ROTATED_FIND_ANGLE_DELTA_POS           ROTATED_FIND_ROTATION_DELTA_ANGLE
#define ROTATED_FIND_ANGLE_DELTA_NEG           ROTATED_FIND_ROTATION_DELTA_ANGLE

/* Prototypes of utility functions. */
void RotateModelCenter(MIL_ID Buffer,
                       double *X,
                       double *Y,
                       double Angle);

double CalculateAngleDist(double Angle1,
                          double Angle2);

void SearchRotatedModelExample(MIL_ID MilSystem, MIL_ID MilDisplay)
   {
   MIL_ID MilSourceImage,              /* Model  image buffer identifier.   */
          MilTargetImage,              /* Target image buffer identifier.   */
          MilDisplayImage,             /* Target image buffer identifier.   */
          MilOverlayImage,             /* Overlay image.                    */
          MilModel,                    /* Model identifier.                 */
          MilResult;                   /* Result identifier.                */
   double RealX       = 0.0,           /* Model real position in x.         */
          RealY       = 0.0,           /* Model real position in y.         */
          RealAngle   = 0.0,           /* Model real angle.                 */
          X           = 0.0,           /* Model position in x found.        */
          Y           = 0.0,           /* Model position in y found.        */
          Angle       = 0.0,           /* Model angle found.                */
          Score       = 0.0,           /* Model correlation score.          */
          Time        = 0.0,           /* Model search time.                */
          ErrX        = 0.0,           /* Model error position in x.        */
          ErrY        = 0.0,           /* Model error position in y.        */
          ErrAngle    = 0.0,           /* Model error angle.                */
          SumErrX     = 0.0,           /* Model total error position in x.  */
          SumErrY     = 0.0,           /* Model total error position in y.  */
          SumErrAngle = 0.0,           /* Model total error angle.          */
          SumTime     = 0.0;           /* Model total search time.          */
   long   NbFound     = 0,             /* Number of models found.           */
          AnnotationColor = M_COLOR_RED;  /* Drawing color.                 */

   /* Load target image into image buffers and display it. */
   MbufRestore(ROTATED_FIND_IMAGE_FILE, MilSystem, &MilSourceImage);
   MbufRestore(ROTATED_FIND_IMAGE_FILE, MilSystem, &MilTargetImage);
   MbufRestore(ROTATED_FIND_IMAGE_FILE, MilSystem, &MilDisplayImage);
   MdispSelect(MilDisplay, MilDisplayImage);

   /* Prepare for overlay annotations. */
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a normalized grayscale model. */
   MpatAllocModel(MilSystem, MilSourceImage,
                  ROTATED_FIND_MODEL_X_POS, ROTATED_FIND_MODEL_Y_POS,
                  ROTATED_FIND_MODEL_WIDTH, ROTATED_FIND_MODEL_HEIGHT,
                  M_NORMALIZED+M_CIRCULAR_OVERSCAN, &MilModel);

   /* Set the search model speed. */
   MpatSetSpeed(MilModel, M_MEDIUM);

   /* Set the position search accuracy. */
   MpatSetAccuracy(MilModel, M_HIGH);

   /* Activate the search model angle mode. */
   MpatSetAngle(MilModel, M_SEARCH_ANGLE_MODE, M_ENABLE);

   /* Set the search model range angle. */
   MpatSetAngle(MilModel, M_SEARCH_ANGLE_DELTA_NEG, ROTATED_FIND_ANGLE_DELTA_NEG);
   MpatSetAngle(MilModel, M_SEARCH_ANGLE_DELTA_POS, ROTATED_FIND_ANGLE_DELTA_POS);

   /* Set the search model angle accuracy. */
   MpatSetAngle(MilModel, M_SEARCH_ANGLE_ACCURACY, ROTATED_FIND_MIN_ANGLE_ACCURACY);

   /* Set the search model angle interpolation mode to bilinear. */
   MpatSetAngle(MilModel, M_SEARCH_ANGLE_INTERPOLATION_MODE, M_BILINEAR);

   /* Preprocess the model. */
   MpatPreprocModel(MilSourceImage, MilModel, M_DEFAULT);

   /* Allocate a result buffer. */
   MpatAllocResult(MilSystem, 1L, &MilResult);

   /* Draw the original model position */
   MpatDraw(M_DEFAULT, MilModel, MilOverlayImage, M_DRAW_BOX+M_DRAW_POSITION,
                                                       M_DEFAULT, M_ORIGINAL);

   /* Pause to show the original image and model position. */
   printf("\nA %ldx%ld model was defined in the source image.\n",
                          ROTATED_FIND_MODEL_WIDTH, ROTATED_FIND_MODEL_HEIGHT);
   printf("It will be searched in images rotated from %ld degree to %ld degree.\n",
                    -ROTATED_FIND_ROTATION_DELTA_ANGLE, ROTATED_FIND_ROTATION_DELTA_ANGLE);
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* First, perform a dummy find operation to verify the model for better function timing accuracy. */
   MpatFindModel(MilSourceImage, MilModel, MilResult);

   /* If the model was found above the acceptance threshold. */
   if (MpatGetNumber(MilResult, M_NULL) == 1L)
      {
      /* Search for the model in images at different angles. */
      RealAngle = ROTATED_FIND_ROTATION_DELTA_ANGLE;
      while (RealAngle >= -ROTATED_FIND_ROTATION_DELTA_ANGLE)
         {
         /* Rotate the image from the model image to target image. */
         MimRotate(MilSourceImage, MilTargetImage, RealAngle, M_DEFAULT,
                   M_DEFAULT, M_DEFAULT, M_DEFAULT, M_BILINEAR+M_OVERSCAN_CLEAR);

         /* Reset the timer. */
         MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

         /* Find the model in the target image. */
         MpatFindModel(MilTargetImage, MilModel, MilResult);

         /* Read the time spent in MpatFindModel(). */
         MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);

         /* Clear the overlay image. */
         MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

         /* If one model was found above the acceptance threshold. */
         if (MpatGetNumber(MilResult, M_NULL) == 1L)
            {
            /* Read results and draw a box around model occurrence. */
            MpatGetResult(MilResult, M_POSITION_X, &X);
            MpatGetResult(MilResult, M_POSITION_Y, &Y);
            MpatGetResult(MilResult, M_ANGLE, &Angle);
            MpatGetResult(MilResult, M_SCORE, &Score);

            MgraColor(M_DEFAULT, AnnotationColor);
            MpatDraw(M_DEFAULT, MilResult, MilOverlayImage,
                     M_DRAW_BOX+M_DRAW_POSITION, M_DEFAULT, M_DEFAULT);

            MbufCopy(MilTargetImage, MilDisplayImage);

            /* Calculate the angle error and the position errors for statistics. */
            ErrAngle = CalculateAngleDist(Angle, RealAngle);

            RotateModelCenter(MilSourceImage, &RealX, &RealY, RealAngle);
            ErrX = fabs(X - RealX);
            ErrY = fabs(Y - RealY);

            SumErrAngle += ErrAngle;
            SumErrX += ErrX;
            SumErrY += ErrY;
            SumTime += Time;
            NbFound++;

            /* Verify the precision for the position and the angle. */
            if ((ErrX > ROTATED_FIND_MIN_POSITION_ACCURACY) ||
                (ErrY > ROTATED_FIND_MIN_POSITION_ACCURACY) ||
                (ErrAngle > ROTATED_FIND_MIN_ANGLE_ACCURACY))
               {
               printf("Model accuracy error at angle %.1f !\n\n", RealAngle);
               printf("Errors are X:%.3f, Y:%.3f and Angle:%.2f\n\n", ErrX, ErrY, ErrAngle);
               printf("Press <Enter> to continue.\n\n");
               getch();
               }
            }
         else
            {
            printf("Model was not found at angle %.1f !\n\n", RealAngle);
            printf("Press <Enter> to continue.\n\n");
            getch();
            }

         RealAngle -= ROTATED_FIND_ROTATION_ANGLE_STEP;
         }

      /* Print out the search result statistics */
      /* of the models found in rotated images. */
      printf("\nSearch statistics for the model found in the rotated images.\n");
      printf("------------------------------------------------------------\n");
      printf("The average position error is \t\tX:%.3f, Y:%.3f\n", SumErrX/NbFound, SumErrY/NbFound);
      printf("The average angle error is \t\t%.3f\n", SumErrAngle/NbFound);
      printf("The average search time is \t\t%.3f ms\n\n", SumTime*1000.0/NbFound);
      }
   else
      {
      printf("Model was not found!\n\n");
      }

   /* Wait for a key to be pressed. */
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Free all allocations. */
   MpatFree(MilResult);
   MpatFree(MilModel);
   MbufFree(MilTargetImage);
   MbufFree(MilSourceImage);
   MbufFree(MilDisplayImage);
   }

/* Calculate the rotated center of the model to compare the accuracy with
 *  the center of the occurrence found during pattern matching.
 */
void RotateModelCenter(MIL_ID Buffer,
                       double *X,
                       double *Y,
                       double Angle)
   {
   long   BufSizeX = MbufInquire(Buffer, M_SIZE_X, M_NULL);
   long   BufSizeY = MbufInquire(Buffer, M_SIZE_Y, M_NULL);
   double RadAngle = Angle * ROTATED_FIND_RAD_PER_DEG;
   double CosAngle = cos(RadAngle);
   double SinAngle = sin(RadAngle);

   double OffSetX = (BufSizeX-1)/2.0F;
   double OffSetY = (BufSizeY-1)/2.0F;

   *X = (ROTATED_FIND_MODEL_X_CENTER-OffSetX)*CosAngle + (ROTATED_FIND_MODEL_Y_CENTER-OffSetY)*SinAngle + OffSetX;
   *Y = (ROTATED_FIND_MODEL_Y_CENTER-OffSetY)*CosAngle - (ROTATED_FIND_MODEL_X_CENTER-OffSetX)*SinAngle + OffSetY;
   }

/* Calculate the absolute difference between the real angle
 * and the angle found.
 */
double CalculateAngleDist(double Angle1, double Angle2)
   {
   double dist = fabs(Angle1 - Angle2);

   while(dist >= 360.0)
      dist -= 360.0;

   if(dist > 180.0)
      dist = 360.0 - dist;

   return dist;
   }

/*****************************************************************************/
/* Automatic model allocation example. */

/* Source and target images file specifications. */
#define AUTO_MODEL_IMAGE_FILE         M_IMAGE_PATH MIL_TEXT("Wafer.mim")
#define AUTO_MODEL_TARGET_IMAGE_FILE  M_IMAGE_PATH MIL_TEXT("WaferShifted.mim")
//#define AUTO_MODEL_IMAGE_FILE         M_IMAGE_PATH MIL_TEXT("CircuitsBoard.mim")
//#define AUTO_MODEL_TARGET_IMAGE_FILE  M_IMAGE_PATH MIL_TEXT("CircuitsBoard.mim")

/* Model width and height */
#define AUTO_MODEL_WIDTH   64L
#define AUTO_MODEL_HEIGHT  64L

void AutoAllocationModelExample(MIL_ID MilSystem, MIL_ID MilDisplay)
{
   MIL_ID MilImage,                /* Image buffer identifier.             */
          MilOverlayImage,         /* Overlay image.                       */
          MilSubImage,             /* Sub-image buffer identifier.         */
          MilOverlaySubImage,      /* Overlay sub-image buffer identifier. */
          Model,                   /* Model identifier.                    */
          Result;                  /* Result buffer identifier.            */
   long   AllocError;              /* Allocation error variable.           */
   long   ImageWidth, ImageHeight; /* Target image dimensions              */
   double OrgX=0.0, OrgY=0.0;      /* Original center of model.            */
   double x=0.0, y=0.0, Score=0.0; /* Result variables.                    */
   long   AnnotationColor = M_COLOR_RED; /* Drawing color.                 */

   /* Load model image into an image buffer. */
   MbufRestore(AUTO_MODEL_IMAGE_FILE, MilSystem, &MilImage);

   /* Display the image and prepare for overlay annotations. */
   MdispSelect(MilDisplay, MilImage);
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Restrict the region to be processed to the bottom right corner of the image. */
   MbufInquire(MilImage, M_SIZE_X, &ImageWidth);
   MbufInquire(MilImage, M_SIZE_Y, &ImageHeight);
   MbufChild2d(MilImage, ImageWidth/2, ImageHeight/2,
                         ImageWidth/2, ImageHeight/2, &MilSubImage);
   MbufChild2d(MilOverlayImage, ImageWidth/2, ImageHeight/2,
                         ImageWidth/2, ImageHeight/2, &MilOverlaySubImage);

   /* Automatically allocate a normalized grayscale type model. */
   MpatAllocAutoModel(MilSystem, MilSubImage, AUTO_MODEL_WIDTH, AUTO_MODEL_HEIGHT,
                      M_DEFAULT, M_DEFAULT, M_NORMALIZED, M_DEFAULT, &Model);

   /* Set the search accuracy to high. */
   MpatSetAccuracy(Model, M_HIGH);

   /* Check for that model allocation was successful. */
   MappGetError(M_CURRENT, &AllocError);
   if (!AllocError)
      {
      /* Draw a box around the model. */
      MgraColor(M_DEFAULT, AnnotationColor);
      MpatDraw(M_DEFAULT, Model, MilOverlaySubImage, M_DRAW_BOX+M_DRAW_POSITION,
                                                                M_DEFAULT, M_ORIGINAL);
      printf("A model was automatically defined in the image.\n");
      printf("Press <Enter> to continue.\n\n");
      getch();

      /* Clear the overlay image. */
      MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

      /* Load target image into an image buffer. */
      MbufLoad(AUTO_MODEL_TARGET_IMAGE_FILE, MilImage);

      /* Allocate result. */
      MpatAllocResult(MilSystem, 1L, &Result);

      /* Find model. */
      MpatFindModel(MilSubImage, Model, Result);

      /* If one model was found above the acceptance threshold set. */
      if (MpatGetNumber(Result, M_NULL) == 1L)
         {
         /* Get results. */
         MpatGetResult(Result, M_POSITION_X, &x);
         MpatGetResult(Result, M_POSITION_Y, &y);
         MpatGetResult(Result, M_SCORE, &Score);

         /* Draw a box around the occurrence. */
         MgraColor(M_DEFAULT, AnnotationColor);
         MpatDraw(M_DEFAULT, Result, MilOverlaySubImage, M_DRAW_BOX+M_DRAW_POSITION,
                                                                    M_DEFAULT, M_DEFAULT);

         /* Analyze and print results. */
         MpatInquire(Model,M_ORIGINAL_X,&OrgX);
         MpatInquire(Model,M_ORIGINAL_Y,&OrgY);
         printf("An image misaligned by 50 pixels in X and 20 pixels in Y was loaded.\n\n");
         printf("The image was found to be shifted by %.2f in X, and %.2f in Y.\n",x-OrgX, y-OrgY);
         printf("Model match score is %.1f percent.\n", Score);
         printf("Press <Enter> to end.\n\n");
         getch();
         }
      else
         {
         printf("Error: Pattern not found properly.\n");
         printf("Press <Enter> to end.\n\n");
         getch();
         }

      /* Free result buffer and model. */
      MpatFree(Result);
      MpatFree(Model);
      }
   else
      {
      printf("Error: Automatic model definition failed.\n");
      printf("Press <Enter> to end.\n\n");
      getch();
      }

   /* Clear the overlay image. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Free child buffer and defaults. */
   MbufFree(MilSubImage);
   MbufFree(MilOverlaySubImage);
   MbufFree(MilImage);
}


Example: mstr.c

/*******************************************************************************/
/*
* File name: MStr.c
*
* Synopsis:  This program uses the String Reader module to define a font
*            from an image containing a mosaic of Quebec license plates.
*            Two String Models are then defined and parameterized to read
*            only some valid Quebec license plates.
*            A license plate reading is then performed in a target image
*            of a car on the road.
*/
#include <mil.h>
#include <conio.h>

/* MIL image file specifications. */
#define IMAGE_FILE_DEFINITION M_IMAGE_PATH MIL_TEXT("QcPlates.mim")
#define IMAGE_FILE_TO_READ    M_IMAGE_PATH MIL_TEXT("LicPlate.mim")

/* String containing all characters used for font definition. */
#define TEXT_DEFINITION       "AVS300CVK781JNK278 EBX380QKN918HCC839 YRH900ZQR756977AMQ GPK742389EYE569ESQ"

/* Font normalization size Y. */
#define NORMALIZATION_SIZE_Y    20L

/* Max size of plate string. */
#define STRING_MAX_SIZE         32L

/*****************************************************************************/
/* Main. */
void main(void)
   {
   MIL_ID MilApplication,                          /* Application identifier.          */
          MilSystem,                               /* System identifier.               */
          MilDisplay,                              /* Display identifier.              */
          MilImage,                                /* Image buffer identifier.         */
          MilOverlayImage,                         /* Overlay image.                   */
          MilStrContext,                           /* String context identifier.       */
          MilStrResult;                            /* String result buffer identifier. */
   long   NumberOfStringRead;                      /* Total number of strings to read. */
   double Score;                                   /* String score.                    */
   char*  StringResult[STRING_MAX_SIZE+1];         /* String of characters read.       */
   double Time = 0.0;                              /* Time variable.                   */

   /* Print module name. */
   printf("\nSTRING READER MODULE:\n");
   printf("---------------------\n\n");

   /* Allocate defaults */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Restore the font definition image */
   MbufRestore(IMAGE_FILE_DEFINITION, MilSystem, &MilImage);

   /* Display the image and prepare for overlay annotations. */
   MdispSelect(MilDisplay, MilImage);
   MdispControl(MilDisplay, M_OVERLAY, M_ENABLE);
   MdispInquire(MilDisplay, M_OVERLAY_ID, &MilOverlayImage);

   /* Allocate a new empty String Reader context. */
   MstrAlloc( MilSystem, M_FEATURE_BASED, M_DEFAULT, &MilStrContext);

   /* Allocate a new empty String Reader result buffer. */
   MstrAllocResult(MilSystem, M_DEFAULT, &MilStrResult);

   /* Add a new empty user defined font to the context. */
   MstrControl(MilStrContext, M_CONTEXT, M_FONT_ADD, M_USER_DEFINED);

   /* Add user defined characters from the license plate mosaic image. */
   MstrEditFont(MilStrContext, M_FONT_INDEX(0), M_CHAR_ADD,
                M_USER_DEFINED + M_FOREGROUND_BLACK,
                MilImage, TEXT_DEFINITION, M_NULL);

   /* Draw all the characters in the font in the overlay image. */
   MgraColor(M_DEFAULT, M_COLOR_GREEN);
   MstrDraw(M_DEFAULT, MilStrContext, MilOverlayImage, M_DRAW_CHAR,
            M_FONT_INDEX(0), M_NULL, M_ORIGINAL);

   /* Normalize the characters of the font to an appropriate size. */
   MstrEditFont(MilStrContext, M_FONT_INDEX(0), M_CHAR_NORMALIZE,
                M_SIZE_Y, NORMALIZATION_SIZE_Y, M_NULL, M_NULL);

   /* Add 2 new empty strings models to the context for the 2 valid types of
      plates (3 letters followed by 3 numbers or 3 numbers followed by 3 letters)
      Note that the read time increases with the number of strings in the context.
   */
   MstrControl(MilStrContext, M_CONTEXT, M_STRING_ADD, M_USER_DEFINED);
   MstrControl(MilStrContext, M_CONTEXT, M_STRING_ADD, M_USER_DEFINED);

   /* Set number of strings to read. */
   MstrControl(MilStrContext, M_CONTEXT, M_STRING_NUMBER, 1);

   /* Set number of expected characters for all string models to 6 characters. */
   MstrControl(MilStrContext, M_STRING_INDEX(M_ALL), M_STRING_SIZE_MIN, 6);
   MstrControl(MilStrContext, M_STRING_INDEX(M_ALL), M_STRING_SIZE_MAX, 6);

   /* Set default constraint to uppercase letter for all string models */
   MstrSetConstraint(MilStrContext, M_STRING_INDEX(0), M_DEFAULT, M_LETTER + M_UPPERCASE, M_NULL );
   MstrSetConstraint(MilStrContext, M_STRING_INDEX(1), M_DEFAULT, M_LETTER + M_UPPERCASE, M_NULL );

   /* Set constraint of 3 last characters to digit for the first string model */
   MstrSetConstraint(MilStrContext, M_STRING_INDEX(0), 3, M_DIGIT, M_NULL );
   MstrSetConstraint(MilStrContext, M_STRING_INDEX(0), 4, M_DIGIT, M_NULL );
   MstrSetConstraint(MilStrContext, M_STRING_INDEX(0), 5, M_DIGIT, M_NULL );

   /* Set constraint of 3 first characters to digit for the second string model */
   MstrSetConstraint(MilStrContext, M_STRING_INDEX(1), 0, M_DIGIT, M_NULL );
   MstrSetConstraint(MilStrContext, M_STRING_INDEX(1), 1, M_DIGIT, M_NULL );
   MstrSetConstraint(MilStrContext, M_STRING_INDEX(1), 2, M_DIGIT, M_NULL );

   /* Pause to show the font definition. */
   printf("This program has defined a font with this Quebec plates mosaic image.\n");
   printf("Press <Enter> to continue.\n\n");
   getch();

   /* Clear the display overlay. */
   MdispControl(MilDisplay, M_OVERLAY_CLEAR, M_DEFAULT);

   /* Load image to read into image buffer. */
   MbufLoad(IMAGE_FILE_TO_READ, MilImage);

   /* Preprocess the String Reader context. */
   MstrPreprocess(MilStrContext, M_DEFAULT);

   /* First, perform a dummy read for better function timing accuracy (model cache effet,...). */
   MstrRead(MilStrContext, MilImage, MilStrResult);

   /* Reset the timer. */
   MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

   /* Perform the read operation on the specified target image. */
   MstrRead(MilStrContext, MilImage, MilStrResult);

   /* Read the time. */
   MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);

   /* Get number of strings read and show the result. */
   MstrGetResult(MilStrResult, M_GENERAL, M_STRING_NUMBER + M_TYPE_LONG, &NumberOfStringRead);
   if( NumberOfStringRead >= 1)
      {
      printf("The license plate was read successfully (%.2lf ms)\n\n", Time*1000 );

      /* Draw read result. */
      MgraColor(M_DEFAULT, M_COLOR_BLUE);
      MstrDraw(M_DEFAULT, MilStrResult, MilOverlayImage, M_DRAW_STRING, M_ALL, M_NULL, M_DEFAULT);
      MgraColor(M_DEFAULT, M_COLOR_GREEN);
      MstrDraw(M_DEFAULT, MilStrResult, MilOverlayImage, M_DRAW_STRING_BOX, M_ALL, M_NULL, M_DEFAULT);

      /* Print the read result. */
      printf(" String                   Score\n" );
      printf(" ---------------------------------------\n" );
      MstrGetResult(MilStrResult, 0, M_STRING, StringResult);
      MstrGetResult(MilStrResult, 0, M_STRING_SCORE, &Score);
      printf(" %s                  %.1lf\n", StringResult, Score );
      }
   else
      {
      printf("Error: Plate was not read.\n");
      }

   /* Pause to show results. */
   printf("\nPress <Enter> to end.\n\n");
   getch();

   /* Free all allocations. */
   MstrFree(MilStrContext);
   MstrFree(MilStrResult);
   MbufFree(MilImage);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   }


Example: mthread.c

/*******************************************************************************/
/*
 * File name: MThread.c
 *
 * Synopsis:  This program shows how to use threads in a MIL application and
 *            synchronize them with event. It creates 4 processing threads that
 *            are used to work in 4 different regions of a display buffer.
 *
 *     Thread usage:
 *      - The main thread starts a processing thread in each of the 4 different
 *        quarters of a display buffer. The main thread then waits for a key to
 *        be pressed to stop them.
 *      - The top-left and bottom-left threads work in a loop, as follows: the
 *        top-left thread adds a constant to its buffer, then sends an event to
 *        the bottom-left thread. The bottom-left thread waits for the event
 *        from the top-left thread, rotates the top-left buffer image, then sends an
 *        event to the top-left thread to start a new loop.
 *      - The top-right and bottom-right threads work the same way as the
 *        top-left and bottom-left threads, except that the bottom-right thread
 *        performs an edge detection operation, rather than a rotation.
 *
 *      Note : Under MIL-Lite, the threads will do graphic annotations instead.
 */
#include <mil.h>
#include <conio.h>
#include <windows.h>

/* Local defines. */
#define IMAGE_FILE         M_IMAGE_PATH MIL_TEXT("Bird.mim")
#define IMAGE_WIDTH        256L
#define IMAGE_HEIGHT       240L
#define STRING_LENGHT_MAX  40
#define STRING_POS_X       10
#define STRING_POS_Y       220
#define DRAW_RADIUS_NUMBER 5
#define DRAW_RADIUS_STEP   10
#define DRAW_CENTER_POSX   196
#define DRAW_CENTER_POSY   180

/* Function prototypes. */
unsigned long MFTYPE TopThread(void *TPar);
unsigned long MFTYPE BotLeftThread(void *TPar);
unsigned long MFTYPE BotRightThread(void *TPar);
void BalanceThreadScheduling();

/* Thread parameters structure. */
typedef struct ThreadParam
   {
   MIL_ID Id;
   MIL_ID System;
   MIL_ID SrcImage;
   MIL_ID DstImage;
   MIL_ID ReadyEvent;
   MIL_ID DoneEvent;
   long   NumberOfIteration;
   long   Radius;
   long   Exit;
   struct ThreadParam *SlaveThreadParam;
   } THREAD_PARAM;

/* Main function: */
/* -------------- */
void main(void)
   {
   MIL_ID MilApplication,        /* Application identifier.                    */
          MilSystem,             /* System identifier.                         */
          MilDisplay,            /* Display identifier.                        */
          MilImage;              /* Image buffer identifiers.                  */
   THREAD_PARAM TParTopLeft,     /* Parameters passed to top left thread.      */
                TParBotLeft,     /* Parameters passed to bottom left thread.   */
                TParTopRight,    /* Parameters passed to top right thread.     */
                TParBotRight;    /* Parameters passed to bottom right thread.  */

   /* Allocate defaults. */
   MappAllocDefault(M_SETUP, &MilApplication, &MilSystem, &MilDisplay, M_NULL, M_NULL);

   /* Allocate and display the main image buffer. */
   MbufAlloc2d(MilSystem, IMAGE_WIDTH*2, IMAGE_HEIGHT*2, 8+M_UNSIGNED,
                                         M_IMAGE+M_PROC+M_DISP, &MilImage);
   MbufClear(MilImage, 0);
   MdispSelect(MilDisplay,MilImage);

   /* Allocate a destination child buffer for each thread. */
   MbufChild2d(MilImage, 0,            0, IMAGE_WIDTH, IMAGE_HEIGHT, &TParTopLeft.SrcImage);
   MbufChild2d(MilImage, 0, IMAGE_HEIGHT, IMAGE_WIDTH, IMAGE_HEIGHT, &TParBotLeft.DstImage);
   MbufChild2d(MilImage, IMAGE_WIDTH,  0, IMAGE_WIDTH, IMAGE_HEIGHT, &TParTopRight.SrcImage);
   MbufChild2d(MilImage, IMAGE_WIDTH, IMAGE_HEIGHT,IMAGE_WIDTH, IMAGE_HEIGHT, &TParBotRight.DstImage);

   /* Allocate synchronization events. */
   MthrAlloc(MilSystem, M_EVENT, M_DEFAULT, M_NULL, M_NULL, &TParTopLeft.DoneEvent);
   MthrAlloc(MilSystem, M_EVENT, M_DEFAULT, M_NULL, M_NULL, &TParBotLeft.DoneEvent);
   MthrAlloc(MilSystem, M_EVENT, M_DEFAULT, M_NULL, M_NULL, &TParTopRight.DoneEvent);
   MthrAlloc(MilSystem, M_EVENT, M_DEFAULT, M_NULL, M_NULL, &TParBotRight.DoneEvent);

   /* Intitalize remaining thread parameters. */
   TParTopLeft.System               = MilSystem;
   TParTopLeft.DstImage             = TParTopLeft.SrcImage;
   TParTopLeft.ReadyEvent           = TParBotLeft.DoneEvent;
   TParTopLeft.NumberOfIteration    = 0;
   TParTopLeft.Radius               = 0;
   TParTopLeft.Exit                 = 0;
   TParTopLeft.SlaveThreadParam     = &TParBotLeft;

   TParBotLeft.System               = MilSystem;
   TParBotLeft.SrcImage             = TParTopLeft.DstImage;
   TParBotLeft.ReadyEvent           = TParTopLeft.DoneEvent;
   TParBotLeft.NumberOfIteration    = 0;
   TParBotLeft.Radius               = 0;
   TParBotLeft.Exit                 = 0;
   TParBotLeft.SlaveThreadParam     = 0;

   TParTopRight.System              = MilSystem;
   TParTopRight.DstImage            = TParTopRight.SrcImage;
   TParTopRight.ReadyEvent          = TParBotRight.DoneEvent;
   TParTopRight.NumberOfIteration   = 0;
   TParTopRight.Radius              = 0;
   TParTopRight.Exit                = 0;
   TParTopRight.SlaveThreadParam    = &TParBotRight;

   TParBotRight.System              = MilSystem;
   TParBotRight.SrcImage            = TParTopRight.DstImage;
   TParBotRight.ReadyEvent          = TParTopRight.DoneEvent;
   TParBotRight.NumberOfIteration   = 0;
   TParBotRight.Radius              = 0;
   TParBotRight.Exit                = 0;
   TParBotRight.SlaveThreadParam    = 0;

   /* Initialize the top buffers to process. */
   MbufLoad(IMAGE_FILE, TParTopLeft.SrcImage);
   MbufLoad(IMAGE_FILE, TParTopRight.SrcImage);

   /* Start the 4 threads. */
   MthrAlloc(M_DEFAULT, M_THREAD, M_DEFAULT, &TopThread     , &TParTopLeft,  &TParTopLeft.Id);
   MthrAlloc(M_DEFAULT, M_THREAD, M_DEFAULT, &BotLeftThread , &TParBotLeft,  &TParBotLeft.Id);
   MthrAlloc(M_DEFAULT, M_THREAD, M_DEFAULT, &TopThread     , &TParTopRight, &TParTopRight.Id);
   MthrAlloc(M_DEFAULT, M_THREAD, M_DEFAULT, &BotRightThread, &TParBotRight, &TParBotRight.Id);

   /* Set events to start operation of top left and top right threads. */
   MthrControl(TParTopLeft.ReadyEvent,  M_EVENT_SET, M_SIGNALED);
   MthrControl(TParTopRight.ReadyEvent, M_EVENT_SET, M_SIGNALED);

   /* Report that the threads are started and wait for a key press to stop them. */
   printf("\nMULTI-THREADING:\n");
   printf("----------------\n\n");
   printf("4 threads running...\n");
   printf("Press <Enter> to stop.\n\n");
   getch();

   /* Signal the threads to exit. */
   TParTopLeft.Exit  = 1;
   TParTopRight.Exit = 1;

   /* Wait for all threads to terminate. */
   MthrWait(TParTopLeft.Id , M_THREAD_END_WAIT, M_NULL);
   MthrWait(TParBotLeft.Id , M_THREAD_END_WAIT, M_NULL);
   MthrWait(TParTopRight.Id, M_THREAD_END_WAIT, M_NULL);
   MthrWait(TParBotRight.Id, M_THREAD_END_WAIT, M_NULL);

   /* Print statistics. */
   printf("Top left iterations done:     %4ld.\n", TParTopLeft.NumberOfIteration);
   printf("Bottom left iterations done:  %4ld.\n", TParBotLeft.NumberOfIteration);
   printf("Top right iterations done:    %4ld.\n", TParTopRight.NumberOfIteration);
   printf("Bottom right iterations done: %4ld.\n", TParBotRight.NumberOfIteration);
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free threads. */
   MthrFree(TParTopLeft.Id);
   MthrFree(TParBotLeft.Id);
   MthrFree(TParTopRight.Id);
   MthrFree(TParBotRight.Id);

   /* Free events. */
   MthrFree(TParTopLeft.DoneEvent);
   MthrFree(TParBotLeft.DoneEvent);
   MthrFree(TParTopRight.DoneEvent);
   MthrFree(TParBotRight.DoneEvent);

   /* Free buffers. */
   MbufFree(TParTopLeft.SrcImage);
   MbufFree(TParTopRight.SrcImage);
   MbufFree(TParBotLeft.DstImage);
   MbufFree(TParBotRight.DstImage);
   MbufFree(MilImage);

   /* Free defaults. */
   MappFreeDefault(MilApplication, MilSystem, MilDisplay, M_NULL, M_NULL);
   }

/* Top left and top right threads' function (Add an offset): */
/* --------------------------------------------------------- */
unsigned long MFTYPE TopThread(void *ThreadParameters)
{
   THREAD_PARAM  *TPar = (THREAD_PARAM *)ThreadParameters;
   MIL_TEXT_CHAR Text[STRING_LENGHT_MAX];

   while (!TPar->Exit)
      {
      /* Wait for bottom ready event before proceeding. */
      MthrWait(TPar->ReadyEvent, M_EVENT_WAIT, M_NULL);

      /* If processing available, Add a constant to the image. */
      #if (!M_MIL_LITE)
         {
         MimArith(TPar->SrcImage, 5L, TPar->DstImage, M_ADD_CONST);
         }
      /* else draw a filled rectangle. */
      #else
         {
         TPar->Radius = TPar->SlaveThreadParam->Radius = (TPar->NumberOfIteration % DRAW_RADIUS_NUMBER) * DRAW_RADIUS_STEP;
         if (TPar->Radius == 0)
            MbufLoad(IMAGE_FILE, TPar->DstImage);
         MgraColor(M_DEFAULT, 0xff);
         MgraRectFill(M_DEFAULT, TPar->DstImage,
                      DRAW_CENTER_POSX - TPar->Radius, DRAW_CENTER_POSY - TPar->Radius,
                      DRAW_CENTER_POSX + TPar->Radius, DRAW_CENTER_POSY + TPar->Radius);
         }
      #endif

      /* Increment iteration count and draw text. */
      TPar->NumberOfIteration++;
      MgraColor(M_DEFAULT, 0xFF);
      MOs_ltoa(TPar->NumberOfIteration, Text, 10);
      MgraText(M_DEFAULT, TPar->DstImage, STRING_POS_X, STRING_POS_Y, Text);

      /* Signal to the bottom thread that the first part of processing is complete. */
      MthrControl(TPar->DoneEvent, M_EVENT_SET, M_SIGNALED);

      /* For a smoother display effect, optional yield to the other threads. */
      BalanceThreadScheduling();
      }

   /* Require the bottom thread to exit. */
   TPar->SlaveThreadParam->Exit = 1;

   /* Signal the bottom thread end to wake up. */
   MthrControl(TPar->DoneEvent, M_EVENT_SET, M_SIGNALED);

   return(1L);
}

/* Bottom-left thread function (Rotate): */
/* ------------------------------------- */
unsigned long MFTYPE BotLeftThread(void *ThreadParameters)
{
   THREAD_PARAM  *TPar = (THREAD_PARAM *)ThreadParameters;
   MIL_TEXT_CHAR Text[STRING_LENGHT_MAX];

   while (!TPar->Exit)
      {
      /* Wait for the event in top-left function to be ready before proceeding. */
      MthrWait(TPar->ReadyEvent, M_EVENT_WAIT, M_NULL);

      /* If processing available, add a constant to the image. */
      #if (!M_MIL_LITE)
         {
         MimRotate(TPar->SrcImage, TPar->DstImage, (TPar->NumberOfIteration*5)%360,
                   M_DEFAULT, M_DEFAULT, M_DEFAULT, M_DEFAULT, M_NEAREST_NEIGHBOR+M_OVERSCAN_CLEAR);
         }
      /* else copy the top image and draw a filled circle. */
      #else
         {
         MbufCopy(TPar->SrcImage,TPar->DstImage);
         MgraColor(M_DEFAULT, 0x80);
         MgraArcFill(M_DEFAULT, TPar->DstImage, DRAW_CENTER_POSX, DRAW_CENTER_POSY,
                                                TPar->Radius, TPar->Radius, 0, 360);
         }
      #endif

      /* Print iteration count and draw a circle. */
      TPar->NumberOfIteration++;
      MgraColor(M_DEFAULT, 0xFF);
      MOs_ltoa(TPar->NumberOfIteration, Text, 10);
      MgraText(M_DEFAULT, TPar->DstImage, STRING_POS_X, STRING_POS_Y, Text);

      /* Signal to the top thread that the last part of the processing is complete. */
      MthrControl(TPar->DoneEvent, M_EVENT_SET, M_SIGNALED);

      /* For a smoother display effect, optional yield to the other threads. */
      BalanceThreadScheduling();
      }

   return(1L);
}

/* Bottom-right thread function (Edge Detect): */
/* ------------------------------------------- */
unsigned long MFTYPE BotRightThread(void *ThreadParameters)
{
   THREAD_PARAM  *TPar = (THREAD_PARAM *)ThreadParameters;
   MIL_TEXT_CHAR Text[STRING_LENGHT_MAX];

   while (!TPar->Exit)
      {
      /* Wait for the event in top-right function to be ready before proceeding. */
      MthrWait(TPar->ReadyEvent, M_EVENT_WAIT, M_NULL);

      /* If processing available, add a constant to the image. */
      #if (!M_MIL_LITE)
         {
         MimConvolve(TPar->SrcImage, TPar->DstImage, M_EDGE_DETECT);
         }
      /* else copy the top image and draw a filled circle. */
      #else
         {
         MbufCopy(TPar->SrcImage,TPar->DstImage);
         MgraColor(M_DEFAULT, 0x40);
         MgraArcFill(M_DEFAULT, TPar->DstImage, DRAW_CENTER_POSX, DRAW_CENTER_POSY,
                     TPar->Radius/2, TPar->Radius/2, 0, 360);
         }
      #endif

      /* Increment iteration count and draw text. */
      TPar->NumberOfIteration++;
      MgraColor(M_DEFAULT, 0xFF);
      MOs_ltoa(TPar->NumberOfIteration, Text, 10);
      MgraText(M_DEFAULT, TPar->DstImage, STRING_POS_X, STRING_POS_Y, Text);

      /* Signal to the top thread that the last part of the processing is complete. */
      MthrControl(TPar->DoneEvent, M_EVENT_SET, M_SIGNALED);

      /* For a smoother display effect, optional yield to the other threads. */
      BalanceThreadScheduling();
      }

   return(1L);
}

/* Thread Scheduling Adjustment Handling */
/* ------------------------------------- */
/*                                                                                       */
/* This function is used to give a smoother display effect. It balances the number of    */
/* iterations of each thread by yielding its time slice frequently.                      */
/*                                                                                       */
/* NOTE: In some situations, Windows adjusts the priority or quantum value of threads.   */
/*       The intent of these adjustments is to improve system throughput and             */
/*       responsiveness. However, like any scheduling algorithms these adjustments are   */
/*       not perfect, and they might not be beneficial to all applications. The          */
/*       following function is introduced to minimize the impact of thread scheduling    */
/*       adjustment as performed by Windows. Refer to the "Inside Windows NT             */
/*       (Second Edition, Microsoft Press, 1998, ISBN 1-57231-677-2)" manual for more    */
/*       details on thread scheduling under Windows.                                     */
void BalanceThreadScheduling()
{
   Sleep(0);
}


Example: muart.c

/* File name: muart.c
 * Synopsis:  This program allows you to test all the UART features
 *            to read and write data.  The user must physically link
 *            the UART connector on the Matrox board to the specified
 *            COM port on the same computer.
 *
 * Note :     This example will only run with Matrox boards that support
 *            the UART features. These boards are: Matrox Meteor_II,
 *            Matrox Meteor_II/MC, Matrox Meteor_II/DIG
 *            and Matrox Corona_II.
 */

/* Headers. */
#include <stdio.h>
#include <mil.h>
#include <windows.h>

/* Data string to be sent. */
#define TEST_STRING        "This is a test string."

/* UART configuration parameters. */

/* See board specific notes for a complete list of available baud rates. */
#define CONFIG_SPEED       19200

/* Only 1 or 2 stop bits are allowed. */
#define CONFIG_STOP_BITS   1

/* Only 7 or 8 data bits are allowed. */
#define CONFIG_DATA_LENGTH 8

/* Parity can be set to M_DISABLE, M_ODD or M_EVEN. */
#define CONFIG_PARITY      M_DISABLE

/* Standard windows COM port name. */
#define COM_PORT_NUMBER    MIL_TEXT("COM1")

/* Hooked Data Struct. */
typedef struct
{
   MIL_ID Digitizer;
   char   *ReadBuffer;
   long   ReadSize;
   long   ReadPosition;
}UartHook;

/* Hooked function prototypes. */
long MFTYPE ReadHook(long , MIL_ID , void MPTYPE *);

int main(void)
{
   MIL_ID MilApplication,  /* Application identifier.  */
          MilSystem,       /* System identifier.       */
          MilDigitizer;    /* Digitizer identifier.    */

   DCB dcb;                /* Windows COM port configuration struct. */
   HANDLE hCom;            /* Windows COM port handle.  */

   char *TestString;
   char *ReadBuffer;
   long SendSize;
   long ReadSize;
   long SentSize;
   long i;
   long volatile DoSomething=0;

   volatile UartHook UserStruct;

   /* String buffer allocations. */
   TestString = TEST_STRING;
   SendSize = strlen( TestString );
   ReadBuffer = malloc ( SendSize + 1 );
   for ( i=0; i<=SendSize ; i++ )
      ReadBuffer[i] = '\0';

   /* MIL allocations. */
   MappAlloc( M_DEFAULT, &MilApplication );
   MsysAlloc( M_SYSTEM_SETUP, M_DEFAULT, M_DEFAULT, &MilSystem);
   MdigAlloc( MilSystem, M_DEFAULT, M_CAMERA_SETUP, M_DEFAULT, &MilDigitizer);

   /* Changing UART configuration on Matrox board. */
   MdigControl( MilDigitizer, M_UART_PARITY,       CONFIG_PARITY      );
   MdigControl( MilDigitizer, M_UART_SPEED,        CONFIG_SPEED       );
   MdigControl( MilDigitizer, M_UART_DATA_LENGTH,  CONFIG_DATA_LENGTH );
   MdigControl( MilDigitizer, M_UART_STOP_BITS,    CONFIG_STOP_BITS   );

   /* Opening windows COM port handle. */
   hCom = CreateFile ( COM_PORT_NUMBER , GENERIC_READ | GENERIC_WRITE, 0, NULL, OPEN_EXISTING, 0, NULL );

   if ( hCom == INVALID_HANDLE_VALUE )
   {
      printf( " Unable to open com port\n");
      return 0;
   }

   if ( !GetCommState ( hCom, &dcb ))
   {
      printf( " Unable to get com port state\n");
      return 0;
   }

   /* Changing windows COM port configuration. */
   dcb.BaudRate = CONFIG_SPEED;
   dcb.ByteSize = CONFIG_DATA_LENGTH;

   if       ( CONFIG_STOP_BITS == 1 )
      dcb.StopBits = ONESTOPBIT;
   else if  ( CONFIG_STOP_BITS == 2 )
      dcb.StopBits = TWOSTOPBITS;

   if       ( CONFIG_PARITY == M_DISABLE )
      dcb.Parity = NOPARITY;
   else if  ( CONFIG_PARITY == M_EVEN    )
      dcb.Parity = EVENPARITY;
   else if  ( CONFIG_PARITY == M_ODD     )
      dcb.Parity = ODDPARITY;

   dcb.fRtsControl = RTS_CONTROL_HANDSHAKE;

   if ( !SetCommState( hCom, &dcb ) )
   {
      printf( " Unable to set com port to desired configuration\n");
      return 0;
   }

   /* Test to send data from the Matrox UART. */
   printf("The program will now send a string from your Matrox board to your com port.\n");
   printf("press <Enter> to send data.\n");
   getchar();

   /* Setting the string delimiter to the standard '\0' character. */
   MdigControl( MilDigitizer, M_UART_WRITE_STRING_LENGTH, M_DEFAULT );

   /* Sending string through the Matrox UART. */
   MdigControl( MilDigitizer, M_UART_WRITE_STRING, ( unsigned long ) TestString );

   /* Reading string through the windows COM port. */
   if ( !ReadFile( hCom, ReadBuffer, SendSize, &ReadSize, NULL))
   {
      printf( " Unable to read data through com port\n");
      return 0;
   }

   /* Display the result. */
   printf( "String read through com port: \n");
   printf( ReadBuffer );

   /* Test to read data from the Matrox board UART with M_UART_STRING_RECEIVE. */
   printf("\n\nThe program will now send a string from your com port to your Matrox board.\n");
   printf("press <Enter> to send data.\n");
   getchar();

   /* Clearing the read buffer. */
   for ( i=0; i<=SendSize ; i++ )
      ReadBuffer[i] = '\0';

   /* Writing data through the windows COM port. */
   if ( !WriteFile( hCom, TestString, SendSize, &SentSize, NULL))
   {
      printf( " Unable to write data through com port\n");
      return 0;
   }

   /* Setting the read timeout between each characters to 10 seconds. */
   MdigControl( MilDigitizer, M_UART_TIMEOUT, 10000 );

   /* Setting the delimiter to the standard '\0' character. */
   MdigControl( MilDigitizer, M_UART_STRING_DELIMITER, M_DEFAULT );

   /* Setting the string length to stop on the set delimiter. */
   MdigControl( MilDigitizer, M_UART_READ_STRING_LENGTH, M_DEFAULT );

   /* Setting the maximum string length to prevent global protection faults. */
   MdigControl( MilDigitizer, M_UART_READ_STRING_MAXIMUM_LENGTH, SendSize );

   /* Reading incoming data through the Matrox board UART. */
   MdigControl( MilDigitizer, M_UART_READ_STRING, (long)ReadBuffer );

   /* Display the result. */
   printf( "String read through MIL Uart: \n");
   printf( ReadBuffer );

   /* Test reading data from the Matrox board UART with a hooked function. */
   printf("\n\nThe program will now send a string from your com port to your Matrox board\n");
   printf("and read the data through a hooked function.\n");
   printf("press <Enter> to send data.\n");
   getchar();

   /* Clearing the read buffer. */
   for ( i=0; i<=SendSize ; i++ )
      ReadBuffer[i] = '\0';

   /* Initialize UART hook structure. */
   UserStruct.Digitizer = MilDigitizer;
   UserStruct.ReadBuffer = ReadBuffer;
   UserStruct.ReadSize = SendSize;
   UserStruct.ReadPosition =0;

   /* Hook the function to M_UART_RECEIVED_DATA. */
   MdigHookFunction(MilDigitizer, M_UART_DATA_RECEIVED, ReadHook, (void *)(&UserStruct));

   /* Send data through the Windows COM port */
   if ( !WriteFile( hCom, TestString, SendSize, &SentSize, NULL))
   {
      printf( " Unable to write data through com port\n");
      return 0;
   }

   /* At this point the CPU is free to perform other tasks and the incoming string */
   /* will be read during that time. Here, the CPU will only wait the end of       */
   /* the string reading function.                                                 */
   while (UserStruct.ReadPosition < SendSize )
      DoSomething=DoSomething;

   /* Display the result. */
   printf( "String read through hooked function: \n");
   printf( ReadBuffer );

   /* Pause to show the result. */
   printf("\nTransfer complete.\n");
   printf("Press <Enter> to end.\n");
   getchar();

   /* Unhook functions. */
   MdigHookFunction(MilDigitizer, M_UART_DATA_RECEIVED+M_UNHOOK, ReadHook, (void *)(&UserStruct));

   /* Free allocations. */
   free(ReadBuffer);
   CloseHandle(hCom);
   MdigFree( MilDigitizer );
   MsysFree( MilSystem );
   MappFree( MilApplication );

   return 0;
}

/* UART read hook function. */
long MFTYPE ReadHook(long HookType, MIL_ID EventId, void MPTYPE *UserStructPtr)
{
   UartHook *Params = ( UartHook* ) UserStructPtr;
   long Pending = M_TRUE;
   char TestChar=0;
   volatile long ReadChar = (long)&TestChar;

   /* While there are still characters left in the incoming buffer, read them. */
   MdigInquire( Params->Digitizer, M_UART_DATA_PENDING, &Pending );
   while ( Pending == M_TRUE )
   {
      MdigControl( Params->Digitizer, M_UART_READ_CHAR, ReadChar );
      MdigInquire( Params->Digitizer, M_UART_DATA_PENDING, &Pending );
      if ( Params->ReadPosition < Params->ReadSize )
         Params->ReadBuffer[Params->ReadPosition++] = TestChar;
   }
   return 0;


Example: odysseymultiboard.c

/*

  OdysseyMultiBoard.c

  Multi-Odyssey system processing demo with equal processing load.

  Note:
      Each buffer grabbed is processed with all the processor boards.
      This means that when each processing board is fast enough, the frame
      rate should be the camera frame rate times the number of processor boards.
      Display can be the limiting factor for speed. Comment MdispSelect() if needed.

      The grab system is the one specified by MilConfig default values.
      It should be the first Odyssey and have the grab module.
      The types of the processing systems are specified below.
*/

/* Headers. */
#include <conio.h>
#include <mil.h>

// Number of processing systems.
#define PROCESSOR_NB_MAX              8
#define USE_GRAB_SYSTEM_AS_PROCESSOR  M_YES
#define PROCESSOR_SYSTEM_TYPE         M_SYSTEM_ODYSSEY

// Number of processing buffers.
#define BUFFER_PER_PROCESSOR          2
#define BUFFER_NUMBER_MAX             (PROCESSOR_NB_MAX*BUFFER_PER_PROCESSOR)
#define BUFFER_SCALE                  1.0

// Number of grab buffers.
#define BUFFER_PER_DIGITIZER          2

// Annotation string length.
#define MAX_STRING_LENGHT 80

// Print debug statement.
#define DEBUG M_NO

/* ************************************************************************  */
/* This example performs double buffered grab with real time processing with */
/* multiple systems.                                                         */

/* Main function. */
void main(void)
   {
   MIL_ID MilApplication;
   MIL_ID MilSystem     ;
   MIL_ID MilDigitizer  ;
   MIL_ID MilDisplay    ;
   MIL_ID MilImageDisp  ;
   MIL_ID GrabBufId[BUFFER_PER_DIGITIZER];
   MIL_ID ProcSysId[PROCESSOR_NB_MAX];
   MIL_ID ProcBufId[BUFFER_NUMBER_MAX];
   MIL_ID CurrentProcSrcBufId, CurrentProcDstBufId;
   long   GrabIndex = 0, n, m;
   long   NbProc = 0, NbGrab =0, NbSystem = 0;
   double Time   = 0.0;
   char   Text[MAX_STRING_LENGHT];
   long   SizeX, SizeY, SizeBand;

   /* MIL application allocation. */
   MappAlloc(M_DEFAULT, &MilApplication);

   /* Allocations on the default grab system. */
   MsysAlloc("M_DEFAULT", M_DEFAULT, M_DEFAULT, &MilSystem);
   MdispAlloc(MilSystem, M_DEV0, "M_DEFAULT", M_DEFAULT, &MilDisplay);
   MdigAlloc(MilSystem, M_DEV0, "M_DEFAULT", M_DEFAULT, &MilDigitizer);

   /* Inquire digitizer size. */
   SizeBand = (long)(MdigInquire(MilDigitizer, M_SIZE_BAND, M_NULL));
   SizeX =    (long)(MdigInquire(MilDigitizer, M_SIZE_X, M_NULL)*BUFFER_SCALE);
   SizeY =    (long)(MdigInquire(MilDigitizer, M_SIZE_Y, M_NULL)*BUFFER_SCALE);

   /* Allocate 1 display buffer, clear and display it. */
   MbufAllocColor(MilSystem, SizeBand, SizeX, SizeY, 8L+M_UNSIGNED, M_IMAGE+M_GRAB+M_DISP, &MilImageDisp);
   MbufClear(MilImageDisp, 0x0);
   MdispSelect(MilDisplay, MilImageDisp);

   /* Allocate grab buffers. */
   for (n=0; n< BUFFER_PER_DIGITIZER; n++)
      {
      MbufAllocColor(MilSystem, SizeBand, SizeX, SizeY, 8L+M_UNSIGNED, M_IMAGE+M_GRAB, &GrabBufId[n]);
      }

   /* Decide whether to use the grab system to process. */
   NbSystem = 0;
   if (USE_GRAB_SYSTEM_AS_PROCESSOR)
       {
        ProcSysId[0] = MilSystem;
        NbSystem++;
       }

   /* Allocate and order the processing systems. */
   for (n = 0, m = NbSystem; n < (PROCESSOR_NB_MAX-m); n++)
      {
       MappControl(M_ERROR, M_PRINT_DISABLE);
       MsysAlloc(PROCESSOR_SYSTEM_TYPE, n, M_DEFAULT, &ProcSysId[NbSystem]);
       MappControl(M_ERROR, M_PRINT_ENABLE);

       /* Count the processing system. */
       if (ProcSysId[NbSystem])
          NbSystem++;
      }

   /* Allocate and order the processing buffers alternating the target system. */
   for (n = 0; n < (NbSystem*BUFFER_PER_PROCESSOR); n++)
      {
      MbufAllocColor(ProcSysId[n%NbSystem], SizeBand, SizeX, SizeY, 8L+M_UNSIGNED, M_IMAGE+M_PROC, &ProcBufId[n]);
      }

   /* Grab continuously on display at the specified scale. */
   MdigControl(MilDigitizer, M_GRAB_SCALE, BUFFER_SCALE);
   MdigGrabContinuous(MilDigitizer,MilImageDisp);

   /* Print a message. */
   printf("\n MULTI BOARDS PROCESSING:\n\n %ld system(s) allocated.\n\n", NbSystem);
   printf(" Press <Enter> to start processing.\n\n");
   getch();

   /* Halt continuous grab. */
   MdigHalt(MilDigitizer);

   /* Put the digitizer in asynchronous mode. */
   MdigControl(MilDigitizer, M_GRAB_MODE, M_ASYNCHRONOUS);

   /* Grab the first buffer. */
   NbGrab = 0;
   MdigGrab(MilDigitizer, GrabBufId[NbGrab++]);

   /* Process one buffer while grabbing the other. */
   NbProc = 0;
   while( !kbhit() )
      {
      /* Grab one buffer while processing the other. */
      MdigGrab(MilDigitizer, GrabBufId[NbGrab % BUFFER_PER_DIGITIZER]);
      #if DEBUG
      printf("grab index = %ld.\n", NbGrab % BUFFER_PER_DIGITIZER);
      #endif DEBUG

      /* Synchronize and start the timer. */
      if (NbProc == 0)
         MappTimer(M_TIMER_RESET+M_SYNCHRONOUS, M_NULL);

      /* Process each image with all the processors. To have each frame processed only
         once by one processor in round robin fashion, just comment out the following
         for(...) statement.
      */
      for (n=0; n<NbSystem; n++)
          {
            /* Calculate target processing buffer. */
            CurrentProcSrcBufId = ProcBufId[NbProc%(NbSystem*BUFFER_PER_PROCESSOR)];
            CurrentProcDstBufId = ProcBufId[(NbProc+NbSystem)%(NbSystem*BUFFER_PER_PROCESSOR)];
            #if DEBUG
            printf("copy index = %ld, ", (NbGrab-1)%BUFFER_PER_DIGITIZER);
            printf("proc src index = %ld, ", NbProc%(NbSystem*BUFFER_PER_PROCESSOR));
            printf("proc dst index = %ld\n", (NbProc+NbSystem)%(NbSystem*BUFFER_PER_PROCESSOR));
            #endif /* DEBUG */

            /* Copy the buffer already grabbed to a processing platform. */
            MbufCopy(GrabBufId[(NbGrab-1) % BUFFER_PER_DIGITIZER], CurrentProcSrcBufId);

            /* Draw the buffer index. */
            sprintf(Text, "Buffer #%ld.", NbProc);
            MgraText(M_DEFAULT, CurrentProcSrcBufId, 50, 50, Text);

            /* Process the buffer. */
            MimArith(CurrentProcSrcBufId, M_NULL, CurrentProcDstBufId, M_NOT);

            /* Process the buffer. */
            MimRotate(CurrentProcDstBufId, CurrentProcSrcBufId, (NbProc*10)%360,
                      SizeX/2, SizeY/2, SizeX/2, SizeY/2, M_NEAREST_NEIGHBOR);

            /* Update the display. */
            MbufCopy(CurrentProcSrcBufId, MilImageDisp);

            /* Count processed buffers. */
            NbProc++;
          }
      /* Count grabbed buffers. */
      NbGrab++;
      }
   getch();

   /* Wait for grab end and stop timer. */
   MdigGrabWait(MilDigitizer, M_GRAB_END);

   /* Print statistics. */
   if (NbProc!=0)
      {
      MappTimer(M_TIMER_READ+M_SYNCHRONOUS, &Time);
      printf("%ld Frames processed at a frame rate of %.2f frames/sec (%.2f ms/frame).\n\n",
             NbProc, NbProc/Time, 1000.0*Time/NbProc);
      }
   else
      printf("No frame has been grabbed.\n");
   printf("Press <Enter> to end.\n\n");
   getch();

   /* Free allocations. */
   for (n = 0; n < (NbSystem*BUFFER_PER_PROCESSOR); n++)
      MbufFree(ProcBufId[n]);
   for (n = 0; n < NbSystem; n++)
      {
      if ((ProcSysId[n]) && (!((n == 0) && USE_GRAB_SYSTEM_AS_PROCESSOR)))
         MsysFree(ProcSysId[n]);
      }
   for (n=0; n < BUFFER_PER_DIGITIZER; n++)
      {
      MbufFree(GrabBufId[n]);
      }
   MbufFree(MilImageDisp);
   MdispFree(MilDisplay);
   MdigFree(MilDigitizer);
   MsysFree(MilSystem);
   MappFree(MilApplication);
}