GNU Astronomy Utilities

Next: , Previous: , Up: Gnuastro library   [Contents][Index]

10.3.6 Dimensions (dimension.h)

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.

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.

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

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.

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.

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.

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.

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:


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


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


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


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.


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.


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: , Previous: , Up: Gnuastro library   [Contents][Index]