Coordinate System

TCoordinateMap data structure and related functions to work with IImageVPA objects' image coordinate system. More...

Data Structures
struct	CVIPointD
	Cartesian 2D point (X, Y) with double components. More...
struct	TCoordinateMap
	Defines a coordinate system that describes an affine linear transformation. More...

Functions
void	BoundingRectangle (TArea Area, TCoordinateMap CS, TDRect &BoundingBox)
	Calculates the smallest bounding rectangle for the given Area. More...
void	ComposeCoordinateMaps (TCoordinateMap CS1, TCoordinateMap CS2, TCoordinateMap &CSOut)
	Concatenates mathematically two coordinate systems. More...
cvbbool_t	CoordinateMapInverseTransform (double Xin, double Yin, TCoordinateMap CS, double &Xout, double &Yout)
	Transform a coordinate point Xin, Yin using the inverse of the given coordinate system CS. More...
cvbbool_t	CoordinateMapInverseTransformArea (TArea AreaIn, TCoordinateMap CS, TArea &AreaOut)
	Transforms the AreaIn using the inverse of the coordinate system CS. More...
cvbbool_t	CoordinateMapIsTranslation (TCoordinateMap CS)
	Checks whether the coordinate system only describes a translation. More...
void	CoordinateMapTransform (double Xin, double Yin, TCoordinateMap CS, double &Xout, double &Yout)
	Transforms a coordinate point using the given coordinate system CS. More...
void	CoordinateMapTransformArea (TArea AreaIn, TCoordinateMap CS, TArea &AreaOut)
	Transforms the AreaIn using the given coordinate system CS. More...
cvbbool_t	GetImageOrigin (IMG Image, double &OrgX, double &OrgY)
	Gets the origin of the Image object's coordinate system. More...
void	ImageAreaToPixel (IMG Image, TArea ImageArea, TArea &PixelArea)
	Converts the ImageArea (in image coordinates) to pixel coordinates. More...
void	ImageToPixel (IMG Image, double ImageX, double ImageY, double &PixelX, double &PixelY)
	Transforms a point (ImageX, ImageY) in image coordinates into pixel coordinates. More...
cvbbool_t	ImageToPixelCoordinates (IMG Image, double ImageX, double ImageY, double &PixelX, double &PixelY)
	Transforms a point (ImageX, ImageY) in image coordinates into pixel coordinates. More...
void	InitCoordinateMap (TCoordinateMap &CS)
	Initializes the given TCoordinateMap CS with the default coordinate system. More...
cvbbool_t	InverseCoordinateMap (TCoordinateMap CSin, TCoordinateMap &CSout)
	Inverts a given coordinate system, if possible. More...
void	PixelAreaToImage (IMG Image, TArea PixelArea, TArea &ImageArea)
	Converts the PixelArea (in pixel coordinates) to image coordinates. More...
void	PixelToImage (IMG Image, double PixelX, double PixelY, double &ImageX, double &ImageY)
	Transforms a point (PixelX, PixelY) in pixel coordinates into image coordinates. More...
cvbbool_t	PixelToImageCoordinates (IMG Image, double PixelX, double PixelY, double &ImageX, double &ImageY)
	Transforms a point (PixelX, PixelY) in pixel coordinates into image coordinates. More...
cvbbool_t	SetImageOrigin (IMG Image, double OrgX, double OrgY)
	Sets only the origin of the Image object's coordinate system. More...

Detailed Description

TCoordinateMap data structure and related functions to work with IImageVPA objects' image coordinate system.

Function Documentation

BoundingRectangle()

void BoundingRectangle ( TArea  Area, TCoordinateMap  CS, TDRect &  BoundingBox  )

related

Calculates the smallest bounding rectangle for the given Area.

This function takes the coordinate system CS into account. That means that first the Area is transformed via CoordinateMapTransformArea and then the bounding box is calculated.

Parameters

[in]	Area	Area of interest for which the bounding rectangle is to be calculated.
[in]	CS	Coordinate system to transform Area.
[out]	BoundingBox	Variable to be filled with bounding rectangle borders.

ComposeCoordinateMaps()

void ComposeCoordinateMaps ( TCoordinateMap  CS1, TCoordinateMap  CS2, TCoordinateMap &  CSOut  )

related

Concatenates mathematically two coordinate systems.

Calculation

Parameters

[in]	CS1	First coordinate system.
[in]	CS2	Second coordinate system.
[out]	CSOut	Variable to be filled with the result components.

CoordinateMapInverseTransform()

cvbbool_t CoordinateMapInverseTransform ( double  Xin, double  Yin, TCoordinateMap  CS, double &  Xout, double &  Yout  )

related

Transform a coordinate point Xin, Yin using the inverse of the given coordinate system CS.

Attention

If the inversion fails; Xout and Yout are not modified.

Calculation

This function is a shorthand for

TCoordinateMap CSInverse;
if(!InverseCoordinateMap(CS, CSInverse))
  return false;
 
CoordinateMapTransform(Xin, Yin, CSInverse, Xout, Yout);
return true;

Parameters

[in]	Xin	X component of the point.
[in]	Yin	Y component of the point.
[in]	CS	Coordinate system to be inverted and the used to transform the point Xin, Yin.
[out]	Xout	Variable to be filled with transformed X coordinate.
[out]	Yout	Variable to be filled with transformed Y coordinate.

Returns

true if inversion of the coordinate system CS succeeded; false otherwise (determinant of TCoordinateMap::Matrix of CS is zero).

See also

MatrixDeterminant

CoordinateMapInverseTransformArea()

cvbbool_t CoordinateMapInverseTransformArea ( TArea  AreaIn, TCoordinateMap  CS, TArea &  AreaOut  )

related

Transforms the AreaIn using the inverse of the coordinate system CS.

Attention

If the inversion fails; AreaOut is not modified.

Calculation

This function is a shorthand for

TCoordinateMap CSInverse;
if(!InverseCoordinateMap(CS, CSInverse))
  return false;
 
CoordinateMapTransformArea(AreaIn, CSInverse, AreaOut);
return true;

Parameters

[in]	AreaIn	Area to be transformed.
[in]	CS	Coordinate system to be inverted and the used to transform the point Xin, Yin.
[out]	AreaOut	Area to be filled with transformed area points.

Returns

true, if the inversion succeeded, false otherwise (the determinant of TCoordinateMap::Matrix of CS is zero).

See also

MatrixDeterminant

CoordinateMapIsTranslation()

cvbbool_t CoordinateMapIsTranslation ( TCoordinateMap  CS )

related

Checks whether the coordinate system only describes a translation.

This function checks if the TCoordinateMap::Matrix is the unit matrix.

Parameters

[in]

CS

Coordinate to be checked.

Returns

true, if the coordinate system only describes a translationL; false otherwise.

CoordinateMapTransform()

void CoordinateMapTransform ( double  Xin, double  Yin, TCoordinateMap  CS, double &  Xout, double &  Yout  )

related

Transforms a coordinate point using the given coordinate system CS.

Calculation

Parameters

[in]	Xin	X component of coordinate point.
[in]	Yin	Y component of coordinate point.
[in]	CS	Coordinate system used for the transformation.
[out]	Xout	Variable to be filled with the X component of transformed point.
[out]	Yout	Variable to be filled with the Y component of transformed point.

CoordinateMapTransformArea()

void CoordinateMapTransformArea ( TArea  AreaIn, TCoordinateMap  CS, TArea &  AreaOut  )

related

Transforms the AreaIn using the given coordinate system CS.

CoordinateMapTransform is used on every point of AreaIn.

Parameters

[in]	AreaIn	Area to be transformed.
[in]	CS	Coordinate system used to transform AreaIn.
[out]	AreaOut	Area to be filled with transformed area points.

GetImageOrigin()

cvbbool_t GetImageOrigin	(	IMG	Image,
		double &	OrgX,
		double &	OrgY
	)

Gets the origin of the Image object's coordinate system.

This implementation does effectively this:

cvbbool_t GetImageOrigin(IMG Image, double &OrgX, double &OrgY)
{
  TCoordinateMap cs = { 0 };
  if(!GetImageCoordinates(Image, cs))
    return false;
  OrgX = cs.OrgX;
  OrgY = cs.OrgY;
  return true;
}

Parameters

[in]	Image	Image object handle to get the coordinate system from.
[out]	OrgX	Variable to receive the X component of the origin.
[out]	OrgY	Variable to receive the Y component of the origin.

Returns

true if successful; false if e.g. Image is not valid.

See also

GetImageCoordinates, SetImageOrigin

ImageAreaToPixel()

void ImageAreaToPixel	(	IMG	Image,
		TArea	ImageArea,
		TArea &	PixelArea
	)

Converts the ImageArea (in image coordinates) to pixel coordinates.

Attention

It is safer to use this code as this checks the return values:

cvbbool_t AreaPixelToImage(IMG Image, const TArea PixelArea, TArea &ImageArea)
{
  TCoordinateMap cs = { 0 };
  if(!GetImageCoordinates(Image, cs))
    return false;
    
  CoordinateMapTransformArea(PixelArea, cs, ImageArea);
  return true;
}

Parameters

[in]	Image	Image object handle to get the coordinate system from.
[in]	ImageArea	Area of interest in image coordinates.
[out]	PixelArea	Variable to receive ImageArea in pixel coordinates; NaN on error.

See also

ImageToPixelCoordinates, PixelAreaToImage

ImageToPixel()

void ImageToPixel	(	IMG	Image,
		double	ImageX,
		double	ImageY,
		double &	PixelX,
		double &	PixelY
	)

Transforms a point (ImageX, ImageY) in image coordinates into pixel coordinates.

Deprecated:

Use ImageToPixelCoordinates instead which reports an error if Image is invalid.

Parameters

[in]	Image	Image object handle to get the coordinate system from.
[in]	ImageX	X component of point in image coordinates.
[in]	ImageY	Y component of point in image coordinates.
[out]	PixelX	Variable to be set to X component in pixel coordinates; NaN if Image is invalid.
[out]	PixelY	Variable to be set to Y component in pixel coordinates; NaN if Image is invalid.

ImageToPixelCoordinates()

cvbbool_t ImageToPixelCoordinates	(	IMG	Image,
		double	ImageX,
		double	ImageY,
		double &	PixelX,
		double &	PixelY
	)

Transforms a point (ImageX, ImageY) in image coordinates into pixel coordinates.

This function uses the Image object's coordinate system as follows:

TCoordinateMap cs = { 0 };
if(!GetImageCoordinates(Image, cs))
  return false;
 
CoordinateMapTransform(ImageX, ImageY, cs, PixelX, PixelY);
return true;

Parameters

[in]	Image	Image object handle to get the coordinate system from.
[in]	ImageX	X component of point in image coordinates.
[in]	ImageY	Y component of point in image coordinates.
[out]	PixelX	Variable to be set to X component in pixel coordinates; not set on failure.
[out]	PixelY	Variable to be set to Y component in pixel coordinates; not set on failure.

Returns

true if successful; false if e.g. Image is not valid.

InitCoordinateMap()

void InitCoordinateMap ( TCoordinateMap &  CS )

related

Initializes the given TCoordinateMap CS with the default coordinate system.

The default coordinate system has its location (TCoordinateMap::OrgX and TCoordinateMap::OrgY) at the top-left: (0, 0) point. The TCoordinateMap::Matrix is initialized to the unit matrix. Thus the direction for the X-axis is to the right and Y-axis is facing downwards. This then resembles the pixel coordinate system.

When seen as a homogeneous coordinates matrix the values would be:

The last row is virtual (not in the data structure) and is assumed to be (0, 0, 1).

Parameters

[out]

CS

TCoordinateMap to be filled with default values.

InverseCoordinateMap()

cvbbool_t InverseCoordinateMap ( TCoordinateMap  CSin, TCoordinateMap &  CSout  )

related

Inverts a given coordinate system, if possible.

First tries to execute InverseMatrix on TCoordinateMap::Matrix of CSin and if that succeeds calls MatrixRTransform on the negative origin with the result of the inversion.

If the determinant of TCoordinateMap::Matrix of CSin is zero, false is returned and CSout is set to CSin.

Parameters

[in]	CSin	Input coordinate system to be inverted.
[out]	CSout	Variable to be filled with inverted coordinate system components.

Returns

true, if the inversion succeeded, false otherwise (the determinant of TCoordinateMap::Matrix of CSin is zero).

See also

MatrixDeterminant

PixelAreaToImage()

void PixelAreaToImage	(	IMG	Image,
		TArea	PixelArea,
		TArea &	ImageArea
	)

Converts the PixelArea (in pixel coordinates) to image coordinates.

Attention

It is safer to use this code as this checks the return values:

cvbbool_t AreaPixelToImage(IMG Image, const TArea PixelArea, TArea &ImageArea)
{
  TCoordinateMap cs = { 0 };
  if(!GetImageCoordinates(Image, cs))
    return false;
    
  return CoordinateMapInverseTransformArea(PixelArea, cs, ImageArea);
}

Parameters

[in]	Image	Image object handle to get the coordinate system from.
[in]	PixelArea	Area of interest in pixel coordinates.
[out]	ImageArea	Variable to receive PixelArea in image coordinates; NaN on error.

See also

PixelToImageCoordinates, ImageAreaToPixel

PixelToImage()

void PixelToImage	(	IMG	Image,
		double	PixelX,
		double	PixelY,
		double &	ImageX,
		double &	ImageY
	)

Transforms a point (PixelX, PixelY) in pixel coordinates into image coordinates.

Deprecated:

Use PixelToImageCoordinates instead which reports an error if Image is invalid.

Parameters

[in]	Image	Image object handle to get the coordinate system from.
[in]	PixelX	X component of point in pixel coordinates.
[in]	PixelY	Y component of point in pixel coordinates.
[out]	ImageX	Variable to be set to X component in image coordinates; NaN if Image is invalid.
[out]	ImageY	Variable to be set to Y component in image coordinates; NaN if Image is invalid.

PixelToImageCoordinates()

cvbbool_t PixelToImageCoordinates	(	IMG	Image,
		double	PixelX,
		double	PixelY,
		double &	ImageX,
		double &	ImageY
	)

Transforms a point (PixelX, PixelY) in pixel coordinates into image coordinates.

This function uses the Image object's coordinate system as follows:

TCoordinateMap cs = { 0 };
if(!GetImageCoordinates(Image, cs))
  return false;
 
return CoordinateMapInverseTransform(ImageX, ImageY, cs, PixelX, PixelY);

Parameters

[in]	Image	Image object handle to get the coordinate system from.
[in]	PixelX	X component of point in pixel coordinates.
[in]	PixelY	Y component of point in pixel coordinates.
[out]	ImageX	Variable to be set to X component in image coordinates; not set on failure.
[out]	ImageY	Variable to be set to Y component in image coordinates; not set on failure.

Returns

true if successful; false if e.g. Image is not valid.

SetImageOrigin()

cvbbool_t SetImageOrigin	(	IMG	Image,
		double	OrgX,
		double	OrgY
	)

Sets only the origin of the Image object's coordinate system.

This implementation does effectively this:

cvbbool_t SetImageOrigin(IMG Image, double OrgX, double OrgY)
{
  TCoordinateMap cs = { 0 };
  if(!GetImageCoordinates(Image, cs))
    return false;
  cs.OrgX = OrgX;
  cs.OrgY = OrgY;
  return SetImageCoordinates(Image, cs);
}

Parameters

[in]	Image	Image object handle to set the coordinate system to.
[in]	OrgX	X component for new origin.
[in]	OrgY	Y component for new origin.

Returns

true if successful; false if e.g. Image is not valid.

See also

GetImageCoordinates, SetImageCoordinates, GetImageOrigin