Package com.victorvalentim.zividomelive.render.camera

Class OrbitCamera

java.lang.Object
com.victorvalentim.zividomelive.render.camera.OrbitCamera
public final class OrbitCamera extends Object
Scene-space quaternion orbit camera provided as a native ziviDomeLive service.

The camera transforms the scene modelview directly inside Scene.sceneRender(PGraphicsOpenGL). Because it operates in scene space, the same pose works across Standard, domemaster, equirectangular, and skybox views without changing spherical calibration controls.

Typical usage inside a Scene:

 public void sceneRender(PGraphicsOpenGL pg) {
     pg.pushMatrix();
     services.camera().apply(pg);
     // ... draw scene content ...
     pg.popMatrix();
 }

Rotations use unit quaternions (gimbal-lock free). Programmatic pose changes are smoothly interpolated (SLERP/LERP), while direct mouse manipulation is applied immediately so drag and wheel gestures remain attached to the pointer.

API stability: Advanced Stable.

Since:
2.0.0

  • Constructor Summary

    Constructors
    Constructor
    Description
    OrbitCamera()
    Creates an orbit camera with a default distance of 1500 units.
    OrbitCamera(float initialDistance)
    Creates an orbit camera looking at the origin from the given distance.
    OrbitCamera(processing.core.PVector initialTarget, float initialDistance)
    Creates an orbit camera looking at an initial target from the given distance.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    apply(processing.opengl.PGraphicsOpenGL pg)
    Applies the camera transform to the given scene graphics.
    float
    getDistance()
    Returns the current (interpolated) orbit distance.
    Quaternion
    getOrientation()
    Returns the current immutable, interpolated orientation quaternion.
    processing.core.PVector
    getTarget()
    Returns a copy of the current (interpolated) look-at target.
    void
    goTo(processing.core.PVector target, Quaternion orientation, float distance)
    Changes target, orientation, and distance as one smoothly interpolated pose.
    void
    mouseEvent(processing.event.MouseEvent event)
    Handles mouse input: drag to orbit, wheel to fly in/out.
    void
    reset(float d)
    Resets the camera to identity orientation, origin target and the given distance.
    void
    resetInputState()
    Clears transient pointer state without changing the camera pose.
    void
    rotateAround(float ax, float ay, float az, float angle)
    Orbits the camera around a world-space axis (eases smoothly).
    void
    rotateAround(processing.core.PVector axis, float angle)
    Orbits the camera around a world-space Processing vector (eases smoothly).
    void
    rotateAroundImmediate(float ax, float ay, float az, float angle)
    Applies an orbit rotation immediately, keeping the interpolation goal synchronized.
    void
    rotateAroundImmediate(processing.core.PVector axis, float angle)
    Applies an orbit rotation around a Processing vector immediately.
    void
    setCollapseGuard(float guard)
    Sets a collapse-guard dead zone around distance 0.
    void
    setDistance(float d)
    Sets the goal orbit distance (clamped, eased smoothly).
    void
    setDistanceImmediate(float distance)
    Immediately changes only the distance and synchronizes its interpolation goal.
    void
    setDistanceLimits(float min, float max)
    Sets the allowed distance range for zoom.
    void
    setDragSensitivity(float dragSensitivity)
    Sets drag sensitivity in radians per pixel.
    void
    setLerpFactor(float lerpFactor)
    Sets the interpolation amount per frame (0..1).
    void
    setOrientation(Quaternion q)
    Sets the goal orientation (eased smoothly).
    void
    setOrientationImmediate(Quaternion orientation)
    Immediately changes only the orientation and synchronizes its interpolation goal.
    void
    setTarget(float x, float y, float z)
    Sets the goal look-at target (eased smoothly).
    void
    setTarget(processing.core.PVector target)
    Sets the goal look-at target from a Processing vector (eased smoothly).
    void
    setTargetImmediate(processing.core.PVector target)
    Immediately changes only the look-at target and synchronizes its interpolation goal.
    void
    setWheelSteps(float wheelStep, float wheelPadStep)
    Sets the wheel zoom step sizes.
    void
    snapTo(float tx, float ty, float tz, Quaternion q, float d)
    Immediately snaps the camera to the given pose with no interpolation.
    void
    snapTo(processing.core.PVector target, Quaternion orientation, float distance)
    Immediately snaps the camera to a pose described with a Processing target vector.
    void
    update()
    Advances smooth interpolation toward the current goals by one step.
    void
    zoom(float amount)
    Changes the goal distance by a signed amount (clamped to limits).
    void
    zoomImmediate(float amount)
    Changes the current distance immediately and keeps its interpolation goal synchronized.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • OrbitCamera

      public OrbitCamera(float initialDistance)
      Creates an orbit camera looking at the origin from the given distance.
      Parameters:
      initialDistance - initial distance from the target

    • OrbitCamera

      public OrbitCamera(processing.core.PVector initialTarget, float initialDistance)
      Creates an orbit camera looking at an initial target from the given distance.
      Parameters:
      initialTarget - initial look-at target; must not be null
      initialDistance - initial distance from the target

    • OrbitCamera

      public OrbitCamera()
      Creates an orbit camera with a default distance of 1500 units.

  • Method Details

    • apply

      public void apply(processing.opengl.PGraphicsOpenGL pg)
      Applies the camera transform to the given scene graphics. Call inside sceneRender between pushMatrix/popMatrix.

      This method reads camera state but does not advance interpolation.

      Parameters:
      pg - non-null scene graphics to transform

    • update

      public void update()
      Advances smooth interpolation toward the current goals by one step.

      The ziviDomeLive facade calls this exactly once per Processing frame for its shared camera; scenes using SceneCameraService must not call it again. Code that constructs a standalone camera owns its update cadence.

    • rotateAround

      public void rotateAround(float ax, float ay, float az, float angle)
      Orbits the camera around a world-space axis (eases smoothly).
      Parameters:
      ax - axis x component
      ay - axis y component
      az - axis z component
      angle - rotation angle in radians

    • rotateAround

      public void rotateAround(processing.core.PVector axis, float angle)
      Orbits the camera around a world-space Processing vector (eases smoothly).
      Parameters:
      axis - world-space axis; must not be null
      angle - rotation angle in radians

    • rotateAroundImmediate

      public void rotateAroundImmediate(float ax, float ay, float az, float angle)
      Applies an orbit rotation immediately, keeping the interpolation goal synchronized.
      Parameters:
      ax - axis x component
      ay - axis y component
      az - axis z component
      angle - rotation angle in radians

    • rotateAroundImmediate

      public void rotateAroundImmediate(processing.core.PVector axis, float angle)
      Applies an orbit rotation around a Processing vector immediately.
      Parameters:
      axis - world-space axis; must not be null
      angle - rotation angle in radians

    • zoom

      public void zoom(float amount)
      Changes the goal distance by a signed amount (clamped to limits).
      Parameters:
      amount - distance delta (positive flies away, negative flies in)

    • zoomImmediate

      public void zoomImmediate(float amount)
      Changes the current distance immediately and keeps its interpolation goal synchronized. This is intended for direct manipulation such as mouse-wheel navigation.
      Parameters:
      amount - distance delta (positive flies away, negative flies in)

    • mouseEvent

      public void mouseEvent(processing.event.MouseEvent event)
      Handles mouse input: drag to orbit, wheel to fly in/out.
      Parameters:
      event - non-null Processing mouse event

    • resetInputState

      public void resetInputState()
      Clears transient pointer state without changing the camera pose. The next drag starts from a fresh anchor instead of reusing stale coordinates.

    • setTarget

      public void setTarget(float x, float y, float z)
      Sets the goal look-at target (eased smoothly).
      Parameters:
      x - target x
      y - target y
      z - target z

    • setTarget

      public void setTarget(processing.core.PVector target)
      Sets the goal look-at target from a Processing vector (eased smoothly).
      Parameters:
      target - desired target; must not be null

    • setDistance

      public void setDistance(float d)
      Sets the goal orbit distance (clamped, eased smoothly).
      Parameters:
      d - desired distance

    • setOrientation

      public void setOrientation(Quaternion q)
      Sets the goal orientation (eased smoothly).
      Parameters:
      q - desired orientation quaternion

    • goTo

      public void goTo(processing.core.PVector target, Quaternion orientation, float distance)
      Changes target, orientation, and distance as one smoothly interpolated pose.
      Parameters:
      target - desired look-at target; must not be null
      orientation - desired orientation; must not be null
      distance - desired orbit distance

    • snapTo

      public void snapTo(float tx, float ty, float tz, Quaternion q, float d)
      Immediately snaps the camera to the given pose with no interpolation.
      Parameters:
      tx - target x
      ty - target y
      tz - target z
      q - orientation quaternion
      d - distance

    • snapTo

      public void snapTo(processing.core.PVector target, Quaternion orientation, float distance)
      Immediately snaps the camera to a pose described with a Processing target vector.
      Parameters:
      target - look-at target; must not be null
      orientation - orientation quaternion; must not be null
      distance - orbit distance

    • setTargetImmediate

      public void setTargetImmediate(processing.core.PVector target)
      Immediately changes only the look-at target and synchronizes its interpolation goal.
      Parameters:
      target - desired target; must not be null

    • setOrientationImmediate

      public void setOrientationImmediate(Quaternion orientation)
      Immediately changes only the orientation and synchronizes its interpolation goal.
      Parameters:
      orientation - desired orientation; must not be null

    • setDistanceImmediate

      public void setDistanceImmediate(float distance)
      Immediately changes only the distance and synchronizes its interpolation goal.
      Parameters:
      distance - desired orbit distance

    • reset

      public void reset(float d)
      Resets the camera to identity orientation, origin target and the given distance.
      Parameters:
      d - distance to reset to

    • setDistanceLimits

      public void setDistanceLimits(float min, float max)
      Sets the allowed distance range for zoom.
      Parameters:
      min - minimum distance; callers should supply a finite value no greater than max
      max - maximum distance; callers should supply a finite value no less than min

    • setCollapseGuard

      public void setCollapseGuard(float guard)
      Sets a collapse-guard dead zone around distance 0. When positive, the orbit distance can never enter (-guard, +guard) nor flip sign through zero, which prevents the view from collapsing when the allowed distance range spans both negative and positive values. Set to 0 to disable.
      Parameters:
      guard - half-width of the forbidden zone around zero (>= 0)

    • setLerpFactor

      public void setLerpFactor(float lerpFactor)
      Sets the interpolation amount per frame (0..1). Higher is snappier.
      Parameters:
      lerpFactor - easing factor

    • setDragSensitivity

      public void setDragSensitivity(float dragSensitivity)
      Sets drag sensitivity in radians per pixel.
      Parameters:
      dragSensitivity - finite sensitivity value

    • setWheelSteps

      public void setWheelSteps(float wheelStep, float wheelPadStep)
      Sets the wheel zoom step sizes.
      Parameters:
      wheelStep - finite distance change per standard notch
      wheelPadStep - finite distance change per fractional (trackpad) notch

    • getDistance

      public float getDistance()
      Returns the current (interpolated) orbit distance.
      Returns:
      current distance

    • getTarget

      public processing.core.PVector getTarget()
      Returns a copy of the current (interpolated) look-at target.
      Returns:
      current target as a new PVector

    • getOrientation

      public Quaternion getOrientation()
      Returns the current immutable, interpolated orientation quaternion.
      Returns:
      current orientation