C API

mathop.h File Reference


Detailed Description

Author:
Andrea Vedaldi

Definition in file mathop.h.

#include "generic.h"

Go to the source code of this file.

ui16 VL_FAST_SQRT_UI (vl_uint8, ui8) float vl_dist_l2_f(float *dist
 Auto distances.

Defines

#define VL_LOG_OF_2   0.693147180559945
 Logarithm of 2 (math constant).
#define VL_PI   3.141592653589793
 Pi (math constant).
#define VL_EPSILON_F   1.19209290E-07F
 IEEE single precision epsilon (math constant).
#define VL_EPSILON_D   2.220446049250313e-16
 IEEE double precision epsilon (math constant).
#define VL_NAN_F   (vl_nan_f.value)
 IEEE single precision NaN (not signaling).
#define VL_INFINITY_F   (vl_infinity_f.value)
 IEEE single precision positive infinity (not signaling).
#define VL_NAN_D   (vl_nan_d.value)
 IEEE double precision NaN (not signaling).
#define VL_INFINITY_D   (vl_infinity_d.value)
 IEEE double precision positive infinity (not signaling).

Functions

VL_INLINE float vl_mod_2pi_f (float x)
 Fast mod(x, 2 * VL_PI).
VL_INLINE double vl_mod_2pi_d (double x)
 Fast mod(x, 2 * VL_PI).
VL_INLINE int vl_floor_f (float x)
 Fast (int) floor(x).
VL_INLINE int vl_floor_d (double x)
 Fast (int) floor(x).
VL_INLINE float vl_abs_f (float x)
 Fast abs(x).
VL_INLINE double vl_abs_d (double x)
 Fast abs(x).
VL_INLINE float vl_fast_atan2_f (float y, float x)
 Fast atan2 approximation.
VL_INLINE double vl_fast_atan2_d (double y, double x)
 Fast atan2 approximation.
VL_INLINE float vl_fast_resqrt_f (float x)
 Fast resqrt approximation.
VL_INLINE double vl_fast_resqrt_d (double x)
 Fast resqrt approximation.
VL_INLINE float vl_fast_sqrt_f (float x)
 Fast sqrt approximation.
VL_INLINE double vl_fast_sqrt_d (float x)
 Fast sqrt approximation.
VL_INLINE vl_uint32 vl_fast_sqrt_ui32 (vl_uint32 x)
 Fast sqrt approximation.
VL_INLINE vl_uint16 vl_fast_sqrt_ui16 (vl_uint16 x)
 Fast sqrt approximation.
VL_INLINE vl_uint8 vl_fast_sqrt_ui8 (vl_uint8 x)
 Fast sqrt approximation.

Define Documentation

#define VL_EPSILON_D   2.220446049250313e-16

1.0 + VL_EPSILON_D is the smallest representable double precision number greater than 1.0. Numerically, VL_EPSILON_D is equal to $ 2^{-52} $.

Definition at line 39 of file mathop.h.

Referenced by vl_fast_atan2_d(), and vl_sift_calc_raw_descriptor().

#define VL_EPSILON_F   1.19209290E-07F

1.0F + VL_EPSILON_F is the smallest representable single precision number greater than 1.0F. Numerically, VL_EPSILON_F is equal to $ 2^{-23} $.

Definition at line 31 of file mathop.h.

Referenced by _vl_dsift_normalize_histogram(), normalize_histogram(), vl_fast_atan2_f(), and vl_pgm_write_f().


Function Documentation

VL_INLINE double vl_abs_d ( double  x  ) 

Parameters:
x argument.
Returns:
abs(x)

Definition at line 162 of file mathop.h.

Referenced by vl_fast_atan2_d(), and vl_sift_detect().

VL_INLINE float vl_abs_f ( float  x  ) 

Parameters:
x argument.
Returns:
abs(x)

Definition at line 155 of file mathop.h.

Referenced by vl_fast_atan2_f(), vl_sift_calc_keypoint_descriptor(), and vl_sift_calc_raw_descriptor().

VL_INLINE double vl_fast_atan2_d ( double  y,
double  x 
)

Parameters:
y argument.
x argument.
The function computes a relatively rough but fast approximation of atan2(y,x).

Algorithm
The algorithm approximates the function $ f(r)=atan((1-r)/(1+r)) $, $ r \in [-1,1] $ with a third order polynomial $ f(r)=c_0 + c_1 r + c_2 r^2 + c_3 r^3 $. To fit the polynomial we impose the constraints

\begin{eqnarray*} f(+1) &=& c_0 + c_1 + c_2 + c_3 = atan(0) = 0,\\ f(-1) &=& c_0 - c_1 + c_2 - c_3 = atan(\infty) = \pi/2,\\ f(0) &=& c_0 = atan(1) = \pi/4. \end{eqnarray*}

The last degree of freedom is fixed by minimizing the $ l^{\infty} $ error, which yields

\[ c_0=\pi/4, \quad c_1=-0.9675, \quad c_2=0, \quad c_3=0.1821, \]

with maximum error of 0.0061 radians at 0.35 degrees.

Returns:
Approximation of atan2(y,x).

Definition at line 227 of file mathop.h.

References vl_abs_d(), VL_EPSILON_D, and VL_PI.

VL_INLINE float vl_fast_atan2_f ( float  y,
float  x 
)

Parameters:
y argument.
x argument.
The function computes a relatively rough but fast approximation of atan2(y,x).

Algorithm
The algorithm approximates the function $ f(r)=atan((1-r)/(1+r)) $, $ r \in [-1,1] $ with a third order polynomial $ f(r)=c_0 + c_1 r + c_2 r^2 + c_3 r^3 $. To fit the polynomial we impose the constraints

\begin{eqnarray*} f(+1) &=& c_0 + c_1 + c_2 + c_3 = atan(0) = 0,\\ f(-1) &=& c_0 - c_1 + c_2 - c_3 = atan(\infty) = \pi/2,\\ f(0) &=& c_0 = atan(1) = \pi/4. \end{eqnarray*}

The last degree of freedom is fixed by minimizing the $ l^{\infty} $ error, which yields

\[ c_0=\pi/4, \quad c_1=-0.9675, \quad c_2=0, \quad c_3=0.1821, \]

with maximum error of 0.0061 radians at 0.35 degrees.

Returns:
Approximation of atan2(y,x).

Definition at line 207 of file mathop.h.

References vl_abs_f(), VL_EPSILON_F, and VL_PI.

Referenced by vl_dsift_process().

VL_INLINE double vl_fast_resqrt_d ( double  x  ) 

Parameters:
x argument.
The function quickly computes an approximation of $ x^{-1/2} $.

Algorithm
The goal is to compute $ y = x^{-1/2} $, which we do by finding the solution of $ 0 = f(y) = y^{-2} - x$ by two Newton steps. Each Newton iteration is given by

\[ y \leftarrow y - \frac{f(y)}{\dot f(y)} = y + \frac{1}{2} (y-xy^3) = \frac{y}{2} \left( 3 - xy^2 \right) \]

which yields a simple polynomial update rule.

The clever bit (attributed to either J. Carmack or G. Tarolli) is the way an initial guess $ y \approx x^{-1/2} $ is chosen.

See also:
Inverse Sqare Root.
Returns:
Approximation of resqrt(x).

Definition at line 304 of file mathop.h.

Referenced by vl_fast_sqrt_d().

VL_INLINE float vl_fast_resqrt_f ( float  x  ) 

Parameters:
x argument.
The function quickly computes an approximation of $ x^{-1/2} $.

Algorithm
The goal is to compute $ y = x^{-1/2} $, which we do by finding the solution of $ 0 = f(y) = y^{-2} - x$ by two Newton steps. Each Newton iteration is given by

\[ y \leftarrow y - \frac{f(y)}{\dot f(y)} = y + \frac{1}{2} (y-xy^3) = \frac{y}{2} \left( 3 - xy^2 \right) \]

which yields a simple polynomial update rule.

The clever bit (attributed to either J. Carmack or G. Tarolli) is the way an initial guess $ y \approx x^{-1/2} $ is chosen.

See also:
Inverse Sqare Root.
Returns:
Approximation of resqrt(x).

Definition at line 279 of file mathop.h.

Referenced by vl_fast_sqrt_f().

VL_INLINE double vl_fast_sqrt_d ( float  x  ) 

Parameters:
x argument.
The function computes a fast approximation of sqrt(x).

Floating-point algorithm
For the floating point cases, the function uses vl_fast_resqrt_f (or vl_fast_resqrt_d) to compute x * vl_fast_resqrt_f(x).

Integer algorithm
We seek for the largest integer y such that $ y^2 \leq x $. Write $ y = w + b_k 2^k + z $ where the binary expansion of the various variable is

\[ x = \sum_{i=0}^{n-1} 2^i a_i, \qquad w = \sum_{i=k+1}^{m-1} 2^i b_i, \qquad z = \sum_{i=0}^{k-1} 2^i b_i. \]

Assume w known. Expanding the square and using the fact that $ b_k^2=b_k $, we obtain the following constraint for $ b_k $ and z:

\[ x - w^2 \geq 2^k ( 2 w + 2^k ) b_k + z (z + 2wz + 2^{k+1}z b_k) \]

A necessary condition for $ b_k = 1 $ is that this equation is satisfied for $ z = 0 $ (as the second term is always non-negative). In fact, this condition is also sufficient, since we are looking for the largest solution y.

This yields the following iterative algorithm. First, note that if x is stored in n bits, where n is even, then the integer square root does not require more than $ m = n / 2 $ bit to be stored. Thus initially, $ w = 0 $ and $ k = m - 1 = n/2 - 1 $. Then, at each iteration the equation is tested, determining $ b_{m-1}, b_{m-2}, ... $ in this order.

Returns:
Approximation of sqrt(x).

Definition at line 389 of file mathop.h.

References vl_fast_resqrt_d().

VL_INLINE float vl_fast_sqrt_f ( float  x  ) 

Parameters:
x argument.
The function computes a fast approximation of sqrt(x).

Floating-point algorithm
For the floating point cases, the function uses vl_fast_resqrt_f (or vl_fast_resqrt_d) to compute x * vl_fast_resqrt_f(x).

Integer algorithm
We seek for the largest integer y such that $ y^2 \leq x $. Write $ y = w + b_k 2^k + z $ where the binary expansion of the various variable is

\[ x = \sum_{i=0}^{n-1} 2^i a_i, \qquad w = \sum_{i=k+1}^{m-1} 2^i b_i, \qquad z = \sum_{i=0}^{k-1} 2^i b_i. \]

Assume w known. Expanding the square and using the fact that $ b_k^2=b_k $, we obtain the following constraint for $ b_k $ and z:

\[ x - w^2 \geq 2^k ( 2 w + 2^k ) b_k + z (z + 2wz + 2^{k+1}z b_k) \]

A necessary condition for $ b_k = 1 $ is that this equation is satisfied for $ z = 0 $ (as the second term is always non-negative). In fact, this condition is also sufficient, since we are looking for the largest solution y.

This yields the following iterative algorithm. First, note that if x is stored in n bits, where n is even, then the integer square root does not require more than $ m = n / 2 $ bit to be stored. Thus initially, $ w = 0 $ and $ k = m - 1 = n/2 - 1 $. Then, at each iteration the equation is tested, determining $ b_{m-1}, b_{m-2}, ... $ in this order.

Returns:
Approximation of sqrt(x).

Definition at line 382 of file mathop.h.

References vl_fast_resqrt_f().

Referenced by _vl_dsift_normalize_histogram(), normalize_histogram(), and vl_dsift_process().

ui16 VL_FAST_SQRT_UI ( vl_uint8  ,
ui8   
)

Parameters:
dist pointer to the distance matrix (out).
M number of dimensions
NX number of data points in X.
NY number of data points in Y.
X first data set.
Y second data set.

VL_INLINE vl_uint16 vl_fast_sqrt_ui16 ( vl_uint16  x  ) 

Parameters:
x argument.
The function computes a fast approximation of sqrt(x).

Floating-point algorithm
For the floating point cases, the function uses vl_fast_resqrt_f (or vl_fast_resqrt_d) to compute x * vl_fast_resqrt_f(x).

Integer algorithm
We seek for the largest integer y such that $ y^2 \leq x $. Write $ y = w + b_k 2^k + z $ where the binary expansion of the various variable is

\[ x = \sum_{i=0}^{n-1} 2^i a_i, \qquad w = \sum_{i=k+1}^{m-1} 2^i b_i, \qquad z = \sum_{i=0}^{k-1} 2^i b_i. \]

Assume w known. Expanding the square and using the fact that $ b_k^2=b_k $, we obtain the following constraint for $ b_k $ and z:

\[ x - w^2 \geq 2^k ( 2 w + 2^k ) b_k + z (z + 2wz + 2^{k+1}z b_k) \]

A necessary condition for $ b_k = 1 $ is that this equation is satisfied for $ z = 0 $ (as the second term is always non-negative). In fact, this condition is also sufficient, since we are looking for the largest solution y.

This yields the following iterative algorithm. First, note that if x is stored in n bits, where n is even, then the integer square root does not require more than $ m = n / 2 $ bit to be stored. Thus initially, $ w = 0 $ and $ k = m - 1 = n/2 - 1 $. Then, at each iteration the equation is tested, determining $ b_{m-1}, b_{m-2}, ... $ in this order.

Returns:
Approximation of sqrt(x).

VL_INLINE vl_uint32 vl_fast_sqrt_ui32 ( vl_uint32  x  ) 

Parameters:
x argument.
The function computes a fast approximation of sqrt(x).

Floating-point algorithm
For the floating point cases, the function uses vl_fast_resqrt_f (or vl_fast_resqrt_d) to compute x * vl_fast_resqrt_f(x).

Integer algorithm
We seek for the largest integer y such that $ y^2 \leq x $. Write $ y = w + b_k 2^k + z $ where the binary expansion of the various variable is

\[ x = \sum_{i=0}^{n-1} 2^i a_i, \qquad w = \sum_{i=k+1}^{m-1} 2^i b_i, \qquad z = \sum_{i=0}^{k-1} 2^i b_i. \]

Assume w known. Expanding the square and using the fact that $ b_k^2=b_k $, we obtain the following constraint for $ b_k $ and z:

\[ x - w^2 \geq 2^k ( 2 w + 2^k ) b_k + z (z + 2wz + 2^{k+1}z b_k) \]

A necessary condition for $ b_k = 1 $ is that this equation is satisfied for $ z = 0 $ (as the second term is always non-negative). In fact, this condition is also sufficient, since we are looking for the largest solution y.

This yields the following iterative algorithm. First, note that if x is stored in n bits, where n is even, then the integer square root does not require more than $ m = n / 2 $ bit to be stored. Thus initially, $ w = 0 $ and $ k = m - 1 = n/2 - 1 $. Then, at each iteration the equation is tested, determining $ b_{m-1}, b_{m-2}, ... $ in this order.

Returns:
Approximation of sqrt(x).

VL_INLINE vl_uint8 vl_fast_sqrt_ui8 ( vl_uint8  x  ) 

Parameters:
x argument.
The function computes a fast approximation of sqrt(x).

Floating-point algorithm
For the floating point cases, the function uses vl_fast_resqrt_f (or vl_fast_resqrt_d) to compute x * vl_fast_resqrt_f(x).

Integer algorithm
We seek for the largest integer y such that $ y^2 \leq x $. Write $ y = w + b_k 2^k + z $ where the binary expansion of the various variable is

\[ x = \sum_{i=0}^{n-1} 2^i a_i, \qquad w = \sum_{i=k+1}^{m-1} 2^i b_i, \qquad z = \sum_{i=0}^{k-1} 2^i b_i. \]

Assume w known. Expanding the square and using the fact that $ b_k^2=b_k $, we obtain the following constraint for $ b_k $ and z:

\[ x - w^2 \geq 2^k ( 2 w + 2^k ) b_k + z (z + 2wz + 2^{k+1}z b_k) \]

A necessary condition for $ b_k = 1 $ is that this equation is satisfied for $ z = 0 $ (as the second term is always non-negative). In fact, this condition is also sufficient, since we are looking for the largest solution y.

This yields the following iterative algorithm. First, note that if x is stored in n bits, where n is even, then the integer square root does not require more than $ m = n / 2 $ bit to be stored. Thus initially, $ w = 0 $ and $ k = m - 1 = n/2 - 1 $. Then, at each iteration the equation is tested, determining $ b_{m-1}, b_{m-2}, ... $ in this order.

Returns:
Approximation of sqrt(x).

VL_INLINE int vl_floor_d ( double  x  ) 

Parameters:
x argument.
Returns:
(int) floor(x)

Definition at line 138 of file mathop.h.

Referenced by fast_expn(), vl_sift_calc_keypoint_orientations(), and vl_sift_keypoint_init().

VL_INLINE int vl_floor_f ( float  x  ) 

Parameters:
x argument.
Returns:
(int) floor(x)

Definition at line 129 of file mathop.h.

Referenced by vl_dsift_process(), vl_sift_calc_keypoint_descriptor(), and vl_sift_calc_raw_descriptor().

VL_INLINE double vl_mod_2pi_d ( double  x  ) 

Parameters:
x input value.
The function is optimized for small absolute values of x.

The result is guaranteed not to be smaller than 0. However, due to finite numerical precision and rounding errors, the result can be equal to 2 * VL_PI (for instance, if x is a very small negative number).

Returns:
mod(x, 2 * VL_PI)

Definition at line 112 of file mathop.h.

References VL_PI.

VL_INLINE float vl_mod_2pi_f ( float  x  ) 

Parameters:
x input value.
The function is optimized for small absolute values of x.

The result is guaranteed not to be smaller than 0. However, due to finite numerical precision and rounding errors, the result can be equal to 2 * VL_PI (for instance, if x is a very small negative number).

Returns:
mod(x, 2 * VL_PI)

Definition at line 104 of file mathop.h.

References VL_PI.

Referenced by vl_dsift_process(), vl_sift_calc_keypoint_descriptor(), and vl_sift_calc_raw_descriptor().