Class CameraAbstract

A camera transforms points from the 'world' reference (often the map's reference) to the view (pixel coordinates). In layman terms: just like with television, the camera's position, orientation (and other parameters like the projection) determines what is shown on screen.

Note that the Camera API is a low-level API. For simple map navigation use cases, it's recommended to use the higher-level API. The MapNavigator API works in both 2D and 3D, on all map references. If you use the low-level Camera API, keep in mind that the same camera manipulation implementation might not work for other types of camera's (OrthographicCamera vs PerspectiveCamera) or other (types of) map references (projected vs. geocentric).

This is a base class shared by both PerspectiveCamera and OrthographicCamera. It describes the position, orientation and viewport of the camera, as well as provide functions to transform between 3D 'world' and 'view' (pixel) points.

The camera's position, orientation and viewport are described by the following parameters:

  • The eye point: the 3D position that the camera is looking from, in world coordinates.
  • The forward vector: the 3D direction the camera is looking in, in world coordinates. The combination of the forward and up vector determines the orientation of the camera. in world space.
  • The up vector: the 3D direction that indicates the 'up' direction of the camera, in world coordinates. The combination of the forward and up vector determines the orientation of the camera, in world space.
  • The near plane distance: the distance from the eye to the near clipping plane. Points that fall outside of the near/far interval, are clipped. Note that the near plane distance can be negative.
  • The far plane distance: the distance from the eye to the far clipping plane. Points that fall outside of the near/far interval, are clipped.
  • The width in pixels of the camera's viewport.
  • The height in pixels of the camera's viewport.
  • The worldReference: the coordinate reference in which the camera is positioned and oriented.

In practice, you only work with PerspectiveCamera and OrthographicCamera. Besides the camera position, orientation and viewport, these subclasses also define a projection (orthographic vs. perspective).

See

Hierarchy

Constructors

constructor

Accessors

aspectRatio eye eyePoint far forward height near up width worldReference

Methods

asLookAt asLookFrom lookAt lookFrom toView toViewPoint toWorld toWorldPoint

Constructors

constructor

Accessors

aspectRatio

  • get aspectRatio(): number

  • The aspect ratio of the view port (width / height).

    Returns number

eye

  • get eye(): Vector3

  • The 3D position that the camera is looking from, in world coordinates.

    Returns Vector3

eyePoint

  • get eyePoint(): Point

  • The 3D position that the camera is looking from, in world coordinates. This one is a shape instead of a Vector3, so it can easily be transformed to other references.

    Returns Point

far

  • get far(): number

  • The world distance from the eye to the far clipping plane. Points that fall outside of the near/far interval, are clipped. By default, this gets updated automatically on a 3D Map, to keep the earth's surface visible. See WebGLMap.adjustDepthRange for more information.

    Returns number

forward

  • get forward(): Vector3

  • The 3D direction the camera is looking in, in world coordinates. The combination of the forward and up vector determines the orientation of the camera. in world space.

    Returns Vector3

height

  • get height(): number

  • The height, in pixels, of the camera's viewport.

    Returns number

near

  • get near(): number

  • The world distance from the eye to the near clipping plane. Points that fall outside of the near/far interval, are clipped. By default, this gets updated automatically on a 3D Map, to keep the earth's surface visible. See WebGLMap.adjustDepthRange for more information. Note that the near plane distance can be negative.

    Returns number

up

  • get up(): Vector3

  • The 3D direction that indicates the 'up' direction of the camera, in world coordinates. The combination of the forward and up vector determines the orientation of the camera, in world space.

    Returns Vector3

width

  • get width(): number

  • The width, in pixels, of the camera's viewport.

    Returns number

worldReference

Methods

asLookAt

  • Returns a LookAt that matches the position and orientation of this camera.

    Note you can only use this function if this camera's worldReference is not a 2D reference.

    Parameters

    • distance: number

      a distance (in the world reference's unit) between the camera's position and the LookAt's ref. For geocentric references, the world unit is usually 1 meter.

    Returns LookAt

    a LookAt object that matches position and orientation of this camera.

    Since

    2023.1

asLookFrom

  • Returns a LookFrom that matches the position and orientation of this camera.

    Note you can only use this function if this camera's worldReference is not a 2D reference. 

    // keep looking from the same point, but pitch the view up 10 degrees
    var lookFrom = map.camera.asLookFrom();
    lookFrom.pitch += 10;
    map.camera = map.camera.lookFrom(lookFrom);

    Returns LookFrom

    a LookFrom object that matches position and orientation of this camera.

    Since

    2023.1

lookAt

  • Returns a camera that matches the position and orientation of the specified LookAt.

    If lookAt.ref is a Point, then that point will be transformed to worldReference (if necessary).

    Note you can only use this function if this camera's worldReference is not a 2D reference. 

    map.camera = map.camera.lookAt({
      ref: createPoint(getReference("CRS:84"), [52, 2, 0]),
      distance: 50e3,
      yaw: 180,
      pitch: -35,
      roll: 0
    });

    Parameters

    • lookAt: LookAt

      The returned camera will match this LookFrom's position and orientation.

    Returns Camera

    a camera that matches the position and orientation of the LookAt that was passed in.

    Since

    2023.1

lookFrom

  • Returns a camera that matches the position and orientation of the specified LookFrom.

    If lookFrom.eye is a Point, then that point will be transformed to worldReference (if necessary).

    Note you can only use this function if this camera's worldReference is not a 2D reference.

    To perform a lookFrom with navigation constraints enforced you can use MapNavigator#lookFrom. This call will respect navigations constraints and additionally it can do the operation animated. 

    map.camera = map.camera.lookFrom({
     eye: createPoint(getReference("CRS:84"), [0, 0, 20e3]),
     yaw: 180,
     pitch: -35,
     roll: 0
    });

    Parameters

    • lookFrom: LookFrom

      The returned camera will match this LookFrom's position and orientation.

    Returns Camera

    a camera that matches the position and orientation of the LookFrom that was passed in.

    Since

    2023.1

toView

  • Transforms a Vector3 from world to view

    Parameters

    • worldVec: Vector3

      The world point to transform to view space (pixels).

    • Optional vectorSFCT: Vector3

      An optional 'out' parameter. If this is defined, it's x,y and z properties will be assigned to the result of the transformation. If it's not defined, a new Vector3 with the result is constructed and returned. Use this out parameter if you need to transform many points at once, and want to avoid creating many objects.

    Returns Vector3

    The transformed point, in view space (pixels)

toViewPoint

  • Transforms a Point from world to view

    Parameters

    • point: Point

      The point to transform to view space (pixels). If this point is not defined in this camera's worldReference, it will first be transformed to the worldReference.

    • Optional outPointSFCT: Point

      An optional 'out' parameter. If this is defined, that point will be moved to the result of the transformation. If it's not defined, a new Point with the result is constructed and returned. Use this out parameter if you need to transform many points at once, and want to avoid creating many Point instances.

    Returns Point

    The transformed point, in view space (pixels).

toWorld

  • Transforms a Vector3 to world.

    Parameters

    • viewVec: Vector3

      The view point (pixels) to transform to world space.

    • Optional vectorSFCT: Vector3

      An optional 'out' parameter. If this is defined, it's x,y and z properties will be assigned to the result of the transformation. If it's not defined, a new Vector3 with the result is constructed and returned. Use this out parameter if you need to transform many points at once, and want to avoid creating many objects.

    Returns Vector3

    The transformed point, in world space.

toWorldPoint

  • Transforms a Point to world.

    Parameters

    • viewPoint: Point

      The point to transform to view space (pixels). A 'view' point has 'null' as its reference.

    • Optional outPointSFCT: Point

      An optional 'out' parameter. If this is defined, that point will be moved to the result of the transformation. If it is defined, and has a reference other than worldReference, it will be transformed to that reference. If it's not defined, a new Point with the result is constructed and returned. Use this out parameter if you need to transform many points at once, and want to avoid creating many Point instances.

    Returns Point

    The transformed point, in view space (pixels).

Settings

Member Visibility

Theme