VLFeat - Documentation > C API

# VLFeat.org

Documentation> C API

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

Macros | Typedefs | Enumerations | Functions | Variables
mathop.h File Reference

Math operations (Mathematical operations) More...

`#include "generic.h"`
`#include <math.h>`
`#include <float.h>`

## Macros

#define | VL_E 2.718281828459045
| Euler constant.
#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) More...
#define | VL_EPSILON_D 2.220446049250313e-16
| IEEE double precision epsilon (math constant) More...
#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)

## Typedefs

typedef float(* | VlFloatVectorComparisonFunction )(vl_size dimension, float const *X, float const *Y)
| Pointer to a function to compare vectors of floats.
typedef double(* | VlDoubleVectorComparisonFunction )(vl_size dimension, double const *X, double const *Y)
| Pointer to a function to compare vectors of doubles.
typedef float(* | VlFloatVector3ComparisonFunction )(vl_size dimension, float const *X, float const *Y, float const *Z)
| Pointer to a function to compare 3 vectors of doubles.
typedef double(* | VlDoubleVector3ComparisonFunction )(vl_size dimension, double const *X, double const *Y, double const *Z)
| Pointer to a function to compare 3 vectors of doubles.
typedef enum _VlVectorComparisonType | VlVectorComparisonType
| Vector comparison types.

## Enumerations

enum | _VlVectorComparisonType { VlDistanceL1, VlDistanceL2, VlDistanceChi2, VlDistanceHellinger, VlDistanceJS, VlDistanceMahalanobis, VlKernelL1, VlKernelL2, VlKernelChi2, VlKernelHellinger, VlKernelJS }
| Vector comparison types. More...

## Functions

float | vl_mod_2pi_f (float x)
| Fast `mod(x, 2 * VL_PI)` More...
double | vl_mod_2pi_d (double x)
| Fast `mod(x, 2 * VL_PI)` More...
long int | vl_floor_f (float x)
| Floor and convert to integer. More...
long int | vl_floor_d (double x)
| Floor and convert to integer. More...
long int | vl_ceil_f (float x)
| Ceil and convert to integer. More...
long int | vl_ceil_d (double x)
| Ceil and convert to integer. More...
long int | vl_round_f (float x)
| Round. More...
long int | vl_round_d (double x)
| Round. More...
float | vl_abs_f (float x)
| Fast `abs(x)` More...
double | vl_abs_d (double x)
| Fast `abs(x)` More...
double | vl_log2_d (double x)
| Base-2 logaritghm. More...
float | vl_log2_f (float x)
| Base-2 logaritghm. More...
double | vl_sqrt_d (double x)
| Square root. More...
float | vl_sqrt_f (float x)
| Square root. More...
vl_bool | vl_is_nan_f (float x)
| Check whether a floating point value is NaN. More...
vl_bool | vl_is_nan_d (double x)
| Check whether a floating point value is NaN. More...
vl_bool | vl_is_inf_f (float x)
| Check whether a floating point value is infinity. More...
vl_bool | vl_is_inf_d (double x)
| Check whether a floating point value is infinity. More...
float | vl_fast_atan2_f (float y, float x)
| Fast `atan2` approximation. More...
double | vl_fast_atan2_d (double y, double x)
| Fast `atan2` approximation. More...
float | vl_fast_resqrt_f (float x)
| Fast `resqrt` approximation. More...
double | vl_fast_resqrt_d (double x)
| Fast `resqrt` approximation. More...
float | vl_fast_sqrt_f (float x)
| Fast `sqrt` approximation. More...
double | vl_fast_sqrt_d (float x)
| Fast `sqrt` approximation. More...
vl_uint64 | vl_fast_sqrt_ui64 (vl_uint64 x)
| Fast integer `sqrt` approximation. More...
vl_uint32 | vl_fast_sqrt_ui32 (vl_uint32 x)
| Fast `sqrt` approximation. More...
vl_uint16 | vl_fast_sqrt_ui16 (vl_uint16 x)
| Fast `sqrt` approximation. More...
vl_uint8 | vl_fast_sqrt_ui8 (vl_uint8 x)
| Fast `sqrt` approximation. More...
char const * | vl_get_vector_comparison_type_name (int type)
| Get the symbolic name of a vector comparison type. More...
VlFloatVectorComparisonFunction | vl_get_vector_comparison_function_f (VlVectorComparisonType type)
| Get vector comparison function from comparison type. More...
VlDoubleVectorComparisonFunction | vl_get_vector_comparison_function_d (VlVectorComparisonType type)
| Get vector comparison function from comparison type. More...
void | vl_eval_vector_comparison_on_all_pairs_f (float *result, vl_size dimension, float const *X, vl_size numDataX, float const *Y, vl_size numDataY, VlFloatVectorComparisonFunction function)
| Evaluate vector comparison function on all vector pairs. More...
void | vl_eval_vector_comparison_on_all_pairs_d (double *result, vl_size dimension, double const *X, vl_size numDataX, double const *Y, vl_size numDataY, VlDoubleVectorComparisonFunction function)
| Evaluate vector comparison function on all vector pairs. More...

## Variables

union {
} | vl_nan_f
| IEEE single precision quiet NaN constant. More...
union {
} | vl_infinity_f
| IEEE single precision infinity constant. More...
union {
} | vl_nan_d
| IEEE double precision quiet NaN constant. More...
union {
} | vl_infinity_d
| IEEE double precision infinity constant. More...

## Detailed Description

Author
  Andrea Vedaldi, David Novotny

## Macro Definition 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} \).

#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} \).

## Enumeration Type Documentation

enum _VlVectorComparisonType

Enumerator
VlDistanceL1 | l1 distance (squared intersection metric)
VlDistanceL2 | squared l2 distance
VlDistanceChi2 | squared Chi2 distance
VlDistanceHellinger | squared Hellinger's distance
VlDistanceJS | squared Jensen-Shannon distance
VlDistanceMahalanobis | squared mahalanobis distance
VlKernelL1 | intersection kernel
VlKernelL2 | l2 kernel
VlKernelChi2 | Chi2 kernel
VlKernelHellinger | Hellinger's kernel
VlKernelJS | Jensen-Shannon kernel

## Function Documentation

double vl_abs_d | ( | double | x | ) |

inline

See also
  vl_abs_f

float vl_abs_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  `abs(x)`

long int vl_ceil_d | ( | double | x | ) |

inline

See also
  vl_ceil_f

long int vl_ceil_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  `lceilf(x)`

vl_eval_vector_comparison_on_all_pairs_d | ( | double * | result,
|  | vl_size | dimension,
|  | double const * | X,
|  | vl_size | numDataX,
|  | double const * | Y,
|  | vl_size | numDataY,
|  | VlDoubleVectorComparisonFunction | function
| ) |  |

See also
  vl_eval_vector_comparison_on_all_pairs_f

vl_eval_vector_comparison_on_all_pairs_f | ( | float * | result,
|  | vl_size | dimension,
|  | float const * | X,
|  | vl_size | numDataX,
|  | float const * | Y,
|  | vl_size | numDataY,
|  | VlFloatVectorComparisonFunction | function
| ) |  |

Parameters

  result | comparison matrix (output).
  dimension | number of vector components (rows of X and Y).
  X | data matrix X.
  Y | data matrix Y.
  numDataX | number of vectors in X (columns of X)
  numDataY | number of vectros in Y (columns of Y)
  function | vector comparison function.

The function evaluates function on all pairs of columns from matrices X and Y, filling a numDataX by numDataY matrix.

If Y is a null pointer the function compares all columns from X with themselves.

double vl_fast_atan2_d | ( | double | y,
|  | double | x
| ) |  |

inline

See also
  vl_fast_atan2_f

float vl_fast_atan2_f | ( | float | y,
|  | float | x
| ) |  |

inline

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)`.

double vl_fast_resqrt_d | ( | double | x | ) |

inline

See also
  vl_fast_resqrt_d

float vl_fast_resqrt_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  approximation of `resqrt(x)`.

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)}{\frac{df(y)}{dy}} = 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.

double vl_fast_sqrt_d | ( | float | x | ) |

inline

Fast `sqrt` approximation.

Parameters

  x | argument.

Returns
  approximation of `sqrt(x)`.

The function uses vl_fast_resqrt_f (or vl_fast_resqrt_d) to compute `x * vl_fast_resqrt_f(x)`.

float vl_fast_sqrt_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  approximation of `sqrt(x)`.

The function uses vl_fast_resqrt_f (or vl_fast_resqrt_d) to compute `x * vl_fast_resqrt_f(x)`.

vl_uint16 vl_fast_sqrt_ui16 | ( | vl_uint16 | x | ) |

inline

Fast integer `sqrt` approximation.

Parameters

  x | non-negative integer.

Returns
  largest integer \(y\) such that \(y^2 \leq x\).

See also
  Algorithm

vl_uint32 vl_fast_sqrt_ui32 | ( | vl_uint32 | x | ) |

inline

Fast integer `sqrt` approximation.

Parameters

  x | non-negative integer.

Returns
  largest integer \(y\) such that \(y^2 \leq x\).

See also
  Algorithm

vl_uint64 vl_fast_sqrt_ui64 | ( | vl_uint64 | x | ) |

inline

Parameters

  x | non-negative integer.

Returns
  largest integer \(y\) such that \(y^2 \leq x\).

See also
  Algorithm

vl_uint8 vl_fast_sqrt_ui8 | ( | vl_uint8 | x | ) |

inline

Fast integer `sqrt` approximation.

Parameters

  x | non-negative integer.

Returns
  largest integer \(y\) such that \(y^2 \leq x\).

See also
  Algorithm

long int vl_floor_d | ( | double | x | ) |

inline

See also
  vl_floor_f

long int vl_floor_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  Similar to ``(int) floor(x)

vl_get_vector_comparison_function_d | ( | VlVectorComparisonType | type | ) |

See also
  vl_get_vector_comparison_function_f

vl_get_vector_comparison_function_f | ( | VlVectorComparisonType | type | ) |

Parameters

  type | vector comparison type.

Returns
  comparison function.

char const* vl_get_vector_comparison_type_name | ( | int | type | ) |

inline

Parameters

  type | vector comparison type.

Returns
  data symbolic name.

vl_bool vl_is_inf_d | ( | double | x | ) |

inline

Parameters

  x | argument.

Returns
  true if x is infinity.

vl_bool vl_is_inf_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  true if x is infinity.

vl_bool vl_is_nan_d | ( | double | x | ) |

inline

Parameters

  x | argument.

Returns
  true if x is NaN.

vl_bool vl_is_nan_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  true if x is NaN.

double vl_log2_d | ( | double | x | ) |

inline

Parameters

  x | argument.

Returns
  `log(x)`.

float vl_log2_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  `log(x)`.

double vl_mod_2pi_d | ( | double | x | ) |

inline

See also
  vl_mod_2pi_f

float vl_mod_2pi_f | ( | float | x | ) |

inline

Parameters

  x | input value.

Returns
  `mod(x, 2 * VL_PI)`

The function is optimized for small absolute values of x.

The result is guaranteed to be not 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).

long int vl_round_d | ( | double | x | ) |

inline

Parameters

  x | argument.

Returns
  `lround(x)` This function is either the same or similar to C99 `lround()`.

long int vl_round_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  `lroundf(x)` This function is either the same or similar to C99 `lroundf()`.

double vl_sqrt_d | ( | double | x | ) |

inline

Parameters

  x | argument.

Returns
  `sqrt(x)`.

float vl_sqrt_f | ( | float | x | ) |

inline

Parameters

  x | argument.

Returns
  `sqrt(x)`.

## Variable Documentation

union { ... } vl_infinity_d

Initial value:
=
{ 0x7FF0000000000000ui64 }

union { ... } vl_infinity_f

Initial value:
=
{ 0x7F800000UL }

union { ... } vl_nan_d

Initial value:
=
{ 0x7FF8000000000000ui64 }

union { ... } vl_nan_f

Initial value:
=
{ 0x7FC00000UL }