## elliptic 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_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 ()

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

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

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

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

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

#### Parameters

radius | Circular area radius (in pixels). |

#### Returns

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

## Types and Values