Top | ![]() |
![]() |
![]() |
![]() |
Function gwy_math_humanize_numbers()
deals with number representation.
Nearest object finding functions gwy_math_find_nearest_line()
and gwy_math_find_nearest_point()
can be useful in
widget and vector layer implementation.
And gwy_math_lin_solve()
, gwy_math_lin_solve_rewrite()
, and gwy_math_fit_polynom()
are general purpose numeric
methods.
#define GWY_ROUND(x) ((gint)floor((x) + 0.5))
Rounds a floating point number to nearest integer.
#define gwy_round(x) ((gint)floor((x) + 0.5))
Rounds a floating point number to nearest integer.
#define gwy_clamp(x, lower, upper) fmin(fmax((x), (lower)), (upper))
Clamps a floating point number to an interval.
The behaviour is undefined if lower
is larger than upper
.
The macro uses fmax()
and fmin()
and evaluates its arguments only once.
gdouble gwy_math_humanize_numbers (gdouble unit
,gdouble maximum
,gint *precision
);
Finds a human-friendly representation for a range of numbers.
gboolean gwy_math_is_in_polygon (gdouble x
,gdouble y
,const gdouble *poly
,guint n
);
Establishes wether the test point x
, y
is inside the polygon poly
. The polygon can be defined either clockwise
or anti-clockwise and can be a concave, convex or self-intersecting polygon.
gint gwy_math_find_nearest_line (gdouble x
,gdouble y
,gdouble *d2min
,gint n
,const gdouble *coords
,const gdouble *metric
);
Finds the line nearest to the given point.
x |
X-coordinate of the point. |
|
y |
Y-coordinate of the point. |
|
d2min |
Where to store the squared minimal distance, or |
|
n |
The number of lines (i.e. |
|
coords |
Line coordinates stored as x00, y00, x01, y01, x10, y10, etc. |
|
metric |
Metric matrix (2x2, but stored sequentially by rows: m11, m12, m21, m22), it must be positive definite.
Vector norm is then calculated as m11*x*x + (m12 + m21)*x*y + m22*y*y. It can be |
gint gwy_math_find_nearest_point (gdouble x
,gdouble y
,gdouble *d2min
,gint n
,const gdouble *coords
,const gdouble *metric
);
Finds the point nearest to the given point.
x |
X-coordinate of the point. |
|
y |
Y-coordinate of the point. |
|
d2min |
Location to store the squared minimal distance to, or |
|
n |
The number of points (i.e. |
|
coords |
Point coordinates stored as x0, y0, x1, y1, x2, y2, etc. |
|
metric |
Metric matrix (2x2, but stored sequentially by rows: m11, m12, m21, m22). Vector norm is then calculated
as m11*x*x + (m12 + m21)*x*y + m22*y*y. It can be |
gint gwy_math_find_nearest_corner (gdouble x
,gdouble y
,gdouble *d2min
,gint n
,const gdouble *coords
,const gdouble *metric
);
Finds the rectangle corner nearest to the given point.
The rectangles are given as non-redundant coordinates, i.e. only four numbers per rectangle. If you already have
all the 4×2 coordinates per rectangle use gwy_math_find_nearest_point()
instead.
The quadruples of points are interpreted as pairs of opposite rectangle corners. They are the 0th and 2nd corners
of the rectangle. The 1st point has coordinates (x0
, y1
) and the 3rd has coordinates (x1
, y0
). Meaning we move
away from a given corner by keeping x
and changing y
, and towards a given corner by keeping y
and changing x
.
x |
X-coordinate of the point. |
|
y |
Y-coordinate of the point. |
|
d2min |
Location to store the squared minimal distance to, or |
|
n |
The number of rectangles (i.e. |
|
coords |
Corner coordinates stored as x00, y00, x01, y01, x10, y10, etc. |
|
metric |
Metric matrix (2x2, but stored sequentially by rows: m11, m12, m21, m22). Vector norm is then calculated
as m11*x*x + (m12 + m21)*x*y + m22*y*y. It can be |
gint gwy_math_cut_line_by_rectangle (gdouble x
,gdouble y
,gdouble vx
,gdouble vy
,const gdouble *rect
,gdouble *t
);
Finds the closest intersection of a half-line with a rectangle side.
The intersection time is such that (x
+ t
×vx
, y
+ t
×vy
) lies on a side of the rectangle. If the point is
inside the rectangle, there is always exactly one intersection provided (vx
, vy
) is non-zero. If the point is
outside, there may be multiple intersections. The closest one corresponds to the line entering the rectangle and
the corresponding t
is computed. There may not be any intersections, for instance when the half-line is pointed
away from the rectangle.
The side numbering corresponds to rect
. Each rectangle side has exactly one coordinate constant and equal to x₁,
y₁, x₂ or y₂. So the corresponding index in rect
is returned.
x |
X-coordinate of the point. |
|
y |
Y-coordinate of the point. |
|
vx |
X-component of the line vector. |
|
vy |
Y-component of the line vector. |
|
rect |
Quadruple of points (x₁, y₁, x₂, y₂) defining two opposite corners of the rectangle. |
|
t |
Location where to store the intersection time. If the function return a negative value the intersection time is not set. |
gdouble * gwy_math_lin_solve (gint n
,const gdouble *matrix
,const gdouble *rhs
,gdouble *result
);
Solve a regular system of linear equations.
gdouble * gwy_math_lin_solve_rewrite (gint n
,gdouble *matrix
,gdouble *rhs
,gdouble *result
);
Solves a regular system of linear equations.
This is a memory-conservative version of gwy_math_lin_solve()
overwriting matrix
and rhs
with intermediate
results.
gboolean gwy_math_tridiag_solve_rewrite (gint n
,gdouble *d
,const gdouble *a
,const gdouble *b
,gdouble *rhs
);
Solves a tridiagonal system of linear equations.
gdouble * gwy_math_fit_polynom (gint ndata
,const gdouble *xdata
,const gdouble *ydata
,gint n
,gdouble *coeffs
);
Fits a polynomial through a general (x, y) data set.
gboolean gwy_math_choleski_decompose (gint n
,gdouble *matrix
);
Decomposes a symmetric positive definite matrix in place.
void gwy_math_choleski_solve (gint n
,const gdouble *decomp
,gdouble *rhs
);
Solves a system of linear equations with predecomposed symmetric positive definite matrix a
and right hand side
b
.
n |
The dimension of |
|
decomp |
Lower triangular part of Choleski decomposition as computed by |
|
rhs |
Right hand side vector. Is is modified in place, on return it contains the solution. |
gboolean gwy_math_choleski_invert (gint n
,gdouble *matrix
);
Inverts a symmetric positive definite matrix in place.
guint gwy_math_curvature (const gdouble *coeffs
,gdouble *kappa1
,gdouble *kappa2
,gdouble *phi1
,gdouble *phi2
,gdouble *xc
,gdouble *yc
,gdouble *zc
);
Calculates curvature parameters at the apex from two-dimensional quadratic polynomial coefficients.
This is an old name for gwy_math_curvature_at_apex()
. See the description there.
coeffs |
Array of the six polynomial coefficients of a quadratic surface in the following order: 1, x, y, x², xy, y². |
|
kappa1 |
Location to store the smaller curvature to. |
|
kappa2 |
Location to store the larger curvature to. |
|
phi1 |
Location to store the direction of the smaller curvature to. |
|
phi2 |
Location to store the direction of the larger curvature to. |
|
xc |
Location to store x-coordinate of the centre of the quadratic surface. |
|
yc |
Location to store y-coordinate of the centre of the quadratic surface. |
|
zc |
Location to store value at the centre of the quadratic surface. |
guint gwy_math_curvature_at_apex (const gdouble *coeffs
,gdouble *kappa1
,gdouble *kappa2
,gdouble *phi1
,gdouble *phi2
,gdouble *xc
,gdouble *yc
,gdouble *zc
);
Calculates curvature parameters at the apex from two-dimensional quadratic polynomial coefficients.
See also gwy_math_curvature_at_origin()
which computes the local surface curvature at x
=0 and y
=0.
If the quadratic surface was obtained by fitting the dimensions of the fitted area should not differ, in the lateral coordinates used, by many orders from 1. Otherwise the recognition of flat surfaces might not work.
Curvatures have signs, positive mean a concave (cup-like) surface, negative mean a convex (cap-like) surface. They are ordered including the sign.
Directions are angles from the interval (-π/2, π/2].
If the quadratic surface is degenerate, i.e. flat in at least one direction, the centre is undefined. The centre is then chosen as the closest point the origin of coordinates. For flat surfaces this means the origin is simply returned as the centre position. Consequently, you should use Cartesian coordinates with origin in a natural centre, for instance centre of image or grain.
coeffs |
Array of the six polynomial coefficients of a quadratic surface in the following order: 1, x, y, x², xy, y². |
|
kappa1 |
Location to store the smaller curvature to. |
|
kappa2 |
Location to store the larger curvature to. |
|
phi1 |
Location to store the direction of the smaller curvature to. |
|
phi2 |
Location to store the direction of the larger curvature to. |
|
xc |
Location to store x-coordinate of the centre of the quadratic surface. |
|
yc |
Location to store y-coordinate of the centre of the quadratic surface. |
|
zc |
Location to store value at the centre of the quadratic surface. |
guint gwy_math_curvature_at_origin (const gdouble *coeffs
,gdouble *kappa1
,gdouble *kappa2
,gdouble *phi1
,gdouble *phi2
);
Calculates curvature parameters at origin from two-dimensional quadratic polynomial coefficients.
See gwy_math_curvature()
for discussion of scaling and sign convenrions. This function function differs from it
by computing the local surface curvature at x
=0 and y
=0, whereas gwy_math_curvature()
computes the curvature at
the apex of the parabolic surface.
The array coeffs
is consistent with gwy_math_curvature_at_apex()
, even though here the constant term is not used.
coeffs |
Array of the six polynomial coefficients of a quadratic surface in the following order: 1, x, y, x², xy, y². |
|
kappa1 |
Location to store the smaller curvature to. |
|
kappa2 |
Location to store the larger curvature to. |
|
phi1 |
Location to store the direction of the smaller curvature to. |
|
phi2 |
Location to store the direction of the larger curvature to. |
gboolean gwy_math_refine_maximum_1d (const gdouble *y
,gdouble *x
);
Performs subpixel refinement of parabolic a one-dimensional maximum.
The central value corresponds to x-coordinate 0, distances between values are unity. The refinement is based by
fitting a parabola through the maximum. If it fails or the calculated maximum lies farther than the surrounding
values the function sets the refined maximum to the origin and returns FALSE
.
gboolean gwy_math_refine_maximum_2d (const gdouble *z
,gdouble *x
,gdouble *y
);
Performs subpixel refinement of parabolic a two-dimensional maximum.
The central value corresponds to coordinates (0,0), distances between values are unity. The refinement is based by
fitting a two-dimensional parabola through the maximum. If it fails or the calculated maximum lies farther than
the surrounding values the function sets the refined maximum to the origin and returns FALSE
.
gboolean gwy_math_refine_maximum (const gdouble *z
,gdouble *x
,gdouble *y
);
Performs subpixel refinement of parabolic a two-dimensional maximum.
An alias for gwy_math_refine_maximum_2d()
.
gdouble gwy_math_find_minimum_1d (GwyRealFunc function
,gdouble a
,gdouble b
,gpointer user_data
);
Finds a minimum of a real function in a finite interval.
The function simply does what it says on the tin. If there are multiple minima in [a,b] any of them can be returned, even though some effort to scan the interval is made. There is no requiement for the minimum to lie inside [a,b]; if it occurrs at one of the endpoints, the endpoint is returned.
guint * gwy_check_regular_2d_grid (const gdouble *coords
,guint stride
,guint n
,gdouble tolerance
,guint *xres
,guint *yres
,GwyXY *xymin
,GwyXY *xystep
);
Detects if points in plane form a regular rectangular grid oriented along the Cartesian axes.
Points lying in one straight line are not considered to form a rectangle.
When the function fails, i.e. the points do not form a regular grid, the values of output arguments are undefined.
See also gwy_check_regular_2d_lattice()
which is more lenient.
coords |
Array of |
|
stride |
Actual number of double values in one block. It must be at least 2 if |
|
n |
Number of items in |
|
tolerance |
Relative distance from pixel center which is still considered OK. Pass a negative value for some reasonable default. The maximum meaningful value is 0.5, beyond that the point would end up in a different pixel. |
|
xres |
Location where to store the number of columns. |
|
yres |
Location where to store the number of rows. |
|
xymin |
Location where to store the minimum coordinates (top left corner of the corresponding image). |
|
xystep |
Location where to store the pixel size. |
guint * gwy_check_regular_2d_lattice (const gdouble *coords
,guint stride
,guint n
,guint *xres
,guint *yres
,GwyXY *xymin
,GwyXY *vx
,GwyXY *vy
,gdouble *maxdiff
);
Detects if points in plane form more or less a regular lattice.
At present points lying in one straight line are not considered to form a lattice and neither are points sets with duplicate points (corresponding to the same lattice point).
Any rotation in the plane, a moderate amount of missing points, moderate skew and moderate deviations from the
exact lattice positions should not prevent lattice detection. Large defects may, and so may large differences
between lattice step sizes. The function prefers basis vectors vx
and vy
in which the point set resembles
a rectangle. When the goal is to render the data to an image this is normally the desired behaviour. However, for
an odd overal shape of the point set the result may not be useful.
The caller can check for holes in the lattice by comparing returned xres
×yres
with n
, for skew by evaluating the
angle between vx
and vy
and for deviations by inspecting maxdiff
.
When the function fails, i.e. return NULL
, the values of output arguments are undefined.
See also gwy_check_regular_2d_grid()
which is faster for simple complete Cartesian grids and may work better for
them if the steps in x
and y
differ a lot.
coords |
Array of |
|
stride |
Actual number of double values in one block. It must be at least 2 if |
|
n |
Number of items in |
|
xres |
Location where to store the number of columns. |
|
yres |
Location where to store the number of rows. |
|
xymin |
Location where to store the minimum coordinates (top left corner of the corresponding image). |
|
vx |
Location where to store the pixel step vector along |
|
vy |
Location where to store the pixel step vector along |
|
maxdiff |
Location where to store the maximum difference of a point from exact lattice location, or |
void gwy_accumulate_counts (guint *array
,gint n
,gboolean do_rewind
);
Transforms counts in histogram bins to cumulative counts.
Each element of the array becomes the sum of previous elements, possibly plus itself. The behaviour depends on
do_rewind
.
If do_rewind
is FALSE
each elements becomes the sum of all previous elements plus itself. The function only works
with n
elements of array
. The array [3, 1, 5, 2] with n
=4 is transformed to [3, 4, 9, 11].
Often, this function is used for transforming block sizes to indices where a block starts. In such case pass TRUE
and array
must have n
+1 elements because the items are effectively shifted right by one. The first element becomes
zero and the (n
+1)-th one becomes the sum of all elements up to n
-1. The array [3, 1, 5, 2, ?] with n
=4 becomes
[0, 3, 4, 9, 11]. The value marked ? is not read, but is overwritten.
gdouble * gwy_math_linspace (gdouble *array
,gint n
,gdouble first
,gdouble step
);
Fills an array with a arithmetic progression of numbers.
Element i
is set to first
+ i
*step
.
Note that the arguments differ from the similar numpy function.
gdouble gwy_math_median (gsize n
,gdouble *array
);
Finds median of an array of values using Quick select algorithm.
See gwy_math_kth_rank()
for details of how the values are shuffled.
gdouble gwy_math_kth_rank (gsize n
,gdouble *array
,gsize k
);
Finds k-th item of an array of values using Quick select algorithm.
The value positions change as follows. The returned value is guaranteed to be at k
-th position in the array (i.e.
correctly ranked). All other values are correctly ordered with respect to this value: preceeding values are
smaller (or equal) and following values are larger (or equal).
void gwy_math_kth_ranks (gsize n
,gdouble *array
,guint nk
,const guint *k
,gdouble *values
);
Finds simultaneously several k-th items of an array of values.
The values are shuffled similarly to gwy_math_kth_rank()
, except that the guarantee holds for all given ranks
simultaneously. All values with explicitly requested ranks are at their correct positions and all values lying
between them in the array are also between them numerically.
void gwy_math_percentiles (gsize n
,gdouble *array
,GwyPercentileInterpolationType interp
,guint np
,const gdouble *p
,gdouble *values
);
Finds simultaneously several percentiles of an array of values.
The values in array
are shuffled similarly to gwy_math_kth_ranks()
. However, it is difficult to state how exactly
p
translates to the values that become correctly ranked (and it depends on interp
). Hence you can only assume
the set of values is preserved.
n |
Number of items in |
|
array |
Array of doubles. It is shuffled by this function. |
|
interp |
Interpolation method to use for percentiles that do not correspond exactly to an integer rank. |
|
np |
Number of percentiles to find. |
|
p |
Array of size |
|
values |
Array where to store values with percentiles given in |
void gwy_math_sort (gsize n
,gdouble *array
);
Sorts an array of doubles using a quicksort algorithm.
This is usually about twice as fast as the generic quicksort function thanks to specialization for doubles.
void gwy_guint_sort (gsize n
,guint *array
);
Sorts an array of unsigned integers using a quicksort algorithm.
This is usually about twice as fast as the generic quicksort function thanks to specialization for integers.
void gwy_math_sort_with_index (gsize n
,gdouble *array
,guint *index_array
);
Sorts an array of doubles using a quicksort algorithm, remembering the permutation.
The simplest and probably most common use of index_array
is to fill it with numbers 0 to n
-1 before calling
gwy_math_sort()
. After sorting, index_array
[i
] then contains the original position of the i
-th item of the
sorted array.
gdouble gwy_math_trimmed_mean (gsize n
,gdouble *array
,guint nlowest
,guint nhighest
);
Finds trimmed mean of an array of values.
At least one value must remain after the trimming, i.e. nlowest
+ nhighest
must be smaller than n
. Usually one
passes the same number as both nlowest
and nhighest
, but it is not a requirement.
The function can be also used to calculate normal mean values as it implements efficiently the cases when no trimming is done at either end.
gint gwy_compare_double (gconstpointer a
,gconstpointer b
);
Compares two double values, given as pointers.
This function is suitable as GCompareFunc and can be also used with plain qsort()
. The typical usage is sorting
of arrays containing structs where the first item is a floating point value/coordinate, followed by additional
data. For sorting of plain arrays of doubles use gwy_math_sort()
.
It should only be used to sort normal numbers. The behaviour for NaNs is undefined.
gdouble
gwy_xlnx_int (guint x
);
Calculates natural logarithm multiplied by the argument for integers.
The value for zero x
is taken as the limit, i.e. zero.
This function is useful for entropy calculations where values of n
*log(n
) can be evaulated a lot for small n
.
Therefore, values for small arguments are tabulated. For large arguments the function is evaluated using the
standard log()
function which is of course slower.
gdouble
gwy_sinc (gdouble x
);
Calculates the sinc function.
The sinc function is equal to sin(x
)/x
for non-zero x
, and defined to the limit 1 for zero x
.
gdouble gwy_canonicalize_angle (gdouble phi
,gboolean positive
,gboolean oriented
);
Canonicalizes an angle to requested interval.
For positive
=FALSE
, oriented
=FALSE
the output interval is [-π/2,π/2].
For positive
=FALSE
, oriented
=TRUE
the output interval is [-π,π].
For positive
=TRUE
, oriented
=FALSE
the output interval is [0,π).
For positive
=TRUE
, oriented
=TRUE
the output interval is [0,2π).
guint gwy_math_histogram (const gdouble *values
,guint n
,gdouble min
,gdouble max
,guint nbins
,guint *counts
);
Counts the numbers of values falling into equal-sized bins.
The value of min
must not be larger than max
. The values may lie outside [min
,max
]. They are not counted in
the histogram, nor the returned total.
Rounding rules for values exactly at the edge of two bins are arbitrary and must not be relied upon.
values |
Values to make histogram from. |
|
n |
Number of values in |
|
min |
Minimum value to consider (left edge of histogram). |
|
max |
Maximum value to consider (right edge of histogram). |
|
nbins |
Number of histogram bins (number of |
|
counts |
Array where to store the counts. |
int
gwy_isnan (double x
);
Alternative isnan()
implementation which works even with fast math.
int
gwy_isinf (double x
);
Alternative isinf()
implementation which works even with fast math.
int
gwy_isnormal (double x
);
Alternative isnormal()
implementation which works even with fast math.
double
gwy_exp10 (double x
);
Inline function or macro defined to a working exp10()
implementation.
#define GWY_SQRT3 1.73205080756887729352744634150587236694280525381038
The square root of 3.
#define GWY_SQRT_PI 1.77245385090551602729816748334114518279754945612237
The square root of pi.
Type of interpolation for percentile calculation.
The interpolations are used when the percentile does not correspond exactly to a rank.