GNU Astronomy Utilities

6.1.4.1 ImageCrop options

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.

Input image parameters:

--hstartwcs

(=INT) Specify the first keyword card (line number) to start finding the input image world coordinate system information. Distortions were only recently included in WCSLIB (from version 5). Therefore until now, different telescope would apply their own specific set of WCS keywords 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 completely wrong results. For example in the CANDELS-GOODS South images⁵¹.

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.

--hendwcs

(=INT) Specify the last keyword card to read for specifying the image world coordinate system on the input images. See --hstartwcs

Crop box parameters:

-x

--xc

(=FLT) The first FITS axis value of central position of the crop box in single image mode.

-y

--yc

(=FLT) The second FITS axis value of the central position of the crop box in single image mode.

-s

--section

(=STR) 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.

-l

--polygon

(=STR) String of crop polygon vertices. Note that currently only convex polygons should be used. In the future we will make it work for all kinds of polygons. Convex polygons are polygons that do not have an internal angle more than 180 degrees. This option can be used both in the image and WCS modes. The rectangular region that completely encompasses the polygon will be kept and all the pixels that are outside of it will be removed.

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 vertice 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 webpage⁵² 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 ImageCrop 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, there is no need for --wcsmode, you may also provide many FITS image or tiles and ImageCrop will stitch them all):

$ astimgcrop --wcsmode desired-filter-image(s).fits        \
  --polygon="53.187414,-27.779152 : 53.159507,-27.759633 : \
             53.134517,-27.787144 : 53.161906,-27.807208"

--outpolygon

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 ImageCrop 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.

-r

--ra

(=FLT) The first FITS axis value of central position of the crop box in single image mode.

-d

--dec

(=FLT) The second FITS axis value of the central position of the crop box in single image mode.

-i

--xcol

(=INT) Column number of the first FITS axis position of the box center, starting from zero. In SAO ds9, the first FITS axis is the horizontal axis.

-j

--ycol

(=INT) Column number of the second FITS axis position of the box center, starting from zero. In SAO ds9, the second FITS axis is the vertical axis.

-a

--iwidth

(=INT) Width the square box to crop in image mode in units of pixels. In order for the chosen central pixel to be in the center of the cropped image, the final width has to be an odd number, therefore if the value to this option is an even number, the final crop width will be one pixel larger in each dimension. If you want an even sided crop box, use the --section option to specify the boundaries of the box, see Crop section syntax.

-f

--racol

(=INT) Column number of Right Ascension (RA) in the input catalog, starting from zero.

-g

--deccol

(=INT) Column number of declination in the input catalog, starting from zero.

-w

--wwidth

(=FLT) The width of the crop box in WCS mode in units of arc-seconds.

Output options:

-c

--checkcenter

(=INT) Box size of region in the center of the image to check in units of pixels. This is only used in WCS mode. Because surveys don’t often have a clean square or rectangle shape, some of the pixels on the sides of the surveys don’t have any data and are commonly filled with zero valued pixels.

If the RA and Dec of any of the targets specified in the catalog fall in such regions, that cropped image will be useless! Therefore with this option, you can specify a width of a small box (3 pixels is often good enough) around the central pixel of the cropped image. If all the pixels in this small box have the value of zero, no cropped image will be created and this object will be flagged in the final log file.

-p

--suffix

(=STR) The suffix (or post-fix) of the output files for when you want all the cropped images to have a special ending. One case where this might be helpful is when besides the science images, you want the weight images (or exposure maps, which are also distributed with survey images) of the cropped regions too. So in one run, you can set the input images to the science images and --suffix=_s.fits. In the next run you can set the weight images as input and --suffix=_w.fits.

-b

--noblank

Pixels outside of the input image that are in the crop box will not be used. By default they are filled with blank values (depending on type), see Blank pixels.

-z

--zeroisnotblank

In float or double images, it is common to give the value of zero to blank pixels. If the input image type is one of these two types, such pixels will also be considered as blank. You can disable this behavior with this option, see Blank pixels.

Operating mode options:

-I

--imgmode

Operate in Image mode as described above. This option is only useful when catalog is being provided. If coordinates are given on the command-line, the mode is automatically set based on them.

-W

--wcsmode

Operate in WCS mode. See explanations for --imgmode.

Read in other formats.

GNU Astronomy Utilities 0.2.28-34fb manual, October 2016.