GNU Astronomy Utilities


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


10.3.20 Matching (match.h)

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

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