envitia::maplink::earth::Camera Class Reference

Detailed Description

The virtual camera within a Surface3D scene.

The Camera class allows an application to modify the view within a Surface3D by configuring the parameters of a virtual Camera:

• Position : The location of the camera in east-north-up (ENU) space.
• Position (Geocentric) : The location of the camera in earth-centered earth-fixed (ECEF) space.
• Orientation : The rotation of the camera, or direction it is facing.
• Field of view (fov) : The extent of the world which is seen by the camera.

The units used by the Camera are:

• Position in degrees latitude and longitude.
• Position (Geocentric) in meters.
• Altitude in meters, relative to the ellipsoid (sea level).
• Field of view in degrees.

The camera's orientation may be set in several ways:

• orientationGeocentric : Specified as Euler Angles.
• orientationVectors, orientationVectorsGeocentric : Specified as forward, right, and up vectors.
• lookAt, lookAtGeocentric : Specified based on the camera's position, a target position, and a rotation/up vector.

In order to move the camera the application should use the methods on this class, which will update the camera's parameters for any subsequent calls to Surface3D::redraw().

Public Member Functions
void	position (const GeodeticPoint &pos)
GeodeticPoint	position () const
void	latitude (double lat)
double	latitude () const
void	longitude (double lon)
double	longitude () const
void	altitude (double alt)
double	altitude () const
void	translate (const GeodeticPoint &translation)
void	minAltitude (double alt)
double	minAltitude () const
	Get the minimum altitude limit of the camera.
void	minAltitudeRelativeToTerrain (bool relative)
bool	minAltitudeRelativeToTerrain () const
	Get whether the minimum altitude limit is relative to the terrain.
void	maxAltitude (double alt)
double	maxAltitude () const
	Get the maximum altitude limit of the camera.
void	maxAltitudeRelativeToTerrain (bool relative)
bool	maxAltitudeRelativeToTerrain () const
	Get whether the maximum altitude limit is relative to the terrain.
void	lookAt (const GeodeticPoint &targetPos)
GeodeticPoint	lookAt () const
void	lookAt (const GeodeticPoint &cameraPos, const GeodeticPoint &targetPos, double roll)
void	lookAt (const GeodeticPoint &cameraPos, const GeodeticPoint &targetPos, const GeodeticDirection &cameraUp)
void	orientationVectors (const GeodeticDirection &forward, const GeodeticDirection &right, const GeodeticDirection &up)
GeodeticDirection	forward () const
GeodeticDirection	right () const
GeodeticDirection	up () const
void	roll (double angle)
double	roll () const
void	positionGeocentric (const GeocentricPoint &pos)
	Set the position of the camera in geocentric (ECEF) space.
GeocentricPoint	positionGeocentric () const
	Get the position of the camera in geocentric (ECEF) space.
void	translateGeocentric (const GeocentricPoint &translation)
	Translate the camera in geocentric (ECEF) space.
void	orientationGeocentric (const Rotation &angles)
void	lookAtGeocentric (const GeocentricPoint &targetPos)
GeocentricPoint	lookAtGeocentric () const
void	lookAtGeocentric (const GeocentricPoint &cameraPos, const GeocentricPoint &targetPos, double roll)
void	lookAtGeocentric (const GeocentricPoint &cameraPos, const GeocentricPoint &targetPos, const GeocentricDirection &cameraUp)
void	orientationVectorsGeocentric (const GeocentricDirection &forward, const GeocentricDirection &right, const GeocentricDirection &up)
GeocentricDirection	forwardGeocentric () const
	Get the forward vector of the camera in geocentric space.
GeocentricDirection	rightGeocentric () const
	Get the right vector of the camera in geocentric space.
GeocentricDirection	upGeocentric () const
	Get the up vector of the camera in geocentric space.
void	fov (double angle)
double	fov () const

Member Function Documentation

altitude() [1/2]

double envitia::maplink::earth::Camera::altitude

(

)

const

Get the altitude of the camera.

Returns

The altitude of the camera in meters.

altitude() [2/2]

void envitia::maplink::earth::Camera::altitude

(

double

alt

)

Set the altitude of the camera.

Parameters

alt	The altitude of the camera in meters.

forward()

GeodeticDirection envitia::maplink::earth::Camera::forward

(

)

const

Get the forward vector of the camera.

Note

Vectors in geodetic space do not correspond to straight lines in geocentric space. The vector returned by this method will be normalised, and therefore may not match the vector passed to orientationVectors.

forwardGeocentric()

GeocentricDirection envitia::maplink::earth::Camera::forwardGeocentric

(

)

const

Get the forward vector of the camera in geocentric space.

fov() [1/2]

double envitia::maplink::earth::Camera::fov

(

)

const

Get the field of view of the camera.

Returns

The field of view of the camera in degrees.

fov() [2/2]

void envitia::maplink::earth::Camera::fov

(

double

angle

)

Set the field of view of the camera.

Parameters

angle

The camera's field of view in degrees.

latitude() [1/2]

double envitia::maplink::earth::Camera::latitude

(

)

const

Get the latitude of the camera.

Returns

The latitude of the camera in degrees.

latitude() [2/2]

void envitia::maplink::earth::Camera::latitude

(

double

lat

)

Set the latitude of the camera.

Parameters

lat	The latitude of the camera in degrees.

longitude() [1/2]

double envitia::maplink::earth::Camera::longitude

(

)

const

Get the longitude of the camera.

Returns

The longitude of the camera in degrees.

longitude() [2/2]

void envitia::maplink::earth::Camera::longitude

(

double

lon

)

Set the longitude of the camera.

Parameters

lon	The longitude of the camera in degrees.

lookAt() [1/4]

GeodeticPoint envitia::maplink::earth::Camera::lookAt

(

)

const

Query the camera's target point.

Returns

The target position.

lookAt() [2/4]

void envitia::maplink::earth::Camera::lookAt	(	const GeodeticPoint &	cameraPos,
		const GeodeticPoint &	targetPos,
		const GeodeticDirection &	cameraUp )

Set the camera to point at a target

Parameters

cameraPos	The position of the camera.
targetPos	The target position.
cameraUp	The up vector of the camera. Will be used to calculate the camera's roll angle.

lookAt() [3/4]

void envitia::maplink::earth::Camera::lookAt	(	const GeodeticPoint &	cameraPos,
		const GeodeticPoint &	targetPos,
		double	roll )

Set the camera to point at a target

Parameters

cameraPos	The position of the camera.
targetPos	The target position.
roll	The roll angle of the camera in degrees around the camera's forward vector. Zero roll corresponds to the camera being 'flat' relative to the earth's surface.

lookAt() [4/4]

void envitia::maplink::earth::Camera::lookAt

(

const GeodeticPoint &

targetPos

)

Set the camera to point at a target.

Parameters

targetPos

The target position.

lookAtGeocentric() [1/4]

GeocentricPoint envitia::maplink::earth::Camera::lookAtGeocentric

(

)

const

Query the camera's target point in geocentric space.

Returns

The target position.

lookAtGeocentric() [2/4]

void envitia::maplink::earth::Camera::lookAtGeocentric	(	const GeocentricPoint &	cameraPos,
		const GeocentricPoint &	targetPos,
		const GeocentricDirection &	cameraUp )

Set the camera to point at a target in geocentric space.

Parameters

cameraPos	The position of the camera.
targetPos	The target position.
cameraUp	The up vector of the camera, used to calculate the camera's roll angle.

lookAtGeocentric() [3/4]

void envitia::maplink::earth::Camera::lookAtGeocentric	(	const GeocentricPoint &	cameraPos,
		const GeocentricPoint &	targetPos,
		double	roll )

Set the camera to point at a target in geocentric space.

Parameters

cameraPos	The position of the camera.
targetPos	The target position.
roll	The roll angle of the camera in degrees around the camera's forward vector. Zero roll corresponds to the camera being 'flat' relative to the earth's surface.

lookAtGeocentric() [4/4]

void envitia::maplink::earth::Camera::lookAtGeocentric

(

const GeocentricPoint &

targetPos

)

Set the camera to point at a target in geocentric space.

Parameters

targetPos

The target position.

maxAltitude() [1/2]

double envitia::maplink::earth::Camera::maxAltitude

(

)

const

Get the maximum altitude limit of the camera.

maxAltitude() [2/2]

void envitia::maplink::earth::Camera::maxAltitude

(

double

alt

)

Set the maximum altitude limit of the camera.

If set the camera's altitude will be restricted to be less than or equal to this value.

The default altitude limit is std::numeric_limits<double>::max (no limit).

Parameters

alt	The maximum altitude limit.

maxAltitudeRelativeToTerrain() [1/2]

bool envitia::maplink::earth::Camera::maxAltitudeRelativeToTerrain

(

)

const

Get whether the maximum altitude limit is relative to the terrain.

maxAltitudeRelativeToTerrain() [2/2]

void envitia::maplink::earth::Camera::maxAltitudeRelativeToTerrain

(

bool

relative

)

Set whether the maximum altitude limit is relative to the terrain.

If true the camera's maximum altitude will be based on the terrain height at the camera's latitude/longitude.

If false the maximum altitude will be based on the globe.

By default this option is disabled.

Parameters

relative

true if the limit should be relative to the terrain, false otherwise.

minAltitude() [1/2]

double envitia::maplink::earth::Camera::minAltitude

(

)

const

Get the minimum altitude limit of the camera.

minAltitude() [2/2]

void envitia::maplink::earth::Camera::minAltitude

(

double

alt

)

Set the minimum altitude limit of the camera.

If set the camera's altitude will be restricted to be greater than or equal to this value.

The default altitude limit is zero, relative to the terrain.

Parameters

alt	The minimum altitude limit.

minAltitudeRelativeToTerrain() [1/2]

bool envitia::maplink::earth::Camera::minAltitudeRelativeToTerrain

(

)

const

Get whether the minimum altitude limit is relative to the terrain.

minAltitudeRelativeToTerrain() [2/2]

void envitia::maplink::earth::Camera::minAltitudeRelativeToTerrain

(

bool

relative

)

Set whether the minimum altitude limit is relative to the terrain.

If true the camera's minimum altitude will be based on the terrain height at the camera's latitude/longitude.

If false the minimum altitude will be based on the globe, and the camera may be positioned below the terrain.

By default this option is enabled.

Parameters

relative

true if the limit should be relative to the terrain, false otherwise.

orientationGeocentric()

void envitia::maplink::earth::Camera::orientationGeocentric

(

const Rotation &

angles

)

Set the camera's orientation in geocentric space.

The provided vector will be interpreted as rotation around the 3 axis in geocentric(ECEF) space.

The rotation will be applied as an extrinsic rotation (The rotation axis will remain fixed). The rotation will be applied in the order x, y, z.

Prior to the rotation the camera's orientation is

• Forward is the negative X axis
• Right is the positive Y axis
• Up is the positive Z axis

See also

orientationVectorsGeocentric

lookAtGeocentric

Parameters

angles

The orientation angles of the camera.

orientationVectors()

void envitia::maplink::earth::Camera::orientationVectors	(	const GeodeticDirection &	forward,
		const GeodeticDirection &	right,
		const GeodeticDirection &	up )

Set the camera orientation as vectors

As directions in geodetic space do not correspond to straight lines in geocentric space the recommended approach for this method should be to base the directions on other points, or to provide vectors with a short length. Vectors with a length of > 1.0 degrees in x/y may represent a significantly different direction due to the curvature of the earth.

Parameters

forward	The direction the camera is pointing.
right	A vector pointing to the right from the camera's position.
up	A vector pointing up from the camera's position.

orientationVectorsGeocentric()

void envitia::maplink::earth::Camera::orientationVectorsGeocentric	(	const GeocentricDirection &	forward,
		const GeocentricDirection &	right,
		const GeocentricDirection &	up )

Set the camera orientation as vectors in geocentric space.

Parameters

forward	The direction the camera is pointing.
right	A vector pointing to the right from the camera's position.
up	A vector pointing up from the camera's position.

position() [1/2]

GeodeticPoint envitia::maplink::earth::Camera::position

(

)

const

Get the position of the camera.

Returns

The position of the camera.

position() [2/2]

void envitia::maplink::earth::Camera::position

(

const GeodeticPoint &

pos

)

Set the position of the camera.

Parameters

pos	The position of the camera.

positionGeocentric() [1/2]

GeocentricPoint envitia::maplink::earth::Camera::positionGeocentric

(

)

const

Get the position of the camera in geocentric (ECEF) space.

positionGeocentric() [2/2]

void envitia::maplink::earth::Camera::positionGeocentric

(

const GeocentricPoint &

pos

)

Set the position of the camera in geocentric (ECEF) space.

right()

GeodeticDirection envitia::maplink::earth::Camera::right

(

)

const

Get the right vector of the camera.

Note

Vectors in geodetic space do not correspond to straight lines in geocentric space. The vector returned by this method will be normalised, and therefore may not match the vector passed to orientationVectors.

rightGeocentric()

GeocentricDirection envitia::maplink::earth::Camera::rightGeocentric

(

)

const

Get the right vector of the camera in geocentric space.

roll() [1/2]

double envitia::maplink::earth::Camera::roll

(

)

const

Get the roll angle of the camera.

Returns

the roll angle of the camera in degrees, wrapped to the range 0 - 360.

roll() [2/2]

void envitia::maplink::earth::Camera::roll

(

double

angle

)

Set the roll angle of the camera.

The roll angle is specified in degrees, around the camera's forward vector. Zero roll corresponds to the camera being 'flat' relative to the earth's surface.

Parameters

angle

The roll angle of the camera.

translate()

void envitia::maplink::earth::Camera::translate

(

const GeodeticPoint &

translation

)

Translate the camera's position.

Parameters

translation

The translation to apply to the camera's position.

translateGeocentric()

void envitia::maplink::earth::Camera::translateGeocentric

(

const GeocentricPoint &

translation

)

Translate the camera in geocentric (ECEF) space.

up()

GeodeticDirection envitia::maplink::earth::Camera::up

(

)

const

Get the up vector of the camera.

Note

Vectors in geodetic space do not correspond to straight lines in geocentric space. The vector returned by this method will be normalised, and therefore may not match the vector passed to orientationVectors.

upGeocentric()

GeocentricDirection envitia::maplink::earth::Camera::upGeocentric

(

)

const

Get the up vector of the camera in geocentric space.