agi.foundation.graphics

(agi.foundation.graphics-2025r1.jar)

Class ModelPrimitive

java.lang.Object

agi.foundation.graphics.Primitive

agi.foundation.graphics.ModelPrimitive

All Implemented Interfaces:

IDisposable, AutoCloseable

public final class ModelPrimitive
extends Primitive
implements IDisposable

The model primitive loads and renders glTF 2.0 (.gltf, .glb), COLLADA (DAE) and AGI MDL (MDL) models.

See Also:

Model Primitive topic

Constructor Summary

Constructors

Constructor and Description
ModelPrimitive() Initializes a default model primitive.
ModelPrimitive(String uri) For convenience.
ModelPrimitive(String uri, ModelUpAxis upAxis) For convenience.
ModelPrimitive(URI uri) Initializes a model primitive with the specified uri.
ModelPrimitive(URI uri, ModelUpAxis upAxis) Initializes a model primitive with the specified uri and up axis.

Method Summary

Modifier and Type	Method and Description
protected void	dispose(boolean disposing)
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
ModelArticulationCollection	getArticulations() Gets the model's articulations.
UnitQuaternion	getOrientation() Gets the model's orientation.
Cartesian	getPosition() Gets the position of the model.
double	getScale() Gets the linear scale used to increase or decrease the size of the rendered model.
float	getTranslucency() Gets the primitive's translucency.
URI	getUri() Gets the URI of the file used to load the file.
void	load(String uri) For convenience.
void	load(String uri, ModelUpAxis upAxis) For convenience.
void	load(URI uri) Loads a glTF 2.0 (.gltf, .glb), COLLADA (DAE) or AGI MDL (MDL) model using the specified uri.
void	load(URI uri, ModelUpAxis upAxis) Loads a glTF 2.0 (.gltf, .glb), COLLADA (DAE) or AGI MDL (MDL) model using the specified uri and upAxis.
void	setOrientation(UnitQuaternion quaternion) Sets the model's orientation.
void	setPosition(Cartesian position) Sets the position of the model.
void	setPositionCartographic(CentralBody centralBody, Cartographic position) For convenience.
void	setScale(double value) Sets the linear scale used to increase or decrease the size of the rendered model.
void	setTranslucency(float value) Sets the primitive's translucency.

Methods inherited from class agi.foundation.graphics.Primitive

dispose, getAutomaticallyComputeBoundingSphere, getBoundingSphere, getColor, getDisplay, getDisplayCondition, getReferenceFrame, getTag, setAutomaticallyComputeBoundingSphere, setBoundingSphere, setColor, setDisplay, setDisplayCondition, setReferenceFrame, setTag

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface agi.foundation.compatibility.IDisposable

close, dispose

Constructor Detail

ModelPrimitive

public ModelPrimitive()

Initializes a default model primitive.

After constructing the primitive, call ModelPrimitive.load(java.net.URI) to load a model file and set Position, Orientation, and Scale to place, orientate, and size the model in the 3D scene.

The primitive's properties are initialized to the following values:

• agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere: true
• agi.foundation.graphics.primitive.BoundingSphere: BoundingSphere.MaximumRadiusBoundingSphere (get)
• agi.foundation.graphics.primitive.Color: White
• agi.foundation.graphics.primitive.Display: true
• agi.foundation.graphics.primitive.DisplayCondition: null
• agi.foundation.graphics.primitive.ReferenceFrame: The earth's agi.foundation.celestial.earthcentralbody.FixedFrame
• agi.foundation.graphics.primitive.Translucency: 0
• Articulations: null
• Orientation: [1, 0, 0, 0]
• Position: Cartesian.Zero
• Scale: 1
• Uri: null

Once the primitive is constructed, it must be added to Primitives (get) before it will be rendered.

See Also:

ModelPrimitive.ModelPrimitive(java.net.URI)., ModelPrimitive.load(java.net.URI)., Position, Orientation, Scale, Video Streams on Models topic

ModelPrimitive

public ModelPrimitive(URI uri)

Initializes a model primitive with the specified uri.

After constructing the primitive, set Position, Orientation, and Scale to place, orientate, and size the model in the 3D scene.

If the model includes articulations, they can be accessed using Articulations.

The primitive's properties are initialized to the following values:

• agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere: true
• agi.foundation.graphics.primitive.BoundingSphere: BoundingSphere.MaximumRadiusBoundingSphere (get)
• agi.foundation.graphics.primitive.Color: White
• agi.foundation.graphics.primitive.Display: true
• agi.foundation.graphics.primitive.DisplayCondition: null
• agi.foundation.graphics.primitive.ReferenceFrame: The earth's agi.foundation.celestial.earthcentralbody.FixedFrame
• agi.foundation.graphics.primitive.Translucency: 0
• Articulations: null if the model does not include articulations
• Orientation: [1, 0, 0, 0]
• Position: Cartesian.Zero
• Scale: 1
• Uri: uri

Once the primitive is constructed, it must be added to Primitives (get) before it will be rendered.

Parameters:

uri - The URI of the model file to load.

Throws:

UncheckedFileNotFoundException - Could not find or access uri.

ArgumentException - Only file URIs are supported at this time. uri must start with file:///.

See Also:

ModelPrimitive.load(java.net.URI).

ModelPrimitive

public ModelPrimitive(String uri)

For convenience. Initializes a model primitive with the specified file path.

See ModelPrimitive.ModelPrimitive(java.net.URI). for a full discussion.

Parameters:

uri - The path to the model file.

See Also:

ModelPrimitive.ModelPrimitive(java.net.URI).

ModelPrimitive

public ModelPrimitive(URI uri,
                      ModelUpAxis upAxis)

Initializes a model primitive with the specified uri and up axis.

After constructing the primitive, set Position, Orientation, and Scale to place, orientate, and size the model in the 3D scene.

If the model includes articulations, they can be accessed using Articulations.

The primitive's properties are initialized to the following values:

• agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere: true
• agi.foundation.graphics.primitive.BoundingSphere: BoundingSphere.MaximumRadiusBoundingSphere (get)
• agi.foundation.graphics.primitive.Color: White
• agi.foundation.graphics.primitive.Display: true
• agi.foundation.graphics.primitive.DisplayCondition: null
• agi.foundation.graphics.primitive.ReferenceFrame: The earth's agi.foundation.celestial.earthcentralbody.FixedFrame
• agi.foundation.graphics.primitive.Translucency: 0
• Articulations: null if the model does not include articulations
• Orientation: [1, 0, 0, 0]
• Position: Cartesian.Zero
• Scale: 1
• Uri: uri

Once the primitive is constructed, it must be added to Primitives (get) before it will be rendered.

Parameters:

uri - The URI of the model file to load.

upAxis - The axis representing the up direction of the model file.

Throws:

UncheckedFileNotFoundException - Could not find or access uri.

ArgumentException - Only file URIs are supported at this time. uri must start with file:///.

ArgumentException - Only MDL models can have their up axis specified.

See Also:

ModelPrimitive.load(java.net.URI).

ModelPrimitive

public ModelPrimitive(String uri,
                      ModelUpAxis upAxis)

For convenience. Initializes a model primitive with the specified file path and up axis.

See ModelPrimitive.ModelPrimitive(java.net.URI, ModelUpAxis). for a full discussion.

Parameters:

uri - The path to the model file.

upAxis - The axis representing the up direction of the model file.

See Also:

ModelPrimitive.ModelPrimitive(java.net.URI).

Method Detail

finalize

protected void finalize()
                 throws Throwable

Description copied from class: java.lang.Object

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Overrides:

finalize in class Object

Throws:

Throwable - the Exception raised by this method

See Also:

WeakReference, PhantomReference

dispose

protected void dispose(boolean disposing)

Overrides:

dispose in class Primitive

getTranslucency

public float getTranslucency()

Gets the primitive's translucency. The model primitive only supports a translucency of 0.

Overrides:

getTranslucency in class Primitive

Throws:

ArgumentOutOfRangeException - Translucency must be 0 for the model primitive.

setTranslucency

public void setTranslucency(float value)

Sets the primitive's translucency. The model primitive only supports a translucency of 0.

Overrides:

setTranslucency in class Primitive

Throws:

ArgumentOutOfRangeException - Translucency must be 0 for the model primitive.

getUri

public final URI getUri()

Gets the URI of the file used to load the file.

See Also:

ModelPrimitive.load(java.net.URI).

getScale

public final double getScale()

Gets the linear scale used to increase or decrease the size of the rendered model.

A Scale of 1 renders the model using its actual size. Values less than 1 decrease the size of the rendered model and values greater than 1 increase the size of the rendered model.

If the model's agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere property is true when setting Scale, the Radius of the model's agi.foundation.graphics.primitive.BoundingSphere is set to fit around the model. Otherwise, it is the caller's responsibility to update the model's agi.foundation.graphics.primitive.BoundingSphere to a sphere that encompasses the model.

Throws:

ArgumentOutOfRangeException - Scale is less than 0.

setScale

public final void setScale(double value)

Sets the linear scale used to increase or decrease the size of the rendered model.

A Scale of 1 renders the model using its actual size. Values less than 1 decrease the size of the rendered model and values greater than 1 increase the size of the rendered model.

If the model's agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere property is true when setting Scale, the Radius of the model's agi.foundation.graphics.primitive.BoundingSphere is set to fit around the model. Otherwise, it is the caller's responsibility to update the model's agi.foundation.graphics.primitive.BoundingSphere to a sphere that encompasses the model.

Throws:

ArgumentOutOfRangeException - Scale is less than 0.

getPosition

public final Cartesian getPosition()

Gets the position of the model. The position is defined in the model's ReferenceFrame.

If the model's agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere property is true when setting the model's position, the Center of the model's agi.foundation.graphics.primitive.BoundingSphere is set to the new position. Otherwise, it is the caller's responsibility to update the model's agi.foundation.graphics.primitive.BoundingSphere to a sphere that encompasses the model.

See Also:

SetPositionCartographic

setPosition

public final void setPosition(Cartesian position)

Sets the position of the model. The position is defined in the model's ReferenceFrame.

If the model's agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere property is true when setting the model's position, the Center of the model's agi.foundation.graphics.primitive.BoundingSphere is set to the new position. Otherwise, it is the caller's responsibility to update the model's agi.foundation.graphics.primitive.BoundingSphere to a sphere that encompasses the model.

See Also:

SetPositionCartographic

getOrientation

public final UnitQuaternion getOrientation()

Gets the model's orientation. The quaternion is a rotation from the model's local axes to the axes of the model's ReferenceFrame.

See Also:

Model Primitive topic

setOrientation

public final void setOrientation(UnitQuaternion quaternion)

Sets the model's orientation. The quaternion is a rotation from the model's local axes to the axes of the model's ReferenceFrame.

See Also:

Model Primitive topic

getArticulations

public final ModelArticulationCollection getArticulations()

Gets the model's articulations. Articulations identify geometry and contain transformations for manipulating that geometry. Articulations may be null if the model doesn't contain any articulations.

load

public final void load(URI uri)

Loads a glTF 2.0 (.gltf, .glb), COLLADA (DAE) or AGI MDL (MDL) model using the specified uri.

If the model includes articulations, they can be accessed using Articulations.

If the model's agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere property is true, agi.foundation.graphics.primitive.BoundingSphere is set to fit around the model. Otherwise, it is the caller's responsibility to update the model's agi.foundation.graphics.primitive.BoundingSphere to a sphere that encompasses the model.

Loading a new model does not change the model's Position, Orientation, or Scale.

Parameters:

uri - The URI of the model file to load.

Throws:

UncheckedFileNotFoundException - Could not find or access uri.

ArgumentException - Only file URIs are supported at this time. uri must start with file:///.

load

public final void load(String uri)

For convenience. Loads a glTF 2.0 (.gltf, .glb), COLLADA (DAE) or AGI MDL (MDL) model using a file path. See ModelPrimitive.load(java.net.URI) for a full discussion.

Parameters:

uri - The path to the model file.

See Also:

ModelPrimitive.load(java.net.URI).

load

public final void load(URI uri,
                       ModelUpAxis upAxis)

Loads a glTF 2.0 (.gltf, .glb), COLLADA (DAE) or AGI MDL (MDL) model using the specified uri and upAxis.

If the model includes articulations, they can be accessed using Articulations.

If the model's agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere property is true, agi.foundation.graphics.primitive.BoundingSphere is set to fit around the model. Otherwise, it is the caller's responsibility to update the model's agi.foundation.graphics.primitive.BoundingSphere to a sphere that encompasses the model.

Loading a new model does not change the model's Position, Orientation, or Scale.

Parameters:

uri - The URI of the model file to load.

upAxis - The axis representing the up direction of the model file.

Throws:

UncheckedFileNotFoundException - Could not find or access uri.

ArgumentException - Only file URIs are supported at this time. uri must start with file:///.

ArgumentException - Only MDL models can have their up axis specified.

load

public final void load(String uri,
                       ModelUpAxis upAxis)

For convenience. Loads a glTF 2.0 (.gltf, .glb), COLLADA (DAE) or AGI MDL (MDL) model using a file path. See ModelPrimitive.load(java.net.URI) for a full discussion.

Parameters:

uri - The path to the model file.

upAxis - The axis representing the up direction of the model file.

See Also:

ModelPrimitive.load(java.net.URI).

setPositionCartographic

public final void setPositionCartographic(CentralBody centralBody,
                                          Cartographic position)

For convenience. Sets the Cartographic position of the model. Longitude and latitude are in radians, and altitude is in meters. This also sets Position.

centralBody is used to convert the position to Cartesian.

See Position for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

position - The new Cartographic position of the model.

Throws:

ArgumentNullException - centralBody is null.

IllegalStateException - The primitive's ReferenceFrame (get) is not equal to centralBody fixed frame.

See Also:

Position