elliptic — Functions to work with elliptic areas

## Functions

 gint gwy_data_field_elliptic_area_fill () gint gwy_data_field_elliptic_area_extract () void gwy_data_field_elliptic_area_unextract () gint gwy_data_field_get_elliptic_area_size () gint gwy_data_field_get_elliptic_intersection () gint gwy_data_field_circular_area_fill () gint gwy_data_field_circular_area_extract () gint gwy_data_field_circular_area_extract_with_pos () void gwy_data_field_circular_area_unextract () gint gwy_data_field_get_circular_area_size () gboolean gwy_data_field_local_maximum ()

## Includes

```#include <libprocess/gwyprocess.h>
```

## Description

Method for extraction and putting back data from/to elliptic and circular areas can be used to implement sample-wise operations, that is operations that depend only on sample value not on its position, on these areas:

 ```1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31``` ```gint n, i; data = g_new(gdouble, width*height); n = gwy_data_field_elliptic_area_extract(data_field, col, row, width, height, data); for (i = 0; i < n; i++) { ... do something with data[i] ... } gwy_data_field_elliptic_area_unextract(data_field, col, row, width, height, data);]| Another possibility is to use #GwyDataLine methods on the extracted data (in practice one would use the same data line repeatedly, of course): |[GwyDataLine *data_line; gdouble *data; gint n; n = gwy_data_field_get_elliptic_area_size(data_field, width, height); data_line = gwy_data_line_new(n, 1.0, FALSE); data = gwy_data_line_get_data(data_line); gwy_data_field_elliptic_area_extract(data_field, col, row, width, height, data); gwy_data_line_pixelwise_filter(data_line, ...); gwy_data_field_elliptic_area_unextract(data_field, col, row, width, height, data); g_object_unref(data_line);]|```

## Functions

### gwy_data_field_elliptic_area_fill ()

```gint
gwy_data_field_elliptic_area_fill (`GwyDataField *data_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. In versions prior to 2.59 the bounding box must be completely contained in the data field. Since version 2.59 the ellipse can intersect the data field in any manner.

#### Parameters

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

```gint
gwy_data_field_elliptic_area_extract (`GwyDataField *data_field`,
`gint col`,
`gint row`,
`gint width`,
`gint height`,
`gdouble *data`);```

Extracts values from an elliptic region of a data field.

The elliptic region is defined by its bounding box. In versions prior to 2.59 the bounding box must be completely contained in the data field. Since version 2.59 the ellipse can intersect the data field in any manner.

#### Parameters

 data_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 Location 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_data_field_get_elliptic_area_size()`.

#### Returns

The number of extracted values.

### gwy_data_field_elliptic_area_unextract ()

```void
gwy_data_field_elliptic_area_unextract
(`GwyDataField *data_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. In versions prior to 2.59 the bounding box must be completely contained in the data field. Since version 2.59 the ellipse can intersect the data field in any manner.

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

#### Parameters

 data_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. It must be the same array as in previous `gwy_data_field_elliptic_area_extract()`.

### gwy_data_field_get_elliptic_area_size ()

```gint
gwy_data_field_get_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_data_field_get_elliptic_intersection()` 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_data_field_get_elliptic_intersection ()

```gint
gwy_data_field_get_elliptic_intersection
(`GwyDataField *data_field`,
`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

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

Since: 2.59

### gwy_data_field_circular_area_fill ()

```gint
gwy_data_field_circular_area_fill (`GwyDataField *data_field`,
`gint col`,
`gint row`,
`gdouble radius`,
`gdouble value`);```

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

#### Parameters

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

```gint
gwy_data_field_circular_area_extract (`GwyDataField *data_field`,
`gint col`,
`gint row`,
`gdouble radius`,
`gdouble *data`);```

Extracts values from a circular region of a data field.

#### Parameters

 data_field A data field. col Row index of circular area centre. row Column index of circular area centre. radius Circular area radius (in pixels). See `gwy_data_field_circular_area_extract_with_pos()` for caveats. data Location to store the extracted values to. See `gwy_data_field_circular_area_extract_with_pos()`.

#### Returns

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

### gwy_data_field_circular_area_extract_with_pos ()

```gint
gwy_data_field_circular_area_extract_with_pos
(`GwyDataField *data_field`,
`gint col`,
`gint row`,
`gdouble radius`,
`gdouble *data`,
`gint *xpos`,
`gint *ypos`);```

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

The row and column indices stored to `xpos` and `ypos` are relative to the area centre, i.e. to (`col` , `row` ). The central pixel will therefore have 0 at the corresponding position in both `xpos` and `ypos` .

#### Parameters

 data_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 radii are NOT recommended. data Location to store the extracted values to. Its size has to be sufficient to contain all the extracted values. As a conservative estimate (2*floor(`radius` )+1)^2 can be used, or the size can be calculated with `gwy_data_field_get_circular_area_size()`. xpos Location to store relative column indices of values in `data` to, the size requirements are the same as for `data` . ypos Location to store relative tow 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.

Since: 2.2

### gwy_data_field_circular_area_unextract ()

```void
gwy_data_field_circular_area_unextract
(`GwyDataField *data_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_data_field_circular_area_extract()` allowing to implement pixel-wise filters on circular areas. Values from `data` are put back to the same positions `gwy_data_field_circular_area_extract()` took them from.

#### Parameters

 data_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. It must be the same array as in previous `gwy_data_field_circular_area_unextract()`.

### gwy_data_field_get_circular_area_size ()

```gint
gwy_data_field_get_circular_area_size (`gdouble radius`);```

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

#### Returns

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

### gwy_data_field_local_maximum ()

```gboolean
gwy_data_field_local_maximum (`GwyDataField *dfield`,
`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.

#### Parameters

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

Since: 2.49

© David Nečas and Petr Klapetek