Image Manager (CVCImg.dll) 14.1
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]AreaArea of interest for which the bounding rectangle is to be calculated.
[in]CSCoordinate system to transform Area.
[out]BoundingBoxVariable 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]CS1First coordinate system.
[in]CS2Second coordinate system.
[out]CSOutVariable 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:612
cvbbool_t InverseCoordinateMap(TCoordinateMap CSin, TCoordinateMap &CSout)
Inverts a given coordinate system, if possible.
Definition: GeometryExports.cpp:642
Defines a coordinate system that describes an affine linear transformation.
Definition: CVTypes.h:110
Parameters
[in]XinX component of the point.
[in]YinY component of the point.
[in]CSCoordinate system to be inverted and the used to transform the point Xin, Yin.
[out]XoutVariable to be filled with transformed X coordinate.
[out]YoutVariable 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;
void CoordinateMapTransformArea(TArea AreaIn, TCoordinateMap CS, TArea &AreaOut)
Transforms the AreaIn using the given coordinate system CS.
Definition: GeometryExports.cpp:710
Parameters
[in]AreaInArea to be transformed.
[in]CSCoordinate system to be inverted and the used to transform the point Xin, Yin.
[out]AreaOutArea 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]CSCoordinate 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]XinX component of coordinate point.
[in]YinY component of coordinate point.
[in]CSCoordinate system used for the transformation.
[out]XoutVariable to be filled with the X component of transformed point.
[out]YoutVariable 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]AreaInArea to be transformed.
[in]CSCoordinate system used to transform AreaIn.
[out]AreaOutArea 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:153
cvbbool_t GetImageCoordinates(IMG Image, TCoordinateMap &CS)
Gets the coordinate system of an Image.
Definition: PseudoCOMExports.cpp:64
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]ImageImage object handle to get the coordinate system from.
[out]OrgXVariable to receive the X component of the origin.
[out]OrgYVariable 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;
}
Describes an area of interest that is using three points (P0, P1 and P2).
Definition: CVTypes.h:170
Parameters
[in]ImageImage object handle to get the coordinate system from.
[in]ImageAreaArea of interest in image coordinates.
[out]PixelAreaVariable 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]ImageImage object handle to get the coordinate system from.
[in]ImageXX component of point in image coordinates.
[in]ImageYY component of point in image coordinates.
[out]PixelXVariable to be set to X component in pixel coordinates; NaN if Image is invalid.
[out]PixelYVariable 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]ImageImage object handle to get the coordinate system from.
[in]ImageXX component of point in image coordinates.
[in]ImageYY component of point in image coordinates.
[out]PixelXVariable to be set to X component in pixel coordinates; not set on failure.
[out]PixelYVariable 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]CSTCoordinateMap 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]CSinInput coordinate system to be inverted.
[out]CSoutVariable 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);
}
cvbbool_t CoordinateMapInverseTransformArea(TArea AreaIn, TCoordinateMap CS, TArea &AreaOut)
Transforms the AreaIn using the inverse of the coordinate system CS.
Definition: GeometryExports.cpp:748
Parameters
[in]ImageImage object handle to get the coordinate system from.
[in]PixelAreaArea of interest in pixel coordinates.
[out]ImageAreaVariable 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]ImageImage object handle to get the coordinate system from.
[in]PixelXX component of point in pixel coordinates.
[in]PixelYY component of point in pixel coordinates.
[out]ImageXVariable to be set to X component in image coordinates; NaN if Image is invalid.
[out]ImageYVariable 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:688
Parameters
[in]ImageImage object handle to get the coordinate system from.
[in]PixelXX component of point in pixel coordinates.
[in]PixelYY component of point in pixel coordinates.
[out]ImageXVariable to be set to X component in image coordinates; not set on failure.
[out]ImageYVariable 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:104
cvbbool_t SetImageCoordinates(IMG Image, TCoordinateMap CS)
Sets the given coordinate system CS to the given Image.
Definition: PseudoCOMExports.cpp:40
Parameters
[in]ImageImage object handle to set the coordinate system to.
[in]OrgXX component for new origin.
[in]OrgYY component for new origin.
Returns
true if successful; false if e.g. Image is not valid.
See also
GetImageCoordinates, SetImageCoordinates, GetImageOrigin