GwySpline — Sampling curves in plane
GwySpline *  gwy_spline_new () 
void  gwy_spline_free () 
GwySpline *  gwy_spline_copy () 
GwySpline *  gwy_spline_new_from_points () 
guint  gwy_spline_get_npoints () 
const GwyXY *  gwy_spline_get_points () 
const GwyXY *  gwy_spline_get_tangents () 
gdouble  gwy_spline_get_slackness () 
gboolean  gwy_spline_get_closed () 
void  gwy_spline_set_points () 
void  gwy_spline_set_slackness () 
void  gwy_spline_set_closed () 
gdouble  gwy_spline_length () 
const GwyXY *  gwy_spline_sample_naturally () 
gdouble  gwy_spline_sample_uniformly () 
GwySpline 
#include <libprocess/gwyprocess.h>
GwySpline *
gwy_spline_new (void
);
Creates a new empty spline curve.
You need to set the curve points using gwy_spline_set_points()
before any sampling along the curve. Alternatively,
use gwy_spline_new_from_points()
to construct the spline already with some points.
A newly created spline curve.
Since: 2.45
void
gwy_spline_free (GwySpline *spline
);
Frees a spline curve and all associated resources.
spline 
A spline curve. 
Since: 2.45
GwySpline *
gwy_spline_copy (GwySpline *spline
);
Creates a copy of a spline curve.
spline 
A spline curve. 
A newly created spline curve.
Since: 2.49
GwySpline * gwy_spline_new_from_points (const GwyXY *xy
,guint n
);
Creates a new spline curve passing through given points.
See gwy_spline_set_points()
for discussion.
xy 
Array of points in plane the curve will pass through. 

n 
Number of points in 
A newly created spline curve.
Since: 2.45
guint
gwy_spline_get_npoints (GwySpline *spline
);
Gets the number of points of a spline curve.
spline 
A spline curve. 
The number of XY points defining the curve.
Since: 2.45
const GwyXY *
gwy_spline_get_points (GwySpline *spline
);
Gets the coordinates of spline curve points.
If the spline is empty (there are no points) the function returns NULL
.
spline 
A spline curve. 
Coordinates of the XY points defining the curve. The returned
array is owned by spline
, must not be modified and is only
guaranteed to exist so long as the spline is not modified nor
destroyed.
Since: 2.45
const GwyXY *
gwy_spline_get_tangents (GwySpline *spline
);
Gets tangents to the curve in its defining points.
See gwy_spline_sample_uniformly()
for discussion.
If the spline is empty (there are no points) the function returns NULL
.
spline 
A spline curve. 
Tangents to the spline in the XY points defining the curve. The returned array is owned by spline
, must
not be modified and is only guaranteed to exist so long as the spline is not modified nor destroyed.
Since: 2.45
gdouble
gwy_spline_get_slackness (GwySpline *spline
);
Gets the slackness parameter of a spline curve.
See gwy_spline_set_slackness()
for discussion.
spline 
A spline curve. 
The slackness parameter value.
Since: 2.45
gboolean
gwy_spline_get_closed (GwySpline *spline
);
Reports whether a spline curve is closed or not.
See gwy_spline_set_closed()
for discussion.
spline 
A spline curve. 
TRUE
if spline
is closed, FALSE
if it is openended.
Since: 2.45
void gwy_spline_set_points (GwySpline *spline
,const GwyXY *xy
,guint n
);
Sets the coordinates of XY points a spline curve should pass through.
It is possible to pass n
=0 to make the spline empty (xy
can be NULL
then) but such spline may not be sampled
using gwy_spline_sample_uniformly()
.
The coordinates should be devicescaled, i.e. they should data field rows and columns, or screen or image pixels. Generally, the unit length should be about the smallest distinguishable distance.
This is important namely for gwy_spline_sample_naturally()
that stops refining the curve when the details become
too tiny, even though there may be sharp changes of direction. It is also important if the physical X and Y scales
differ.
Using unscaled physical coordinates may produce odd results.
spline 
A spline curve. 

xy 
Array of points in plane the curve will pass through. 

n 
Number of points in 
Since: 2.45
void gwy_spline_set_slackness (GwySpline *spline
,gdouble slackness
);
Sets the slackness parameter of a spline curve.
The slackness parameter determines how taut or slack the curve is.
The curve always passes through the given XY points. For zero slackness the curve is maximally taut, i.e. the shortest possible passing through the points. Such curve is formed by straight segments. For slackness of 1 the curve is a ‘free’ spline. Values smaller than 1 mean tensile stress while values larger than 1 compressive stres. The default value is 1/sqrt(2).
spline 
A spline curve. 

slackness 
New slackness parameter value from the range [0, 
Since: 2.45
void gwy_spline_set_closed (GwySpline *spline
,gboolean closed
);
Sets whether a spline curve is closed or open.
In closed curve the last point is connected smoothly with the first point, forming a cycle. Note you should not
repeat the point in the xy
array. When a closed curve is sampled, the sampling starts from the first point and
continues beyond the last point until it gets close to the first point again.
An open curve begins with the first point and ends with the last point. It has zero curvature at these two points.
spline 
A spline curve. 

closed 
Since: 2.45
gdouble
gwy_spline_length (GwySpline *spline
);
Calculates the length of a spline curve.
This is useful when you want to sample the curve with a specific step (at least approximately).
Note gwy_spline_sample_uniformly()
also returns the length.
spline 
A spline curve. 
The curve length.
Since: 2.45
const GwyXY * gwy_spline_sample_naturally (GwySpline *spline
,guint *n
);
Samples efficiently a spline curve.
This function calculates coordinates of points that lie on the spline curve and are sufficient for a good approximation by straight lines. This is particularly useful for drawing the curve.
See gwy_spline_sample_uniformly()
for some discussion of closed versus open curves and corner case handling.
spline 
A spline curve. 

n 
Location where to store the number of returned points. 
Coordinates of the XY points defining the sampled curve. The returned array is owned by spline
, must not
be modified and is only guaranteed to exist so long as the spline is not modified nor destroyed.
Since: 2.45
gdouble gwy_spline_sample_uniformly (GwySpline *spline
,GwyXY *xy
,GwyXY *t
,guint n
);
Samples uniformly a spline curve.
This function calculates coordinates of points that lie on the spline curve and are equidistant along it. For open curves the first sampled point coincides with the first given XY point and, similar, the last with the last. For closed curves the first point again coincides with the first given XY point but the last lies one sampling distance before the curve gets back again to the first point.
If you want to specify the sampling step instead of the number of samples use gwy_spline_length()
first to obtain
the curve length and calculate n
accordingly.
A singlepoint curve always consists of a single point. Hence all samples lie in this point. A twopoint curve is
always formed by straight segments, in the case of a closed curve one going forward and the other back.
A meaningful sampling requires n
at least 2, nevertheless, the function permits also n
of one or zero.
The tangents vectors stored in t
are normalised and oriented from the beginning of the curve towards the end. If
two or more consecutive given XY points coincide or the curve has only a single point the vectors may be (0,0).
spline 
A spline curve. 

xy 
Array where the sampled point coordinates should be stored in. May be 

t 
Array where tangent vectors at the 

n 
The number of samples to take. 
The curve length.
Since: 2.45
typedef struct _GwySpline GwySpline;