## elliptic

elliptic — Functions to work with elliptic areas

## Synopsis

    #include <libprocess/gwyprocess.h>

    gint                gwy_data_field_elliptic_area_fill   (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             gdouble value);
    gint                gwy_data_field_elliptic_area_extract
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             gdouble *data);
    void                gwy_data_field_elliptic_area_unextract
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             const gdouble *data);
    gint                gwy_data_field_get_elliptic_area_size
                                                            (gint width,
                                                             gint height);
    gint                gwy_data_field_circular_area_fill   (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gdouble radius,
                                                             gdouble value);
    gint                gwy_data_field_circular_area_extract
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gdouble radius,
                                                             gdouble *data);
    gint                gwy_data_field_circular_area_extract_with_pos
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gdouble radius,
                                                             gdouble *data,
                                                             gint *xpos,
                                                             gint *ypos);
    void                gwy_data_field_circular_area_unextract
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gdouble radius,
                                                             const gdouble *data);
    gint                gwy_data_field_get_circular_area_size
                                                            (gdouble radius);

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

    gdouble *data;
    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);

## Details

### 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 which must be completely contained in the data field.

`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 which must be completely contained in the data field.

`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 which must be completely contained in the data field.

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.

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

`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_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.

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

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

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

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

`radius` : | Circular area radius (in pixels).
Returns : | The number of pixels in a circular region with given rectangular bounds (or its upper bound).