GwySpline (HEAD)

GwySpline — Sampling curves in plane

Functions

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 ()

Types and Values

GwySpline

Includes

#include <libprocess/gwyprocess.h>

Description

Functions

gwy_spline_new ()

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.

Returns

A newly created spline curve.

Since: 2.45

gwy_spline_free ()

void
gwy_spline_free (GwySpline *spline);

Frees a spline curve and all associated resources.

Parameters

spline

A spline curve.

Since: 2.45

gwy_spline_copy ()

GwySpline *
gwy_spline_copy (GwySpline *spline);

Creates a copy of a spline curve.

Parameters

spline

A spline curve.

Returns

A newly created spline curve.

Since: 2.49

gwy_spline_new_from_points ()

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.

Parameters

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

Returns

A newly created spline curve.

Since: 2.45

gwy_spline_get_npoints ()

guint
gwy_spline_get_npoints (GwySpline *spline);

Gets the number of points of a spline curve.

Parameters

spline

A spline curve.

Returns

The number of XY points defining the curve.

Since: 2.45

gwy_spline_get_points ()

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.

Parameters

spline

A spline curve.

Returns

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

gwy_spline_get_tangents ()

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.

Parameters

spline

A spline curve.

Returns

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

gwy_spline_get_slackness ()

gdouble
gwy_spline_get_slackness (GwySpline *spline);

Gets the slackness parameter of a spline curve.

See gwy_spline_set_slackness() for discussion.

Parameters

spline

A spline curve.

Returns

The slackness parameter value.

Since: 2.45

gwy_spline_get_closed ()

gboolean
gwy_spline_get_closed (GwySpline *spline);

Reports whether a spline curve is closed or not.

See gwy_spline_set_closed() for discussion.

Parameters

spline

A spline curve.

Returns

TRUE if spline is closed, FALSE if it is open-ended.

Since: 2.45

gwy_spline_set_points ()

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 device-scaled, 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.

Parameters

spline	A spline curve.
xy	Array of points in plane the curve will pass through.
n	Number of points in xy .

Since: 2.45

gwy_spline_set_slackness ()

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

Parameters

spline	A spline curve.
slackness	New slackness parameter value from the range [0, G_SQRT2].

Since: 2.45

gwy_spline_set_closed ()

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.

Parameters

spline	A spline curve.
closed	TRUE to make spline closed, FALSE to make it open-ended.

Since: 2.45

gwy_spline_length ()

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.

Parameters

spline

A spline curve.

Returns

The curve length.

Since: 2.45

gwy_spline_sample_naturally ()

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.

Parameters

spline	A spline curve.
n	Location where to store the number of returned points.

Returns

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

gwy_spline_sample_uniformly ()

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 single-point curve always consists of a single point. Hence all samples lie in this point. A two-point 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).

Parameters

spline	A spline curve.
xy	Array where the sampled point coordinates should be stored in. May be NULL if you are only interested in the tangents.
t	Array where tangent vectors at the xy coordinates should be stored in. May be NULL if you are only interested in the coordinates.
n	The number of samples to take.

Returns

The curve length.

Since: 2.45

Types and Values

GwySpline

typedef struct _GwySpline GwySpline;