Image Manager (CVCImg.dll) 14.0
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.

## ◆ 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;
void CoordinateMapTransform(double Xin, double Yin, TCoordinateMap CS, double &Xout, double &Yout)
Transforms a coordinate point using the given coordinate system CS.
Definition: GeometryExports.cpp:626
cvbbool_t InverseCoordinateMap(TCoordinateMap CSin, TCoordinateMap &CSout)
Inverts a given coordinate system, if possible.
Definition: GeometryExports.cpp:657
Defines a coordinate system that describes an affine linear transformation.
Definition: CVTypes.h:110
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).
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;
void CoordinateMapTransformArea(TArea AreaIn, TCoordinateMap CS, TArea &AreaOut)
Transforms the AreaIn using the given coordinate system CS.
Definition: GeometryExports.cpp:727
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).
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;
}
cvbbool_t GetImageOrigin(IMG Image, double &OrgX, double &OrgY)
Gets the origin of the Image object's coordinate system.
Definition: PseudoCOMExports.cpp:155
cvbbool_t GetImageCoordinates(IMG Image, TCoordinateMap &CS)
Gets the coordinate system of an Image.
Definition: PseudoCOMExports.cpp:66
void * IMG
CVB 2D image handle.
Definition: CVTypes.h:95
double OrgY
Y coordinate of the origin.
Definition: CVTypes.h:112
double OrgX
X coordinate of the origin.
Definition: CVTypes.h:111
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.
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;
}
Describes an area of interest that is using three points (P0, P1 and P2).
Definition: CVTypes.h:170
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.
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).
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);
}
cvbbool_t CoordinateMapInverseTransformArea(TArea AreaIn, TCoordinateMap CS, TArea &AreaOut)
Transforms the AreaIn using the inverse of the coordinate system CS.
Definition: GeometryExports.cpp:766
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.
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);
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.
Definition: GeometryExports.cpp:704
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);
}
cvbbool_t SetImageOrigin(IMG Image, double OrgX, double OrgY)
Sets only the origin of the Image object's coordinate system.
Definition: PseudoCOMExports.cpp:106
cvbbool_t SetImageCoordinates(IMG Image, TCoordinateMap CS)
Sets the given coordinate system CS to the given Image.
Definition: PseudoCOMExports.cpp:41
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.