Shaped areas: Gwyddion Library Reference Manual

Shaped areas

Shaped areas — Functions for non-rectangular regions of different shapes

Functions

gsize	gwy_field_elliptic_area_fill ()
gsize	gwy_nield_elliptic_area_fill ()
gsize	gwy_nield_elliptic_fill ()
gsize	gwy_field_elliptic_area_extract ()
gsize	gwy_nield_elliptic_area_extract ()
void	gwy_field_elliptic_area_insert ()
void	gwy_nield_elliptic_area_insert ()
gsize	gwy_elliptic_area_size ()
gsize	gwy_elliptic_intersection_size ()
gsize	gwy_field_circular_area_fill ()
gsize	gwy_nield_circular_area_fill ()
gsize	gwy_field_circular_area_extract ()
gsize	gwy_nield_circular_area_extract ()
void	gwy_field_circular_area_insert ()
void	gwy_nield_circular_area_insert ()
gsize	gwy_circular_area_size ()
gsize	gwy_nield_linear_area_fill ()
gsize	gwy_nield_linear_area_extract ()
void	gwy_nield_linear_area_insert ()
gsize	gwy_linear_area_size ()
gboolean	gwy_field_local_maximum ()

Includes

#include <libgwyddion/gwyddion.h>

Description

Methods for filling, extraction and insertion of data from/to shaped areas can be used as simple drawing primitives or for preparation of round kernels. The can also help with implementation of sample-wise operations, that is operations that depend only on sample value not on its position, on these areas:

gint n, i;

data = g_new(gdouble, width*height);
n = gwy_field_elliptic_area_extract(field, col, row, width, height, data, NULL, NULL);
for (i = 0; i < n; i++) {
   ... do something with data[i] ...
}
gwy_field_elliptic_area_insert(field, col, row, width, height, data);]|

Another possibility is to use #GwyLine methods on the extracted data (in practice one would use the same data
line repeatedly, of course):

|[GwyLine *line;
gdouble *data;
gint n;

n = gwy_elliptic_area_size(width, height);
line = gwy_line_new(n, 1.0, FALSE);
data = gwy_line_get_data(line);
gwy_field_elliptic_area_extract(field, col, row, width, height, data, NULL, NULL);
gwy_line_pixelwise_filter(line, ...);
gwy_field_elliptic_area_insert(field, col, row, width, height, data);
g_object_unref(line);]|

Although the circular area functions allow any real positive ratius, to get areas that do not deviate from true
circles after pixelization too much, half-integer values are recommended. Integer radii are NOT recommended.

Be mindful that the relative row and column indices of extracted values, which can be returned by the data
extraction functions, have different meanings for different shapes since they are specified differently.
Furthemore, the order of values in data is not specified – it is always consistend between the extraction and
insertion though. You need always to use the extraction function first, even if you only care about the
coordinates, not the data, because it is the only way to guarantee the insertion function will put your data where
intended.

Functions

gwy_field_elliptic_area_fill()

gsize
gwy_field_elliptic_area_fill (GwyField *field,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              gdouble value);

Fills an elliptic region of a data field with given value.

The elliptic region is defined by its bounding box. The ellipse can intersect the data field in any manner.

Parameters

field	A data field.
col	Upper-left bounding box column coordinate.
row	Upper-left bounding box row coordinate.
width	Bounding box width (number of columns).
height	Bounding box height (number of rows).
value	Value to be entered.

Returns

The number of filled values.

gwy_nield_elliptic_area_fill()

gsize
gwy_nield_elliptic_area_fill (GwyNield *nield,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              gint value);

Fills an elliptic region of a number field with given value.

The elliptic region is defined by its bounding box. The ellipse can intersect the number field in any manner.

Parameters

nield	A number field.
col	Upper-left bounding box column coordinate.
row	Upper-left bounding box row coordinate.
width	Bounding box width (number of columns).
height	Bounding box height (number of rows).
value	Value to be entered.

Returns

The number of filled values.

gwy_nield_elliptic_fill()

gsize
gwy_nield_elliptic_fill (GwyNield *nield);

Fills an maximum-sized elliptic region of a number field with one.

This is a convenience wrapper for the common use case of gwy_nield_elliptic_area_fill(). Note that the area outside of the ellipse is not cleared. Nevertheless, a newly created GwyNield is alaways zero-filled.

Parameters

nield

A number field.

Returns

The number of filled values.

gwy_field_elliptic_area_extract()

gsize
gwy_field_elliptic_area_extract (GwyField *field,
                                 gint col,
                                 gint row,
                                 gint width,
                                 gint height,
                                 gdouble *data,
                                 gint *rcols,
                                 gint *rrows);

Extracts values from an elliptic region of a data field.

The elliptic region is defined by its bounding box. The ellipse can intersect the data field in any manner.

The row and column indices stored to rrows and rcols are relative to the area top left corner, i.e. to (col , row ). Note that the convention is different than for circular areas.

All three output arrays are optional. However, if you simply want a quick upper bound for their size, use gwy_elliptic_area_size() instead of passing all three as NULL.

Parameters

field	A data field.
col	Upper-left bounding box column coordinate.
row	Upper-left bounding box row coordinate.
width	Bounding box width (number of columns).
height	Bounding box height (number of rows).
data	Optional array to store the extracted values to. Its size has to be sufficient to contain all the extracted values. As a conservative estimate `width` *`height` can be used, or the size can be calculated with `gwy_elliptic_area_size()`.
rcols	Optional array to store relative column indices of values in `data` to, the size requirements are the same as for `data` .
rrows	Optional array to store relative row indices of values in `data` to, the size requirements are the same as for `data` .

Returns

The number of extracted values.

gwy_nield_elliptic_area_extract()

gsize
gwy_nield_elliptic_area_extract (GwyNield *nield,
                                 gint col,
                                 gint row,
                                 gint width,
                                 gint height,
                                 gint *data,
                                 gint *rcols,
                                 gint *rrows);

Extracts values from an elliptic region of a number field.

The elliptic region is defined by its bounding box. The ellipse can intersect the number field in any manner.

All three output arrays are optional. However, if you simply want a quick upper bound for their size, use gwy_elliptic_area_size() instead of passing all three as NULL.

Parameters

nield	A number field.
col	Upper-left bounding box column coordinate.
row	Upper-left bounding box row coordinate.
width	Bounding box width (number of columns).
height	Bounding box height (number of rows).
data	Optional array to store the extracted values to. Its size has to be sufficient to contain all the extracted values. As a conservative estimate `width` *`height` can be used, or the size can be calculated with `gwy_nield_get_elliptic_area_size()`.
rcols	Optional array to store relative column indices of values in `data` to, the size requirements are the same as for `data` .
rrows	Optional array to store relative row indices of values in `data` to, the size requirements are the same as for `data` .

Returns

The number of extracted values.

gwy_field_elliptic_area_insert()

void
gwy_field_elliptic_area_insert (GwyField *field,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                const gdouble *data);

Puts values back to an elliptic region of a data field.

The elliptic region is defined by its bounding box. The ellipse can intersect the data field in any manner.

This method does the reverse of gwy_field_elliptic_area_extract() allowing to implement pixel-wise filters on elliptic areas. Values from data are put back to the same positions gwy_field_elliptic_area_extract() took them from.

Parameters

field	A data field.
col	Upper-left bounding box column coordinate.
row	Upper-left bounding box row coordinate.
width	Bounding box width (number of columns).
height	Bounding box height (number of rows).
data	The values to put back. The array must correspond to `gwy_field_elliptic_area_extract()`.

gwy_nield_elliptic_area_insert()

void
gwy_nield_elliptic_area_insert (GwyNield *nield,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                const gint *data);

Puts values back to an elliptic region of a number field.

The elliptic region is defined by its bounding box. The ellipse can intersect the number field in any manner.

This method does the reverse of gwy_nield_elliptic_area_extract() allowing to implement pixel-wise filters on elliptic areas. Values from data are put back to the same positions gwy_nield_elliptic_area_extract() took them from.

Parameters

nield	A number field.
col	Upper-left bounding box column coordinate.
row	Upper-left bounding box row coordinate.
width	Bounding box width (number of columns).
height	Bounding box height (number of rows).
data	The values to put back. The array must correspond to `gwy_nield_elliptic_area_extract()`.

gwy_elliptic_area_size()

gsize
gwy_elliptic_area_size (gint width,
                        gint height);

Calculates an upper bound of the number of samples in an elliptic region.

This function is useful for elliptic areas more or less contained within the data field. Otherwise the returned size can be overestimated a lot. Use gwy_elliptic_intersection_size() for elliptic areas intersecting the data field in arbitrary manner.

Parameters

width	Bounding box width.
height	Bounding box height.

Returns

The number of pixels in an elliptic region with given rectangular bounds (or its upper bound).

gwy_elliptic_intersection_size()

gsize
gwy_elliptic_intersection_size (gint xres,
                                gint yres,
                                gint col,
                                gint row,
                                gint width,
                                gint height);

Calculates an upper bound of the number of samples in an elliptic region intersecting a data field.

Parameters

xres	Number of columns of the entire image.
yres	Number of rows of the entire image.
col	Upper-left bounding box column coordinate.
row	Upper-left bounding box row coordinate.
width	Bounding box width.
height	Bounding box height.

Returns

The number of pixels in an elliptic region with given rectangular bounds (or its upper bound).

gwy_field_circular_area_fill()

gsize
gwy_field_circular_area_fill (GwyField *field,
                              gint col,
                              gint row,
                              gdouble radius,
                              gdouble value);

Fills a circular region of a data field with given value.

Parameters

field	A data field.
col	Row index of circular area centre.
row	Column index of circular area centre.
radius	Circular area radius (in pixels). Any value is allowed, although to get areas that do not deviate from true circles after pixelization too much, half-integer values are recommended, integer values are NOT recommended.
value	Value to be entered.

Returns

The number of filled values.

gwy_nield_circular_area_fill()

gsize
gwy_nield_circular_area_fill (GwyNield *nield,
                              gint col,
                              gint row,
                              gdouble radius,
                              gint value);

Fills an circular region of a number field with given value.

Parameters

nield	A number field.
col	Row index of circular area centre.
row	Column index of circular area centre.
radius	Circular area radius (in pixels). Any value is allowed, although to get areas that do not deviate from true circles after pixelization too much, half-integer values are recommended, integer values are NOT recommended.
value	Value to be entered.

Returns

The number of filled values.

gwy_field_circular_area_extract()

gsize
gwy_field_circular_area_extract (GwyField *field,
                                 gint col,
                                 gint row,
                                 gdouble radius,
                                 gdouble *data,
                                 gint *rcols,
                                 gint *rrows);

Extracts values with positions from a circular region of a data field.

The row and column indices stored to rrows and rcols are relative to the area centre, i.e. to (col , row ). The central pixel will therefore have 0 at the corresponding position in both rrows and rcols . Note that the convention is different than for elliptic areas.

All three output arrays are optional. However, if you simply want a quick upper bound for their size, use gwy_circular_area_size() instead of passing all three as NULL.

Parameters

field	A data field.
col	Row index of circular area centre.
row	Column index of circular area centre.
radius	Circular area radius (in pixels).
data	Optional array to store the extracted values to. Its size has to be sufficient to contain all the extracted values. As a conservative estimate (2floor(`radius`* )+1)^2 can be used, or the size can be calculated with `gwy_circular_area_size()`.
rcols	Optional array to store relative column indices of values in `data` to, the size requirements are the same as for `data` .
rrows	Optional array to store relative row indices of values in `data` to, the size requirements are the same as for `data` .

Returns

The number of extracted values. It can be zero when the inside of the circle does not intersect with the data field.

gwy_nield_circular_area_extract()

gsize
gwy_nield_circular_area_extract (GwyNield *nield,
                                 gint col,
                                 gint row,
                                 gdouble radius,
                                 gint *data,
                                 gint *rcols,
                                 gint *rrows);

Extracts values from a circular region of a number field.

All three output arrays are optional. However, if you simply want a quick upper bound for their size, use gwy_circular_area_size() instead of passing all three as NULL.

Parameters

nield	A number field.
col	Row index of circular area centre.
row	Column index of circular area centre.
radius	Circular area radius (in pixels).
data	Optional array to store the extracted values to.
rcols	Optional array to store relative column indices of values in `data` to, the size requirements are the same as for `data` .
rrows	Optional array to store relative row indices of values in `data` to, the size requirements are the same as for `data` .

Returns

The number of extracted values. It can be zero when the inside of the circle does not intersect with the number field.

gwy_field_circular_area_insert()

void
gwy_field_circular_area_insert (GwyField *field,
                                gint col,
                                gint row,
                                gdouble radius,
                                const gdouble *data);

Puts values back to a circular region of a data field.

This method does the reverse of gwy_field_circular_area_extract() allowing to implement pixel-wise filters on circular areas. Values from data are put back to the same positions gwy_field_circular_area_extract() took them from.

Parameters

field	A data field.
col	Row index of circular area centre.
row	Column index of circular area centre.
radius	Circular area radius (in pixels).
data	The values to put back. The array must correspond to `gwy_field_circular_area_insert()`.

gwy_nield_circular_area_insert()

void
gwy_nield_circular_area_insert (GwyNield *nield,
                                gint col,
                                gint row,
                                gdouble radius,
                                const gint *data);

Puts values back to a circular region of a number field.

This method does the reverse of gwy_nield_circular_area_extract() allowing to implement pixel-wise filters on circular areas. Values from data are put back to the same positions gwy_nield_circular_area_extract() took them from.

Parameters

nield	A number field.
col	Row index of circular area centre.
row	Column index of circular area centre.
radius	Circular area radius (in pixels).
data	The values to put back. The array must correspond to `gwy_nield_circular_area_insert()`.

gwy_circular_area_size()

gsize
gwy_circular_area_size (gdouble radius);

Calculates an upper bound of the number of samples in a circular region.

Parameters

radius

Circular area radius (in pixels).

Returns

The number of pixels in a circular region with given rectangular bounds (or its upper bound).

gwy_nield_linear_area_fill()

gsize
gwy_nield_linear_area_fill (GwyNield *nield,
                            gint col1,
                            gint row1,
                            gint col2,
                            gint row2,
                            gboolean connect4,
                            gint value);

Fills a thin linear region of a number field with given value.

The thin linear region is defined by its end points. The line can intersect the number field in any manner.

Parameters

nield	A number field.
col1	Column index of the first endpoint.
row1	Row index of the first endpoint.
col2	Column index of the second endpoint.
row2	Row index of the second endpoint.
connect4	`TRUE` for a 4-connected line (it would be flood-fillable), `FALSE` for an 8-connected line (it can connect only diagonally).
value	Value to be entered.

Returns

The number of filled values.

gwy_nield_linear_area_extract()

gsize
gwy_nield_linear_area_extract (GwyNield *nield,
                               gint col1,
                               gint row1,
                               gint col2,
                               gint row2,
                               gboolean connect4,
                               gint *data,
                               gint *rcols,
                               gint *rrows);

Extracts values from a thin linear region of a number field.

The thin linear region is defined by its end points. The line can intersect the number field in any manner.

The row and column indices stored to rcols and rrows are relative to the first endpoint, i.e. to (col1 , row1 ), i.e. the first endpoint corresponds to (0,0). The order in which line pixels appear in rcols and rrows is not defined. They can appear starting from the second end point for example. It is only guaranteed that gwy_nield_linear_area_insert() uses the same order.

All three output arrays are optional. However, if you simply want a quick upper bound for their size, use gwy_linear_area_size() instead of passing all three as NULL.

Parameters

nield	A number field.
col1	Column index of the first endpoint.
row1	Row index of the first endpoint.
col2	Column index of the second endpoint.
row2	Row index of the second endpoint.
connect4	`TRUE` for a 4-connected line (it would be flood-fillable), `FALSE` for an 8-connected line (it can connect only diagonally).
data	Optional array to store the extracted values to. Its size has to be sufficient to contain all the extracted values. As a conservative estimate width+height+1 can be used, or the size can be calculated with `gwy_linear_area_size()`.
rcols	Optional array to store relative column indices of values in `data` to, the size requirements are the same as for `data` .
rrows	Optional array to store relative row indices of values in `data` to, the size requirements are the same as for `data` .

Returns

The number of extracted values.

gwy_nield_linear_area_insert()

void
gwy_nield_linear_area_insert (GwyNield *nield,
                              gint col1,
                              gint row1,
                              gint col2,
                              gint row2,
                              gboolean connect4,
                              const gint *data);

Puts values back to an thin linear region of a number field.

The thin linear region is defined by its end points. The line can intersect the number field in any manner.

This method does the reverse of gwy_nield_linear_area_extract() allowing to implement pixel-wise filters on linear areas. Values from data are put back to the same positions gwy_nield_linear_area_extract() took them from.

Parameters

nield	A number field.
col1	Column index of the first endpoint.
row1	Row index of the first endpoint.
col2	Column index of the second endpoint.
row2	Row index of the second endpoint.
connect4	`TRUE` for a 4-connected line (it would be flood-fillable), `FALSE` for an 8-connected line (it can connect only diagonally).
data	The values to put back. The array must correspond to `gwy_nield_linear_area_extract()`.

gwy_linear_area_size()

gsize
gwy_linear_area_size (gint col1,
                      gint row1,
                      gint col2,
                      gint row2,
                      gboolean connect4);

Calculates an upper bound of the number of samples in a thin line region.

Parameters

col1	Column index of the first endpoint.
row1	Row index of the first endpoint.
col2	Column index of the second endpoint.
row2	Row index of the second endpoint.
connect4	`TRUE` for a 4-connected line (it would be flood-fillable), `FALSE` for an 8-connected line (it can connect only diagonally).

Returns

The number of pixels in a thin line region with given rectangular bounds (or its upper bound).

gwy_field_local_maximum()

gboolean
gwy_field_local_maximum (GwyField *field,
                         gdouble *x,
                         gdouble *y,
                         gint ax,
                         gint ay);

Searches an elliptical area in a data field for local maximum.

The area may stick outside the data field.

The function first finds the maximum within the ellipse, intersected with the data field and then tries subpixel refinement. The maximum is considered successfully located if it is inside the data field, i.e. not on edge, there is no higher value in its 8-neighbourhood, and the subpixel refinement of its position succeeds (which usually happens when the first two conditions are met, but not always).

Even if the function returns FALSE the values of x and y are reasonable, but they may not correspond to an actual maximum.

The radii can be zero. A single pixel is then examined, but if it is indeed a local maximum, its position is refined.

The radii can also be negative. In such case a full-width or full-height strip is searched in the corresponding direction, or the entire field if both are negative.

Parameters

field	A two-dimensional data field.
x	Approximate maximum `x` -location to be improved (in pixels).
y	Approximate maximum `y` -location to be improved (in pixels).
ax	Horizontal search radius.
ay	Vertical search radius.

Returns

TRUE if the maximum was successfully located. FALSE when the location is problematic and should not be used.