Next: Linked lists, Previous: Library data container, Up: Gnuastro library [Contents][Index]

An array is a contiguous region of memory. Hence, at the lowest level,
every element of an array just has one single-valued position: the number
of elements that lie between it and the first element in the array. This is
also known as the *index* of the element within the array. A dataset’s
number of dimensions is high-level abstraction (meta-data) that we project
onto that contiguous patch of memory. When the array is interpreted as a
one-dimensional dataset, this index is also the *coordinate* of the
element. But once we associate the patch of memory with a higher dimension,
there must also be one coordinate for each dimension.

The functions and macros in this section provide you with the tools to convert an index into a coordinate and vice-versa along with several other issues for example issues with the neighbors of an element in a multi-dimensional context.

- Function:

*size_t*

**gal_dimension_total_size***(size_t*`ndim`

, size_t`*dsize`

) Return the total number of elements for a dataset with

`ndim`

dimensions that has`dsize`

elements along each dimension.

- Function:

*size_t **

**gal_dimension_increment***(size_t*`ndim`

, size_t`*dsize`

) Return an allocated array that has the number of elements necessary to increment an index along every dimension. For example along the fastest dimension (last element in the

`dsize`

and returned arrays), the value is`1`

(one).

- Function:

*size_t*

**gal_dimension_num_neighbors***(size_t*`ndim`

) The maximum number of neighbors (any connectivity) that a data element can have in

`ndim`

dimensions. Effectively, this function just returns \(3^n-1\) (where \(n\) is the number of dimensions).

- Function-like macro:
**GAL_DIMENSION_FLT_TO_INT***(*`FLT`

) Calculate the integer pixel position that the floating point

`FLT`

number belongs to. In the FITS format (and thus in Gnuastro), the center of each pixel is allocated on an integer (not it edge), so the pixel which hosts a floating point number cannot simply be found with internal type conversion.

- Function:

*void*

**gal_dimension_add_coords***(size_t*`*c1`

, size_t`*c2`

, size_t`*out`

, size_t`ndim`

) For every dimension, add the coordinates in

`c1`

with`c2`

and put the result into`out`

. In other words, for dimension`i`

run`out[i]=c1[i]+c2[i];`

. Hence`out`

may be equal to any one of`c1`

or`c2`

.

- Function:

*size_t*

**gal_dimension_coord_to_index***(size_t*`ndim`

, size_t`*dsize`

, size_t`*coord`

) Return the index (counting from zero) from the coordinates in

`coord`

(counting from zero) assuming the dataset has`ndim`

elements and the size of the dataset along each dimension is in the`dsize`

array.

- Function:

*void*

**gal_dimension_index_to_coord***(size_t*`index`

, size_t`ndim`

, size_t`*dsize`

, size_t`*coord`

) Fill in the

`coord`

array with the coordinates that correspond to`index`

assuming the dataset has`ndim`

elements and the size of the dataset along each dimension is in the`dsize`

array. Note that both`index`

and each value in`coord`

are assumed to start from`0`

(zero). Also that the space which`coord`

points to must already be allocated before calling this function.

- Function:

*size_t*

**gal_dimension_dist_manhattan***(size_t*`*a`

, size_t`*b`

, size_t`ndim`

) Return the manhattan distance (see Wikipedia) between the two coordinates

`a`

and`b`

(each an array of`ndim`

elements).

- Function-like macro:
**GAL_DIMENSION_NEIGHBOR_OP***(*`index`

,`ndim`

,`dsize`

,`connectivity`

,`dinc`

,`operation`

) Parse the neighbors of the element located at

`index`

and do the requested operation on them. This is defined as a macro to allow easy definition of any operation on the neighbors of a given element without having to use loops within your source code (the loops are implemented by this macro). For an example of using this function, please see Library demo - inspecting neighbors. The input arguments to this function-like macro are described below:`index`

Distance of this element from the first element in the array on a contiguous patch of memory (starting from 0), see the discussion above.

`ndim`

The number of dimensions associated with the contiguous patch of memory.

`dsize`

The full array size along each dimension. This must be an array and is assumed to have the same number elements as

`ndim`

. See the discussion under the same element in Generic data container (`gal_data_t`

).`connectivity`

Most distant neighbors to consider. Depending on the number of dimensions, different neighbors may be defined for each element. This function-like macro distinguish between these different neighbors with this argument. It has a value between

`1`

(one) and`ndim`

. For example in a 2D dataset, 4-connected neighbors have a connectivity of`1`

and 8-connected neighbors have a connectivity of`2`

. Note that this is inclusive, so in this example, a connectivity of`2`

will also include connectivity`1`

neighbors.`dinc`

An array keeping the length necessary to increment along each dimension. You can make this array with the following function. Just don’t forget to free the array after you are done with it:

size_t *dinc=gal_dimension_increment(ndim, dsize);

`dinc`

depends on`ndim`

and`dsize`

, but it must be defined outside this function-like macro since it involves allocation to help in performance.`operation`

Any C operation that you would like to do on the neighbor. This macro will provide you a

`nind`

variable that can be used as the index of the neighbor that is currently being studied. It is defined as ‘`size_t ndim;`

’. Note that`operation`

will be repeated the number of times there is a neighbor for this element.

This macro works fully within its own

`{}`

block and except for the`nind`

variable that shows the neighbor’s index, all the variables within this macro’s block start with`gdn_`

.

Next: Linked lists, Previous: Library data container, Up: Gnuastro library [Contents][Index]

JavaScript license information

GNU Astronomy Utilities 0.5 manual, December 2017.