GNU Astronomy Utilities manual

6.1.2 Crop section syntax

When in image mode, one of the methods to crop only one rectangular section from the input image is to use the --section option. ImageCrop has a powerful syntax to read the box parameters from a string of characters. If you leave certain parts of the string to be empty, ImageCrop can fill them for you based on the input image sizes.

To define a box, you need the coordinates of two points: the first pixel in the box at (X1, Y1) and the pixel which is immediately outside of the box (X2, Y2), four coordinates in total. The four coordinates can be specified with one string in this format: X1:X2,Y1:Y2. It is given to the --section option. Therefore, the pixels along the first axis that are \geqX1 and <X2 will be included in the cropped image. The same goes for the second axis. Note that each different term will be read as an integer, not a float (there are no sub-pixels in ImageCrop, you can use ImageWarp to shift the matrix with any subpixel distance, then crop the warped image, see ImageWarp). Also, following the FITS standard, pixel indexes along each axis start from unity(1) not zero(0).

You can omit any of the values and they will be filled automatically. The left hand side of the colon (:) will be filled with 1, and the right side with the image size. So, 2:,: will include the full range of pixels along the second axis and only those with a first axis index larger than 2 in the first axis. If the colon is omitted for a dimension, then the full range is automatically used. So the same string is also equal to 2:, or 2: or even 2. If you want such a case for the second axis, you should set it to: ,2.

If you specify a negative value, it will be seen as before the indexes of the image which are outside the image along the bottom or left sides when viewed in SAO ds9. In case you want to count from the top or right sides of the image, you can use an asterisk (*). When confronted with a *, ImageCrop will replace it with the maximum length of the image in that dimension. So *-10:*+10,*-20:*+20 will mean that the crop box will be 20\times40 pixels in size and only include the top corner of the input image with 3/4 of the image being covered by blank pixels, see Blank pixels.

If you feel more comfortable with space characters between the values, you can use as many space characters as you wish, just be careful to put your value in double quotes, for example --section="5:200, 123:854". If you forget, anything after the first space will not be seen by --section, because the unquoted space character is one of the characters that separates options on the command line.

Read in other formats.
GNU Astronomy Utilities manual, November 2015.