LuciadCPillar 2024.0.08
luciad::PerspectiveCamera Class Referencefinal

A camera that uses an perspective projection. More...

#include <luciad/cameras/PerspectiveCamera.h>

Inheritance diagram for luciad::PerspectiveCamera:
luciad::Camera

Classes

class  Builder
 Factory object that can create new PerspectiveCamera instances. More...
 

Public Member Functions

 ~PerspectiveCamera () override
 
Builder asBuilder () const
 Returns a Builder that is initially configured to build cameras identical to this camera. More...
 
Look asLook () const
 Returns the position and orientation of the camera. More...
 
LookAt asLookAt (double distance) const
 Returns a LookAt that matches the position and orientation of this camera. More...
 
LookFrom asLookFrom () const
 Returns a LookFrom that matches the position and orientation of this camera. More...
 
Coordinate getEye () const override
 Returns the current location of the camera in map coordinates. More...
 
double getFar () const override
 Returns the distance from the eye to the far clipping plane. More...
 
Coordinate getForward () const override
 Returns the (normalized) direction corresponding to the forward direction of the view. More...
 
Angle getFovY () const
 Returns the vertical field of view of the camera. More...
 
double getHeight () const override
 Returns the height in device independent pixels of the viewport of this camera. More...
 
double getNear () const override
 Returns the distance from the eye to the near clipping plane. More...
 
Coordinate getUp () const override
 Returns the (normalized) direction corresponding to the upward direction of the view. More...
 
double getWidth () const override
 Returns the width in device independent pixels of the viewport of this camera. More...
 
Coordinate mapToView (Coordinate mapPoint) const override
 Transforms a point in map coordinates to view coordinates. More...
 
Coordinate viewToMap (Coordinate viewPoint) const override
 Transforms a view point to map coordinates. More...
 
- Public Member Functions inherited from luciad::Camera
virtual ~Camera ()=default
 
virtual Coordinate getEye () const =0
 Returns the current location of the camera in map coordinates. More...
 
virtual double getFar () const =0
 Returns the distance from the eye to the far clipping plane. More...
 
virtual Coordinate getForward () const =0
 Returns the (normalized) direction corresponding to the forward direction of the view. More...
 
virtual double getHeight () const =0
 Returns the height in device independent pixels of the viewport of this camera. More...
 
virtual double getNear () const =0
 Returns the distance from the eye to the near clipping plane. More...
 
virtual Coordinate getUp () const =0
 Returns the (normalized) direction corresponding to the upward direction of the view. More...
 
virtual double getWidth () const =0
 Returns the width in device independent pixels of the viewport of this camera. More...
 
virtual Coordinate mapToView (Coordinate mapPoint) const =0
 Transforms a point in map coordinates to view coordinates. More...
 
virtual Coordinate viewToMap (Coordinate viewPoint) const =0
 Transforms a view point to map coordinates. More...
 

Detailed Description

A camera that uses an perspective projection.

Also known as a pinhole camera.

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 cameras (OrthographicCamera vs PerspectiveCamera) or other (types of) map references (projected vs. geocentric).

A camera transforms points from the map reference to the view (device independent pixel coordinates).

Besides the position, orientation and size properties that it inherits from Camera, the perspective camera defines its projection using a field of view: the angle, in degrees, that determines the vertical viewing angle of the camera. The horizontal field-of-view angle can be derived from the vertical field-of-view and the camera's aspect ratio.

Perspective Camera

Cameras in LuciadCPillar are immutable. You can manipulate the map's camera by creating a modified copy using the builder. The new camera can then be set on the map.

Currently, the PerspectiveCamera is only used in combination with geocentric (3D) map references (aka 3D maps). For now, you cannot use this camera if the map has a projected (grid) reference.

To manipulate a perspective camera in a geocentric reference, consider using lookAt or lookFrom. This allows you to reason about the camera in terms of yaw (angle from north direction), pitch (angle wrt. horizon) and roll. You could also just manipulate the camera's eye position and forward/up directions directly, if that's a better fit for your use case.

Map navigation constraints configured on MapNavigator are not enforced when this camera is updated on the map. Constraints are only respected when using MapNavigator.

Example:

// low-level manipulation of perspective camera: put camera looking over Europe, faced towards the north
auto perspectiveCamera = std::dynamic_pointer_cast<PerspectiveCamera>(map->getCamera());
Camera::Look newCameraPosition{Coordinate(6214861.581912037, 710226.7751339739, 4927634.769711619),
Coordinate(0.9588725076044676, -0.12713997961061635, -0.25376946180526144),
Coordinate(-0.2469197372006221, -0.06727846255744102, 0.9666976010400992)};
auto newCamera = perspectiveCamera->asBuilder().look(newCameraPosition).build();
// ...
// Set the camera on the map, for example by using Map::getAnimationManager
map->setCamera(newCamera);
Structure describing the position and orientation of the camera.
Definition: Camera.h:60
A "POD" for a 3D coordinate.
Definition: Coordinate.h:14
Since
2021.1

Constructor & Destructor Documentation

◆ ~PerspectiveCamera()

luciad::PerspectiveCamera::~PerspectiveCamera ( )
override

Member Function Documentation

◆ asBuilder()

Builder luciad::PerspectiveCamera::asBuilder ( ) const

Returns a Builder that is initially configured to build cameras identical to this camera.

You can then change a subset of the camera properties using this builder to create a new camera.

Returns
a Builder that is initially configured to build cameras identical to this camera.

◆ asLook()

Look luciad::PerspectiveCamera::asLook ( ) const

Returns the position and orientation of the camera.

Returns
the position and orientation of the camera.

◆ asLookAt()

LookAt luciad::PerspectiveCamera::asLookAt ( double  distance) const

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

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

◆ asLookFrom()

LookFrom luciad::PerspectiveCamera::asLookFrom ( ) const

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

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

◆ getEye()

Coordinate luciad::PerspectiveCamera::getEye ( ) const
overridevirtual

Returns the current location of the camera in map coordinates.

Returns
the current location of the camera in map coordinates.

Implements luciad::Camera.

◆ getFar()

double luciad::PerspectiveCamera::getFar ( ) const
overridevirtual

Returns the distance from the eye to the far clipping plane.

Points that fall outside of the near/far interval are clipped.

Returns
the distance from the eye to the far clipping plane.

Implements luciad::Camera.

◆ getForward()

Coordinate luciad::PerspectiveCamera::getForward ( ) const
overridevirtual

Returns the (normalized) direction corresponding to the forward direction of the view.

It is defined in the map reference.

Returns
the (normalized) direction corresponding to the forward direction of the view.

Implements luciad::Camera.

◆ getFovY()

Angle luciad::PerspectiveCamera::getFovY ( ) const

Returns the vertical field of view of the camera.

Returns
the vertical field of view of the camera.
See also
PerspectiveCamera::Builder::fovY

◆ getHeight()

double luciad::PerspectiveCamera::getHeight ( ) const
overridevirtual

Returns the height in device independent pixels of the viewport of this camera.

Returns
the height in device independent pixels of the viewport of this camera.

Implements luciad::Camera.

◆ getNear()

double luciad::PerspectiveCamera::getNear ( ) const
overridevirtual

Returns the distance from the eye to the near clipping plane.

Points that fall outside of the near/far interval are clipped.

Returns
the distance from the eye to the near clipping plane.

Implements luciad::Camera.

◆ getUp()

Coordinate luciad::PerspectiveCamera::getUp ( ) const
overridevirtual

Returns the (normalized) direction corresponding to the upward direction of the view.

It is defined in the map reference.

Returns
the (normalized) direction corresponding to the upward direction of the view.

Implements luciad::Camera.

◆ getWidth()

double luciad::PerspectiveCamera::getWidth ( ) const
overridevirtual

Returns the width in device independent pixels of the viewport of this camera.

Returns
the width in device independent pixels of the viewport of this camera.

Implements luciad::Camera.

◆ mapToView()

Coordinate luciad::PerspectiveCamera::mapToView ( Coordinate  mapPoint) const
overridevirtual

Transforms a point in map coordinates to view coordinates.

For perspective cameras, the resulting view coordinate will contain a z-coordinate. This allows to transform the resulting view point back to the original point.

Parameters
mapPointA point, defined in the reference of the Map.
Returns
a point in view coordinates, in device independent pixels. (0, 0) is defined in the top-left corner of the screen.
Note
This method does not take into account the visibility of a map location. It will, for example, convert the point regardless of whether it is clipped away or not by the rendering pipeline. For most use cases, it is preferred to use the ViewMapTransformation to convert a location in map coordinates to view coordinates.

Implements luciad::Camera.

◆ viewToMap()

Coordinate luciad::PerspectiveCamera::viewToMap ( Coordinate  viewPoint) const
overridevirtual

Transforms a view point to map coordinates.

When the camera is a perspective camera, the z-value of the view point is used to determine the depth of the Map point:

  • -∞ => the point is located on the eye point of the camera
  • ]-∞, 0[ => the point is located between the camera eye point and the near plane
  • [0, 1] => the point is between the near plane and the far plane
  • ]1, far/(far-near)] => the point is located beyond the far plane.
  • ]far/(far-near), +∞[ => the point is located behind the camera.
Parameters
viewPointA view point, in device independent pixels. (0, 0) is defined in the top-left corner of the screen.
Returns
a point defined in the reference of the map reference.
Note
This method does not take terrain or earth geometry into account. For most use cases, it is preferred to use the ViewMapTransformation to convert a view location to a map point on the terrain or a visible surface.

Implements luciad::Camera.