Package com.luciad.cameras

Class PerspectiveCamera.Builder

java.lang.Object
com.luciad.cameras.PerspectiveCamera.Builder
All Implemented Interfaces:
AutoCloseable
Enclosing class:
PerspectiveCamera
public static final class PerspectiveCamera.Builder extends Object implements AutoCloseable
Factory object that can create new PerspectiveCamera instances.

  • Constructor Details

    • Builder

      public Builder(@NotNull PerspectiveCamera.Builder other)
      Copy constructor.
      Parameters:
      other - the builder to copy.

  • Method Details

    • finalize

      protected void finalize()
      Overrides:
      finalize in class Object

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • eye

      @NotNull public PerspectiveCamera.Builder eye(@NotNull Coordinate eye)
      Sets the eye the position of the new camera.
      Parameters:
      eye - the position of the new camera.
      Returns:
      this builder

    • orientation

      @NotNull public PerspectiveCamera.Builder orientation(@NotNull Coordinate forward, @NotNull Coordinate up)
      Sets the forward the viewing direction of the new camera and the camera's up direction.
      Parameters:
      forward - the viewing direction of the new camera
      up - the camera's up direction
      Returns:
      this builder

    • look

      @NotNull public PerspectiveCamera.Builder look(@NotNull Camera.Look look)
      Sets the position and orientation of the new camera.
      Parameters:
      look - the position and orientation of the new camera.
      Returns:
      this builder

    • lookAt

      @NotNull public PerspectiveCamera.Builder lookAt(@NotNull Camera.LookAt lookAt)
      Sets the description of what the camera is looking at and the orientation of the camera.
      Parameters:
      lookAt - the description of what the camera is looking at and the orientation of the camera.
      Returns:
      this builder

    • lookFrom

      @NotNull public PerspectiveCamera.Builder lookFrom(@NotNull Camera.LookFrom lookFrom)
      Sets the description of the position and orientation of the new camera.
      Parameters:
      lookFrom - the description of the position and orientation of the new camera.
      Returns:
      this builder

    • fovY

      @NotNull public PerspectiveCamera.Builder fovY(@NotNull Angle fovY)
      Sets the vertical field of view.

      Note
      The horizontal field of view will be derived from vertical field of view based on the aspect ratio. You can convert between horizontal and vertical field-of-view angles using the following formulae: 
          // Vertical -> horizontal field-of-view
    double aspectRatio = (double) (camera.getWidth()) / camera.getHeight();
    Angle cameraFovX = Angle.fromRadians(2.0 * Math.atan(Math.tan(camera.getFovY().getRadians() / 2.0) * aspectRatio));

    // Horizontal -> vertical field-of-view
    Angle newFovX = new Angle(60.0);
    Angle newFovY = Angle.fromRadians(2 * Math.atan(Math.tan(newFovX.getRadians() / 2.0) / aspectRatio));
      Parameters:
      fovY - the new vertical field of view.
      Returns:
      this builder

    • nearFar

      @NotNull public PerspectiveCamera.Builder nearFar(double nearPlane, double farPlane)
      Sets the near and far clipping distances of the new camera.

      These values only take effect when the map's automatic near/far adjustment is turned off (see Map#setAutoAdjustDepthRangeEnabled).

      Note that choosing a range that is too wide can introduce depth artifacts. Choosing a range that is too narrow can clip parts of the visible object, or even clip it away completely.

      Both distances are in the units of the map reference (meters for a geocentric reference). The near plane must be positive and smaller than the far plane.

      Guidelines for choosing a range:

      • Depth precision is governed by the far to near ratio, not by the absolute values. Very large ratios make distant surfaces z-fight, so keep the ratio as small as the scene allows (up to the order of 1e5 is usually fine).
      • Push the near plane as far from the eye as you can without clipping the closest geometry you care about. The near plane dominates precision, so a needlessly small one wastes precision over the whole range.
      • Pull the far plane in to just beyond the farthest geometry that has to stay visible.
      • Prefer deriving both from the distance between the eye and what you are looking at, rather than fixed values, so the range tracks the scene as you zoom.

      Example ranges for a geocentric (meters) map, with an earth radius of about 6.378e6:

      • Close to the ground, inspecting buildings (eye a few hundred meters up): near about 1, far about 1e5.
      • Regional view (eye tens of kilometers up): near about 1e2, far about 1e6.
      • Whole-earth view (eye a couple of earth radii out): near about 1e5, far about 5e7, reaching the far side of the globe.
      Parameters:
      nearPlane - the distance from the eye to the near clipping plane.
      farPlane - the distance from the eye to the far clipping plane.
      Returns:
      this builder
      Since:
      2026.1

    • build

      @NotNull public PerspectiveCamera build()
      Returns a new perspective camera.
      Returns:
      a new perspective camera.