Class SoCameraInteractor
- java.lang.Object
-
- com.openinventor.inventor.Inventor
-
- com.openinventor.inventor.viewercomponents.SoCameraInteractor
-
- All Implemented Interfaces:
SafeDisposable
public class SoCameraInteractor extends Inventor implements SafeDisposable
Utility class to manipulate a camera. This class provides some useful algorithms to manipulate a camera (translation, rotation, zoom, etc).This class is not, strictly speaking, a true interactor. It does not respond to input events. However it provides the camera manipulation algorithms you need to build an interactor that provides behavior similar to the Open Inventor viewer classes, for example
SoWinExaminerViewer
. An interactor could handle system-dependent events or Open Inventor events (usingSoEventCallback
). It could also be triggered from the user interface (buttons, sliders, etc).Start by creating an instance of
SoCameraInteractor
by giving the camera to be manipulated either to the constructor ofSoCameraInteractor
or to thegetNewInstance()
method. Then, for example, to provide examinerViewer-like rotation behavior:- On a mouse button down event, call
activateOrbiting()
. - On mouse move event, if button is down, call
orbit()
.
To provide the viewer's automatic adjustment of near and far clip planes behavior, call the
adjustClippingPlanes()
method before each render traversal.To see an example "viewer" implemented using this class, please see the SceneExaminer class provided as source code in the Open Inventor SDK:
.../source/com/openinventor/inventor/viewercomponents/nodes
EXAMPLE SceneInteractor SceneExaminer
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand
-
-
Field Summary
-
Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle
-
-
Constructor Summary
Constructors Constructor Description SoCameraInteractor(SoCamera camera)
Create aSoCameraInteractor
for the specified camera.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
activateOrbiting(SbVec2f startPos)
Set the starting point for interactive orbiting.void
activatePanning(SbVec2f initPos, SbViewportRegion vpRegion)
Set the starting point for interactive panning.void
adjustClippingPlanes(SoNode sceneRoot, SbViewportRegion vpRegion)
Adjust near and far clipping planes to minimize clipping of objects in the scene.void
changeViewVolume(float height, float aspect)
Change camera's view volume.boolean
dispose()
Explicitly call this method to force object to dispose its unmanaged resources.void
dolly(float scaleFactor)
Dolly - Makes the scene appear larger or smaller.void
dollyInWindow(SbVec2f topLeftCorner, SbVec2f bottomRightCorner, SbViewportRegion vpRegion)
Moves the camera forward or backward along the view vector to view the region defined by the given corners in normalized screen coordinates.void
dollyWithZoomCenter(SbVec2f centerPos, float scaleFactor, SbViewportRegion vpRegion)
Modifies the camera to ajust the view around the specified point.SoCamera
getCamera()
Returns the associated camera.SbVec3f
getDirectionVector()
Returns the direction vector of the camera.SbVec3f
getFocalPoint()
Returns the camera's "focal point", located focalDistance units from the camera position along the view direction vector (defined by the camera's orientation field).static SoCameraInteractor
getNewInstance(SoCamera camera)
Create an instance for the specified camera.SbVec3f
getViewportCenter()
Deprecated.As of Open Inventor 9500.boolean
isDisposable()
Returns a boolean flag which indicates if it is safe to callSafeDisposable.dispose()
on the object.SbRotation
lookAt(SbVec3f position, SbVec3f target, SbVec3f up)
Returns the rotation needed to point a camera at position toward the given target point while keeping the "up" direction of the camera parallel to the specified up vector.void
orbit(SbRotation rotation)
Orbit the camera by the specified rotation.void
orbit(SbVec2f newPos)
Orbit the camera based on offset from the previous screen position.void
pan(SbVec2f newPos, SbViewportRegion vpRegion)
Pan the camera based on offset from starting point.void
pivot(float angle)
Pivot the camera.void
pointAt(SbVec3f targetPoint)
Sets the orientation of the camera so that it points toward the given target point while keeping the "up" direction of the camera parallel to the positive world coordinate y-axis.boolean
popCamera()
Restore saved camera.SbVec3f
projectToPlane(SbVec2f point, float distFromEye, SbViewportRegion vpRegion)
Project specified 2D point on the plane parallel to the near plane that is at distFromEye units from the eye, see alsoSbViewVolume.getPlanePoint
.SbVec2f
projectToScreen(SbVec3f point, SbViewportRegion vpRegion)
Map a 3D point in world coordinates to a 2D point in normalized screen coordinates (0 <= x,y <= 1), see alsoSbViewVolume.projectToScreen
.void
pushCamera()
Save current camera.void
roll(float angle)
Roll the camera.void
rotate(float angle)
Rotate the camera around the center specified bysetRotationCenter()
and the axis specified bysetRotationAxis()
.void
rotate(SbRotation rot)
Rotate the camera.void
setOrientation(SbRotation rot)
Set the orientation of the camera.void
setPosition(SbVec2f pos, float distFromEye, SbViewportRegion vpRegion)
Move camera to the specified position.void
setPosition(SbVec3f pos)
Move camera to the specified position.void
setRotationAxis(SbVec3f axis)
Set the axis of rotation.void
setRotationCenter(SbVec3f pos)
Set the center of rotation.void
synchronize(SoCamera camera)
Copy field values from the specified camera to the camera of this interactor.void
tilt(float angle)
Tilt the camera.void
translate(SbVec2f displacement, SbViewportRegion vpRegion)
Move camera by the specified 2D displacement.void
translate(SbVec3f trans)
Move camera by the specified 3D displacement.void
viewAll(SoNode node, SbViewportRegion vpRegion)
Move the camera to view the scene defined by the given node.void
viewAll(SoPath path, SbViewportRegion vpRegion)
Move the camera to view the scene defined by the given path.void
viewAxis(SbVec3f direction, SbVec3f up)
Moves and rotates the camera to be aligned with the given direction vector while keeping the up direction of the camera parallel to the specified up vector.void
viewIn(SoNode node, SbViewportRegion vpRegion)
Move camera to the center of the scene defined by the specified node.void
viewIn(SbBox3f bbox)
Move camera to the center of the specified box.void
viewIn(SoPath path, SbViewportRegion vpRegion)
Move camera to the center of the scene defined by the specified path.void
viewX()
Calls viewX((boolean)false).void
viewX(boolean reverse)
NOTE: The camera position is not changed, so the camera may not be looking toward the scene.void
viewY()
Calls viewY((boolean)false).void
viewY(boolean reverse)
Rotate camera to look parallel to the Y axis with +Z up.void
viewZ()
Calls viewZ((boolean)false).void
viewZ(boolean reverse)
Rotate camera to look parallel to the Z axis with +Y up.void
zoom(float zoom)
Zoom - Makes the scene appear larger or smaller.void
zoomInWindow(SbVec2f topLeftCorner, SbVec2f bottomRightCorner, SbViewportRegion vpRegion)
Zooms to the region defined by the given corners in normalized screen coordinates.-
Methods inherited from class com.openinventor.inventor.Inventor
getNativeResourceHandle
-
-
-
-
Constructor Detail
-
SoCameraInteractor
public SoCameraInteractor(SoCamera camera)
Create aSoCameraInteractor
for the specified camera. The camera should be anSoPerspectiveCamera
orSoOrthographicCamera
object. Create an empty object if camera pointer is NULL or invalid
-
-
Method Detail
-
viewZ
public void viewZ()
Calls viewZ((boolean)false).
-
viewY
public void viewY()
Calls viewY((boolean)false).
-
viewX
public void viewX()
Calls viewX((boolean)false).
-
isDisposable
public boolean isDisposable()
Description copied from interface:SafeDisposable
Returns a boolean flag which indicates if it is safe to callSafeDisposable.dispose()
on the object.- Specified by:
isDisposable
in interfaceSafeDisposable
- Returns:
true
if the object can be disposed in a safe manner
-
dispose
public boolean dispose()
Description copied from class:Inventor
Explicitly call this method to force object to dispose its unmanaged resources. The object may not be reused in the application code after this call.- Specified by:
dispose
in interfaceSafeDisposable
- Overrides:
dispose
in classInventor
- Returns:
true
if this object native resources were successfully disposed;false
if it was already disposed or no native resources has been registered for this object.
-
setPosition
public void setPosition(SbVec2f pos, float distFromEye, SbViewportRegion vpRegion)
Move camera to the specified position.- Parameters:
pos
- new position (2D point in normalized screen coordinates: 0 <= x,y <= 1)distFromEye
- the distance at which the point would be back projected.vpRegion
- the actual viewport region
-
orbit
public void orbit(SbRotation rotation)
Orbit the camera by the specified rotation. "Orbit" means to rotate the camera around a fixed point in 3D space. The rotation point is specified using thesetRotationCenter()
method. This method automatically calls thesetRotationAxis()
method with the axis defined by theSbRotation
parameter.Orbit is often used in an "examiner" type of viewer to allow the user to rotate the camera around a point of interest in the scene. Orbit based on mouse or touch events can be implemented using the
orbit()
method. This method can be used, for example, to animate the camera to a new viewpoint. To implement orbit around the camera's "focal point", callsetRotationCenter()
with the value returned fromgetFocalPoint()
.- Parameters:
rotation
- Incremental rotation, i.e. this rotation is multiplied with the current camera orientation.
-
orbit
public void orbit(SbVec2f newPos)
Orbit the camera based on offset from the previous screen position. This method can be used to implement an interactive orbit operation in response to mouse move or touch events. TheactivateOrbiting()
method should be called at the start of the operation. This method uses anSbSphereSheetProjector
to compute a rotation value based on the specified point and the previously specified point.- Parameters:
newPos
- new position, 2D point in normalized screen coordinates (0 <= x,y <= 1). Typically this value is obtained from theSoEvent
method getNormalizedPosition().
-
pushCamera
public void pushCamera()
Save current camera. The values of the camera fields are saved and can be restored by callingpopCamera()
.
-
setPosition
public void setPosition(SbVec3f pos)
Move camera to the specified position.- Parameters:
pos
- new position in world coordinates
-
pan
public void pan(SbVec2f newPos, SbViewportRegion vpRegion)
Pan the camera based on offset from starting point. This method can be used to implement an interactive panning operation in response to move move or touch events. TheactivatePanning()
method should be called at the start of the operation.- Parameters:
newPos
- new position in normalized screen coordinates (0 <= x,y <= 1). Typically this value is obtained from theSoEvent
method getNormalizedPosition().vpRegion
- the actual viewport region
-
pointAt
public void pointAt(SbVec3f targetPoint)
Sets the orientation of the camera so that it points toward the given target point while keeping the "up" direction of the camera parallel to the positive world coordinate y-axis. If this is not possible, it uses the positive z-axis as "up". Equivalent to calling theSoCamera
methodpointAt()
.- Parameters:
targetPoint
- target point
-
translate
public void translate(SbVec2f displacement, SbViewportRegion vpRegion)
Move camera by the specified 2D displacement.- Parameters:
displacement
- 2D displacement in normalized screen coordinates: 0 <= x,y <= 1vpRegion
- the actual viewport region
-
translate
public void translate(SbVec3f trans)
Move camera by the specified 3D displacement.- Parameters:
trans
- translation value in world coordinates
-
activateOrbiting
public void activateOrbiting(SbVec2f startPos)
Set the starting point for interactive orbiting. This method should be called when starting an interaction. Typically this is triggered by a mouse button or touch event. On subsequent mouse move or touch events, call theorbit()
method with the new cursor or touch position.Orbit is often used in an "examiner" type of viewer to allow the user to rotate the camera around a point of interest in the scene. To implement orbit around the camera's "focal point", call
setRotationCenter()
with the value returned fromgetFocalPoint()
.- Parameters:
startPos
- starting position, 2D point in normalized screen coordinates (0 <= x,y <= 1). Typically this value is obtained from theSoEvent
method getNormalizedPosition().
-
getFocalPoint
public SbVec3f getFocalPoint()
Returns the camera's "focal point", located focalDistance units from the camera position along the view direction vector (defined by the camera's orientation field).This is the reference point for some algorithms. For example,
orbit()
is often used in an "examiner" type of viewer to allow the user to rotate the camera around a point of interest in the scene. To implement orbit around the camera's focal point, call thesetRotationCenter()
method with the focal point before calling theorbit()
method.- Returns:
- focal point in world coordinates
-
dolly
public void dolly(float scaleFactor)
Dolly - Makes the scene appear larger or smaller. For a perspective camera, moves the camera forward or backward along the view vector (details below). For an orthographic camera, changes the height field to give a similar visual effect (moving an orthographic camera forward and backward has no visual effect). This is the preferred way to implement the visual effect of "zooming" in and out for a perspective camera. For a perspective camera, dolly means the same thing it means for a camera on a movie set.Note: 'scaleFactor' is the inverse of what you might expect. To make the scene appear 2X larger, specify a scaleFactor of 0.5. This is because scaleFactor multiplies the camera 'focalDistance' or 'height'.
- Perspective camera: The camera has a "focal point" located
focalDistance units from the camera
position along the view direction vector (
orientation). Unlike a real camera, neither focal point nor focal distance has effect on the appearance of the image. The focal point is just a reference point for some algorithms. You can think of it as the "look at" point. The
dolly()
method computes a scale factor from the 'delta' parameter. A new "focal distance" is computed as the current value of the camera's focalDistance field multiplied by this scale factor. Then the camera's position field is modified so the camera is the new focal distance away from the focal point. - Orthographic camera: The
dolly()
method computes a scale factor from the 'delta' parameter and multiplies the camera's height field by this scale factor.
- Perspective camera: The camera has a "focal point" located
focalDistance units from the camera
position along the view direction vector (
orientation). Unlike a real camera, neither focal point nor focal distance has effect on the appearance of the image. The focal point is just a reference point for some algorithms. You can think of it as the "look at" point. The
-
changeViewVolume
public void changeViewVolume(float height, float aspect)
Change camera's view volume. Allows changing the view volume height and width with a single call. For a perspective camera, the height parameter is heightAngle in radians. For an orthographic camera, the height parameter is height in world coordinates.- Parameters:
height
- new camera height or heightAngleaspect
- new camera aspect ratio
-
zoom
public void zoom(float zoom)
Zoom - Makes the scene appear larger or smaller. Sets the camera's heightAngle field (for a perspective camera) or height field (for an orthographic camera) to the specified value. For a perspective camera, the value is in radians and the default is 0.785398. For an orthographic camera the value is in World Coordinates and the default is 2.Conceptually, zoom means approximately the same thing as it does for a real camera - changing the "focal length" of the lens. Making the heightAngle (or height) larger corresponds to using a wide-angle lens, so the scene appears smaller. Making the heightAngle (or height) smaller corresponds to using a telephoto lens, so the scene appears larger.
NOTE: For a perspective camera, we strongly recommend implementing the visual effect of "zoom" by moving the camera closer to, or farther away from, the scene (see
dolly()
). Very small and very large values of heightAngle can produce undesirable results.- Parameters:
zoom
- new zoom value
-
viewY
public void viewY(boolean reverse)
Rotate camera to look parallel to the Y axis with +Z up. NOTE: The camera position is not changed, so the camera may not be looking toward the scene. CallingviewAll()
will move the camera so that the scene is visible again.- Parameters:
reverse
- If false, rotate to look in the -Y direction, else in +Y direction.
-
getViewportCenter
@Deprecated public SbVec3f getViewportCenter()
Deprecated.As of Open Inventor 9500. Use getFocalPoint() instead.Returns the viewport center. On other words, returns the camera's "focal point", located focalDistance units from the camera position along the view direction vector ( orientation).- Returns:
- center in world coordinates
Warning Deprecated since Open Inventor 9500. Use
getFocalPoint()
instead.
-
popCamera
public boolean popCamera()
Restore saved camera. The values of the camera fields are restored to the last pushed values. Returns true if successful, false if the vector of pushed cameras is empty.
-
synchronize
public void synchronize(SoCamera camera)
Copy field values from the specified camera to the camera of this interactor. If the two cameras are not the same type, common fields are copied and the height or heightAngle field is computed.
-
getNewInstance
public static SoCameraInteractor getNewInstance(SoCamera camera)
Create an instance for the specified camera. The camera should be anSoPerspectiveCamera
orSoOrthographicCamera
object. Returns null if the camera parameter is null.
-
getCamera
public SoCamera getCamera()
Returns the associated camera.
-
viewAll
public void viewAll(SoPath path, SbViewportRegion vpRegion)
-
setRotationAxis
public void setRotationAxis(SbVec3f axis)
Set the axis of rotation. Default is (0, 0, 0). This vector is used by therotate(float)
method.- Parameters:
axis
- new rotations axis
-
viewIn
public void viewIn(SoNode node, SbViewportRegion vpRegion)
Move camera to the center of the scene defined by the specified node. Compute the bounding box of the scene and move the camera to the center of this box. The near and far clipping planes will be adjusted to see the inside of the box.- Parameters:
node
- root node of the scenevpRegion
- the actual viewport region
-
setOrientation
public void setOrientation(SbRotation rot)
Set the orientation of the camera. Replaces any previous rotations applied to the camera. Camera position does not change.- Parameters:
rot
- new orientation
-
viewAll
public void viewAll(SoNode node, SbViewportRegion vpRegion)
-
setRotationCenter
public void setRotationCenter(SbVec3f pos)
Set the center of rotation. Default is (0, 0, 0). This position is used by therotate(float)
andorbit()
methods.- Parameters:
pos
- position in world coordinates
-
viewIn
public void viewIn(SbBox3f bbox)
Move camera to the center of the specified box. The near and far clipping planes will be adjusted to see the inside of the box. If the box is empty, nothing happens.
-
viewX
public void viewX(boolean reverse)
NOTE: The camera position is not changed, so the camera may not be looking toward the scene. CallingviewAll()
will move the camera so that the scene is visible again.- Parameters:
reverse
- If false, rotate to look in the -X direction, else in +X direction.
-
viewZ
public void viewZ(boolean reverse)
Rotate camera to look parallel to the Z axis with +Y up. NOTE: The camera position is not changed, so the camera may not be looking toward the scene. CallingviewAll()
will move the camera so that the scene is visible again.- Parameters:
reverse
- If false, rotate to look in the -Z direction, else in +Z direction.
-
rotate
public void rotate(float angle)
Rotate the camera around the center specified bysetRotationCenter()
and the axis specified bysetRotationAxis()
. The default rotation axis is (0,0,0), so calling this method will not have any visible effect until a rotation axis is set. The rotation axis is automatically set by some methods, e.g.orbit()
.- Parameters:
angle
- angle in radians
-
viewIn
public void viewIn(SoPath path, SbViewportRegion vpRegion)
Move camera to the center of the scene defined by the specified path. Compute the bounding box of the scene and move the camera to the center of this box. The near and far clipping planes will be adjusted to see the inside of the box.- Parameters:
path
- path to the scenevpRegion
- the actual viewport region
-
viewAxis
public void viewAxis(SbVec3f direction, SbVec3f up)
Moves and rotates the camera to be aligned with the given direction vector while keeping the up direction of the camera parallel to the specified up vector. The camera position and orientation are changed to look at the point of interest, but the focalDistance is not changed.- Parameters:
direction
- The new view direction vector: this is the vector from the camera's position to the target point. Any future call to the methodgetDirectionVector()
will return the same vector.up
- The new up direction vector
-
projectToPlane
public SbVec3f projectToPlane(SbVec2f point, float distFromEye, SbViewportRegion vpRegion)
Project specified 2D point on the plane parallel to the near plane that is at distFromEye units from the eye, see alsoSbViewVolume.getPlanePoint
.- Parameters:
point
- point to project in normalized screen coordinates (0 <= x,y <= 1)distFromEye
- the distance at which the point would be back projectedvpRegion
- the actual viewport region- Returns:
- projected point in world coordinates
-
getDirectionVector
public SbVec3f getDirectionVector()
Returns the direction vector of the camera.
-
dollyInWindow
public void dollyInWindow(SbVec2f topLeftCorner, SbVec2f bottomRightCorner, SbViewportRegion vpRegion)
Moves the camera forward or backward along the view vector to view the region defined by the given corners in normalized screen coordinates.- Perspective camera: The visual result is similar to
zoomInWindow()
, but this method changes the camera position (closer or farther away) and focalDisance fields instead of changing the heightAngle. This is the recommended method when using a perspective camera, because it avoids the limitations of very small or very large heightAngle values. - Orthographic camera: This method does nothing because moving the camera closer or farther away does not change the visual result.
- Perspective camera: The visual result is similar to
-
roll
public void roll(float angle)
Roll the camera. Incremental in-place rotation around the view direction vector (camera's local Z axis). Rotations are cumulative. Camera position does not change. Positive values roll the camera counter-clockwise.- Parameters:
angle
- angle in radians
-
activatePanning
public void activatePanning(SbVec2f initPos, SbViewportRegion vpRegion)
Set the starting point for interactive panning. This method should be called when starting an interaction. Typically this is triggered by a mouse button or touch event. On subsequent mouse move or touch events, call thepan()
method with the new cursor or touch position.- Parameters:
initPos
- initial position in normalized screen coordinates (0 <= x,y <= 1). Typically this value is obtained from theSoEvent
method getNormalizedPosition().vpRegion
- the actual viewport region
-
lookAt
public SbRotation lookAt(SbVec3f position, SbVec3f target, SbVec3f up)
Returns the rotation needed to point a camera at position toward the given target point while keeping the "up" direction of the camera parallel to the specified up vector. This method does NOT modify the camera node. Set the returned rotation in the camera's orientation field.- Parameters:
position
- of the cameratarget
- position of the targetup
- up vector of the camera
-
dollyWithZoomCenter
public void dollyWithZoomCenter(SbVec2f centerPos, float scaleFactor, SbViewportRegion vpRegion)
Modifies the camera to ajust the view around the specified point. The algorithm is the same as thedolly()
method (for a perspective camera the position field is changed, for an orthographic camera the height field is changed) and the delta parameter is used the same way.- Parameters:
centerPos
- zoom center in normalized screen coordinates (0 <= x,y <= 1). Typically this value is obtained from theSoEvent
method getNormalizedPosition().scaleFactor
- zoom scalevpRegion
- the actual viewport region
-
tilt
public void tilt(float angle)
Tilt the camera. Incremental in-place rotation up/down (around the camera's local X axis). Rotations are cumulative. Camera position does not change. Positive values tilt the camera up.- Parameters:
angle
- angle in radians
-
projectToScreen
public SbVec2f projectToScreen(SbVec3f point, SbViewportRegion vpRegion)
Map a 3D point in world coordinates to a 2D point in normalized screen coordinates (0 <= x,y <= 1), see alsoSbViewVolume.projectToScreen
.- Parameters:
point
- point to project in world coordinatesvpRegion
- the actual viewport region- Returns:
- 2D point in normalized screen coordinates (0 <= x,y <= 1)
-
rotate
public void rotate(SbRotation rot)
Rotate the camera. Incremental in-place rotation. Rotations are cumulative. Camera position does not change (rotationCenter and rotationAxis do not apply).- Parameters:
rot
- new rotation
-
zoomInWindow
public void zoomInWindow(SbVec2f topLeftCorner, SbVec2f bottomRightCorner, SbViewportRegion vpRegion)
Zooms to the region defined by the given corners in normalized screen coordinates.- Perspective camera: This method modifies the
heightAngle field.
Modifying the heightAngle field changes the projection, similar to changing the focal length of a camera. Making the heightAngle very small or very large may cause rendering artifacts. Therefore thedollyInWindow
method is recommended when using a perspective camera. - Orthographic camera: This method modifies the height field.
- Parameters:
topLeftCorner
- top left corner in normalized screen coordinates (0 <= x,y <= 1)bottomRightCorner
- bottom right corner in normalized screen coordinates (0 <= x,y <= 1)vpRegion
- the actual viewport region
- Perspective camera: This method modifies the
heightAngle field.
-
pivot
public void pivot(float angle)
Pivot the camera. Incremental in-place rotation left/right (around the camera's up vector, i.e. local Y axis). Rotations are cumulative. Camera position does not change. Positive values pivot the camera left.- Parameters:
angle
- angle in radians
-
adjustClippingPlanes
public void adjustClippingPlanes(SoNode sceneRoot, SbViewportRegion vpRegion)
Adjust near and far clipping planes to minimize clipping of objects in the scene. Equivalent to the auto clip planes feature in the viewer classes. Typically called before each render traversal.
-
-