Next: Statistical operations, Previous: Permutations, Up: Gnuastro library [Contents][Index]

Matching is often necessary when the measurements have been done using different instruments, different software or different configurations of the same software. The functions in this part of Gnuastro’s library will be growing to allow matching of images and finding a match between different catalogs (register them). Currently it only provides the The high-level measurements are stored in tables with positions (commonly in RA and Dec with units of degrees).

- Function:

*gal_data_t **

**gal_match_coordinates***(gal_data_t*`*coord1`

, gal_data_t`*coord2`

, double`*aperture`

, int`sorted_by_first`

, int`inplace`

, size_t`minmapsize`

, int`quietmmap`

, size_t`*nummatched`

) -
Return the permutations that when applied, the first

`nummatched`

rows of both inputs match with each other (are the nearest within the given aperture). The two inputs (`coord1`

and`coord2`

) must be List of`gal_data_t`

. Each`gal_data_t`

node in the list should be a single dimensional dataset (column in a table). The dimensions of the coordinates is determined by the number of`gal_data_t`

nodes in the two input lists (which must be equal). Note that the number of rows (or the number of elements in each`gal_data_t`

) in the columns of`coord1`

and`coord2`

can be different.The matching aperture is defined by the

`aperture`

array. If several points of one catalog lie within this aperture of a point in the other, the nearest is defined as the match. In a 2D situation (where the input lists have two nodes), for the most generic case, it must have three elements: the major axis length, axis ratio and position angle (see Defining an ellipse and ellipsoid). If`aperture[1]==1`

, the aperture will be a circle of radius`aperture[0]`

and the third value won’t be used. When the aperture is an ellipse, distances between the points are also calculated in the respective elliptical distances (\(r_{el}\) in Defining an ellipse and ellipsoid).To speed up the search, this function will sort the input coordinates by their first column (first axis). If

*both*are already sorted by their first column, you can avoid the sorting step by giving a non-zero value to`sorted_by_first`

.When sorting is necessary and

`inplace`

is non-zero, the actual input columns will be sorted. Otherwise, an internal copy of the inputs will be made, used (sorted) and later freed before returning. Therefore, when`inplace==0`

, inputs will remain untouched, but this function will take more time and memory.If internal allocation is necessary and the space is larger than

`minmapsize`

, the space will be not allocated in the RAM, but in a file, see description of`--minmapsize`and`--quietmmap`

in Processing options.The number of matches will be put in the space pointed by

`nummatched`

. If there wasn’t any match, this function will return`NULL`

. If match(s) were found, a list with three`gal_data_t`

nodes will be returned. The top two nodes in the list are the permutations that must be applied to the first and second inputs respectively. After applying the permutations, the top`nummatched`

elements will match with each other. The third node is the distances between the respective match. Note that the three nodes of the list are all one-dimensional (a column) and can have different lengths.**Output permutations ignore internal sorting**: the output permutations will correspond to the initial inputs. Therefore, even when`inplace!=0`

(and this function re-arranges the inputs), the output permutation will correspond to original (possibly non-sorted) inputs.The reason for this is that you rarely want the actual positional columns after the match. Usually, you also have other columns (measurements, for example magnitudes) for higher-level processing after the match (that correspond to the input order before sorting). Once you have the permutations, they can be applied to those other columns (see Permutations (

`permutation.h`)) and the higher-level processing can continue.When you read the coordinates from a table using

`gal_table_read`

(see Table input output (`table.h`)), and only ask for the coordinate columns, the inputs to this function are the returned`gal_data_t *`

from two different tables.

Next: Statistical operations, Previous: Permutations, Up: Gnuastro library [Contents][Index]

JavaScript license information

GNU Astronomy Utilities 0.13 manual, September 2020.