GwySpline: Gwyddion Library Reference Manual

## GwySpline 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_n_points ()
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 <libgwyddion/gwyddion.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.

### gwy_spline_free()

    void
    gwy_spline_free (GwySpline *spline);

Frees a spline curve and all associated resources.

#### Parameters

spline | A spline curve. |

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

### 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. | [array length=n]
n | Number of points in `xy` . |

#### Returns

A newly created spline curve.

### gwy_spline_get_n_points()

    guint
    gwy_spline_get_n_points (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.

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

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

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

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

### 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. | [array length=n]
n | Number of points in `xy` . |

### 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`]. |

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

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

### 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. | [out]

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

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

## Types and Values

### GwySpline

    typedef struct _GwySpline GwySpline;