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

#include <luciad/cameras/Camera.h>

Inheritance diagram for luciad::Camera:

Classes
struct	Look
	Structure describing the position and orientation of the camera. More...

struct	Look2D
	Structure describing the position of the camera for an orthographic top-down view. More...

struct	LookAt
	Structure to `orient` a camera based on a specific target point. More...

struct	LookFrom
	Structure describing the position and orientation of the camera. More...

Public Member Functions
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 transforms points from the map reference to view coordinates (device independent pixel coordinates).

In layman's 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 cameras (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 map and view (device independent pixel coordinates on the camera's viewport) 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 map coordinates
The forward vector: the 3D direction the camera is looking in, in map coordinates. The combination of the forward and up vector determines the orientation of the camera, in map space.
The up vector: the 3D direction that indicates the up direction of the camera, in map coordinates. The combination of the forward and up vector determines the orientation of the camera, in map 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.
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 device independent pixels of the camera's viewport. This is the same as the Map width.
The height in device independent pixels of the camera's viewport. This is the same as the Map height.

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).

Unlike Map::ViewMapTransformation, the coordinate conversion methods do not take into account the content on the screen. The camera's methods are nothing more than low-level mathematical functions. In most cases, it is advised to convert coordinate from view to map and vice versa using Map::ViewMapTransformation.

Constructor & Destructor Documentation

◆ ~Camera()

virtual luciad::Camera::~Camera ( )

virtualdefault

Member Function Documentation

◆ getEye()

virtual Coordinate luciad::Camera::getEye ( ) const

pure virtual

Returns the current location of the camera in map coordinates.

Returns: the current location of the camera in map coordinates.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

◆ getFar()

virtual double luciad::Camera::getFar ( ) const

pure virtual

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.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

◆ getForward()

virtual Coordinate luciad::Camera::getForward ( ) const

pure virtual

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.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

◆ getHeight()

virtual double luciad::Camera::getHeight ( ) const

pure virtual

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.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

◆ getNear()

virtual double luciad::Camera::getNear ( ) const

pure virtual

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.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

◆ getUp()

virtual Coordinate luciad::Camera::getUp ( ) const

pure virtual

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.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

◆ getWidth()

virtual double luciad::Camera::getWidth ( ) const

pure virtual

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.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

◆ mapToView()

virtual Coordinate luciad::Camera::mapToView ( Coordinate mapPoint ) const

pure virtual

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

mapPoint A 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.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

◆ viewToMap()

virtual Coordinate luciad::Camera::viewToMap ( Coordinate viewPoint ) const

pure virtual

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

viewPoint A 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.

Implemented in luciad::OrthographicCamera, and luciad::PerspectiveCamera.

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Camera()

Member Function Documentation

◆ getEye()

◆ getFar()

◆ getForward()

◆ getHeight()

◆ getNear()

◆ getUp()

◆ getWidth()

◆ mapToView()

◆ viewToMap()