Camera | DME Component Libraries for Java 2024 r2

java.lang.Object
- agi.foundation.graphics.Camera

All Implemented Interfaces:

IDisposable, AutoCloseable
```
public final class Camera
extends Object
implements IDisposable
```
Implemented by the scene camera. Contains operations to manipulate the camera position, view direction and orientation in the scene.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Rectangular`	`cartographicToWindow(CentralBody centralBody, Cartographic position)` Converts a `Cartographic` position to a pixel coordinate relative to the `Insight3D` control.
`void`	`dispose()` Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
`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.
`boolean`	`getAllowRotationOverConstrainedUpAxis()` Gets whether the camera can rotate over the constrained up axis.
`Axes`	`getAxes()` Gets camera's axes of rotation.
`ConstrainedUpAxis`	`getConstrainedUpAxis()` Gets the axis to constrain the up vector to.
`UnitCartesian`	`getDirection()` Gets the direction of the camera in `Axes`.
`double`	`getDistance()` Gets the distance the camera position is from the reference point.
`double`	`getDistancePerRadius()` Returns the distance that the Camera's Position should be from the ReferencePoint in order to ensure that a sphere with a 1 meter radius centered at the ReferencePoint fits entirely in the view frustum.
`double`	`getFarNearPlaneRatio()` Gets the value that is used to compute subdivisions of the viewing frustum.
`double`	`getFarPlane()` Gets the distance in meters from the camera to the far plane.
`double`	`getFieldOfView()` Gets field of view in radians.
`double`	`getHorizontalFieldOfView()` Gets the horizontal field of view in radians.
`boolean`	`getLockViewDirection()` Gets whether the camera's direction is locked.
`double`	`getNearPlane()` Gets the distance in meters from the camera to the near plane.
`double`	`getPixelSizePerDistance()` Gets the approximate number of meters covered by a pixel that is `1` meter away from the camera.
`Cartesian`	`getPosition()` Gets the position of the camera.
`ReferenceFrame`	`getPositionReferenceFrame()` Gets the `ReferenceFrame` that the `Position` is returned in.
`Cartesian`	`getReferencePoint()` Gets the reference point of the camera.
`ReferenceFrame`	`getReferencePointReferenceFrame()` Gets the `ReferenceFrame` that the `ReferencePoint` is returned in.
`CameraSnapshot`	`getSnapshot()` Gets the camera snapshot settings.
`UnitCartesian`	`getUpVector()` Gets the up direction of the camera in `Axes`.
`double`	`getVerticalFieldOfView()` Gets the vertical field of view in radians.
`CameraVideoRecording`	`getVideoRecording()` Gets the camera video recorder.
`void`	`refreshEvaluators()` Refreshes all evaluators for the axes, points, or vectors that are used in the current camera view.
`void`	`setAllowRotationOverConstrainedUpAxis(boolean value)` Sets whether the camera can rotate over the constrained up axis.
`void`	`setAxes(Axes value)` Sets camera's axes of rotation.
`void`	`setConstrainedUpAxis(ConstrainedUpAxis value)` Sets the axis to constrain the up vector to.
`void`	`setDirection(UnitCartesian value)` Sets the direction of the camera in `Axes`.
`void`	`setDistance(double value)` Sets the distance the camera position is from the reference point.
`void`	`setFarNearPlaneRatio(double value)` Sets the value that is used to compute subdivisions of the viewing frustum.
`void`	`setFarPlane(double value)` Sets the distance in meters from the camera to the far plane.
`void`	`setFieldOfView(double value)` Sets field of view in radians.
`void`	`setLockViewDirection(boolean value)` Sets whether the camera's direction is locked.
`void`	`setNearPlane(double value)` Sets the distance in meters from the camera to the near plane.
`void`	`setPosition(Cartesian value)` Sets the position of the camera.
`void`	`setReferencePoint(Cartesian value)` Sets the reference point of the camera.
`void`	`setUpVector(UnitCartesian value)` Sets the up direction of the camera in `Axes`.
`boolean`	`tryCartographicToWindow(CentralBody centralBody, Cartographic position, Rectangular[] windowPosition)` Converts a `Cartographic` position to a pixel coordinate relative to the `Insight3D` control.
`boolean`	`tryWindowToCartographic(CentralBody centralBody, Rectangular position, Cartographic[] cartographicPosition)` Converts a pixel coordinate relative to the `Insight3D` control to a `Cartographic` position.
`void`	`view(Axes axes, Point cameraPosition, Point referencePoint)` Views from a point to a point.
`void`	`view(Axes axes, Point cameraPosition, Point referencePoint, UnitCartesian upAxis)` Views from a point to a point.
`void`	`viewCentralBody(CentralBody centralBody, Axes axes)` Zoom to a central body and use the specified axes for rotation.
`void`	`viewDirection(Axes axes, Point cameraPosition, Vector direction)` Views from a point to a direction.
`void`	`viewDirection(Axes axes, Point cameraPosition, Vector direction, UnitCartesian upAxis)` Views from a point to a direction.
`void`	`viewExtent(CentralBody centralBody, CartographicExtent extent)` Zooms to a `CartographicExtent` on the `centralBody`.
`void`	`viewExtent(CentralBody centralBody, double west, double south, double east, double north)` Zooms to a rectangular extent composed of `west`, `south`, `east`, `north` on the `centralBody`.
`void`	`viewOffset(Axes axes, Point referencePoint, Cartesian offset)` Sets the camera's reference point - the point the camera is looking at.
`void`	`viewOffset(Axes axes, Point referencePoint, Cartesian offset, UnitCartesian upAxis)` Sets the camera's reference point - the point the camera is looking at.
`void`	`viewOffsetDirection(Axes axes, Point referencePoint, Vector direction)` Sets the camera's reference point - the point the camera is looking at.
`void`	`viewOffsetDirection(Axes axes, Point referencePoint, Vector direction, UnitCartesian upAxis)` Sets the camera's reference point - the point the camera is looking at.
`Visibility`	`visibilityTest(ReferenceFrame referenceFrame, BoundingSphere sphere)` Gets the visibility of a sphere against the view frustum and any occluding central bodies.
`Cartographic`	`windowToCartographic(CentralBody centralBody, Rectangular position)` Converts a pixel coordinate relative to the `Insight3D` control to a `Cartographic` position.

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

- 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
```
public final void dispose()
```
    Description copied from interface: IDisposable
    
    Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
    
    Specified by:
    
    dispose in interface IDisposable
  - dispose
```
protected void dispose(boolean disposing)
```
  - getPosition
```
public final Cartesian getPosition()
```
    Gets the position of the camera.
  - setPosition
```
public final void setPosition(Cartesian value)
```
    Sets the position of the camera.
  - getReferencePoint
```
public final Cartesian getReferencePoint()
```
    Gets the reference point of the camera.
  - setReferencePoint
```
public final void setReferencePoint(Cartesian value)
```
    Sets the reference point of the camera.
  - getDirection
```
public final UnitCartesian getDirection()
```
    Gets the direction of the camera in Axes.
  - setDirection
```
public final void setDirection(UnitCartesian value)
```
    Sets the direction of the camera in Axes.
  - getUpVector
```
public final UnitCartesian getUpVector()
```
    Gets the up direction of the camera in Axes.
  - setUpVector
```
public final void setUpVector(UnitCartesian value)
```
    Sets the up direction of the camera in Axes.
  - getDistance
```
public final double getDistance()
```
    Gets the distance the camera position is from the reference point.
  - setDistance
```
public final void setDistance(double value)
```
    Sets the distance the camera position is from the reference point.
  - getAxes
```
public final Axes getAxes()
```
    Gets camera's axes of rotation.
  - setAxes
```
public final void setAxes(Axes value)
```
    Sets camera's axes of rotation.
  - getConstrainedUpAxis
```
public final ConstrainedUpAxis getConstrainedUpAxis()
```
    Gets the axis to constrain the up vector to.
  - setConstrainedUpAxis
```
public final void setConstrainedUpAxis(ConstrainedUpAxis value)
```
    Sets the axis to constrain the up vector to.
  - getAllowRotationOverConstrainedUpAxis
```
public final boolean getAllowRotationOverConstrainedUpAxis()
```
    Gets whether the camera can rotate over the constrained up axis. For example, if true the camera would be able to flip over the North Pole and view the globe upside down.
  - setAllowRotationOverConstrainedUpAxis
```
public final void setAllowRotationOverConstrainedUpAxis(boolean value)
```
    Sets whether the camera can rotate over the constrained up axis. For example, if true the camera would be able to flip over the North Pole and view the globe upside down.
  - getLockViewDirection
```
public final boolean getLockViewDirection()
```
    Gets whether the camera's direction is locked.
  - setLockViewDirection
```
public final void setLockViewDirection(boolean value)
```
    Sets whether the camera's direction is locked.
  - getFieldOfView
```
public final double getFieldOfView()
```
    Gets field of view in radians. The field of view is applied to the larger of the window dimensions. For example, if the window width was 640 and the height was 480, the field of view applies to the horizontal. Use HorizontalFieldOfView and VerticalFieldOfView to get the horizontal and vertical field of views. Wide fields of views generally show more objects but can look distorted as compared to narrower ones.
    
    See Also:
    
    HorizontalFieldOfView, VerticalFieldOfView
  - setFieldOfView
```
public final void setFieldOfView(double value)
```
    Sets field of view in radians. The field of view is applied to the larger of the window dimensions. For example, if the window width was 640 and the height was 480, the field of view applies to the horizontal. Use HorizontalFieldOfView and VerticalFieldOfView to get the horizontal and vertical field of views. Wide fields of views generally show more objects but can look distorted as compared to narrower ones.
    
    See Also:
    
    HorizontalFieldOfView, VerticalFieldOfView
  - getHorizontalFieldOfView
```
public final double getHorizontalFieldOfView()
```
    Gets the horizontal field of view in radians.
    
    See Also:
    
    FieldOfView, VerticalFieldOfView
  - getVerticalFieldOfView
```
public final double getVerticalFieldOfView()
```
    Gets the vertical field of view in radians.
    
    See Also:
    
    FieldOfView, HorizontalFieldOfView
  - getNearPlane
```
public final double getNearPlane()
```
    Gets the distance in meters from the camera to the near plane.
  - setNearPlane
```
public final void setNearPlane(double value)
```
    Sets the distance in meters from the camera to the near plane.
  - getFarPlane
```
public final double getFarPlane()
```
    Gets the distance in meters from the camera to the far plane.
  - setFarPlane
```
public final void setFarPlane(double value)
```
    Sets the distance in meters from the camera to the far plane.
  - getFarNearPlaneRatio
```
public final double getFarNearPlaneRatio()
```
    Gets the value that is used to compute subdivisions of the viewing frustum. A large value will be faster but lose z-value precision. A small value will have better precision but perform slower. The default value of 1000 achieves a good balance between speed and accuracy.
  - setFarNearPlaneRatio
```
public final void setFarNearPlaneRatio(double value)
```
    Sets the value that is used to compute subdivisions of the viewing frustum. A large value will be faster but lose z-value precision. A small value will have better precision but perform slower. The default value of 1000 achieves a good balance between speed and accuracy.
  - getDistancePerRadius
```
public final double getDistancePerRadius()
```
    Returns the distance that the Camera's Position should be from the ReferencePoint in order to ensure that a sphere with a 1 meter radius centered at the ReferencePoint fits entirely in the view frustum.
  - getSnapshot
```
public final CameraSnapshot getSnapshot()
```
    Gets the camera snapshot settings.
  - getVideoRecording
```
public final CameraVideoRecording getVideoRecording()
```
    Gets the camera video recorder.
  - getPixelSizePerDistance
```
public final double getPixelSizePerDistance()
```
    Gets the approximate number of meters covered by a pixel that is 1 meter away from the camera. This is commonly multiplied by the distance from the camera to an object to compute the approximate number of meters covered by a pixel of the object.
    Example 1:
    
    Assume PixelSizePerDistance is 0.001. This means at 1 meter away, the size of a pixel is 0.001 meters. Therefore, the size of 1 pixel at 2,000 meters away is:
    
    2,000 meters * 0.001 (meters / pixel / meters) = 2 meters/pixel
    
    Example 2:
    
    Assume PixelSizePerDistance is 0.001. This means at 1 meter away, the size of a pixel is 0.001 meters. The diameter, in pixels, of a sphere 2,000 meters away that has a diameter of 10 meters is:
    
    10 meters / (2,000 meters * 0.001 (meters / pixel / meters)) = 5 pixels
    
    PixelSizePerDistance is accurate for a pixel in the center of the window. Accuracy decreases slightly the farther off center a pixel is and the wider the camera's field of view is.
    
    See Also:
    
    FieldOfView
  - getPositionReferenceFrame
```
public final ReferenceFrame getPositionReferenceFrame()
```
    Gets the ReferenceFrame that the Position is returned in. This ReferenceFrame is composed of the camera's from Point and the Axes.
  - getReferencePointReferenceFrame
```
public final ReferenceFrame getReferencePointReferenceFrame()
```
    Gets the ReferenceFrame that the ReferencePoint is returned in. This ReferenceFrame is composed of the camera's to Point and the Axes.
  - refreshEvaluators
```
public final void refreshEvaluators()
```
    Refreshes all evaluators for the axes, points, or vectors that are used in the current camera view. This should be called if the axes, points, or vectors are changed. If you find yourself calling this frequently, consider using the Position and Direction properties instead of methods taking axes, points, and vectors. For more information on evaluators, see the overview topic on Evaluators and Evaluator Groups topic.
  - visibilityTest
```
public final Visibility visibilityTest(ReferenceFrame referenceFrame,
                                       BoundingSphere sphere)
```
    Gets the visibility of a sphere against the view frustum and any occluding central bodies.
    
    Parameters:
    
    referenceFrame - The ReferenceFrame that sphere is in.
    
    sphere - The bounding sphere to be tested.
    
    Returns:
    
    The visibility of the sphere.
  - cartographicToWindow
```
public final Rectangular cartographicToWindow(CentralBody centralBody,
                                              Cartographic position)
```
    Converts a Cartographic position to a pixel coordinate relative to the Insight3D control. This method can throw an exception.
    
    Parameters:
    
    centralBody - The CentralBody of the position.
    
    position - The Cartographic position to convert.
    
    Returns:
    
    The pixel coordinate of the Cartographic position relative to the Insight3D control. The coordinate can be fractional.
  - tryCartographicToWindow
```
public final boolean tryCartographicToWindow(CentralBody centralBody,
                                             Cartographic position,
                                             Rectangular[] windowPosition)
```
    Converts a Cartographic position to a pixel coordinate relative to the Insight3D control. This method does not throw an exception.
    
    Parameters:
    
    centralBody - The CentralBody of the position.
    
    position - The Cartographic position to convert.
    
    windowPosition - The pixel coordinate of the Cartographic position relative to the Insight3D control. The coordinate can be fractional.
    
    Returns:
    
    False if unable to convert the cartographic to a window coordinate.
  - windowToCartographic
```
public final Cartographic windowToCartographic(CentralBody centralBody,
                                               Rectangular position)
```
    Converts a pixel coordinate relative to the Insight3D control to a Cartographic position. For speed, terrain is not considered; if the pixel coordinate does not intersect the ellipsoid, an exception is thrown.
    
    Parameters:
    
    centralBody - The CentralBody of the position.
    
    position - The pixel coordinate to convert.
    
    Returns:
    
    The Cartographic position.
  - tryWindowToCartographic
```
public final boolean tryWindowToCartographic(CentralBody centralBody,
                                             Rectangular position,
                                             Cartographic[] cartographicPosition)
```
    Converts a pixel coordinate relative to the Insight3D control to a Cartographic position. For speed, terrain is not considered. This method does not throw an exception.
    
    Parameters:
    
    centralBody - The CentralBody of the position.
    
    position - The pixel coordinate to convert.
    
    cartographicPosition - The Cartographic position
    
    Returns:
    
    False if unable to convert the window coordinate to a cartographic.
  - viewCentralBody
```
public final void viewCentralBody(CentralBody centralBody,
                                  Axes axes)
```
    Zoom to a central body and use the specified axes for rotation. The reference point is set to the center of the central body and the camera's position is set so the entire central body is visible.
    
    Parameters:
    
    centralBody - The CentralBody to be viewed.
    
    axes - The Axes of rotation. Axes (get) will be set to this.
  - viewExtent
```
public final void viewExtent(CentralBody centralBody,
                             CartographicExtent extent)
```
    Zooms to a CartographicExtent on the centralBody. The camera will be looking straight down at the extent, with the up vector pointing toward local north. The Axes is set to an east-north-up axes at the center of extent.
    
    Parameters:
    
    centralBody - The CentralBody that the extent is on.
    
    extent - The CartographicExtent to be viewed.
  - viewExtent
```
public final void viewExtent(CentralBody centralBody,
                             double west,
                             double south,
                             double east,
                             double north)
```
    Zooms to a rectangular extent composed of west, south, east, north on the centralBody. The camera will be looking straight down at the extent, with the up vector pointing toward local north. The Axes is set to an east-north-up axes at the center of the extent.
    
    Parameters:
    
    centralBody - The CentralBody that the extent is on.
    
    west - The west longitude of the extent.
    
    south - The south latitude of the extent.
    
    east - The east longitude of the extent.
    
    north - The north latitude of the extent.
  - view
```
public final void view(Axes axes,
                       Point cameraPosition,
                       Point referencePoint,
                       UnitCartesian upAxis)
```
    Views from a point to a point. Sets the camera's position and the reference point the camera is looking at.
    
    Parameters:
    
    axes - The Axes of rotation. Axes (get) will be set to this.
    
    cameraPosition - The Point that will be evaluated at the animation time to get Position (get).
    
    referencePoint - The Point that will be evaluated at the animation time to get ReferencePoint (get).
    
    upAxis - The up direction in axes.
  - view
```
public final void view(Axes axes,
                       Point cameraPosition,
                       Point referencePoint)
```
    Views from a point to a point. Sets the camera's position and the reference point the camera is looking at.
    
    Parameters:
    
    axes - The Axes of rotation. Axes (get) will be set to this.
    
    cameraPosition - The Point that will be evaluated at the animation time to get Position (get).
    
    referencePoint - The Point that will be evaluated at the animation time to get ReferencePoint (get).
  - viewDirection
```
public final void viewDirection(Axes axes,
                                Point cameraPosition,
                                Vector direction,
                                UnitCartesian upAxis)
```
    Views from a point to a direction. Sets the camera's position and the direction vector indicating where the camera is looking.
    
    Parameters:
    
    cameraPosition - The Point that will be evaluated at the animation time to get Position (get).
    
    direction - The Vector that will be evaluated at the animation time to get Direction (get).
    
    upAxis - The up direction in axes.
    
    axes - The Axes of rotation. Axes (get) will be set to this.
  - viewDirection
```
public final void viewDirection(Axes axes,
                                Point cameraPosition,
                                Vector direction)
```
    Views from a point to a direction. Sets the camera's position and the direction vector indicating where the camera is looking.
    
    Parameters:
    
    cameraPosition - The Point that will be evaluated at the animation time to get Position (get).
    
    direction - The Vector that will be evaluated at the animation time to get Direction (get).
    
    axes - The Axes of rotation. Axes (get) will be set to this.
  - viewOffset
```
public final void viewOffset(Axes axes,
                             Point referencePoint,
                             Cartesian offset,
                             UnitCartesian upAxis)
```
    Sets the camera's reference point - the point the camera is looking at. The camera's position is the reference point translated by the offset.
    
    Parameters:
    
    axes - The Axes of rotation. Axes (get) will be set to this.
    
    referencePoint - The Point that will be evaluated at the animation time to get ReferencePoint (get).
    
    offset - The offset of the camera position relative to the referencePoint.
    
    upAxis - The up direction in axes.
  - viewOffset
```
public final void viewOffset(Axes axes,
                             Point referencePoint,
                             Cartesian offset)
```
    Sets the camera's reference point - the point the camera is looking at. The camera's position is the reference point translated by the offset.
    
    Parameters:
    
    axes - The Axes of rotation. Axes (get) will be set to this.
    
    referencePoint - The Point that will be evaluated at the animation time to get ReferencePoint (get).
    
    offset - The offset of the camera position relative to the referencePoint.
  - viewOffsetDirection
```
public final void viewOffsetDirection(Axes axes,
                                      Point referencePoint,
                                      Vector direction,
                                      UnitCartesian upAxis)
```
    Sets the camera's reference point - the point the camera is looking at. The camera's position is the reference point translated by the direction vector.
    
    Parameters:
    
    referencePoint - The Point that will be evaluated at the animation time to get ReferencePoint (get).
    
    direction - The Vector that will be evaluated at the animation time to get the direction to offset the camera position. This will be equivalent to the negative of Direction (get).
    
    upAxis - The up direction in axes.
    
    axes - The Axes of rotation. Axes (get) will be set to this.
  - viewOffsetDirection
```
public final void viewOffsetDirection(Axes axes,
                                      Point referencePoint,
                                      Vector direction)
```
    Sets the camera's reference point - the point the camera is looking at. The camera's position is the reference point translated by the direction vector.
    
    Parameters:
    
    referencePoint - The Point that will be evaluated at the animation time to get ReferencePoint (get).
    
    direction - The Vector that will be evaluated at the animation time to get the direction to offset the camera position. This will be equivalent to the negative of Direction (get).
    
    axes - The Axes of rotation. Axes (get) will be set to this.

Class Camera

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface agi.foundation.compatibility.IDisposable

Method Detail

finalize

dispose

dispose

getPosition

setPosition

getReferencePoint

setReferencePoint

getDirection

setDirection

getUpVector

setUpVector

getDistance

setDistance

getAxes

setAxes

getConstrainedUpAxis

setConstrainedUpAxis

getAllowRotationOverConstrainedUpAxis

setAllowRotationOverConstrainedUpAxis

getLockViewDirection

setLockViewDirection

getFieldOfView

setFieldOfView

getHorizontalFieldOfView

getVerticalFieldOfView

getNearPlane

setNearPlane

getFarPlane

setFarPlane

getFarNearPlaneRatio

setFarNearPlaneRatio

getDistancePerRadius

getSnapshot

getVideoRecording

getPixelSizePerDistance

getPositionReferenceFrame

getReferencePointReferenceFrame

refreshEvaluators

visibilityTest

cartographicToWindow

tryCartographicToWindow

windowToCartographic

tryWindowToCartographic

viewCentralBody

viewExtent

viewExtent

view

view

viewDirection

viewDirection

viewOffset

viewOffset

viewOffsetDirection

viewOffsetDirection