---

12.3.29 Warp library (warp.h) ¶

Warping an image to a new pixel grid is commonly necessary as part of astronomical data reduction, for an introduction, see Warp. For details of how we resample the old pixel grid to the new pixel grid, see Resampling. Gnuastro’s Warp program uses the following functions for its default mode (when no linear warps are requested). Through the following functions, you can directly access those features in your own custom programs. The linear warping operations of the Warp program aren’t yet brought into the library. If you need them please get in touch with us at bug-gnuastro@gnu.org. For usage examples of this library, please see Library demo - Warp to another image or Library demo - Warp to new grid.

You are free to provide any valid WCS keywords to the functions defined in this library using the gal_warp_wcsalign_t data type. This might be used to align the input image to the standard WCS grid, potentially changing the pixel scale, removing any valid WCS non-linear distortion available, and projecting to any valid WCS projection type. Further details of the warp library functions and parameters are shown below:

Macro: GAL_WARP_OUTPUT_NAME_WARPED ¶

Macro: GAL_WARP_OUTPUT_NAME_MAXFRAC ¶

Names of the output datasets (in the name component of the output gal_data_ts). By default the output is only a single dataset, but when the checkmaxfrac component of the input is non-zero, it will contain two datasets.

Type (C struct): gal_warp_wcsalign_t ¶

The main data container for inputs, output and internal variables to simplify the WCS-aligning functions. Due to the large number of input variables, this structure makes it easy to call the main functions. Similar to gal_data_t, the gal_warp_wcsalign_t is a structure typedef’d as a new type, see Data container (data.h). Please note that this structure has elements that are allocated dynamically and must be freed after usage. gal_warp_wcsalign_free only frees the internal variables, so you are responsible for freeing your own inputs (cdelt, input, etc.) and the output. The internal variables are cached here to cut cpu-intensive computations. To prevent from using uninitialized variables, we recommend using the helper function gal_warp_wcsalign_template to get a clean structure before setting your own variables. The structure and each of its elements are defined below:

typedef struct
{
  /* Arguments given (and later freed) by the caller. If 'twcs' is
     given, then the "WCS To build" elements will be ignored. */
  gal_data_t       *input;
  size_t       numthreads;
  double      coveredfrac;
  size_t     edgesampling;
  gal_data_t  *widthinpix;
  uint8_t    checkmaxfrac;
  struct wcsprm     *twcs;       /* WCS Predefined. */
  gal_data_t       *ctype;       /* WCS To build.   */
  gal_data_t       *cdelt;       /* WCS To build.   */
  gal_data_t      *center;       /* WCS To build.   */

  /* Output (must be freed by caller) */
  gal_data_t      *output;

  /* Internal variables (allocated and freed internally)  */
  size_t               v0;
  size_t             nhor;
  size_t             ncrn;
  size_t             gcrn;
  int               isccw;
  gal_data_t    *vertices;
} gal_warp_wcsalign_t;

gal_data_t *input

The input dataset. This dataset must contain both the image array of type GAL_TYPE_FLOAT64, and input->wcs should not be NULL for the WCS-aligning operations to work, see Library demo - Warp to new grid.

size_t numthreads

Number of threads to use during the WCS aligning operations. If the given value is 0, the library will calculate the number of available threads at run-time. The warp library functions are thread-safe so you can freely enjoy the merits of parallel processing.

double coveredfrac

Acceptable fraction of output pixel that is covered by input pixels. The value should be between 0 and 1 (inclusive). If the area of an output pixel is covered by less than this fraction, its value will be NaN. For more, see the description of --coveredfrac in Invoking Warp.

size_t edgesampling

Set the number of extra vertices along each edge of the output pixel’s polygon to account for potential curvature due to projection or distortion. A value of 0 is usually enough for this (so the pixel is only defined by a four vertice polygon. Greater values increase memory usage and program execution time. For more, please see the description of --edgesampling in Align pixels with WCS considering distortions.

gal_data_t *widthinpix

Output image size (width and height) in number of pixels. If a NULL pointer is passed, the WCS-aligning operations will estimate the output image size internally such that it contains the full input. This dataset should have a type of GAL_TYPE_SIZE_T and contain exactly two odd values. This ensures that the center of the central pixel lies at the requested central coordinate (note that an image with an even number of pixels doesn’t have a “central” pixel!

struct wcsprm *twcs

The target grid WCS which must follow the standard WCSLIB structure. You can read it from a file using gal_wcs_read or create an entirely new one with gal_wcs_create and later free it with gal_wcs_free, see World Coordinate System (wcs.h). If this element is given, the ctype, cdelt and center elements (which are used to construct a WCS internally) are ignored.

Please note that the wcsprm structure doesn’t contain the image size. To set the final image size, you should use widthinpix.

gal_data_t *ctype

The output’s projection type. The dataset has to have the type GAL_TYPE_STRING, containing exactly two strings. Both strings will be directly passed to WCSLIB and should conform to the FITS standard’s CTYPEi keywords, see the description of --ctype in Align pixels with WCS considering distortions. For example, "RA---TAN" and "DEC--TAN", or "RA---HPX" and "DEC--HPX".

gal_data_t *cdelt

Output pixel scale (size of pixel in the WCS units: value to CUNITi keywords in FITS, usually degrees). The dataset should have a type of GAL_TYPE_FLOAT64 and contain exactly two values. Hint: to convert arcsec to degrees, just divide by 3600.

gal_data_t *center

WCS coordinate of the center of the central pixel of the output. The units depend on the WCS, for example, if the CUNITi keywords are deg, it is in degrees. This dataset should have a type of GAL_TYPE_FLOAT64 and contain exactly two values.

uint8_t checkmaxfrac

When this is non-zero, the output will be a two-element List of gal_data_t. The second element shows the Moiré pattern of the warp. For more, see Moiré pattern in stacking and its correction.

Function:
gal_warp_wcsalign_t
gal_warp_wcsalign_template (void) ¶

A high-level helper function that returns a clean gal_warp_wcsalign_t struct with all values initialized This function returns a copy of a statically allocated structure. So you don’t need to free the returned structure.

The Warp library decides on the program flow based on this struct. Uninitialized pointers can point to random space in RAM which can create segmentation faults, or even worse, produce unnoticed side-effects. It is therefore good practice to manually set unused pointers to NULL and give blank values to numbers Since there are many variables and pointers in gal_warp_wcsalign_t, it is easy to forget initializing them. With that said, we recommend using this function to minimize human error.

Function:
void
gal_warp_wcsalign (gal_warp_wcsalign_t *wa) ¶

A high-level function to align the input dataset’s pixels to its WCS coordinates and write the result in wa->output. This function assumes that the input variables have already been set in the wa structure. The input variables are clearly shown in the definition of gal_warp_wcsalign_t. It will call the lower level functions below to do the job and will free the internal variables afterwards.

The following low-level functions are called from the high-level gal_warp_wcsalign function. They are provided here in scenarios where fine grain control over the thread workflow is necessary, see Multithreaded programming (threads.h).

Function:
void
gal_warp_wcsalign_init (gal_warp_wcsalign_t *wa) ¶

Low-level function to initialize all the elements inside the wa structure assuming that the input variables have been set. The input variables are clearly shown in the definition of gal_warp_wcsalign_t. This includes sanity checking the input arguments, as well as allocating the output image’s empty pixels (that can be filled with gal_warp_wcsalign_onpix, possibly on threads).

Function:
void
gal_warp_wcsalign_onpix (gal_warp_wcsalign_t *nl, size_t ind) ¶

Low-level function that fills pixel ind (counting from 0) in the already initialized output image.

Function:
void *
gal_warp_wcsalign_onthread (void *inparam) ¶

Low-level worker function that can be passed to the high-level gal_threads_spin_off or the lower-level pthread_create with some modifications, see Multithreaded programming (threads.h).

Function:
void
gal_warp_wcsalign_free (gal_warp_wcsalign_t *wa) ¶

Low-level function to free the internal variables inside wa only. The caller must free the input pointers themselves, this function will not free them (they may be necessary in other parts of the caller’s higher-level architecture).

Function:
void
gal_warp_pixelarea (gal_warp_wcsalign_t *wa) ¶

Calculate each input pixel’s area based on its WCS and save it to a copy of the input image with only one difference: the pixel values now show pixel area. For examples on its usage, see Pixel information images.