The options can be classified into the following contexts: Input, Output and operating mode options. Options that are common to all Gnuastro program are listed in Common options and will not be repeated here.
When you are specifying the crop vertices yourself (through --section, or --polygon) on relatively small regions (depending on the resolution of your images) the outputs from image and WCS mode can be approximately equivalent. However, as the crop sizes get large, the curved nature of the WCS coordinates have to be considered. For example, when using --section, the right ascension of the bottom left and top left corners will not be equal. If you only want regions within a given right ascension, use --polygon in WCS mode.
Input image parameters:
Specify the first keyword card (line number) to start finding the input image world coordinate system information.
This is useful when certain header keywords of the input may cause bad conflicts with your crop (see an example described below).
To get line numbers of the header keywords, you can pipe the fully printed header into cat -n like below:
$ astfits image.fits -h1 | cat -n
For example, distortions have only been present in WCSLIB from version 5.15 (released in mid 2016). Therefore some pipelines still apply their own specific set of WCS keywords for distortions and put them into the image header along with those that WCSLIB does recognize. So now that WCSLIB recognizes most of the standard distortion parameters, they will get confused with the old ones and give wrong results. For example, in the CANDELS-GOODS South images that were created before WCSLIB 5.15149.
The two --hstartwcs and --hendwcs are thus provided so when using older datasets, you can specify what region in the FITS headers you want to use to read the WCS keywords. Note that this is only relevant for reading the WCS information, basic data information like the image size are read separately. These two options will only be considered when the value to --hendwcs is larger than that of --hstartwcs. So if they are equal or --hstartwcs is larger than --hendwcs, then all the input keywords will be parsed to get the WCS information of the image.
Specify the last keyword card to read for specifying the image world coordinate system on the input images. See --hstartwcs
Crop box parameters:
The central position of the crop in the input image.
The positions along each dimension must be separated by a comma (,) and fractions are also acceptable.
The comma-separated values can either be in degrees (a single number), or sexagesimal (_h_m_ for RA, _d_m_ for Dec, or _:_:_ for both).
The number of values given to this option must be the same as the dimensions of the input dataset.
The width of the crop should be set with --width.
The units of the coordinates are read based on the value to the --mode option, see below.
Mode to interpret the crop’s coordinates (for example with --center, --catalog or --polygon). The value must either be img (to assume image/pixel coordinates) or wcs (to assume WCS, usually RA/Dec, coordinates), see Crop modes for a full description.
Width of the cropped region about coordinate given to --center. If in WCS mode, value(s) given to this option will be read in the same units as the dataset’s WCS information along this dimension (unless --widthinpix is given). This option may take either a single value (to be used for all dimensions: --width=10 in image-mode will crop a \(10\times10\) pixel image) or multiple values (a specific value for each dimension: --width=10,20 in image-mode will crop a \(10\times20\) pixel image).
The --width option also accepts fractions.
For example, if you want the width of your crop to be 3 by 5 arcseconds along RA and Dec respectively and you are in wcs-mode, you can use: --width=3/3600,5/3600.
The final output will have an odd number of pixels to allow easy identification of the pixel which keeps your requested coordinate (from --center or --catalog). If you want an even sided crop, you can run Crop afterwards with --section=":*-1,:*-1" or --section=2:,2: (depending on which side you do not need), see Crop section syntax.
The basic reason for making an odd-sided crop is that your given central coordinate will ultimately fall within a discrete pixel in the image (defined by the FITS standard). When the crop has an odd number of pixels in each dimension, that pixel can be very well defined as the “central” pixel of the crop, making it unambiguously easy to identify. However, for an even-sided crop, it will be very hard to identify the central pixel (it can be on any of the four pixels adjacent to the central point of the image!).
In WCS mode, interpret the value to --width as number of pixels, not the WCS units like degrees. This is useful when you want a fixed crop size in pixels, even though your center coordinates are in WCS (for example, RA and Dec).
Polygon vertice coordinates (when value is in FLT,FLT:FLT,FLT:... format) or the filename of a SAO DS9 region file (when the value has no , or : characters).
Each vertice can either be in degrees (a single floating point number) or sexagesimal (in formats of ‘_h_m_’ for RA and ‘_d_m_’ for Dec, or simply ‘_:_:_’ for either of them).
The vertices are used to define the polygon: in the same order given to this option. When the vertices are not necessarily ordered in the proper order (for example, one vertice in a square comes after its diagonal opposite), you can add the --polygonsort option which will attempt to sort the vertices before cropping. Note that for concave polygons, sorting is not recommended because there is no unique solution, for more, see the description under --polygonsort.
This option can be used both in the image and WCS modes, see Crop modes.
If a SAO DS9 region file is used, the coordinate mode of Crop will be determined by the contents of the file and any value given to --mode is ignored.
The cropped image will be the size of the rectangular region that completely encompasses the polygon.
By default all the pixels that are outside of the polygon will be set as blank values (see Blank pixels).
However, if --polygonout is called all pixels internal to the vertices will be set to blank.
In WCS-mode, you may provide many FITS images/tiles: Crop will stitch them to produce this cropped region, then apply the polygon.
The syntax for the polygon vertices is similar to, and simpler than, that for --section. In short, the dimensions of each coordinate are separated by a comma (,) and each vertex is separated by a colon (:). You can define as many vertices as you like. If you would like to use space characters between the dimensions and vertices to make them more human-readable, then you have to put the value to this option in double quotation marks.
For example, let’s assume you want to work on the deepest part of the WFC3/IR images of Hubble Space Telescope eXtreme Deep Field (HST-XDF). According to the web page150 the deepest part is contained within the coordinates:
[ (53.187414,-27.779152), (53.159507,-27.759633), (53.134517,-27.787144), (53.161906,-27.807208) ]
They have provided mask images with only these pixels in the WFC3/IR images, but what if you also need to work on the same region in the full resolution ACS images? Also what if you want to use the CANDELS data for the shallow region? Running Crop with --polygon will easily pull out this region of the image for you, irrespective of the resolution. If you have set the operating mode to WCS mode in your nearest configuration file (see Configuration files), there is no need to call --mode=wcs on the command-line.
$ astcrop --mode=wcs desired-filter-image(s).fits \
--polygon="53.187414,-27.779152 : 53.159507,-27.759633 : \
53.134517,-27.787144 : 53.161906,-27.807208"
More generally, you have an image and want to define the polygon yourself (it is not already published like the example above). As the number of vertices increases, checking the vertex coordinates on a FITS viewer (for example, SAO DS9) and typing them in, one by one, can be very tedious and prone to typo errors. In such cases, you can make a polygon “region” in DS9 and using your mouse, easily define (and visually see) it. Given that SAO DS9 has a graphic user interface (GUI), if you do not have the polygon vertices before-hand, it is much more easier build your polygon there and pass it onto Crop through the region file.
You can take the following steps to make an SAO DS9 region file containing your polygon.
Open your desired FITS image with SAO DS9 and activate its “region” mode with Edit→Region.
Then define the region as a polygon with Region→Shape→Polygon.
Click on the approximate center of the region you want and a small square will appear.
By clicking on the vertices of the square you can shrink or expand it, clicking and dragging anywhere on the edges will enable you to define a new vertex.
After the region has been nicely defined, save it as a file with Region→“Save Regions”.
You can then select the name and address of the output file, keep the format as REG (*.reg) and press the “OK” button.
In the next window, keep format as “ds9” and “Coordinate System” as “fk5” for RA and Dec (or “Image” for pixel coordinates).
A plain text file is now created (let’s call it ds9.reg) which you can pass onto Crop with --polygon=ds9.reg.
For the expected format of the region file, see the description of gal_ds9_reg_read_polygon in SAO DS9 library (ds9.h).
However, since SAO DS9 makes this file for you, you do not usually need to worry about its internal format unless something un-expected happens and you find a bug.
Keep all the regions outside the polygon and mask the inner ones with blank pixels (see Blank pixels). This is practically the inverse of the default mode of treating polygons. Note that this option only works when you have only provided one input image. If multiple images are given (in WCS mode), then the full area covered by all the images has to be shown and the polygon excluded. This can lead to a very large area if large surveys like COSMOS are used. So Crop will abort and notify you. In such cases, it is best to crop out the larger region you want, then mask the smaller region with this option.
Sort the given set of vertices to the --polygon option. For a concave polygon it will sort the vertices correctly, however for a convex polygon it there is no unique sorting, so be careful because the crop may not be what you expected.
Polygons come in two classes: convex and concave (or generally, non-convex!), see below for a demonstration. Convex polygons are those where all inner angles are less than 180 degrees. By contrast, a concave polygon is one where an inner angle may be more than 180 degrees.
Concave Polygon Convex Polygon
D --------C D------------- C
\ | E / |
\E | \ |
/ | \ |
A--------B A ----------B
Section of the input image which you want to be cropped. See Crop section syntax for a complete explanation on the syntax required for this input.
File name of catalog for making multiple crops from the input images/cubes. The catalog can be in any of Gnuastro’s recognized Recognized table formats. The columns containing the coordinates for the crop centers can be specified with the --coordcol option (using column names or numbers, see Selecting table columns). The catalog can also contain the name of each crop, you can specify the column containing the name with the --namecol.
The HDU (extension) containing the catalog (if the file given to --catalog is a FITS file). This can either be the HDU name (if it has one) or number (counting from 0). By default (if this option is not given), the second HDU will be used (equivalent to --cathdu=1. For more on how to specify the HDU, see the explanation of the --hdu option in Input/Output options.
The column in a catalog to read as a coordinate. The value can be either the column number (starting from 1), or a match/search in the table meta-data, see Selecting table columns. This option must be called multiple times, depending on the number of dimensions in the input dataset. If it is called more than necessary, the extra columns (later calls to this option on the command-line or configuration files) will be ignored, see Configuration file precedence.
Column selection of crop file name. The value can be either the column number (starting from 1), or a match/search in the table meta-data, see Selecting table columns. This option can be used both in Image and WCS modes, and not a mandatory. When a column is given to this option, the final crop base file name will be taken from the contents of this column. The directory will be determined by the --output option (current directory if not given) and the value to --suffix will be appended. When this column is not given, the row number will be used instead.
JavaScript license information
GNU Astronomy Utilities 0.22 manual, February 2024.