MgraVectors

See also

User Guide:

Reference:

MbufAlloc1d MbufInquire MgraAlloc MgraAllocList MgraControl MgraControlList MgraInquire MgraInquireList MgraVectorsGrid MthrAlloc

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox USB3 Vision driver (Update 19) (o)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox GenTL driver (Update 34) (v)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

mimwarpquadrilateral.cpp
photometricstereowithmotion.cpp

MgraText

MgraVectorsGrid

Synopsis

Draw vectors at arbitrary positions in an image, or add them to a 2D graphics list.

Syntax

void MgraVectors(

MIL_ID ContextGraId,	//in
MIL_ID DstImageBufOrListGraId,	//in
MIL_INT NumVectors,	//in
const MIL_DOUBLE *XArrayPtr,	//in
const MIL_DOUBLE *YArrayPtr,	//in
const MIL_DOUBLE *UArrayPtr,	//in
const MIL_DOUBLE *VArrayPtr,	//in
MIL_INT64 ScaleMode,	//in
MIL_DOUBLE ScaleValue,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function draws vectors destructively (raster-based) in the specified image at arbitrary positions. Alternatively, this function can add a vector-based version of the vectors to the specified 2D graphics list, allowing you to, for example, non-destructively annotate a display without pixelation effects upon scaling. To draw vectors at equally spaced positions, use MgraVectorsGrid().

The vectors are based on the specified starting positions (XArrayPtr and YArrayPtr), and the specified horizontal and vertical displacements (UArrayPtr and VArrayPtr). For example, the values at a given index in the specified arrays define a vector that goes from (x[index], y[index]) to (x[index] + u[index], y[index] + v[index]).

The vectors inherit all the relevant settings of the specified 2D graphics context, such as the foreground color (see MgraAlloc() for default context settings). If part of the vectors fall outside of the specified area (image or display), that part is clipped off.

To modify or inquire 2D graphics context settings, use MgraControl() or MgraInquire(). To modify or inquire 2D graphics list settings, use MgraControlList() or MgraInquireList().

The coordinates of the vectors are interpreted with respect to the input coordinate system, specified using MgraControl() or MgraControlList() with M_INPUT_UNITS. Note that if you set your input coordinate system to M_WORLD and you pass MgraVectors() an uncalibrated image, the function will generate an error.

Unlike most other functions that modify a MIL object, you can call this function concurrently from multiple threads on the same MIL 2D graphics list (DstImageBufOrListGraId) without using an M_MUTEX object, as long as all the other parameters of the concurrent calls do not also share data.

Note that when using a C compiler (not a C++ or other compiler), it is suggested to use the type-specific versions of this particular function, rather than the standard function prototype at the top of this page. An exhaustive list of type-specific versions of this function can be found at the bottom of this page.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Parameters

ContextGraId

Specifies the identifier of the 2D graphics context. This parameter must be set to one of the following values:

For the identifier of the 2D graphics context
Value	Description
M_DEFAULT	Specifies that the default 2D graphics context of the current MIL application is used. Note that there is a different default 2D graphics context for each thread. (summarize) Specifies that the default 2D graphics context of the current MIL application is used. (more details...)
MIL 2D graphics context identifier	Specifies the identifier of the 2D graphics context, which you have allocated using MgraAlloc().

DstImageBufOrListGraId

Specifies the identifier of a valid image buffer in which to draw the vectors or the identifier of a valid 2D graphics list in which to add the vectors. You must have allocated the image buffer or the 2D graphics list using MbufAlloc...() or MgraAllocList(), respectively.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

NumVectors

Specifies the number of vectors to draw.

When using a standard vector (std::vector) overload function in C++, you can pass M_DEFAULT to this parameter and MIL will automatically determine the size based on the number of items in the vector passed to the XArrayPtr, YArrayPtr, UArrayPtr, or VArrayPtr parameter.

XArrayPtr

Accepts the address of one of the following:

array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
Required array size:(NumVectors)

Specifies the address of the array containing the X-coordinates of the starting points of the vectors to draw. The number of elements in the array should be equal to the value specified for the NumVectors parameter.

YArrayPtr

Accepts the address of one of the following:

array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
Required array size:(NumVectors)

Specifies the address of the array containing the Y-coordinates of the starting points of the vectors to draw. The number of elements in the array should be equal to the value specified for the NumVectors parameter.

UArrayPtr

Accepts the address of one of the following:

array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
Required array size:(NumVectors)

Specifies the address of the array containing the displacements, in the X-direction, of the vectors to draw. The number of elements in the array should be equal to the value specified for the NumVectors parameter.

VArrayPtr

Accepts the address of one of the following:

array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
Required array size:(NumVectors)

Specifies the address of the array containing the displacements, in the Y-direction, of the vectors to draw. The number of elements in the array should be equal to the value specified for the NumVectors parameter.

ScaleMode

Specifies how to use the scale value (ScaleValue) to scale the vectors. By default, vectors are not scaled.

For specifying how to use the scale value to scale the vectors
Value	Description
M_DEFAULT	Same as M_ABSOLUTE.
M_ABSOLUTE	Specifies to use the scale value (ScaleValue) as a scaling factor that directly multiplies the vectors' horizontal and vertical displacements (UArrayPtr and VArrayPtr).
M_AUTO	Specifies that MIL determines the scale mode. To do this, MIL makes internal assumptions to establish an ideal scaling factor that optimizes the space taken by the vectors in the destination (DstImageBufOrListGraId) while reducing the chance of overlapping vectors. When using M_AUTO, MIL multiplies the vectors' horizontal and vertical displacements (UArrayPtr and VArrayPtr) by both the scale value (ScaleValue) and the internally established scale factor. (summarize) Specifies that MIL determines the scale mode. (more details...)

ScaleValue

Specifies the value by which to scale the vectors, according to the specified mode (ScaleMode). By default, vectors are not scaled.

For specifying the value by which to scale the vectors, according to the specified mode
Value	Description
M_DEFAULT	Specifies the default value; the default value is 1.0.
Value	Specifies the scale value.

ControlFlag

Specifies how to configure the arrowheads of the vectors, and how to handle null vectors.

For specifying how to configure the arrowheads of the vectors
Value	Description
M_DEFAULT	Same as M_FIXED_LENGTH_ARROWHEADS + M_SKIP_NULL_VECTORS.
M_FIXED_LENGTH_ARROWHEADS +	Specifies that arrowheads are drawn identically for all vectors, regardless of each vector's length.
M_PROPORTIONAL_ARROWHEADS +	Specifies that arrowheads are drawn proportionally to each vector's length.

Combination values for M_FIXED_LENGTH_ARROWHEADS; M_PROPORTIONAL_ARROWHEADS.

You can add one of the following values to the above-mentioned values to determine how to handle null vectors.

Null vectors are vectors with a length of 0. This occurs when a vector's displacement values (UArrayPtr and VArrayPtr) are both 0.

For determining how to handle null vectors
Combination value	Description
M_DRAW_NULL_VECTORS	Specifies that null vectors are drawn as a dot in the destination (DstImageBufOrListGraId).
M_SKIP_NULL_VECTORS	Specifies that null vectors are not drawn in the destination (DstImageBufOrListGraId).

Type-specific versions of the function when using a C compiler

void MgraVectorsDouble (MIL_ID ContextGraId, MIL_ID DstImageBufOrListGraId, MIL_INT NumVectors, const MIL_DOUBLE *XArrayPtr, const MIL_DOUBLE *YArrayPtr, const MIL_DOUBLE *UArrayPtr, const MIL_DOUBLE *VArrayPtr, MIL_INT64 ScaleMode, MIL_DOUBLE ScaleValue, MIL_INT64 ControlFlag)

Details

Parameters

ContextGraId

See ContextGraId of the main function for a description.

DstImageBufOrListGraId

See DstImageBufOrListGraId of the main function for a description.

NumVectors

See NumVectors of the main function for a description.

XArrayPtr

See XArrayPtr of the main function for a description.

YArrayPtr

See YArrayPtr of the main function for a description.

UArrayPtr

See UArrayPtr of the main function for a description.

VArrayPtr

See VArrayPtr of the main function for a description.

ScaleMode

See ScaleMode of the main function for a description.

ScaleValue

See ScaleValue of the main function for a description.

ControlFlag

See ControlFlag of the main function for a description.

void MgraVectorsFloat (MIL_ID ContextGraId, MIL_ID DstImageBufOrListGraId, MIL_INT NumVectors, const MIL_FLOAT *XArrayPtr, const MIL_FLOAT *YArrayPtr, const MIL_FLOAT *UArrayPtr, const MIL_FLOAT *VArrayPtr, MIL_INT64 ScaleMode, MIL_DOUBLE ScaleValue, MIL_INT64 ControlFlag)

Details

Parameters

ContextGraId

See ContextGraId of the main function for a description.

DstImageBufOrListGraId

See DstImageBufOrListGraId of the main function for a description.

NumVectors

See NumVectors of the main function for a description.

XArrayPtr

See XArrayPtr of the main function for a description.

YArrayPtr

See YArrayPtr of the main function for a description.

UArrayPtr

See UArrayPtr of the main function for a description.

VArrayPtr

See VArrayPtr of the main function for a description.

ScaleMode

See ScaleMode of the main function for a description.

ScaleValue

See ScaleValue of the main function for a description.

ControlFlag

See ControlFlag of the main function for a description.

void MgraVectorsInt32 (MIL_ID ContextGraId, MIL_ID DstImageBufOrListGraId, MIL_INT NumVectors, const MIL_INT32 *XArrayPtr, const MIL_INT32 *YArrayPtr, const MIL_INT32 *UArrayPtr, const MIL_INT32 *VArrayPtr, MIL_INT64 ScaleMode, MIL_DOUBLE ScaleValue, MIL_INT64 ControlFlag)

Details

Parameters

ContextGraId

See ContextGraId of the main function for a description.

DstImageBufOrListGraId

See DstImageBufOrListGraId of the main function for a description.

NumVectors

See NumVectors of the main function for a description.

XArrayPtr

See XArrayPtr of the main function for a description.

YArrayPtr

See YArrayPtr of the main function for a description.

UArrayPtr

See UArrayPtr of the main function for a description.

VArrayPtr

See VArrayPtr of the main function for a description.

ScaleMode

See ScaleMode of the main function for a description.

ScaleValue

See ScaleValue of the main function for a description.

ControlFlag

See ControlFlag of the main function for a description.

void MgraVectorsInt64 (MIL_ID ContextGraId, MIL_ID DstImageBufOrListGraId, MIL_INT NumVectors, const MIL_INT64 *XArrayPtr, const MIL_INT64 *YArrayPtr, const MIL_INT64 *UArrayPtr, const MIL_INT64 *VArrayPtr, MIL_INT64 ScaleMode, MIL_DOUBLE ScaleValue, MIL_INT64 ControlFlag)

Details

Parameters

ContextGraId

See ContextGraId of the main function for a description.

DstImageBufOrListGraId

See DstImageBufOrListGraId of the main function for a description.

NumVectors

See NumVectors of the main function for a description.

XArrayPtr

See XArrayPtr of the main function for a description.

YArrayPtr

See YArrayPtr of the main function for a description.

UArrayPtr

See UArrayPtr of the main function for a description.

VArrayPtr

See VArrayPtr of the main function for a description.

ScaleMode

See ScaleMode of the main function for a description.

ScaleValue

See ScaleValue of the main function for a description.

ControlFlag

See ControlFlag of the main function for a description.

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.

Table:	For specifying how to configure the arrowheads of the vectors
+ combination:	For determining how to handle null vectors