Functions
I32	bestline (I32 xy, I32 N, F32 cx, F32 cy, F32 b)
	Calculate Chi-Square Bestline for a Pixellist. More...

I32	bestline_successive_fit (I32 pi32LstPxIn, U32 u32PxCount, vcline psBestline, U32 u32RemovePxCount, U8 u8RemovePercentageIff1, U32 u32UseMinCountPx)
	Calculate Chi-Square Bestline for a Pixellist, Ignores Outliers. More...

I32	linear_regression (I32 xy, I32 N, F32 mx, F32 *b)
	Calculate Linear Regression Bestline for a Pixellist. More...

I32	bestcircle (I32 pxy, I32 N, F32 px, F32 py, F32 rad)
	Calculate Chi-Square Bestcircle for a Pixellist. More...

F32	calculate_chisquare_for_circle (I32 *pxy, I32 N, F32 px, F32 py, F32 rad)
	A-Posteriori Calculation of Chi-Square for a Bestcircle. More...

I32	vc_centerpoint (point lstPtIn, U32 ptCount, point ptCenter)
	Calculate Centerpoint of a Pointlist. More...

I32	vc_centerpoint_successive_fit (point lstPtIn, U32 ptCount, point ptCenter, U32 u32RemovePtsCount, U8 u8RemovePercentageIff1, U32 u32UseMinCountPts)
	Calculate Centerpoint of a Pointlist, Ignores Outliers. More...

I32	vc_successive_fit (point lstPtIn, U32 ptCount, void result, void params, U32 u32RemovePtsCount, U8 u8RemovePercentageIff1, U32 u32UseMinCountPts, I32(calc_result)(point lstPtIn, U32 ptCount, void result, void params), I32(abs_dist)(F32 dist, point sPt, void result, void params))
	Calculate Something of a Pointlist, Ignores Outliers. More...

I32	vc_bestfit_poly1d1d_calculate_poly (VCPolynom1D1D poly, point pt, I32 pointCount, I32 transformInIff1, F32 offsIn, F32 scaleIn, I32 transformOutIff1, F32 offsOut, F32 scaleOut)
	Calculates a VCPolynom1D1D to map point pairs by Least Squares (Slow). More...

I32	vc_bestfit_poly1d1d_map (VCPolynom1D1D poly, F32 from, F32 *to, I32 valCount)
	Maps Points using VCPolynom1D1D. More...

I32	vc_bestfit_poly1d1d_calculate_maxDev (F32 maxDev, VCPolynom1D1D poly, point *pt, I32 pointCount)
	Calculates the Deviation of VCPolynom1D1D to real data. More...

I32	vc_bestfit_poly1d1d_calculate_chiSquare (F32 chiSquare, VCPolynom1D1D poly, point *pt, I32 pointCount)
	Calculates the Chi Square of VCPolynom1D1D to real data. More...

I32	vc_bestfit_poly2d1d_calculate_poly (VCPolynom2D1D poly, point from, F64 *to, I32 pointCount, I32 transformInIff1, F32 offsXIn, F32 offsYIn, F32 scaleXIn, F32 scaleYIn, I32 transformOutIff1, F32 offsZOut, F32 scaleZOut)
	Calculates a VCPolynom2D1D to map point pairs by Least Squares (Slow). More...

I32	vc_bestfit_poly2d1d_map (VCPolynom2D1D poly, point from, F64 *to, I32 pointCount)
	Maps Points using VCPolynom2D1D. More...

I32	vc_bestfit_poly2d1d_calculate_maxDev (F32 maxDev, VCPolynom2D1D poly, point from, F64 to, I32 pointCount)
	Calculates the Deviation of VCPolynom2D1D to real data. More...

I32	vc_bestfit_poly2d2d_calculate_poly (VCPolynom2D2D poly, point from, point *to, I32 pointCount, I32 transformInIff1, F32 offsXIn, F32 offsYIn, F32 scaleXIn, F32 scaleYIn, I32 transformOutIff1, F32 offsXOut, F32 offsYOut, F32 scaleXOut, F32 scaleYOut)
	Calculates a VCPolynom2D2D to map point pairs by Least Squares (Slow). More...

I32	vc_bestfit_poly2d2d_map (VCPolynom2D2D poly, point from, point *to, I32 pointCount)
	Maps Points using VCPolynom2D2D. More...

I32	vc_bestfit_poly2d2d_calculate_maxDev (F32 maxDev, VCPolynom2D2D poly, point from, point to, I32 pointCount)
	Calculates the Deviation of VCPolynom2D2D to real data. More...

I32	vc_bestfit_poly2d2d_calculate_poly_errorband (VCPolynom2D2D poly, point from, point to, F32 fromXVar, F32 *fromYVar, I32 pointCnt, I32 transformInIff1, F32 offsXIn, F32 offsYIn, F32 scaleXIn, F32 scaleYIn, I32 transformOutIff1, F32 offsXOut, F32 offsYOut, F32 scaleXOut, F32 scaleYOut)
	Calculates a VCPolynom2D2D to map point pairs by Least Squares with error bands (Slow). More...

I32	vc_bestfit_homography_calculate_homMat (F64 homMat[3][3], point from, point to, I32 pointCount)
	Calculates a Homography to map point pairs by Least Squares (Slow). More...

I32	vc_bestfit_homography_map (F64 homMat[3][3], point from, point to, I32 pointCount)
	Maps Points using a Homography. More...

I32	vc_bestfit_homography_calculate_maxDev (F32 maxDev, F64 homMat[3][3], point from, point *to, I32 pointCount)
	Calculates the Deviation of Homography to real data. More...

I32	vc_homography_derivate (F32 diffX_x, F32 diffX_y, F32 diffY_x, F32 diffY_y, F32 x, F32 y, I32 pointCnt, F64 homMat[3][3])
	Calculates the Derivate of the Homography at a point given. More...

Detailed Description

Functions in this group fit forms to a given pixel list.

Function Documentation

◆ bestline()

I32 bestline	(	I32 *	xy,
		I32	N,
		float *	cx,
		float *	cy,
		float *	b
	)

The function computes a line minimizing the sum of all quadratic distances of the points in the pixellist to the line. Unlike other methods, this function uses the shortest distance to the line (i.e. perpendicular to the line). The resulting line is defined as: cx * x + cy * y - b = 0.

Parameters

xy	Pointer to the Pixellist, i.e. Alternating x- and y-Coordinates.
N	Number of Points in Pixellist.
cx	Pointer to Result-Parameter `cx` (float).
cy	Pointer to Result-Parameter `cy` (float).
b	Pointer to Result-Parameter `b` (float).

The pixels in the pixellist may have the full I32 coordinate range, the minimum number of pixels in the list is 2. There is no upper limit.

Return values

ERR_PARAM	If `N` is less than 2.
ERR_NONE	On Success.

Memory Consumption: None.

See also: bestcircle(), vc_draw_line().

◆ bestline_successive_fit()

I32 bestline_successive_fit	(	I32 *	pi32LstPxIn,
		U32	u32PxCount,
		vcline *	psBestline,
		U32	u32RemovePxCount,
		U8	u8RemovePercentageIff1,
		U32	u32UseMinCountPx
	)

The function computes a line minimizing the sum of all quadratic distances of the points in the pixellist to the line. Unlike other methods, this function uses the shortest distance to the line (i.e. perpendicular to the line). The resulting line is defined as: cx * x + cy * y - b = 0.

Compared to the function bestline(), this function ignores the given count of points equal to the following text: At first, all points go into the bestline-calculation. The most far point will be removed from the bestline point list, and the bestline will be re- calculated through the remaining points. This will be repeated until the requested point count is reached.

Parameters

pi32LstPxIn	Pointer to the Pixellist, i.e. Alternating x- and y-Coordinates.
u32PxCount	Number of Points in Pixellist.
psBestline	Pointer to Result Bestline.
u32RemovePxCount	Count/Percentage of Pixel to Remove.
u8RemovePercentageIff1	Interpret the Parameter u32RemovePxCount as Percentage (0-100).
u32UseMinCountPx	Minimum Count of Pixel to Use for Final Bestline Calculation.

The pixels in the pixellist may have the full I32 coordinate range, the minimum number of pixels in the list is 2. There is no upper limit.

Return values

ERR_PARAM	If `N` is less than 2.
ERR_NONE	On Success.

Memory Consumption: None.

See also: bestline(), vc_draw_line().

Return values

bestline()	Result if errorneous.
ERR_PARAM	if Minimum Pixel Count is smaller 2.
ERR_SINGULAR	if available Pixel Count smaller than the Minimum Pixel Count.
ERR_MEMORY	if Memory Allocation Fails.

◆ linear_regression()

I32 linear_regression	(	I32 *	xy,
		I32	N,
		float *	mx,
		float *	b
	)

The function computes a line minimizing the sum of all quadratic distances of the points in the pixellist to the line. Unlike bestline() this function measures the distance to the points only in y-direction. This can be good if the input data is not a 2D coordinate list, but e.g., some x-value and a corresponding grey value.

The result line is defined as: mx * x + y - b = 0. An easy way to transform the result to a vcline is to use the function LineFromSlopeInterceptForm().

The function supports Pixel Positions in a range of [-65535,65535]² and N ≤ 65535.

Parameters

xy	Pointer to the Pixellist, i.e. Alternating x- and y-Coordinates.
N	Number of Points in Pixellist.
mx	Pointer to Result-Parameter `mx` (float).
b	Pointer to Result-Parameter `b` (float).

Return values

ERR_PARAM	if `N` < 2.
ERR_SINGULAR	if Line is Perpendicular to the X Axis.
ERR_NONE	on Success.

◆ bestcircle()

I32 bestcircle	(	I32 *	pxy,
		I32	N,
		F32 *	px,
		F32 *	py,
		F32 *	rad
	)

The function computes a circle minimizing the sum of all quadratic distances of the points in the pixellist to the circle. This function uses the shortest distance to the circle (i.e. perpendicular to the circle). The center point and the radius are calculated with subpixel resolution. The resulting circle is defined as:

float x = rad * sin( phi ) + px;

float y = rad * cos( phi ) + py;

Parameters

pxy	Pointer to the Pixellist, i.e. Alternating x- and y-Coordinates.
N	Number of points in pixellist.
px	Pointer to Result Parameter `px` (float).
py	Pointer to Result Parameter `py` (float).
rad	Pointer to Result Parameter `radius` (float).

The function calculates the Moore-Penrose Pseudoinverse equation system and solves it using high-precision integer arithmetics.

(px, py) defines the centerpoint and rad the radius of the circle found. Please make sure that the camera you use has a quadratic pixel architecture or use affine transformation to get virtually quadratic pixels. Otherwise circles in reality will be ellipses in image memory and the function will not be able to make a proper fit.

The pixels in the pixellist may have a coordinate range of [-16384, +16383], the minimum number of pixels in the list is 3, the maximum number is 65535.

Return values

ERR_PARAM	If Count of Pixels in List is not in Range of [3,65535].
ERR_SINGULAR	For example, if Pixels in the Pixellist do not define a Circle but a Line.
ERR_NONE	On Success.

Memory Consumption: None.

See also: bestline().

◆ calculate_chisquare_for_circle()

F32 calculate_chisquare_for_circle	(	I32 *	pxy,
		I32	N,
		F32	px,
		F32	py,
		F32	rad
	)

The function computes a value for Chi-Square for an integer pixel-list with respect to a bestcircle. This function calculates the shortest distance from the points in the pixel- list to the circle (i.e. perpendicular to the circle), sqaures it and adds it to the chisquare value. The chisquare value is finally normalized by N (the number of points in the pixel-list).

Parameters

pxy	Pointer to the Pixellist, i.e. Alternating x- and y-Coordinates.
N	Number of points in pixellist.
px	Pointer to Input Parameter `px` (float).
py	Pointer to Input Parameter `py` (float).
rad	Pointer to Input Parameter `radius` (float).

(px, py) defines the centerpoint and rad the radius of the circle given.

Return values

chisquare

See also: bestcircle().

◆ vc_centerpoint()

I32 vc_centerpoint	(	point *	lstPtIn,
		U32	ptCount,
		point *	ptCenter
	)

The function computes a centerpoint using the arithmetic mean of the points in the pointlist. Internally the accumulator is a F64 value which is the limit for the precision.

Return values

ERR_NONE On Success.

◆ vc_centerpoint_successive_fit()

I32 vc_centerpoint_successive_fit	(	point *	lstPtIn,
		U32	ptCount,
		point *	ptCenter,
		U32	u32RemovePtsCount,
		U8	u8RemovePercentageIff1,
		U32	u32UseMinCountPts
	)

The function computes a centerpoint using the arithmetic mean of the points in the pointlist.

This function ignores the given count of points equal to the following text: At first, all points go into the centerpoint calculation. The most far point will be removed from the centerpoint list, and the centerpoint will be re- calculated through the remaining points. This will be repeated until the requested point count is reached.

Parameters

lstPt	Pointer to the Pointlist.
ptCount	Number of Points in Pointlist.
ptCenter	Pointer to Result Centerpoint.
u32RemovePtsCount	Count/Percentage of Points to Remove.
u8RemovePercentageIff1	Interpret the Parameter u32RemovePtsCount as Percentage (0-100).
u32UseMinCountPts	Minimum Count of Points to Use for Final Centerpoint Calculation.

Return values

ERR_NONE	On Success.
ERR_MEMORY	if copy of point list cannot be allocated.
ERR_PARAM	if ptCount < u32UseMinCountPts.

◆ vc_successive_fit()

I32 vc_successive_fit	(	point *	lstPtIn,
		U32	ptCount,
		void *	result,
		void *	params,
		U32	u32RemovePtsCount,
		U8	u8RemovePercentageIff1,
		U32	u32UseMinCountPts,
		I32()(point lstPtIn, U32 ptCount, void result, void params)	calc_result,
		I32()(F32 dist, point sPt, void result, void *params)	abs_dist
	)

The function computes something using points in the pointlist.

This function ignores the given count of points equal to the following text: At first, all points go into the calculation. The most far point will be removed from the point list, and then something will be re- calculated through the remaining points. This will be repeated until the requested point count is reached.

Parameters

lstPt	Pointer to the Pointlist.
ptCount	Number of Points in Pointlist.
result	Pointer to Result of Something.
params	Pointer to Parameters of Something, passed to function pointers.
u32RemovePtsCount	Count/Percentage of Points to Remove.
u8RemovePercentageIff1	Interpret the Parameter u32RemovePtsCount as Percentage (0-100).
u32UseMinCountPts	Minimum Count of Points to Use for Final Centerpoint Calculation.
calc_result	Must calculate something by using the point list, only return values smaller than 0 are an error.
abs_dist	Must calculate the distance between something and a point, only return values smaller than 0 are an error.

Return values

ERR_NONE	On Success.
ERR_MEMORY	if copy of point list cannot be allocated.
ERR_PARAM	if ptCount < u32UseMinCountPts.
ERR_MODEL	if calc_result or abs_dist has a return value smaller 0.

◆ vc_bestfit_poly1d1d_calculate_poly()

I32 vc_bestfit_poly1d1d_calculate_poly	(	VCPolynom1D1D *	poly,
		point *	pt,
		I32	pointCount,
		I32	transformInIff1,
		F32	offsIn,
		F32	scaleIn,
		I32	transformOutIff1,
		F32	offsOut,
		F32	scaleOut
	)

The function calculates a VCPolynom1D1D to map values by a least squares algorithm.

To enhance the result offs and scale can be set to pre-translate and then pre-scale the input values. A good beginning is to set offs to the mean coordinate of the input data.

To get the maximum deviation between mapped and the true position, the function vc_bestfit_poly1d1d_calculate_maxDev() can be used. But also check the result between the points used for calculation, since polynomials of higher order may tend to overshoot in-between. Therefore leaving out each second neighbor for testing afterwards may be a good idea.

Make sure to have enough points with respect to the order of the polynomial chosen.

I32  fit_example(point *pt, I32 pointCount, U8 calculateIff1)
{
    const I32        polyOrder= 8;
    const F32        offs = 0.0, scale = 1.0;
    F32              sampleMapX, sampleMapY;
    char             acFilename[]="/tmp/poly.ini";
    F32              maxDev = 0.0;
    I32              rc, ee;
    VCPolynom1D1D    poly=NULL_VCPolynom1D1D;
    if(1==calculateIff1)
    {   // Calculate the polynomial and store it in a file.
        // In this case, the variable named 'to' points to the map destination.
        rc =  vc_poly1d1d_allocate(&poly, polyOrder);
        if(rc<0){ee=-1+10*rc; goto fail;}
        rc =  vc_bestfit_poly1d1d_calculate_poly(&poly, pt, pointCount, 1, offs, scale, 0,0,0);
        if(rc<0){ee=-2+10*rc; goto fail;}
        rc =  vc_bestfit_poly1d1d_calculate_maxDev(&maxDev, &poly, pt, pointCount);
        if(rc<0){ee=-3+10*rc; goto fail;}
        vc_poly1d1d_print(&poly, 2);
        printf("Maximum Deviation at Target Set:  %8.6f\n", maxDev);
        rc=  vc_poly1d1d_store_as_ini(acFilename, &poly, 1);
        if(rc<0){ee=-4+10*rc; goto fail;}
    }
    else
    {   // Process points after loading polynomial from file.
        // In this case, the variable named 'to' will be filled with the result mapping.
        rc =  vc_poly1d1d_load_and_allocate_from_ini(&poly, acFilename, 1);
        if(rc<0){ee=-5+10*rc; goto fail;}
        vc_poly1d1d_print(&poly, 2);
        sampleMapX = 5;
        rc =  vc_bestfit_poly1d1d_map(&poly, &sampleMapX, &sampleMapY, 1);
        if(rc<0){ee=-6+10*rc; goto fail;}
        printf("sample Map:   X = %f,  poly(X) = Y = %f\n", sampleMapX, sampleMapY);
    }
    ee=0;
fail:
    vc_poly1d1d_free(&poly);
    return(ee);
}

Parameters

poly	the pre-initalized polynomial with wished order.
pt	pointer to corresponding point list: pt[i].x corresponds to pt[i].y.
pointCount	total point count in list.
transformInIff1,offsIn,scaleIn	For Numerical Stability: Pre-Apply IN[i]=(from[i]-offsIn)/scaleIn.
transformOutIff1,offsOut,scaleOut	For Numerical Stability: Post-Apply to[i]=( OUT[i]*scaleOut)+offsOut.

See also: vc_bestfit_poly1d1d_map(), vc_bestfit_poly1d1d_calculate_maxDev(), vc_poly1d1d_allocate().

◆ vc_bestfit_poly1d1d_map()

I32 vc_bestfit_poly1d1d_map	(	VCPolynom1D1D *	poly,
		F32 *	from,
		F32 *	to,
		I32	valCount
	)

The function maps the given points at from[i] to to[i], it simply loops over them and calculates vc_poly1d1d_map().

Parameters

poly	the polynomial calculated by vc_bestfit_poly1d1d_calculate_poly().
from	input values.
to	output values.
pointCount	total point count in list.

See also: vc_bestfit_poly1d1d_calculate_poly(), vc_poly1d1d_allocate().

◆ vc_bestfit_poly1d1d_calculate_maxDev()

I32 vc_bestfit_poly1d1d_calculate_maxDev	(	F32 *	maxDev,
		VCPolynom1D1D *	poly,
		point *	pt,
		I32	pointCount
	)

The function calculates the deviation of VCPolynom1D1D to real data. All points x values are mapped and the euclidean distance to their counterpart, the y values, is calculated. The maximum distance is returned.

Parameters

maxDev	maximum euclidean distance between poly(pt[i].x) and pt[i].y at target space.
poly	the polynomial calculated by vc_bestfit_poly1d1d_calculate_poly().
pt	pointer to corresponding point list: pt[i].x corresponds to pt[i].y.
pointCount	total point count in list.

See also: vc_bestfit_poly1d1d_map(), vc_bestfit_poly1d1d_calculate_poly(), vc_poly1d1d_allocate().

◆ vc_bestfit_poly1d1d_calculate_chiSquare()

I32 vc_bestfit_poly1d1d_calculate_chiSquare	(	F32 *	chiSquare,
		VCPolynom1D1D *	poly,
		point *	pt,
		I32	pointCount
	)

The function calculates the chi square of VCPolynom1D1D to real data, i.e.

$\texttt{chiSquare} = \frac{ \sqrt{ \sum_{i=0}^{\texttt{pointCount}} (\texttt{poly}(\texttt{pt[i].x}) - \texttt{pt[i].y})^2 }}{ \texttt{pointCount} }$

Parameters

chiSquare	Chi square value.
poly	the polynomial calculated by vc_bestfit_poly1d1d_calculate_poly().
pt	pointer to corresponding point list: pt[i].x corresponds to pt[i].y.
pointCount	total point count in list.

See also: vc_bestfit_poly1d1d_map(), vc_bestfit_poly1d1d_calculate_poly(), vc_poly1d1d_allocate().

◆ vc_bestfit_poly2d1d_calculate_poly()

I32 vc_bestfit_poly2d1d_calculate_poly	(	VCPolynom2D1D *	poly,
		point *	from,
		F64 *	to,
		I32	pointCount,
		I32	transformInIff1,
		F32	offsXIn,
		F32	offsYIn,
		F32	scaleXIn,
		F32	scaleYIn,
		I32	transformOutIff1,
		F32	offsZOut,
		F32	scaleZOut
	)

The function calculates a VCPolynom2D1D with 1= poly->orderRestrictedIff1 to map points to values by a least squares algorithm.

To enhance the result offsX, offsY, scaleX and scaleY can be set to pre-translate and then pre-scale the input values. A good beginning is to set offsX and offsY to the mean coordinate of the input data.

To get the maximum deviation between mapped and the true position, the function vc_bestfit_poly2d1d_calculate_maxDev() can be used. But also check the result between the points used for calculation, since polynomials of higher order may tend to overshoot in-between. Therefore leaving out each second neighbor for testing afterwards may be a good idea.

Make sure to have enough points with respect to the order of the polynomial chosen.

I32  fit_example(point *from, F64 *to, I32 pointCount, U8 calculateIff1)
{
  const I32        polyOrder= 6;
  const F32        offsX = 0.0, offsY = 0.0, scaleX = 1.0, scaleY = 1.0;
  char             acFilename[]="/tmp/poly.ini";
  F32              maxDev = 0.0;
  I32              rc, ee;
  VCPolynom2D1D    poly=NULL_VCPolynom2D1D;
  if(1==calculateIff1)
  {   // Calculate the polynomial and store it in a file.
      // In this case, the variable named 'to' points to the map destination.
      rc =  vc_poly2d1d_allocate(&poly, polyOrder, 1);
      if(rc<0){ee=-1+10*rc; goto fail;}
      rc =  vc_bestfit_poly2d1d_calculate_poly(&poly, from, to, pointCount, 1, offsX, offsY, scaleX, scaleY, 0,0,0,0,0);
      if(rc<0){ee=-2+10*rc; goto fail;}
      rc =  vc_bestfit_poly2d1d_calculate_maxDev(&maxDev, &poly, from, to, pointCount);
      if(rc<0){ee=-3+10*rc; goto fail;}
      vc_poly2d1d_print(&poly, 2);
      printf("Maximum Deviation at Target Set:  %8.6f\n", maxDev);
      rc=  vc_poly2d1d_store_as_ini(acFilename, &poly, 1);
      if(rc<0){ee=-4+10*rc; goto fail;}
  }
  else
  {   // Process points after loading polynomial from file.
      // In this case, the variable named 'to' will be filled with the result mapping.
      rc =  vc_poly2d1d_load_and_allocate_from_ini(&poly, acFilename, 1);
      if(rc<0){ee=-5+10*rc; goto fail;}
      vc_poly2d1d_print(&poly, 2);
      rc =  vc_bestfit_poly2d1d_map(&poly, from, to, pointCount);
      if(rc<0){ee=-6+10*rc; goto fail;}
  }
  ee=0;
fail:
  vc_poly2d1d_free(&poly);
  return(ee);
}

Parameters

poly	the pre-initalized polynomial with 1= `poly`->`orderRestrictedIff1` and wished orders
from,to	pointer to corresponding point lists: from[i] corresponds to to[i].
pointCount	total point count in list.
transformInIff1,offsXIn,offsYIn,scaleXIn,scaleYIn	For Numerical Stability: Pre-Apply IN[i]=(from[i]-offsIn)/scaleIn.
transformOutIff1,offsZOut,scaleZOut	For Numerical Stability: Post-Apply to[i]=( OUT[i]*scaleOut)+offsOut.

See also: vc_bestfit_poly2d1d_map(), vc_bestfit_poly2d1d_calculate_maxDev(), vc_poly2d1d_allocate().

◆ vc_bestfit_poly2d1d_map()

I32 vc_bestfit_poly2d1d_map	(	VCPolynom2D1D *	poly,
		point *	from,
		F64 *	to,
		I32	pointCount
	)

The function maps the given points at from[i] to [i], it simply loops over them and calculates to[i] = poly((from[i] - offs)*scale).

Parameters

poly	the polynomial calculated by vc_bestfit_poly2d1d_calculate_poly().
from	input values.
to	output value.
pointCount	total point count in list.

See also: vc_bestfit_poly2d1d_calculate_poly(), vc_poly2d1d_allocate().

◆ vc_bestfit_poly2d1d_calculate_maxDev()

I32 vc_bestfit_poly2d1d_calculate_maxDev	(	F32 *	maxDev,
		VCPolynom2D1D *	poly,
		point *	from,
		F64 *	to,
		I32	pointCount
	)

The function calculates the deviation of VCPolynom2D1D to real data. All points at from are mapped and the euclidean distance to their counterpart at to is calculated. The maximum distance is returned.

Parameters

maxDev	maximum euclidean distance between poly(from[i]) and to[i] at target space.
poly	the polynomial calculated by vc_bestfit_poly2d1d_calculate_poly().
from,to	pointer to corresponding point lists: from[i] corresponds to to[i].
pointCount	total point count in list.

See also: vc_bestfit_poly2d1d_map(), vc_bestfit_poly2d1d_calculate_poly(), vc_poly2d1d_allocate().

◆ vc_bestfit_poly2d2d_calculate_poly()

I32 vc_bestfit_poly2d2d_calculate_poly	(	VCPolynom2D2D *	poly,
		point *	from,
		point *	to,
		I32	pointCount,
		I32	transformInIff1,
		F32	offsXIn,
		F32	offsYIn,
		F32	scaleXIn,
		F32	scaleYIn,
		I32	transformOutIff1,
		F32	offsXOut,
		F32	offsYOut,
		F32	scaleXOut,
		F32	scaleYOut
	)

The function calculates a VCPolynom2D2D with 1= poly->orderRestrictedIff1 to map point pairs by a least squares algorithm.

To enhance the result offsX, offsY, scaleX and scaleY can be set to pre-translate and then pre-scale the input values. A good beginning is to set offsX and offsY to the mean coordinate of the input data.

To get the maximum deviation between mapped and the true position, the function vc_bestfit_poly2d2d_calculate_maxDev() can be used. But also check the result between the points used for calculation, since polynomials of higher order may tend to overshoot in-between. Therefore leaving out each second neighbor for testing afterwards may be a good idea.

Make sure to have enough points with respect to the order of the polynomial chosen.

I32  fit_example(point *from, point *to, I32 pointCount, U8 calculateIff1)
{
    const I32        polyOrderX= 8, polyOrderY = 6;
    const F32        offsX = 0.0, offsY = 0.0, scaleX = 1.0, scaleY = 1.0;
    char             acFilename[]="/tmp/poly.ini";
    F32              maxDev = 0.0;
    I32              rc, ee;
    VCPolynom2D2D    poly=NULL_VCPolynom2D2D;
    if(1==calculateIff1)
    {   // Calculate the polynomial and store it in a file.
        // In this case, the variable named 'to' points to the map destination.
        rc =  vc_poly2d2d_allocate(&poly, polyOrderX, polyOrderY, 1);
        if(rc<0){ee=-1+10*rc; goto fail;}
        rc =  vc_bestfit_poly2d2d_calculate_poly(&poly, from, to, pointCount, 1, offsX, offsY, scaleX, scaleY, 0,0,0,0,0);
        if(rc<0){ee=-2+10*rc; goto fail;}
        rc =  vc_bestfit_poly2d2d_calculate_maxDev(&maxDev, &poly, from, to, pointCount);
        if(rc<0){ee=-3+10*rc; goto fail;}
        vc_poly2d2d_print(&poly, 2);
        printf("Maximum Deviation at Target Set:  %8.6f\n", maxDev);
        rc=  vc_poly2d2d_store_as_ini(acFilename, &poly, 1);
        if(rc<0){ee=-4+10*rc; goto fail;}
    }
    else
    {   // Process points after loading polynomial from file.
        // In this case, the variable named 'to' will be filled with the result mapping.
        rc =  vc_poly2d2d_load_and_allocate_from_ini(&poly, acFilename, 1);
        if(rc<0){ee=-5+10*rc; goto fail;}
        vc_poly2d2d_print(&poly, 2);
        rc =  vc_bestfit_poly2d2d_map(&poly, from, to, pointCount);
        if(rc<0){ee=-6+10*rc; goto fail;}
    }
    ee=0;
fail:
    vc_poly2d2d_free(&poly);
    return(ee);
}

Parameters

poly	the pre-initalized polynomial with 1= `poly`->`orderRestrictedIff1` and wished orders
from,to	pointer to corresponding point lists: from[i] corresponds to to[i].
pointCount	total point count in list.
transformInIff1,offsXIn,offsYIn,scaleXIn,scaleYIn	For Numerical Stability: Pre-Apply IN[i]=(from[i]-offsIn)/scaleIn.
transformOutIff1,offsXOut,offsYOut,scaleXOut,scaleYOut	For Numerical Stability: Post-Apply to[i]=( OUT[i]*scaleOut)+offsOut.

See also: vc_bestfit_poly2d2d_map(), vc_bestfit_poly2d2d_calculate_maxDev(), vc_poly2d2d_allocate().

◆ vc_bestfit_poly2d2d_map()

I32 vc_bestfit_poly2d2d_map	(	VCPolynom2D2D *	poly,
		point *	from,
		point *	to,
		I32	pointCount
	)

The function maps the given points at from[i] to [i], it simply loops over them and calculates to[i] = poly((from[i] - offs)*scale).

Parameters

poly	the polynomial calculated by vc_bestfit_poly2d2d_calculate_poly().
from	input values.
to	output values.
pointCount	total point count in list.

See also: vc_bestfit_poly2d2d_calculate_poly(), vc_poly2d2d_allocate().

◆ vc_bestfit_poly2d2d_calculate_maxDev()

I32 vc_bestfit_poly2d2d_calculate_maxDev	(	F32 *	maxDev,
		VCPolynom2D2D *	poly,
		point *	from,
		point *	to,
		I32	pointCount
	)

The function calculates the deviation of VCPolynom2D2D to real data. All points at from are mapped and the euclidean distance to their counterpart at to is calculated. The maximum distance is returned.

Parameters

maxDev	maximum euclidean distance between poly(from[i]) and to[i] at target space.
poly	the polynomial calculated by vc_bestfit_poly2d2d_calculate_poly().
from,to	pointer to corresponding point lists: from[i] corresponds to to[i].
pointCount	total point count in list.

See also: vc_bestfit_poly2d2d_map(), vc_bestfit_poly2d2d_calculate_poly(), vc_poly2d2d_allocate().

◆ vc_bestfit_poly2d2d_calculate_poly_errorband()

I32 vc_bestfit_poly2d2d_calculate_poly_errorband	(	VCPolynom2D2D *	poly,
		point *	from,
		point *	to,
		F32 *	fromXVar,
		F32 *	fromYVar,
		I32	pointCount,
		I32	transformInIff1,
		F32	offsXIn,
		F32	offsYIn,
		F32	scaleXIn,
		F32	scaleYIn,
		I32	transformOutIff1,
		F32	offsXOut,
		F32	offsYOut,
		F32	scaleXOut,
		F32	scaleYOut
	)

The function calculates a VCPolynom2D2D with 1= poly->orderRestrictedIff1 to map point pairs by a least squares algorithm utilizing error bands.

The error band values will divide the point's X or Y least squares matrix entry by the error band value given, the error band value may be chosen to be the variance of a normal distributed error of the input.

More information can be found at vc_bestfit_poly2d2d_calculate_poly

Parameters

poly	the pre-initalized polynomial with 1= `poly`->`orderRestrictedIff1` and wished orders
from,to	pointer to corresponding point lists: from[i] corresponds to to[i].
fromXVar,fromYVar	pointer to corresponding error band lists: fromXYVar[i] corresponds to from[i].
pointCount	total point count in list.
transformInIff1,offsXIn,offsYIn,scaleXIn,scaleYIn	For Numerical Stability: Pre-Apply IN[i]=(from[i]-offsIn)/scaleIn.
transformOutIff1,offsXOut,offsYOut,scaleXOut,scaleYOut	For Numerical Stability: Post-Apply to[i]=( OUT[i]*scaleOut)+offsOut.

See also: vc_bestfit_poly2d2d_map(), vc_bestfit_poly2d2d_calculate_maxDev(), vc_poly2d2d_allocate().

◆ vc_bestfit_homography_calculate_homMat()

I32 vc_bestfit_homography_calculate_homMat	(	F64	homMat[3][3],
		point *	from,
		point *	to,
		I32	pointCount
	)

The function calculates a homography to map point pairs by a least squares algorithm.

To get the maximum deviation between mapped and the true position, the function vc_bestfit_homography_calculate_maxDev() can be used.

I32  fit_homography_example(F64 homMat[3][3], point *from, point *to, I32 pointCount, U8 calculateIff1)
{
    I32  rc, ee;
    F32  maxDev = 0.0;
    if(1==calculateIff1)
    {
        // Calculate the homography.
        // In this case, the variable named 'to' points to the map destination.
        rc =  vc_bestfit_homography_calculate_homMat(homMat, from, to, pointCount);
        if(rc<0){ee=-2+10*rc; goto fail;}
        rc =  vc_bestfit_homography_calculate_maxDev(&maxDev, homMat, from, to, pointCount);
        if(rc<0){ee=-3+10*rc; goto fail;}
        printf("Maximum Deviation at Target Set:  %8.6f\n", maxDev);
    }
    else
    {
        // Process points.
        // In this case, the variable named 'to' will be filled with the result mapping.
        rc =  vc_bestfit_homography_map(homMat, from, to, pointCount);
        if(rc<0){ee=-6+10*rc; goto fail;}
    }
    ee=0;
fail:
    return(ee);
}

Parameters

homMat	the homography as output.
from,to	pointer to corresponding point lists: from[i] corresponds to to[i].
pointCount	total point count in list.

See also: vc_bestfit_homography_map(), vc_bestfit_homography_calculate_homMat().

◆ vc_bestfit_homography_map()

I32 vc_bestfit_homography_map	(	F64	homMat[3][3],
		point *	from,
		point *	to,
		I32	pointCount
	)

The function maps the given points at from[i] to [i], it simply loops over them and calculates to[i] = homMat(from[i]).

Parameters

poly	the homography calculated by vc_bestfit_homography_calculate_homMat().
from	input values.
to	output values.
pointCount	total point count in list.

See also: vc_bestfit_homography_calculate_homMat().

◆ vc_bestfit_homography_calculate_maxDev()

I32 vc_bestfit_homography_calculate_maxDev	(	F32 *	maxDev,
		F64	homMat[3][3],
		point *	from,
		point *	to,
		I32	pointCount
	)

The function calculates the deviation of the homography to real data. All points at from are mapped and the euclidean distance to their counterpart at to is calculated. The maximum distance is returned.

Parameters

maxDev	maximum euclidean distance between homMat(from[i]) and to[i] at target space.
homMat	the homography calculated by vc_bestfit_homography_calculate_homMat().
from,to	pointer to corresponding point lists: from[i] corresponds to to[i].
pointCount	total point count in list.

See also: vc_bestfit_homography_map(), vc_bestfit_homography_calculate_homMat().

◆ vc_homography_derivate()

I32 vc_homography_derivate	(	F32 *	diffX_x,
		F32 *	diffX_y,
		F32 *	diffY_x,
		F32 *	diffY_y,
		F32 *	x,
		F32 *	y,
		I32	pointCnt,
		F64	homMat[3][3]
	)

The function calculates the derivate of the homography at a point given.

Parameters

diffX_x,diffX_y,diffY_x,diffY_y	pointer to corresponding partial derivatives at (x,y), set to NULL if not needed.
x,y	coordinate lists input.
pointCount	total point count in list.
homMat	homography to differentiate.

Return values

ERR_SINGULAR if divisor is zero.

See also: vc_bestfit_homography_map(), vc_bestfit_homography_calculate_homMat().

Best Approximations

Functions

Detailed Description

Function Documentation

◆ bestline()

◆ bestline_successive_fit()

◆ linear_regression()

◆ bestcircle()

◆ calculate_chisquare_for_circle()

◆ vc_centerpoint()

◆ vc_centerpoint_successive_fit()

◆ vc_successive_fit()

◆ vc_bestfit_poly1d1d_calculate_poly()

◆ vc_bestfit_poly1d1d_map()

◆ vc_bestfit_poly1d1d_calculate_maxDev()

◆ vc_bestfit_poly1d1d_calculate_chiSquare()

◆ vc_bestfit_poly2d1d_calculate_poly()

◆ vc_bestfit_poly2d1d_map()

◆ vc_bestfit_poly2d1d_calculate_maxDev()

◆ vc_bestfit_poly2d2d_calculate_poly()

◆ vc_bestfit_poly2d2d_map()

◆ vc_bestfit_poly2d2d_calculate_maxDev()

◆ vc_bestfit_poly2d2d_calculate_poly_errorband()

◆ vc_bestfit_homography_calculate_homMat()

◆ vc_bestfit_homography_map()

◆ vc_bestfit_homography_calculate_maxDev()

◆ vc_homography_derivate()