Detailed Description

Simple component for controlling view of 3D Drawing Surfaces.

The default position and orientation of the camera is such that, vertically, it is positioned in the Equatorial plane and its up vector (i.e. 'normal') lies in the prime meridian plane, parallel to the Z axis i.e. it is sitting at the centre of the Earth.

Public Member Functions
TSL3DCameraReturn	angleOfView (double angle)

double	angleOfView () const

void	getCameraAxis (double &directionX, double &directionY, double &directionZ, double &rightX, double &rightY, double &rightZ, double &normalX, double &normalY, double &normalZ)

double	horizonAltitude () const

void	horizonAltitude (double altitude)

void	limitHeightAboveEarth (bool limit, double heightLimit=100.0, bool ignoreTerrain=false)

TSL3DCameraReturn	lookAt (double latitude, double longitude, double altitude, bool makeHorizonLevel)

TSL3DCameraReturn	moveTo (double latitude, double longitude, double altitude, TSL3DCameraMoveAction action=TSL3DCameraMoveActionNone)

bool	orientation (double directionNorthing, double directionEasting, double directionAltitude, double rotation, bool absolute=false)

bool	position (double latitude, double longitude, double *altitude) const

void	reset ()

bool	rotateAroundViewAxis (double angle)

bool	setCameraAxis (double directionX, double directionY, double directionZ, double rightX, double rightY, double rightZ, double normalX, double normalY, double normalZ)

bool	translate (double forward, double sideways, double vertical, TSL3DCameraMoveAction action, bool maintainAltitude)

bool	upsideDown () const

double	viewRotation () const

void	viewExtent (double &width, double &height) const

Member Function Documentation

◆ angleOfView() [1/2]

double TSL3DCamera::angleOfView ( ) const

Query field of view for camera.

Returns field of view angle in degrees.

◆ angleOfView() [2/2]

TSL3DCameraReturn TSL3DCamera::angleOfView ( double angle )

Set field of view for camera.

Defaults to 45 degrees. Make larger for wider field of view.

Parameters

angle New field of view angle in degrees

Returns: TSL3DCamera_OK if successful, otherwise TSL3DCamera_AngleOfView Invalid.

◆ getCameraAxis()

void TSL3DCamera::getCameraAxis	(	double &	directionX,
		double &	directionY,
		double &	directionZ,
		double &	rightX,
		double &	rightY,
		double &	rightZ,
		double &	normalX,
		double &	normalY,
		double &	normalZ )

This method returns the three unit vectors making up the camera axis.

The stored values can then passed back to the Camera by a call to setCamera Axis.

Parameters

directionX	Direction vector. The direction the camera is pointing in.
directionY
directionZ
rightX	Right vector. Defines the rotation about the direction vector.
rightY
rightZ
normalX	Up vector. Defines which way the camera thinks is up.
normalY
normalZ

◆ horizonAltitude() [1/2]

double TSL3DCamera::horizonAltitude ( ) const

Query altitude at which horizon becomes acceptable.

This value defines the cut-off point for the 'setHorizonLevel' parameter of the lookAt method. It is necessary since a viewpoint far away from the earth's surface has no sensible horizon.

Returns altitude in metres.

◆ horizonAltitude() [2/2]

void TSL3DCamera::horizonAltitude ( double altitude )

Set altitude at which horizon becomes acceptable.

This method defines the cut-off point for the 'setHorizonLevel' parameter of the lookAt method. It is necessary since a viewpoint far away from the earth's surface has no sensible horizon.

Parameters

altitude Altitude at which horizon is visible - defaults to 1000km

◆ limitHeightAboveEarth()

void TSL3DCamera::limitHeightAboveEarth	(	bool	limit,
		double	heightLimit = 100.0,
		bool	ignoreTerrain = false )

This method adds the ability to prevent the camera from descending below a certain altitude above the earth. This can be helpful to stop the camera from entering the earth or going so close to the earth that the drawing intersects with the near clip plane.

Parameters

limit	Should the camera limit its height above the earth
heightLimit	The lowest altitude that the camera may descend to.
ignoreTerrain	Should the height limit parameter be interpreted from the height of the terrain at the point of the camera.

◆ lookAt()

TSL3DCameraReturn TSL3DCamera::lookAt	(	double	latitude,
		double	longitude,
		double	altitude,
		bool	makeHorizonLevel )

Sets an orientation by make the camera look at a particular point.

Note that the 'makeHorizonLevel' parameter is only used if the camera altitude is greater than the value set by the horizonAltitude method - or its default value.

Parameters

latitude	Latitude of target position in degrees
longitude	Longitude of target position in degrees
altitude	Altitude of target position in metres above mean sea level
makeHorizonLevel	If true, adjust the apparent 'roll' so that the horizon is horizontal

Returns: TSL3DCamera_OK on success, TSL3DCamera_LatitudeInvalid otherwise

◆ moveTo()

TSL3DCameraReturn TSL3DCamera::moveTo	(	double	latitude,
		double	longitude,
		double	altitude,
		TSL3DCameraMoveAction	action = TSL3DCameraMoveActionNone )

Sets the camera position to a specific geodetic point.

The action parameter allows the camera to also modify the orientation in a specified manner.

Parameters

latitude	Latitude of position in degrees
longitude	Longitude of position in degrees
altitude	Altitude of position in metres above mean sea level
action	Action take with regard to the current camera orientation

Returns: TSL3DCamera_OK on success, TSL3DCamera_LatitudeInvalid otherwise

◆ orientation()

bool TSL3DCamera::orientation	(	double	directionNorthing,
		double	directionEasting,
		double	directionAltitude,
		double	rotation,
		bool	absolute = false )

Set orientation of camera via direction ground relative vector (ENU), and rotation around that vector. This is an Angle-Axis representation.

The direction vector must be unit length.

References

http//www.euclideanspace.com/maths/geometry/rotations/conversions/eulerToAngle/

Also see the Developers Guide.

Parameters

directionNorthing	Northing component of the direction vector
directionEasting	Easting component of the direction vector
directionAltitude	Vertical, altitude component of the direction vector,
rotation	Rotation of the viewpoint around the direction vector, in degrees, positive anti-clockwise
absolute	If true the vector and rotation are applied to a Camera which has its axis aligned to the default ENU axis. If false the rotation specified is cumulative (default).

Returns: true on success, false otherwise

◆ position()

bool TSL3DCamera::position	(	double *	latitude,
		double *	longitude,
		double *	altitude ) const

Query the current lat/long/altitude position of the camera

Parameters

latitude	Storage for current camera latitude
longitude	Storage for current camera longitude
altitude	Storage for current camera altitude

Returns: true on success, false otherwise

◆ reset()

void TSL3DCamera::reset ( )

Reset the camera position and orientation to its default values (the default position and orientation of the camera is such that, vertically, it is positioned in the Equatorial plane and its up vector (i.e. 'normal') lies in the prime meridian plane, parallel to the Z axis i.e. it is sitting at the centre of the Earth).

◆ rotateAroundViewAxis()

bool TSL3DCamera::rotateAroundViewAxis ( double angle )

Rotate the camera around its view axis.

Parameters

angle The angle to rotate by, in degrees (a +ve angle produces a clockwise rotation of the camera around its view axis)

◆ setCameraAxis()

bool TSL3DCamera::setCameraAxis	(	double	directionX,
		double	directionY,
		double	directionZ,
		double	rightX,
		double	rightY,
		double	rightZ,
		double	normalX,
		double	normalY,
		double	normalZ )

This method sets the three unit vectors making up the camera axis.

The vectors shall be at 90 degrees to each other.

The method allows the user to set the camera axis to the values obtained from a previous call to getCameraAxis as such very little checking is carried out to validate the vectors.

The default orientation of the camera is such that, vertically, it is positioned in the Equatorial plane and its up vector (i.e. 'normal') lies in the prime meridian plane, parallel to the Z axis.

Parameters

directionX	Direction vector. The direction the camera is pointing in.
directionY
directionZ
rightX	Right vector. Defines the rotation about the direction vector.
rightY
rightZ
normalX	Up vector. Defines which way the camera thinks is up.
normalY
normalZ

Returns: true if the vectors were set, false otherwise.

◆ translate()

bool TSL3DCamera::translate	(	double	forward,
		double	sideways,
		double	vertical,
		TSL3DCameraMoveAction	action,
		bool	maintainAltitude )

Move camera position by specified delta values, relative to current position and orientation

The orientation may be affected, depending upon the action parameter. Distances are defined in metres

Parameters

forward	Distance to move along current direction vector
sideways	Distance to move along current right vector
vertical	Distance to move along current normal vector
action	Action to perform on current orientation
maintainAltitude	If true, then after translation, the camera is adjusted so that it stays at its original altitude.

Returns: true on success, false otherwise

◆ upsideDown()

bool TSL3DCamera::upsideDown ( ) const

Query as to whether the camera orientation is upside-down relative to the north direction.

This method is used to allow traversal over the poles.

◆ viewExtent()

void TSL3DCamera::viewExtent	(	double &	width,
		double &	height ) const

Return the dimensions of the viewed extent at the camera's front plane.

Parameters

width
height

◆ viewRotation()

double TSL3DCamera::viewRotation ( ) const

Returns the 2D view rotation in degrees.

The value returned is only valid if the following methods are not called:

orientation translate

Detailed Description

Public Member Functions

Member Function Documentation

◆ angleOfView() [1/2]

◆ angleOfView() [2/2]

◆ getCameraAxis()

◆ horizonAltitude() [1/2]

◆ horizonAltitude() [2/2]

◆ limitHeightAboveEarth()

◆ lookAt()

◆ moveTo()

◆ orientation()

◆ position()

◆ reset()

◆ rotateAroundViewAxis()

◆ setCameraAxis()

◆ translate()

◆ upsideDown()

◆ viewExtent()

◆ viewRotation()