| Customize Help
| Save Settings

MgraVectorsGrid


Function Map
Syntax
Description
Parameters
- ContextGraId
Table: For the identifier of the 2D graphics context
- DstImageBufOrListGraId
- UImageBufId
- VImageBufId
- Stride
- ScaleMode
Table: For specifying how to use the scale value to scale the vectors
- ScaleValue
Table: For specifying the value by which to scale the vectors, according to the specified mode
- ControlFlag
Table: For specifying how to configure the arrowheads of the vectors
+ combination: For determining how to handle null vectors
Compilation information
Synopsis
Draw vectors at equally spaced positions in an image, or add them to a 2D graphics list.
Syntax
void MgraVectorsGrid(
MIL_ID ContextGraId, //in
MIL_ID DstImageBufOrListGraId, //in
MIL_ID UImageBufId, //in
MIL_ID VImageBufId, //in
MIL_INT Stride, //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 equally spaced 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 arbitrary positions, use MgraVectors().

The vectors are based on the specified image buffers (UImageBufId and VImageBufId) containing values that correspond to the horizontal and vertical displacements of the vectors. MIL uses the displacements at a given location to calculate the starting and ending positions of the vectors. For example, the values located at (x, y) in the specified buffers (UImageBufId and VImageBufId) define a vector that goes from (x, y) to (x + u[x][y], y + v[x][y]). The number of pixels in the buffers (SizeX x SizeY) determine the number of vectors to draw.

Typically, the image buffers from which the vectors' positions and lengths are inferred are the result of a previous image processing operation, such as an edge detection (for example, MimConvolve()).

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 starting coordinates of the first vector drawn are (0,0). Coordinates 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 MgraVectorsGrid() uncalibrated images, 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 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:

function map For the identifier of the 2D graphics context
Click to summarizeValue Description
Click to summarize 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)
Click to summarize 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.

UImageBufId

Specifies the identifier of a valid image buffer containing the values corresponding to the displacements, in the X-direction, of the vectors to draw. You must have allocated the image buffer using MbufAlloc...().

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. The image buffer must be a single-band buffer.

VImageBufId

Specifies the identifier of a valid image buffer containing the values corresponding to the displacements, in the Y-direction, of the vectors to draw. You must have allocated the image buffer using MbufAlloc...().

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. The image buffer must be a single-band buffer.

Stride

Specifies a value that establishes the positions for which vectors are drawn. MIL always draws a vector for the first position (0,0), and then draws subsequent vectors that are a multiple of the specified stride, in both the X- and Y-direction. For example, if you specify a stride of 2, a vector is drawn for position (0,0), and for every second position after that, in the X-direction and in the Y-direction. Specifying a stride of 1 draws a vector for every position. Increasing the stride increases the space between the vectors drawn.

ScaleMode

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

function map For specifying how to use the scale value to scale the vectors
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_ABSOLUTE.
Click to summarize M_ABSOLUTE

Specifies to use the scale value (ScaleValue) as a scaling factor that directly multiplies the vectors' horizontal and vertical displacements (UImageBufId and VImageBufId).
Click to summarize 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 (UImageBufId and VImageBufId) by both the scale value (ScaleValue) and the internally established scale factor.

(summarize)
ScaleValue

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

function map For specifying the value by which to scale the vectors, according to the specified mode
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.0.
Click to summarize Value

Specifies the scale value.
ControlFlag

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

function map For specifying how to configure the arrowheads of the vectors
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_FIXED_LENGTH_ARROWHEADS + M_SKIP_NULL_VECTORS.
Click to summarize M_FIXED_LENGTH_ARROWHEADS +

Specifies that arrowheads are drawn identically for all vectors, regardless of each vector's length.
Click to summarize 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 (UImageBufId and VImageBufId) are both 0.

function map For determining how to handle null vectors
Click to summarizeCombination value Description
Click to summarize M_DRAW_NULL_VECTORS

Specifies that null vectors are drawn as a dot in the destination (DstImageBufOrListGraId).
Click to summarize M_SKIP_NULL_VECTORS

Specifies that null vectors are not drawn in the destination (DstImageBufOrListGraId).
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT NONE NONE NONE DEFAULT ABSOLUTE AUTO DEFAULT DEFAULT FIXED LENGTH ARROWHEADS PROPORTIONAL ARROWHEADS DRAW NULL VECTORS SKIP NULL VECTORS