#include <GeoMapCamera.h>

Inheritance diagram for GeoMapCamera:

Collaboration diagram for GeoMapCamera:

Public Types
enum class	Mode { Mode2D , Mode3D }

Signals
void	centerChanged ()

void	headingChanged ()

void	tiltChanged ()

void	distanceChanged ()

void	centerElevationChanged ()

void	viewportSizeChanged ()

void	fieldOfViewChanged ()

void	modeChanged ()

void	scenePoseChanged ()

Public Member Functions
	GeoMapCamera (QObject *parent=nullptr)

QGeoCoordinate	center () const

void	setCenter (const QGeoCoordinate &center)

bool	isPositioned () const

qreal	heading () const

void	setHeading (qreal heading)

qreal	tilt () const

void	setTilt (qreal tilt)

qreal	distance () const

void	setDistance (qreal distance)

qreal	centerElevation () const

void	setCenterElevation (qreal elevation)

QSizeF	viewportSize () const

void	setViewportSize (const QSizeF &size)

qreal	fieldOfView () const

void	setFieldOfView (qreal fov)

bool	isTopDown () const

Mode	mode () const

void	setMode (Mode mode)

qreal	default3DTilt () const

Q_INVOKABLE void	reset ()
	Restore the default pose at the current center (heading 0, tilt 0, default distance)

Q_INVOKABLE void	lookAt (const QGeoCoordinate &center, qreal heading, qreal tilt, qreal distance)
	Set the full pose in one call. tilt/distance are clamped.

Q_INVOKABLE void	goTo2D ()

Q_INVOKABLE void	goTo3D ()

Q_INVOKABLE void	beginPan (const QPointF &screenPos)
	Start a pan gesture at the given screen position (pixels)

Q_INVOKABLE void	panTo (const QPointF &screenPos)
	Continue a pan gesture: the ground point picked at beginPan stays under the cursor.

Q_INVOKABLE void	beginOrbit (const QPointF &screenPos)
	Start an orbit gesture at the given screen position (pixels)

Q_INVOKABLE void	orbitTo (const QPointF &screenPos)

Q_INVOKABLE void	rotateBy (qreal degrees, const QPointF &screenPos)

Q_INVOKABLE void	tiltBy (qreal degrees, const QPointF &screenPos)

Q_INVOKABLE void	zoom (qreal amount, const QPointF &screenPos)

Q_INVOKABLE void	zoomBy (qreal factor, const QPointF &screenPos)

Q_INVOKABLE qreal	sceneUnitsPerPixel () const

Q_INVOKABLE qreal	distanceForZoomLevel (qreal zoomLevel) const

Q_INVOKABLE QGeoCoordinate	centerForCoordinateAtScreenPoint (const QGeoCoordinate &coordinate, const QPointF &screenPos, double worldZ=0.0, double centerElevation=qQNaN()) const

QVector3D	cameraPosition () const

QPointF	cameraGroundPosition () const

QPointF	sceneOrigin () const

void	setSceneOrigin (const QPointF &origin)

QVector3D	scenePosition () const

QQuaternion	sceneRotation () const

std::optional< QPointF >	screenToGround (const QPointF &screenPos) const

std::optional< QPointF >	groundPointCapped (const QPointF &screenPos, double maxRange) const

std::optional< QPointF >	worldToScreen (const QPointF &worldGround, double worldZ=0.0) const

Static Public Attributes
static constexpr qreal	kMinDistance = 10.0

static constexpr qreal	kMaxDistance = 40000000.0

static constexpr qreal	kMinTilt = 0.0

static constexpr qreal	kMaxTilt = 85.0

static constexpr qreal	kDefaultDistance = 1500.0

static constexpr qreal	kDefaultFieldOfView = 60.0

static constexpr qreal	kDefault3DTilt = 55.0

Detailed Description

Camera pose model for the GeoMap engine.

Owns the pose as (center, heading, tilt, distance) where center is a geographic coordinate on the ground plane. Implements cursor-anchored pan, orbit, rotate, tilt and zoom: the ground point under the cursor at gesture start stays under the cursor for the duration of the gesture.

Scene space is Web Mercator meters (TileMath), z up, ground plane z=0. Camera position convention (matches the Viewer3D orbit camera): cameraPosition = center + distance * (sin(tilt)sin(heading), -sin(tilt)cos(heading), cos(tilt)) tilt 0 = top-down, tilt kMaxTilt = most oblique 3D view. Angles in degrees.

Definition at line 34 of file GeoMapCamera.h.

Member Enumeration Documentation

◆ Mode

enum class GeoMapCamera::Mode

strong

Map mode: 2D locks tilt against gestures (the map stays top-down until the user explicitly switches to 3D). setTilt itself is not gated so the QML-side mode-transition animation can drive it.

Enumerator
Mode2D
Mode3D

Definition at line 58 of file GeoMapCamera.h.

Constructor & Destructor Documentation

◆ GeoMapCamera()

GeoMapCamera::GeoMapCamera ( QObject * parent = nullptr )

explicit

Definition at line 77 of file GeoMapCamera.cc.

Member Function Documentation

◆ beginOrbit()

void GeoMapCamera::beginOrbit ( const QPointF & screenPos )

Start an orbit gesture at the given screen position (pixels)

Definition at line 370 of file GeoMapCamera.cc.

References screenToGround().

◆ beginPan()

void GeoMapCamera::beginPan ( const QPointF & screenPos )

Start a pan gesture at the given screen position (pixels)

Definition at line 357 of file GeoMapCamera.cc.

References screenToGround().

◆ cameraGroundPosition()

QPointF GeoMapCamera::cameraGroundPosition ( ) const

Ground projection of the camera position (world mercator meters) in double precision, for consumers whose math must not lose meters at world scale (LOD/culling distances).

Definition at line 199 of file GeoMapCamera.cc.

Referenced by SurfacePatchModel::analyzeSurface(), and SurfaceModel::update().

◆ cameraPosition()

QVector3D GeoMapCamera::cameraPosition ( ) const

Derived camera position in world space (mercator meters, z up). Float precision — for rendering/debug display; internal math is double.

Definition at line 192 of file GeoMapCamera.cc.

◆ center()

QGeoCoordinate GeoMapCamera::center ( ) const

Definition at line 79 of file GeoMapCamera.cc.

References TileMath::worldToGeo().

Referenced by centerForCoordinateAtScreenPoint(), lookAt(), and setCenter().

◆ centerChanged

void GeoMapCamera::centerChanged ( )

signal

Referenced by GeoScene::setCamera(), and SurfaceModel::SurfaceModel().

◆ centerElevation()

qreal GeoMapCamera::centerElevation ( ) const

inline

World-z of the look-at point (scene units). The camera orbits distance meters around the center at this height; normally driven from the terrain height at the center so close-zoom 3D never dives under the rendered surface. Ground-plane math (screenToGround, pan/zoom anchors) still intersects z=0, with rays cast from the elevated camera.

Definition at line 98 of file GeoMapCamera.h.

Referenced by SurfacePatchModel::analyzeSurface(), and centerForCoordinateAtScreenPoint().

◆ centerElevationChanged

void GeoMapCamera::centerElevationChanged ( )

signal

Referenced by setCenterElevation(), and SurfaceModel::SurfaceModel().

◆ centerForCoordinateAtScreenPoint()

QGeoCoordinate GeoMapCamera::centerForCoordinateAtScreenPoint	(	const QGeoCoordinate &	coordinate,
		const QPointF &	screenPos,
		double	worldZ = `0.0`,
		double	centerElevation = `qQNaN()`
	)		const

Center that places coordinate at screenPos with the current heading/tilt/ distance (rigid translation solve on the horizontal plane at worldZ, the point's rendered height in world units — 0 for a ground point). Returns the current center when screenPos misses the plane or the viewport is not set. centerElevation overrides the pivot elevation for the solve — pass the elevation the pivot will settle at when it follows terrain to the new center; NaN uses the current centerElevation.

Definition at line 330 of file GeoMapCamera.cc.

References center(), centerElevation(), TileMath::geoToWorld(), and TileMath::worldToGeo().

Referenced by GeoScene::centerForCoordinateAtScreenPoint().

◆ default3DTilt()

qreal GeoMapCamera::default3DTilt ( ) const

inline

Definition at line 119 of file GeoMapCamera.h.

References kDefault3DTilt.

◆ distance()

qreal GeoMapCamera::distance ( ) const

inline

Definition at line 89 of file GeoMapCamera.h.

Referenced by SurfacePatchModel::analyzeSurface(), lookAt(), setDistance(), and SurfaceModel::update().

◆ distanceChanged

void GeoMapCamera::distanceChanged ( )

signal

Referenced by setDistance(), and SurfaceModel::SurfaceModel().

◆ distanceForZoomLevel()

qreal GeoMapCamera::distanceForZoomLevel ( qreal zoomLevel ) const

Camera distance that renders the scene at the scale of a slippy-map zoom level (matches QtLocation map zoomLevel semantics when top-down). Clamped to the distance limits; returns the default distance when the viewport is not set.

Definition at line 320 of file GeoMapCamera.cc.

References kDefaultDistance, kMaxDistance, kMinDistance, TileMath::kTilePixels, and TileMath::worldSize().

◆ fieldOfView()

qreal GeoMapCamera::fieldOfView ( ) const

inline

Definition at line 106 of file GeoMapCamera.h.

◆ fieldOfViewChanged

void GeoMapCamera::fieldOfViewChanged ( )

signal

Referenced by setFieldOfView(), and SurfaceModel::SurfaceModel().

◆ goTo2D()

Q_INVOKABLE void GeoMapCamera::goTo2D ( )

inline

Instant 2D<->3D switch: sets the mode and snaps tilt (the animated transition is driven QML-side via mode + tilt/terrain animations)

Definition at line 129 of file GeoMapCamera.h.

References kMinTilt, Mode2D, setMode(), and setTilt().

◆ goTo3D()

Q_INVOKABLE void GeoMapCamera::goTo3D ( )

inline

Definition at line 135 of file GeoMapCamera.h.

References kDefault3DTilt, Mode3D, setMode(), and setTilt().

◆ groundPointCapped()

std::optional< QPointF > GeoMapCamera::groundPointCapped	(	const QPointF &	screenPos,
		double	maxRange
	)		const

Like screenToGround, but never fails for horizon misses: the result is capped at maxRange ground meters from the camera's ground position, along the ray's horizontal direction. Used for visible-region estimation. Returns std::nullopt only when the viewport is not set.

Definition at line 247 of file GeoMapCamera.cc.

Referenced by SurfacePatchModel::analyzeSurface().

◆ heading()

qreal GeoMapCamera::heading ( ) const

inline

Definition at line 81 of file GeoMapCamera.h.

Referenced by lookAt(), and setHeading().

◆ headingChanged

void GeoMapCamera::headingChanged ( )

signal

Referenced by setHeading(), and SurfaceModel::SurfaceModel().

◆ isPositioned()

bool GeoMapCamera::isPositioned ( ) const

inline

False until the camera is explicitly positioned (setCenter/lookAt). The construction-default pose is null island; consumers must not treat it as a real location (e.g. by fetching terrain there).

Definition at line 79 of file GeoMapCamera.h.

Referenced by SurfaceModel::update().

◆ isTopDown()

bool GeoMapCamera::isTopDown ( ) const

inline

Pose predicate: the camera currently looks straight down (tilt ~0). Distinct from mode(): Mode2D can be mid-transition with tilt > 0, and a Mode3D user can gesture tilt down to 0.

Definition at line 113 of file GeoMapCamera.h.

◆ lookAt()

void GeoMapCamera::lookAt	(	const QGeoCoordinate &	center,
		qreal	heading,
		qreal	tilt,
		qreal	distance
	)

Set the full pose in one call. tilt/distance are clamped.

Definition at line 184 of file GeoMapCamera.cc.

References center(), distance(), heading(), setCenter(), setDistance(), setHeading(), setTilt(), and tilt().

◆ mode()

Mode GeoMapCamera::mode ( ) const

inline

Definition at line 115 of file GeoMapCamera.h.

Referenced by setMode().

◆ modeChanged

void GeoMapCamera::modeChanged ( )

signal

Referenced by setMode().

◆ orbitTo()

void GeoMapCamera::orbitTo ( const QPointF & screenPos )

Continue an orbit gesture: rotate rigidly about the ground point picked at beginOrbit. Full viewport width of drag = 360 deg heading, full height = 180 deg tilt.

Definition at line 379 of file GeoMapCamera.cc.

References Mode3D, setHeading(), and setTilt().

◆ panTo()

void GeoMapCamera::panTo ( const QPointF & screenPos )

Continue a pan gesture: the ground point picked at beginPan stays under the cursor.

Definition at line 362 of file GeoMapCamera.cc.

◆ reset()

void GeoMapCamera::reset ( )

Restore the default pose at the current center (heading 0, tilt 0, default distance)

Definition at line 177 of file GeoMapCamera.cc.

References kDefaultDistance, kMinTilt, setDistance(), setHeading(), and setTilt().

◆ rotateBy()

void GeoMapCamera::rotateBy	(	qreal	degrees,
		const QPointF &	screenPos
	)

Rotate the camera rigidly by degrees about the ground point under screenPos (positive = counterclockwise heading change). Used for two-finger twist gestures.

Definition at line 403 of file GeoMapCamera.cc.

References screenToGround(), and setHeading().

◆ sceneOrigin()

QPointF GeoMapCamera::sceneOrigin ( ) const

inline

World-space reference origin for scene coordinates (set by the renderer, normally bound to GeoScene::sceneOrigin)

Definition at line 200 of file GeoMapCamera.h.

◆ scenePoseChanged

void GeoMapCamera::scenePoseChanged ( )

signal

Emitted whenever scenePosition/sceneRotation may have changed (any pose component or the scene origin)

Referenced by setCenterElevation(), setDistance(), setHeading(), setSceneOrigin(), and setTilt().

◆ scenePosition()

QVector3D GeoMapCamera::scenePosition ( ) const

Camera position in scene coordinates (world minus sceneOrigin, z up), for binding to the View3D camera node

Definition at line 214 of file GeoMapCamera.cc.

◆ sceneRotation()

QQuaternion GeoMapCamera::sceneRotation ( ) const

Camera orientation for the View3D camera node: identity = top-down with north up (matches the pose convention R = Rz(heading) * Rx(tilt))

Definition at line 223 of file GeoMapCamera.cc.

◆ sceneUnitsPerPixel()

qreal GeoMapCamera::sceneUnitsPerPixel ( ) const

Ground-plane world meters spanned by one horizontal pixel at screen center. Returns 0 when the viewport size is not set.

Definition at line 305 of file GeoMapCamera.cc.

References screenToGround().

◆ screenToGround()

std::optional< QPointF > GeoMapCamera::screenToGround ( const QPointF & screenPos ) const

Intersect the pick ray through screenPos (pixels) with the ground plane z=0. Returns the ground point in world meters, or std::nullopt when the ray misses (at/above the horizon) or the viewport is not set.

Definition at line 231 of file GeoMapCamera.cc.

Referenced by beginOrbit(), beginPan(), rotateBy(), sceneUnitsPerPixel(), tiltBy(), and zoomBy().

◆ setCenter()

void GeoMapCamera::setCenter ( const QGeoCoordinate & center )

Definition at line 84 of file GeoMapCamera.cc.

References center(), and TileMath::geoToWorld().

Referenced by lookAt().

◆ setCenterElevation()

void GeoMapCamera::setCenterElevation ( qreal elevation )

Definition at line 136 of file GeoMapCamera.cc.

References centerElevationChanged(), and scenePoseChanged().

◆ setDistance()

void GeoMapCamera::setDistance ( qreal distance )

Definition at line 125 of file GeoMapCamera.cc.

References distance(), distanceChanged(), kMaxDistance, kMinDistance, and scenePoseChanged().

Referenced by lookAt(), reset(), and zoomBy().

◆ setFieldOfView()

void GeoMapCamera::setFieldOfView ( qreal fov )

Definition at line 157 of file GeoMapCamera.cc.

References fieldOfViewChanged().

◆ setHeading()

void GeoMapCamera::setHeading ( qreal heading )

Definition at line 103 of file GeoMapCamera.cc.

References heading(), headingChanged(), and scenePoseChanged().

Referenced by lookAt(), orbitTo(), reset(), and rotateBy().

◆ setMode()

void GeoMapCamera::setMode ( Mode mode )

Definition at line 167 of file GeoMapCamera.cc.

References mode(), and modeChanged().

Referenced by goTo2D(), and goTo3D().

◆ setSceneOrigin()

void GeoMapCamera::setSceneOrigin ( const QPointF & origin )

Definition at line 205 of file GeoMapCamera.cc.

References scenePoseChanged().

◆ setTilt()

void GeoMapCamera::setTilt ( qreal tilt )

Definition at line 114 of file GeoMapCamera.cc.

References kMaxTilt, kMinTilt, scenePoseChanged(), tilt(), and tiltChanged().

Referenced by goTo2D(), goTo3D(), lookAt(), orbitTo(), reset(), and tiltBy().

◆ setViewportSize()

void GeoMapCamera::setViewportSize ( const QSizeF & size )

Definition at line 148 of file GeoMapCamera.cc.

References viewportSizeChanged().

◆ tilt()

qreal GeoMapCamera::tilt ( ) const

inline

Definition at line 85 of file GeoMapCamera.h.

Referenced by SurfacePatchModel::analyzeSurface(), lookAt(), setTilt(), and SurfaceModel::update().

◆ tiltBy()

void GeoMapCamera::tiltBy	(	qreal	degrees,
		const QPointF &	screenPos
	)

Tilt the camera by degrees (clamped), keeping the ground point under screenPos fixed on screen. Used for two-finger vertical swipe gestures.

Definition at line 413 of file GeoMapCamera.cc.

References Mode3D, screenToGround(), and setTilt().

◆ tiltChanged

void GeoMapCamera::tiltChanged ( )

signal

Referenced by setTilt(), and SurfaceModel::SurfaceModel().

◆ viewportSize()

QSizeF GeoMapCamera::viewportSize ( ) const

inline

Definition at line 102 of file GeoMapCamera.h.

Referenced by SurfacePatchModel::analyzeSurface(), and SurfaceModel::update().

◆ viewportSizeChanged

void GeoMapCamera::viewportSizeChanged ( )

signal

Referenced by setViewportSize(), and SurfaceModel::SurfaceModel().

◆ worldToScreen()

std::optional< QPointF > GeoMapCamera::worldToScreen	(	const QPointF &	worldGround,
		double	worldZ = `0.0`
	)		const

Projects a world-space point (mercator meters, z in scene units) to screen pixels. Double precision throughout. Returns std::nullopt when the point is at or behind the camera plane or the viewport is not set.

Definition at line 276 of file GeoMapCamera.cc.

Referenced by GeoScene::screenPositionFor().

◆ zoom()

void GeoMapCamera::zoom	(	qreal	amount,
		const QPointF &	screenPos
	)

Zoom toward/away from the ground point under screenPos. amount is in wheel angleDelta units (positive = zoom in). Distance is clamped.

Definition at line 425 of file GeoMapCamera.cc.

References zoomBy().

◆ zoomBy()

void GeoMapCamera::zoomBy	(	qreal	factor,
		const QPointF &	screenPos
	)

Scale the camera distance by factor (e.g. 0.5 halves the distance), keeping the ground point under screenPos fixed on screen. Used for pinch gestures.

Definition at line 431 of file GeoMapCamera.cc.

References screenToGround(), and setDistance().

Referenced by zoom().

Member Data Documentation

◆ kDefault3DTilt

constexpr qreal GeoMapCamera::kDefault3DTilt = 55.0

staticconstexpr

Definition at line 71 of file GeoMapCamera.h.

Referenced by default3DTilt(), and goTo3D().

◆ kDefaultDistance

constexpr qreal GeoMapCamera::kDefaultDistance = 1500.0

staticconstexpr

Definition at line 69 of file GeoMapCamera.h.

Referenced by distanceForZoomLevel(), and reset().

◆ kDefaultFieldOfView

constexpr qreal GeoMapCamera::kDefaultFieldOfView = 60.0

staticconstexpr

Definition at line 70 of file GeoMapCamera.h.

◆ kMaxDistance

constexpr qreal GeoMapCamera::kMaxDistance = 40000000.0

staticconstexpr

Definition at line 66 of file GeoMapCamera.h.

Referenced by distanceForZoomLevel(), and setDistance().

◆ kMaxTilt

constexpr qreal GeoMapCamera::kMaxTilt = 85.0

staticconstexpr

Definition at line 68 of file GeoMapCamera.h.

Referenced by setTilt().

◆ kMinDistance

constexpr qreal GeoMapCamera::kMinDistance = 10.0

staticconstexpr

Definition at line 65 of file GeoMapCamera.h.

Referenced by distanceForZoomLevel(), and setDistance().

◆ kMinTilt

constexpr qreal GeoMapCamera::kMinTilt = 0.0

staticconstexpr

Definition at line 67 of file GeoMapCamera.h.

Referenced by goTo2D(), reset(), and setTilt().

The documentation for this class was generated from the following files:

src/GeoMap/GeoMapCamera.h
src/GeoMap/GeoMapCamera.cc

Public Types

Signals

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ GeoMapCamera()

Member Function Documentation

◆ beginOrbit()

◆ beginPan()

◆ cameraGroundPosition()

◆ cameraPosition()

◆ center()

◆ centerChanged

◆ centerElevation()

◆ centerElevationChanged

◆ centerForCoordinateAtScreenPoint()

◆ default3DTilt()

◆ distance()

◆ distanceChanged

◆ distanceForZoomLevel()

◆ fieldOfView()

◆ fieldOfViewChanged

◆ goTo2D()

◆ goTo3D()

◆ groundPointCapped()

◆ heading()

◆ headingChanged

◆ isPositioned()

◆ isTopDown()

◆ lookAt()

◆ mode()

◆ modeChanged

◆ orbitTo()

◆ panTo()

◆ reset()

◆ rotateBy()

◆ sceneOrigin()

◆ scenePoseChanged

◆ scenePosition()

◆ sceneRotation()

◆ sceneUnitsPerPixel()

◆ screenToGround()

◆ setCenter()

◆ setCenterElevation()

◆ setDistance()

◆ setFieldOfView()

◆ setHeading()

◆ setMode()

◆ setSceneOrigin()

◆ setTilt()

◆ setViewportSize()

◆ tilt()

◆ tiltBy()

◆ tiltChanged

◆ viewportSize()

◆ viewportSizeChanged

◆ worldToScreen()

◆ zoom()

◆ zoomBy()

Member Data Documentation

◆ kDefault3DTilt

◆ kDefaultDistance

◆ kDefaultFieldOfView

◆ kMaxDistance

◆ kMaxTilt

◆ kMinDistance

◆ kMinTilt