#include <ImFusion/GL/Camera.h>

Abstraction layer to model both intrinsic (projection) and extrinsic (view) parameters of a camera showing a 3D scene. More...

Inheritance diagram for ImFusion::Camera:

Detailed Description

Abstraction layer to model both intrinsic (projection) and extrinsic (view) parameters of a camera showing a 3D scene.

This class was designed with both OpenGL and Computer Vision conventions in mind. It is mainly intended to facilitate setting up 3D views for OpenGL rendering. At the same time it uses terminology that is common popular in Computer Vision environments and provides an interface to easily transfer camera-calibration results into the camera setup used for rendering.

The extrinsic parameters describe the location and orientation of the camera in world space. In OpenGL terminology this is usually described by a view matrix that converts from world coordinates to camera coordinates. The intrinsic parameters describe the way how the scene is projected into a 2D image plane. Note that depending on the selected projection mode, a different set of intrinsic parameters are used to compile the final projection matrix.

See also: Hartley/Zisserman: Multiple View Geometry in Computer Vision; https://ksimek.github.io/2012/08/13/introduction/

Public Types
enum class	Mode { Perspective , Orthographic }
	Intrinsic camera mode/projection mode. More...
enum	MatrixConvention { OpenGL , CV }
	Enumeration to specify matrix conventions of pose (view) matrices. More...

Public Member Functions
	Camera ()
	Creates a new camera object with default parameters.
virtual void	configure (const Properties *p) override
	Configure this object instance by de-serializing the given Properties.
virtual void	configuration (Properties *p) const override
	Serialize the current object configuration into the given Properties object.
Public Member Functions inherited from ImFusion::Configurable
virtual void	configureDefaults ()
	Retrieve the properties of this object, replaces values with their defaults and sets it again.
void	registerParameter (ParameterBase *param)
	Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration().
void	unregisterParameter (const ParameterBase *param)
	Remove the given Parameter or SubProperty from the list of registered parameters.
	Configurable (const Configurable &rhs)
	Configurable (Configurable &&rhs) noexcept
Configurable &	operator= (const Configurable &)
Configurable &	operator= (Configurable &&) noexcept

Static Public Member Functions
static Camera	fromGlViewMatrix (const mat4 &viewMatrix)
	Creates a new Camera object with the given GlView view matrix.
static Camera	fromPose (const mat4 &T, MatrixConvention mc)
	Creates a new Camera object with the given inverse OpenGL view matrix.
static Camera	fromVectors (const vec3 &position, const vec3 &lookVector, const vec3 &upVector)
	Creates a new Camera object with the given parameters.

Intrinsic Parameters
Mode	mode () const
	Returns the intrinsic camera mode.
void	setMode (Mode value)
	Sets the intrinsic camera mode.
void	setIntrinsicMatrix (const mat3 &K, const vec2 &cameraSize)
	Set the intrinsic parameters from a K-matrix commonly used in Computer Vision environments.
mat3	intrinisicMatrix (const vec2 &cameraSize) const
	Get the intrinsic parameters from a K-matrix commonly used in Computer Vision environments.
const vec2 &	principalPoint () const
	Returns the principal point in normalized [0,1] viewport space, origin in top-left corner.
void	setPrincipalPoint (const vec2 &value)
	Sets the principal point in normalized [0,1] viewport space, origin in top-left corner.
const vec2 &	focalLength () const
	Returns the focal length in perspective mode in normalized [0,1] space.
void	setFocalLength (const vec2 &value)
	Sets the focal length in perspective mode in normalized [0,1] space.
void	setFovY (double fov)
	Set camera vertical field of view in degrees.
double	fovY () const
	Get camera vertical field of view in degrees.
double	frustumHeight () const
	Returns the view frustum height in mm in orthographic camera mode.
void	setFrustumHeight (double value)
	Sets the view frustum height in mm in orthographic camera mode.
mat4	openGLProjectionMatrix (double aspectRatio, double nearClipDistance, double farClipDistance) const
	Compute the OpenGL projection matrix based on the camera's intrinsic parameters.

Extrinsic Parameters
void	setPose (const mat4 &T, MatrixConvention mc)
	Set pose as world to camera coordinate system transformation.
mat4	pose (MatrixConvention mc) const
	Get pose as world to camera coordinate system transformation.
void	setVectors (const vec3 &position, const vec3 &lookVector, const vec3 &upVector)
	Set position, look vector and up vector at once.
void	setLookAt (const vec3 &position, const vec3 &center, const vec3 &upVector)
	Set eye position, look center and up vector at once.
void	setLookAt (const Geometry::AlignedBox &worldBounds, const vec3 &lookVector, const vec3 &upVector, double boundsRatio=1.0)
	Set camera position to look at the scene defined by worldBounds using the given lookVector and upVector.
void	setPosition (const vec3 &value)
	Sets the camera location in the world coordinate system.
vec3	position () const
	Returns the camera location in the world coordinate system.
vec3	upVector () const
	Returns the camera's up direction vector in the world coordinate system.
vec3	lookVector () const
	Returns the camera's look direction vector in the world coordinate system.
mat4	openGLViewMatrix () const
	Compute the OpenGL view matrix based on the camera's extrinsic parameters.
mat4	glViewMatrix () const
	Get the GlView view matrix describing the camera's parameters.

Additional Inherited Members
Public Attributes inherited from ImFusion::Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' signalValueChanged signal was emitted.
Protected Attributes inherited from ImFusion::Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Member Enumeration Documentation

◆ Mode

enum class ImFusion::Camera::Mode

strong

Intrinsic camera mode/projection mode.

Enumerator
Perspective	Perspective projection based on principal point and focal length (FOV).
Orthographic	Orthographic projection based on principal point and frustum size.

◆ MatrixConvention

enum ImFusion::Camera::MatrixConvention

Enumeration to specify matrix conventions of pose (view) matrices.

Enumerator
OpenGL	Camera looks along negative z-axis, y-axis up.
CV	Camera looks along positive z-axis, y-axis down.

Member Function Documentation

◆ fromGlViewMatrix()

Camera ImFusion::Camera::fromGlViewMatrix ( const mat4 & viewMatrix )

static

Creates a new Camera object with the given GlView view matrix.

Parameters

viewMatrix OpenGL view matrix from world coordinates to OpenGL camera coordinates.

Note: Use this function with the matrix of a GlView.

◆ fromPose()

Camera ImFusion::Camera::fromPose	(	const mat4 &	T,
		MatrixConvention	mc )

static

Creates a new Camera object with the given inverse OpenGL view matrix.

Parameters

inverseViewMatrix OpenGL view matrix from OpenGL camera coordinate system to world.

◆ fromVectors()

Camera ImFusion::Camera::fromVectors	(	const vec3 &	position,
		const vec3 &	lookVector,
		const vec3 &	upVector )

static

Creates a new Camera object with the given parameters.

Parameters

position	World coordinates of the camera location
lookVector	World coordinates of the camera viewing direction
upVector	Camera's up direction vector

◆ setIntrinsicMatrix()

void ImFusion::Camera::setIntrinsicMatrix	(	const mat3 &	K,
		const vec2 &	cameraSize )

Set the intrinsic parameters from a K-matrix commonly used in Computer Vision environments.

For perspective projections the bottom right element is expected to be 1. The diagonal elements describe focal length and the translational part describes the principal point. Since the intrinsic parameters are invariant to uniform scaling of the camera geometry, you must specify cameraSize to define the scaling of the K matrix (e.g. number of pixels).
For orthographic projections the bottom right element is expected to be 0. The diagonal elements describe the view frustum size in mm (world coordinates) and the translational part describes the principal point. In this case only the principal point is scaled wrt. cameraSize, but not the frustum size since the latter is defined in world space.

Note: Axis skew/2D pixel shearing is not supported by this class, the corresponding elements of the matrix are expected to be 0.0.

◆ intrinisicMatrix()

mat3 ImFusion::Camera::intrinisicMatrix ( const vec2 & cameraSize ) const

Get the intrinsic parameters from a K-matrix commonly used in Computer Vision environments.

For perspective projections the bottom right element is set to 1. The diagonal elements describe focal length and the translational part describes the principal point. Since the intrinsic parameters are invariant to uniform scaling of the camera geometry, you must specify cameraSize to define the scaling of the K matrix (e.g. number of pixels).
For orthographic projections the bottom right element is set to 0. The diagonal elements describe the view frustum size in mm (world coordinates) and the translational part describes the principal point. In this case only the principal point is scaled wrt. cameraSize, but not the frustum size since the latter is defined in world space.

◆ setFovY()

void ImFusion::Camera::setFovY ( double fov )

Set camera vertical field of view in degrees.

Note: This will also update the horizontal FOV (wrt. the aspect ratio). If you need to set horizontal and vertical FOV independently, use setFocalLength().

◆ setLookAt()

void ImFusion::Camera::setLookAt	(	const Geometry::AlignedBox &	worldBounds,
		const vec3 &	lookVector,
		const vec3 &	upVector,
		double	boundsRatio = 1.0 )

Set camera position to look at the scene defined by worldBounds using the given lookVector and upVector.

This function will automatically deduce the camera position based on the camera's intrinsic parameters so that the entire scene will be visible. The boundsRatio parameter controls how much margin is given around the bounds (1.0 would match the bounds exactly)

◆ openGLViewMatrix()

mat4 ImFusion::Camera::openGLViewMatrix ( ) const

Compute the OpenGL view matrix based on the camera's extrinsic parameters.

Note: This is a convenience function calling pose(OpenGL) internally.

◆ glViewMatrix()

mat4 ImFusion::Camera::glViewMatrix ( ) const

Get the GlView view matrix describing the camera's parameters.

View matrix is from OpenGL camera coordinate system to world.

Note: This is a convenience function calling pose(OpenGL).inverse() internally.

◆ configure()

virtual void ImFusion::Camera::configure ( const Properties * p )

overridevirtual

Configure this object instance by de-serializing the given Properties.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configuration() for the inverse functionality

Reimplemented from ImFusion::Configurable.

◆ configuration()

virtual void ImFusion::Camera::configuration ( Properties * p ) const

overridevirtual

Serialize the current object configuration into the given Properties object.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configure() for the inverse functionality

Reimplemented from ImFusion::Configurable.

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

ImFusion/GL/Camera.h

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Intrinsic Parameters

Extrinsic Parameters

Additional Inherited Members

Member Enumeration Documentation

◆ Mode

◆ MatrixConvention

Member Function Documentation

◆ fromGlViewMatrix()

◆ fromPose()

◆ fromVectors()

◆ setIntrinsicMatrix()

◆ intrinisicMatrix()

◆ setFovY()

◆ setLookAt()

◆ openGLViewMatrix()

◆ glViewMatrix()

◆ configure()

◆ configuration()