---

12.3.16 Bounding box (box.h) ¶

Functions related to reporting the bounding box of certain inputs are declared in gnuastro/box.h. All coordinates in this header are in the FITS format (first axis is the horizontal and the second axis is vertical).

Function:
void
gal_box_bound_ellipse_extent (double a, double b, double theta_deg, double *extent) ¶

Return the maximum extent along each dimension of the given ellipse from the center of the ellipse. Therefore this is half the extent of the box in each dimension. a is the ellipse semi-major axis, b is the semi-minor axis, theta_deg is the position angle in degrees. The extent in each dimension is in floating point format and stored in extent which must already be allocated before this function.

Function:
void
gal_box_bound_ellipse (double a, double b, double theta_deg, long *width) ¶

Any ellipse can be enclosed into a rectangular box. This function will write the height and width of that box where width points to. It assumes the center of the ellipse is located within the central pixel of the box. a is the ellipse semi-major axis length, b is the semi-minor axis, theta_deg is the position angle in degrees. The width array will contain the output size in long integer type. width[0], and width[1] are the number of pixels along the first and second FITS axis. Since the ellipse center is assumed to be in the center of the box, all the values in width will be an odd integer.

Function:
void
gal_box_bound_ellipsoid_extent (double *semiaxes, double *euler_deg, double *extent) ¶

Return the maximum extent along each dimension of the given ellipsoid from its center. Therefore this is half the extent of the box in each dimension. The semi-axis lengths of the ellipsoid must be present in the 3 element semiaxis array. The euler_deg array contains the three ellipsoid Euler angles in degrees. For a description of the Euler angles, see description of gal_box_bound_ellipsoid below. The extent in each dimension is in floating point format and stored in extent which must already be allocated before this function.

Function:
void
gal_box_bound_ellipsoid (double *semiaxes, double *euler_deg, long *width) ¶

Any ellipsoid can be enclosed into a rectangular volume/box. The purpose of this function is to give the integer size/width of that box. The semi-axes lengths of the ellipse must be in the semiaxes array (with three elements). The major axis length must be the first element of semiaxes. The only other condition is that the next two semi-axes must both be smaller than the first. The orientation of the major axis is defined through three proper Euler angles (ZXZ order in degrees) that are given in the euler_deg array. The width array will contain the output size in long integer type (in FITS axis order). Since the ellipsoid center is assumed to be in the center of the box, all the values in width will be an odd integer.

The proper Euler angles can be defined in many ways (which axes to rotate about). For a full description of the Euler angles, please see Wikipedia. Here we adopt the ZXZ (or \(Z_1X_2Z_3\)) proper Euler angles were the first rotation is done around the Z axis, the second one about the (rotated) X axis and the third about the (rotated) Z axis.

Function:
void
gal_box_border_from_center (double center, size_t ndim, long *width, long *fpixel, long *lpixel) ¶

Given the center coordinates in center and the width (along each dimension) of a box, return the coordinates of the first (fpixel) and last (lpixel) pixels. All arrays must have ndim elements (one for each dimension).

Function:
void
gal_box_border_rotate_around_center (long *fpixel, long *lpixel, size_t ndim, float rotate_deg) ¶

Modify the input first and last pixels (fpixel and lpixel, that you can estimate with gal_box_border_from_center) to account for the given rotation (in units of degrees) in 2D (currently ndim can only have a value of 2).

Function:
int
gal_box_overlap (long *naxes, long *fpixel_i, long *lpixel_i, long *fpixel_o, long *lpixel_o, size_t ndim) ¶

An ndim-dimensional dataset of size naxes (along each dimension, in FITS order) and a box with first and last (inclusive) coordinate of fpixel_i and lpixel_i is given. This box does not necessarily have to lie within the dataset, it can be outside of it, or only partially overlap. This function will change the values of fpixel_i and lpixel_i to exactly cover the overlap in the input dataset’s coordinates.

This function will return 1 if there is an overlap and 0 if there is not. When there is an overlap, the coordinates of the first and last pixels of the overlap will be put in fpixel_o and lpixel_o.