luciad::OrthographicCamera Class Reference

A camera that uses an orthographic (or parallel) projection. More...

#include <luciad/cameras/OrthographicCamera.h>

Inheritance diagram for luciad::OrthographicCamera:

Classes
class	Builder
	Factory object that can create new OrthographicCamera instances. More...

Public Member Functions
	~OrthographicCamera () override
Builder	asBuilder () const
	Returns a Builder that can build cameras identical to this camera. More...
Look2D	asLook2D () const
	Returns a description of the camera location targeted towards a 2D top-down view of the map. 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...
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 orthographic (or parallel) projection.

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

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

Orthographic 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 OrthographicCamera is only used in combination with projected (grid) references (aka 2D maps). For now, you cannot use this camera if the map has a geocentric (3D) reference.

For projected (grid) references, the camera should be positioned along the positive Z axis, facing the negative Z direction. This way, the camera is positioned facing the XY-plane, where the map is rendered in.

To manipulate an orthographic camera on a projected (grid) or cartesian reference, we recommend using look2D. This allows you to reason about the camera in 2D space, instead of a 3D space. It also allows you to easily rotate and zoom the camera around any arbitrary view / map point.

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

  // low-level manipulation of an orthographic camera: put the world's origin at pixel 200,200,
  // and rotate the camera by 10 degrees (keeping the same scale)
  auto orthographicCamera = std::dynamic_pointer_cast<OrthographicCamera>(map->getCamera());
 
  // Adjust a couple of parameters. look2D::scaleX and look2D::scaleY remain the same
  Camera::Look2D newCameraPosition = orthographicCamera->asLook2D();
  newCameraPosition.viewOrigin = Coordinate(200.0, 200.0);
  newCameraPosition.mapOrigin = Coordinate(0.0, 0.0);
  newCameraPosition.rotation += 10.0;
 
  auto newCamera = orthographicCamera->asBuilder().look2D(newCameraPosition).build();
 
  // ...
  // Set the camera on the map, for example by using Map::getAnimationManager
  map->setCamera(newCamera);

Since

2021.1

Constructor & Destructor Documentation

~OrthographicCamera()

luciad::OrthographicCamera::~OrthographicCamera ( )

override

Member Function Documentation

asBuilder()

Builder luciad::OrthographicCamera::asBuilder

(

)

const

Returns a Builder that can build cameras identical to this camera.

Returns

a Builder that can build cameras identical to this camera.

asLook2D()

Look2D luciad::OrthographicCamera::asLook2D

(

)

const

Returns a description of the camera location targeted towards a 2D top-down view of the map.

Returns

a description of the camera location targeted towards a 2D top-down view of the map.

getEye()

Coordinate luciad::OrthographicCamera::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::OrthographicCamera::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::OrthographicCamera::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.

getHeight()

double luciad::OrthographicCamera::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::OrthographicCamera::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::OrthographicCamera::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::OrthographicCamera::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::OrthographicCamera::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

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.

Implements luciad::Camera.

viewToMap()

Coordinate luciad::OrthographicCamera::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

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.

Implements luciad::Camera.