Click or drag to resize

Model Primitive

ModelPrimitive is a primitive that can load and render COLLADA and AGI's MDL models. COLLADA is an industry standard, XML-based 3D model format. MDL is the 3D model format used by STK. We recommend using COLLADA models, although they consume slightly more disk space since they are XML-based. Models can be downloaded from AGI's website.

Loading Models

The following code sample demonstrates creating and loading a model:

Java
ModelPrimitive model = new ModelPrimitive(modelUri);
EarthCentralBody earth = CentralBodiesFacet.getFromContext().getEarth();
Cartographic position = new Cartographic(Trig.degreesToRadians(39.88), Trig.degreesToRadians(-75.25), 5000.0);
model.setPositionCartographic(earth, position);
Model

The orientation of the model depends on the model itself. For example, in the hellfire.dae model, the missile is laid out lengthwise along the positive x axis. To change the orientation, use the Orientation (get / set) property and provide a quaternion that defines the rotation from the model's local axes to the axes of the reference frame in which the model's position is defined. In this case, the model's position is defined in the central body's fixed frame. A convenient way to compute the quaternion is shown below:

Java
Cartographic center = new Cartographic(Trig.degreesToRadians(-75.25), Trig.degreesToRadians(39.88), 0.0);
PointCartographic origin = new PointCartographic(earth, center);
Axes axes = new AxesNorthEastDown(earth, origin);
AxesEvaluator axesEvaluator = GeometryTransformer.getAxesTransformation(axes, earth.getFixedFrame().getAxes());
UnitQuaternion q = axesEvaluator.evaluate(TimeConstants.J2000);

ElementaryRotation r = new ElementaryRotation(AxisIndicator.SECOND, Math.PI / 2);
q = q.multiply(r);

model.setOrientation(q);

A topographic axes is created based on the model's position where the x axis point in the local north direction, the y axis points in the local east direction and the z axis points in the local down direction. A quaternion that defines the rotation from these axes to the fixed frame axes is created. To point the model in the local up direction, the quaternion is rotated 90 degrees around the y axis.

Like orientation, the size of the model depends on the model itself. To change the size of the model, use the Scale (get / set) property. After a model is initialized, its position can be changed using the Position (get / set) property.

COLLADA models also support raster streams. See the Video Streams on Models topic for more information.

Model Articulations

The model primitive supports model articulations, which allow different parts of the model to be rotated, scaled, and/or translated. If the model supports articulations, they can be accessed through the Articulations (get) property.

An example of how to modify the ModelTransformation of a model's ModelArticulation is shown below:

Java
// Create the model and set the position.
ModelPrimitive model = new ModelPrimitive(modelUri);
EarthCentralBody earth = CentralBodiesFacet.getFromContext().getEarth();
Cartographic position = new Cartographic(Trig.degreesToRadians(-116.75), Trig.degreesToRadians(36.0), 25000.0);
model.setPositionCartographic(earth, position);

// Modify the roll and yaw of the entire model so that the model appears to be parallel
// with the horizon. This method is only to demonstrate how articulations can be used.
// the preferred method is to set the model's orientation.
model.getArticulations().get("Commuter").get("Roll").setCurrentValue(Trig.degreesToRadians(234.0));
model.getArticulations().get("Commuter").get("Yaw").setCurrentValue(Trig.degreesToRadians(-25.0));

// Modify the spin of the propellers.
model.getArticulations().get("props").get("Spin").setCurrentValue(Trig.degreesToRadians(135.0));
Model With No Prop Spin
The model primitive without modifying the spin.
Model With Prop Spin
The model with the spin of the propellers modified to be 135 degrees.

The Articulations (get) property contains an instance of ModelArticulationCollection. ModelArticulationCollection implements Iterable and contains a collection of ModelArticulations. ModelArticulation also implements Iterable and contains a collection of ModelTransformations. Both the ModelArticulationCollection and ModelArticulation classes accept either an integer or string index to access its values. Use the CurrentValue (get / set) property to set the value of the transformation, as shown in the code above. The type of transformation can also be retrieved using the Type (get) property, which returns a ModelTransformationType.

Advanced Shading

Collada models also support the ColladaFX framework, which allows users to write GLSL code to calculate vertex positions, pixel colors, etc. This allows for models to exhibit lighting properties of materials such as metal, glass, plastic, etc. ColladaFX also allows changing OpenGL States, use of all supported OpenGL Texture types (1D, 2D, 3D, cubemap, rectangle, shadow), and render to texture for use with multipass rendering techniques.

The following image shows a satellite that uses a metallic BRDF based on the work of Ashikhmin and Shirley. The paper can be found here This example can be seen in the HowTo example under "Primitives" -> "Models" -> "Draw a Collada model with user defined lighting"

ColladaFX

Within your shader code, you have access to scene data that is useful for shading your model. We refer to these as Preset Uniforms because they are accessed as uniform variables in your vertex or fragment shader. These variables must be declared as uniforms and then can be used. Here is an example using Insight3D's animation time to move a vertex.

GLSL
uniform float agi_Time;
uniform float fullOffset;

// Vertex Shader that oscillates from position to position+fullOffset along the Z axis.
void main()
{
    // Get fractional part of time
    float t = fract(agi_Time);

    // Move apply modelview and projection
    vec4 pos = gl_ModelViewProjectionMatrix * gl_Vertex;

    // Move vertex a certain percentage of offset
    pos.z += fullOffset * t;

    // Set position
    gl_Position = pos;
}

Preset Uniforms

Preset Uniform

Type

Description

agi_ActiveLights

bool[gl_MaxLights]

Light i is active if agi_ActiveLights[i] is true and inactive if false. Light properties can be accessed through gl_LightSources.

agi_CameraPosition

vec3

Position of the camera relative to the model's reference frame.

agi_CentralBodyDepthTexture0, agi_CentralBodyDepthTexture1, ..., agi_CentralBodyDepthTexture7

sampler2D

A texture that contains the depth values after rendering the CentralBody. The number binds the texture to a particular texture unit. See images below.

agi_LightingEnabled

float

1 if lighting is enabled and 0 otherwise.

agi_LODGeometricToleranceOverDistance

float

When multiplied by the distance from the vertex or fragment to the viewer, the result is the geometric error in world space.

agi_LODNegativeGeometricToleranceOverDistance

float

Negative of agi_LODGeometricToleranceOverDistance.

agi_ModelViewMatrix

mat4

Model-View matrix.

agi_ModelViewMatrixRelativeToCameraPosition

mat4

Model-View matrix relative to the camera position.

agi_ModelViewMatrixRelativeToPrimitiveCenter

mat4

Model-View matrix relative to the model's center.

agi_ModelViewProjectionMatrix

mat4

Model-View-Projection matrix.

agi_ModelViewProjectionMatrixRelativeToCameraPosition

mat4

Model-View-Projection matrix relative to the camera position.

agi_ModelViewProjectionMatrixRelativeToPrimitiveCenter

mat4

Model-View-Projection matrix relative to the model's center.

agi_OrthographicProjectionMatrix

mat4

Orthographic projection matrix.

agi_PerspectiveProjectionMatrix

mat4

Perspective projection matrix.

agi_PrimitiveBoundingSphere

vec4

The model's bounding sphere relative to the model's reference frame. The xyz components are the position and w is the radius in meters.

agi_PrimitiveBoundingSphereRelativeToCameraPosition

vec4

The model's bounding sphere relative to the camera position. The xyz components are the position and w is the radius in meters.

agi_PrimitiveColor

vec4

The color of the primitive.

agi_SnapshotPixelScale

float

Scale when rendering high-resolution snapshots. Otherwise it is 1.

agi_TerrainSilhouetteTexture0, agi_TerrainSilhouetteTexture1, ..., agi_TerrainSilhouetteTexture7

sampler2D

A texture that contains the silhouette of the terrain. The number binds the texture to a particular texture unit. See image below.

agi_Time

float

Number of seconds since the animation start time.

agi_Viewport

vec4

The viewport in the format (left, bottom, width, height).

Central Body Rendered Normally
Central Body Rendered Normally
Central Body Depth Texture
Central Body Depth Texture
Terrain Silhouette Texture
Terrain Silhouette Texture

Supported OpenGL States

ColladaFX Element

OpenGL State

Notes

alpha_func

glAlphaFunc

alpha_test_enable

glEnable/glDisable with GL_ALPHA_TEST

blend_color

glBlendColor

blend_enable

glEnable/glDisable with GL_BLEND

blend_equation

glBlendEquation

blend_equation_separate

glBlendEquationSeparate

Requires OpenGL 2.0.

blend_func

glBlendFunc

blend_func_separate

glBlendFuncSeparate

Requires OpenGL 1.4.

color_mask

glColorMask

cull_face

glCullFace

cull_face_enable

glEnable/glDisable with GL_CULL_FACE

depth_clamp_enable

glEnable/glDisable with GL_DEPTH_CLAMP_NV

Requires GL 3.2 or GL_ARB_depth_clamps.

depth_func

glDepthFunc

depth_mask

glDepthMask

depth_range

glDepthRange

depth_test_enable

glEnable/glDisable with GL_DEPTH_TEST

fog_color

glFogfv with GL_FOG_COLOR

fog_density

glFogf with GL_FOG_DENSITY

fog_enable

glEnable/glDisable with GL_FOG

fog_end

glFogf with GL_FOG_END

fog_mode

glFogi with GL_FOG_MODE

fog_start

glFogf with GL_FOG_START

front_face

glFrontFace

line_smooth_enable

glEnable/glDisable with GL_LINE_SMOOTH

line_stipple

glLineStipple

line_stipple_enable

glEnable/glDisable with GL_LINE_STIPPLE

line_width

glLineWidth

point_size

glPointSize

point_smooth_enable

glEnable/glDisable with GL_POINT_SMOOTH

polygon_mode

glPolygonMode

Only FRONT_AND_BACK.

polygon_offset

glPolygonOffset

polygon_offset_fill_enable

glEnable/glDisable with GL_POLYGON_OFFSET_FILL

scissor

glScissor

scissor_test_enable

glEnable/glDisable with GL_SCISSOR_TEST

shade_model

glShadeModel

stencil_func

glStencilFunc

stencil_func_separate

glStencilFuncSeparate

Requires OpenGL 2.0.

stencil_mask

glStencilMask

stencil_mask_separate

glStencilMaskSeparate

Requires OpenGL 2.0.

stencil_op

glStencilOp

stencil_op_separate

glStencilOpSeparate

Requires OpenGL 2.0.

stencil_test_enable

glEnable/glDisable with GL_STENCIL_TEST

texture1D

glBindTexture with GL_TEXTURE_1D

texture2D

glBindTexture with GL_TEXTURE_2D

texture3D

glBindTexture with GL_TEXTURE_3D

textureCUBE

glBindTexture with GL_TEXTURE_CUBE_MAP

Requires OpenGL 1.3.

textureDEPTH

glBindTexture with GL_TEXTURE_2D

Used for depth textures.

textureRECT

glBindTexture with GL_TEXTURE_RECTANGLE_ARB

Unsupported OpenGL States

ColladaFX Element

Notes

auto_normal_enable

clip_plane

Can be emulated in the fragment shader. Removed from OpenGL 3.2 core.

clip_plane_enable

Can be emulated in the fragment shader. Removed from OpenGL 3.2 core.

color_logic_op_enable

Rarely used.

color_material

Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.

color_material_enable

Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.

depth_bounds

Only affects performance, not the visual output. Not in core GL, requires EXT_depth_bounds_test.

depth_bounds_enable

Only affects performance, not the visual output. Not in core GL, requires EXT_depth_bounds_test.

dither_enable

Rarely used.

light_ambient

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_constant_attenuation

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_diffuse

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_enable

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_linear_attenuation

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_model_ambient

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_model_color_control

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_model_local_viewer_enable

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_model_two_side_enable

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_position

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_quadratic_attenuation

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_specular

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_spot_cutoff

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_spot_direction

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

light_spot_exponent

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

lighting_enable

Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.

logic_op

Rarely used.

logic_op_enable

Rarely used.

material_ambient

Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.

material_diffuse

Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.

material_emission

Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.

material_shininess

Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.

material_specular

Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.

model_view_matrix

Can be emulated in the shader. Removed from OpenGL 3.2 core.

multisample_enable

Requires an OpenGL context be created with multisample buffers, which is currently not supported in Insight3D.

normalize_enable

This is always enabled.

point_distance_attenuation

point_fade_threshold_size

point_size_enable

point_size_max

point_size_min

polygon_offset_line_enable

polygon_offset_point_enable

polygon_smooth_enable

projection_matrix

Can be emulated in the shader. Removed from OpenGL 3.2 core.

sample_alpha_to_coverage_enable

Requires an OpenGL context be created with multisample buffers, which is currently not supported in Insight3D.

sample_alpha_to_one_enable

Requires an OpenGL context be created with multisample buffers, which is currently not supported in Insight3D.

sample_coverage

sample_coverage_enable

texture_env_color

Can be emulated in the fragment shader. Removed from OpenGL 3.2 core.

texture_env_color

Can be emulated in the fragment shader. Removed from OpenGL 3.2 core.

texture_pipeline

GLES profile only. GLSL is currently the only supported profile.

texture1D_enable

This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core.

texture2D_enable

This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core.

texture3D_enable

This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core.

textureCUBE_enable

This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core.

textureDEPTH_enable

This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core.

textureRECT_enable

This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core.

See Also