Keystone class for transforming between different (skewed) 2D coordinate systems, while taking account possible radial (camera lens) distortion. More...

#include <Nimble/KeyStone.hpp>

Public Member Functions
void	addExtra (int index, float v)
	Add extra processing borders around one edge. More...

Nimble::Vector2	bottomLeft () const
	Returns the coordinates of the bottom-left corner.

Nimble::Vector2	bottomRight () const
	Returns the coordinates of the bottom-right corner.

Nimble::Rect	boundsROI () const
	The rectangle which contains the Region Of Interest of this keystone This is the ROI in camera images. More...

void	calculateMatrix ()
	Updates the projection matrix.

void	calibrateOutput (const Nimble::Vector2 targets, const Nimble::Vector2 real, const Nimble::Vector2 *center)
	Applies correction, based on four screen-space coordinate pairs. More...

Nimble::Vector3	centerShift () const
	Returns information about the center shift Center shift means that coordinates at the center of the image get this offset. More...

int	closestCorner (Nimble::Vector2) const
	Returns the index of the corner closest to given point.

int	containedPixelCount () const
	Number of pixels that this keystone camera area contains.

int	dpyHeight () const
	The height of the output display area.

Nimble::Vector2i	dpyOffset () const
	The offset to the origin of the output display area.

Nimble::Vector2i	dpySize () const
	The size of the display area (in pixels) that matches this keystone area.

int	dpyWidth () const
	The width of the output display area.

int	dpyX () const
	The x offset to the origin of the output display area.

int	dpyY () const
	The y offset to the origin of the output display area.

const Nimble::Vector4f &	extraBorders () const
	Returns the extra pixels around the edges.

const std::vector < Nimble::Vector2i > &	extraLimits () const
	Information on which pixels are part of the image processing area. More...

void	flipHorizontal ()
	Flips the corner points horizontally.

void	flipVertical ()
	Flips the corner points vertically.

int	generation () const
	Returns the generation number of the object. More...

void	getCornerOrdering (int indices[4])
	Writes the order of the corners to the given parameter. More...

LensCorrection &	lensCorrection ()
	Reference to the lens correction.

const LensCorrection &	lensCorrection () const
	Const reference to the lens correction.

const std::vector < Nimble::Vector2i > &	limits () const
	Information on which pixels are inside the camera area. More...

void	moveCorner (Nimble::Vector2)
	Moves the closest corner point.

const Nimble::Vector2 &	original (int i) const
	Returns a corner point in camera coordinates.

Nimble::Vector2	originalCenter () const
	Returns the center point of the camer acoordinates.

Nimble::Rect	outputBounds ()
	The output area of the screen. More...

const Nimble::Matrix3 &	outputExtension () const
	Returns the extension (fine-tuning) matrix.

Nimble::Vector2	project (const Nimble::Vector2 &p) const
	Project a vector from camera coordinates to the display coordinates This function applies the lens correction and projection matrix on the coordinates. More...

Nimble::Vector2	project01 (const Nimble::Vector2 &p) const
	Project the point from camera coordinates to normalized coordinates in range [0,1]. More...

Nimble::Vector2	projectInverse (const Nimble::Vector2 &p) const
	Do inverse projection (from screen to camera coordinates), ignoring the camera barrel distortion. More...

void	rotate (int turns=1)
	Rotates the keystone corners.

void	setCenterShift (Nimble::Vector3 params)
	Sets the parameters for the center shifting.

void	setExtraBorders (const Nimble::Vector4f &borders)
	Sets the extra pixels around the edges.

void	setLensParam (int i, float v)
	Adjusts the lens correction.

void	setOutputExtension (const Nimble::Matrix3 &m)
	Sets the extension (fine-tuning) matrix. More...

void	setOutputGeometry (unsigned w, unsigned h, int x, int y)
	Sets the output (display) geometry.

void	setUseCenterShift (bool use)
	Controls if this keystone object uses the center shift features.

void	setVertex (int index, float x, float y)
	Sets one vertex without updating matrices.

void	setVertices (const char *str, int w, int h, int dpyw, int dpyh, int dpyx, int dpyy)
	Set vertices, and other parameters.

void	setVertices (const Nimble::Vector2 *vertices, int w, int h, int dpyw, int dpyh, int dpyx, int dpyy)
	Set vertices, and other parameters.

Nimble::Vector2	topLeft () const
	Returns the coordinates of the top-left corner.

Nimble::Vector2	topRight () const
	Returns the coordinates of the top-right corner.

void	updateLimits ()
	Recalculates the limits of which pixels are inside the tracking area, and which are not.

Static Public Member Functions
static Nimble::Matrix3	projectionMatrix (const std::array< Nimble::Vector2, 4 > &vertices)
	Calculates the projection matrix. More...

static void	testCorrection ()
	Test the keystone correction routines.

Detailed Description

Keystone class for transforming between different (skewed) 2D coordinate systems, while taking account possible radial (camera lens) distortion.

Conceptually the keystone correction works in following fashion. In practice the linear operations are accumulated to a single matrix multiplication.

We fix the camera lens correction using object of type Nimble::LensCorrection. This is simple third-order polynomial radial mapping. In the future we can offer a customizeable approach so that you can for example set a custom object to do the lens correction.
We transform the coordinates from camera coordinates to normalized coordinates in range [0,1]. This transformation is based on knowledge of the four corners that represent the area to be tracked.
Then we apply extension matrix within the [0,1] space (more about that later)
Then we multiply the coordinates with the display area (visible pixels) and translate them to desired position in the screen.

The extension matrix would not be necessary if you could set the corner points of the tracking area freely. In practice it is often necessary to limit the camera area so that it does not match the desired output area exactly (there might be noise at the edges etc). To overcome this limitation one can use an extension matrix that that adjusts the area more easily. To define the extension matrix, you pass observed and desired display coordinates to the applyCorrection function (

See Also: applyCorrection).

Author: Tommi Ilmonen

Member Function Documentation

void Nimble::KeyStone::addExtra	(	int	index,
		float	v
	)

Add extra processing borders around one edge.

Parameters

index	The index to the edge (0-3).
v	The number of pixels to add or subtract.

Nimble::Rect Nimble::KeyStone::boundsROI ( ) const

inline

The rectangle which contains the Region Of Interest of this keystone This is the ROI in camera images.

Returns: Bounding rectangle of the ROI

void Nimble::KeyStone::calibrateOutput	(	const Nimble::Vector2 *	targets,
		const Nimble::Vector2 *	real,
		const Nimble::Vector2 *	center
	)

Applies correction, based on four screen-space coordinate pairs.

Parameters

targets	The desired target coordinates.
real	The observed coordinates.
center	the center point observed coordinates

Nimble::Vector3 Nimble::KeyStone::centerShift ( ) const

inline

Returns information about the center shift Center shift means that coordinates at the center of the image get this offset.

Returns: First two elements mean the shift XY, last element is the center shift span

const std::vector<Nimble::Vector2i>& Nimble::KeyStone::extraLimits ( ) const

inline

Information on which pixels are part of the image processing area.

Returns: values work like the values returned from limits.

int Nimble::KeyStone::generation ( ) const

inline

Returns the generation number of the object.

Whenever the keystone information is modified, the generation number is incremented. This information can be used by other objects to check is they need to update some of their data structures.

Returns: Generation number

void Nimble::KeyStone::getCornerOrdering ( int indices[4] )

Writes the order of the corners to the given parameter.

Parameters

[out] indices Array of four corner indices

const std::vector<Nimble::Vector2i>& Nimble::KeyStone::limits ( ) const

inline

Information on which pixels are inside the camera area.

Each item (2D vector) contains values for the first pixel inside the camera area and width of the camera area, per scanline.

Returns: List of scanline line segments

Nimble::Rect Nimble::KeyStone::outputBounds ( )

The output area of the screen.

Returns: Rectangle at [dpyX, dpyY] with size [dpyWidth, dpyHeight]

Nimble::Vector2 Nimble::KeyStone::project ( const Nimble::Vector2 & p ) const

Project a vector from camera coordinates to the display coordinates This function applies the lens correction and projection matrix on the coordinates.

Parameters

p	Point in camera coordinates

Returns: Point in display coordinates

Nimble::Vector2 Nimble::KeyStone::project01 ( const Nimble::Vector2 & p ) const

Project the point from camera coordinates to normalized coordinates in range [0,1].

Parameters

p	Point in camera coordinates

Returns: Point in normalized display coordinates

Nimble::Vector2 Nimble::KeyStone::projectInverse ( const Nimble::Vector2 & p ) const

Do inverse projection (from screen to camera coordinates), ignoring the camera barrel distortion.

Useful as a rough estimation of the point location on the camera image.

Parameters

p	Point in screen coordinates

Returns: Point in camera coordinates

static Nimble::Matrix3 Nimble::KeyStone::projectionMatrix ( const std::array< Nimble::Vector2, 4 > & vertices )

static

Calculates the projection matrix.

See Paul Heckbert's master's thesis, pages 19-21. Often you need to invert this.

Parameters

vertices an array of four corner vertices

Returns: Generated projection matrix

void Nimble::KeyStone::setOutputExtension ( const Nimble::Matrix3 & m )

Sets the extension (fine-tuning) matrix.

By default the extension matrix is set to identity.

Parameters

m	extension matrix

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation