Annotating the 3D display

---

• See also
User Guide:
3D graphics lists
Reference:
M3ddispSelect M3ddispSelectWindow M3dgeoAlloc M3dgeoBox M3dgraAdd M3dgraArc M3dgraAxis M3dgraBox M3dgraControl M3dgraCopy M3dgraCylinder M3dgraDots M3dgraGrid M3dgraLine M3dgraNode M3dgraPlane M3dgraPolygon M3dgraRemove M3dgraSphere M3dgraText
Availability
Available in MIL-Lite


Available in MIL
Previous
Next

You can annotate a 3D display by adding 3D graphics to its 3D graphics list, using functions from the M3dgra...() module. A 3D graphic is a fully 3D object that has a position and orientation in the scene, defined by its transformation matrix and the transformation matrix of its parent graphic.

When you create a 3D graphic, you must add it to a 3D graphics list as a child of another 3D graphic. For more information on 3D graphics lists and the 3D graphics hierarchy, see the 3D graphics lists section later in this chapter.

You can remove an existing 3D graphic using M3dgraRemove().

Types of graphics

You can add the following kinds of 3D graphics:

Types of MIL 3D graphics
A 3D graphic linked to a 3D-displayable point cloud container, or fully corrected depth map image buffer, using M3dgraAdd(), M3ddispSelect(), or M3ddispSelectWindow().	A 3D graphic linked to a meshed 3D-displayable point cloud container, using M3dgraAdd(), M3ddispSelect(), or M3ddispSelectWindow().	3D dots (not associated with a container or image buffer), using M3dgraDots().
A box, using M3dgraBox().	A cylinder, using M3dgraCylinder().	A sphere, using M3dgraSphere().
An axis, using M3dgraAxis().	A line, using M3dgraLine().	An arc, using M3dgraArc().
A plane, using M3dgraPlane().	A grid, using M3dgraGrid(), with M_APPEARANCE set to M_WIREFRAME.	A filled grid, using M3dgraGrid(), with M_APPEARANCE set to M_SOLID.
A polygon, using M3dgraPolygon().	A textured polygon, using M3dgraPolygon().	A textured polygon with portions cut-out, using M3dgraPolygon() with an M_KEYING_COLOR specified.
3D Text, using M3dgraText().

You can also add a node, an invisible 3D graphic you can use to organize other 3D graphics in the 3D graphics list, using M3dgraNode().

Positions of 3D graphics

Every 3D graphic has a transformation matrix that determines the position and rotation of the 3D graphic in the 3D display. Some functions that create 3D graphics require you to specify the transformation matrix, while others determine the transformation matrix from another property that you must specify (such as the start position and end position of a line 3D graphic). Some 3D graphics (such as point clouds) are always created with the identity transformation matrix.

You can change the transformation matrix of an existing 3D graphic using M3dgraCopy() with M_TRANSFORMATION_MATRIX.

Each 3D graphic has a local coordinate system, with a local origin. For example, the local origin of a box 3D graphic is always at the center of the box, and its coordinate system is rotated to match the boxes orientation. When you create a new 3D graphic, you must specify its position and rotation relative to the parent. If the new 3D graphic's position and rotation are specified by a transformation matrix, the transformation matrix you specify will be applied relative to the parent's transformation matrix. If the new 3D graphic's position and rotation are specified by other properties (such as X,Y and Z-coordinates), those properties are interpreted within the coordinate system of the parent 3D graphics object. Any subsequent changes to the transformation matrix of the parent 3D graphic also change the position and orientation of the child 3D graphic.

When you set the transformation matrix of a 3D graphic using M3dgraCopy(), you can specify to use the passed transformation matrix to transform the 3D graphic within the absolute coordinate system, instead of within the coordinate system of the parent 3D graphic. To do this, specify M_RELATIVE_TO_ROOT. MIL calculates the correct transformation matrix within the coordinate system of the parent so that the 3D graphic has the specified transformation matrix in the absolute coordinate system.

The local origin and orientation of a 3D graphic's coordinate system is always determined by its transformation matrix. Changing the transformation matrix of the 3D graphic also alters the local origin and orientation of its coordinate system.

To determine the local origin and orientation of a particular type of 3D graphic, refer to the function used to create it.

Display settings for 3D graphics

Each 3D graphic has settings that determine how it is shown in the 3D display. You can change these settings using M3dgraControl(). You can specify the following for most 3D graphics:

Clipping 3D graphics that extend infinitely

Some types of 3D graphics (such as planes and cylinders) can be added with settings such that they extend infinitely. Every 3D graphics list has a clipping box that limits the size of these 3D graphics. For example, if you add a plane 3D graphic with Size set to M_INFINITE the created plane is clipped to the area that is within the current clipping box of the 3D graphics list.

Changes to the clipping box of a 3D graphics list are not applied retroactively to existing 3D graphics, only to 3D graphics added subsequently.

By default the clipping box of a 3D graphics list is equal to the bounding box of all 3D graphics currently in the list. You can set the clipping box of a 3D graphics list manually using M3dgraCopy() with SrcMilObjectId set to the MIL identifier of a box 3D geometry object (created using M3dgeoAlloc() and defined using M3dgeoBox()). You can restore the default behavior using M3dgraCopy() with SrcMilObjectId set to M_WHOLE_SCENE.

Working with texture images of polygon 3D graphics

You can choose to give a polygon 3D graphic an image buffer as a texture when you add it to a 3D graphics list using M3dgraPolygon(), or using M3dgraCopy() with M_COLOR_TEXTURE. If you set M_COLOR_USE_TEXTURE is set to M_TRUE, the polygon is shown with its texture instead of a solid color. Optionally, you can use M_KEYING_COLOR to specify that one color value in the texture is instead shown as transparent.

Texture mapping

When you add a polygon graphic with a texture to a 3D graphics list using M3dgraPolygon(), you can optionally specify the texture coordinates used to map the texture onto the polygon. If you do not specify texture coordinates, MIL will determine the texture mapping automatically. Typically, you should only use automatic texture mapping for polygons that are rectangles or right-angle triangles with the same aspect ratio as the texture. Otherwise, the texture will be displayed with distortion, as shown in this image.

For cases where automatic texture mapping produces warping, you can use texture coordinates to manually specify what position in the texture image buffer each vertex is mapped to. For example, if the first texture coordinate is (5,12), the first vertex is mapped to the center of the pixel at position (5,12) in the texture image buffer, and so on. The faces of the polygon are colored by interpolating between the specified positions. This animation shows how different texture coordinates affect how the texture is shown on an isosceles triangle polygon.