The string given to --output option will be interpreted depending on how many crops were requested, see Crop modes:
The crop file names will consist of two parts: a variable part (the row number of each target starting from 1) along with a fixed string which you can set with the --suffix option. Optionally, you may also use the --namecol option to define a column in the input catalog to use as the file name instead of numbers.
When the desired crop is not within the input image(s) crop will not produce any image for that crop. If the --quiet option is not given, crop will report which one of the inputs was created and which wasn’t (due to an overlap or the center being empty, see --checkcenter. This information can be formally written in an optional log-file also, see below. At the end, Crop will return successfully to the shell if at least one output file was created. If no output was created at all, then crop will return to the shell with a failure.
By default, as suggested by the FITS standard and implemented in all Gnuastro programs, the first/primary extension of the output files will only contain metadata.
The cropped images/cubes will be written into the 2nd HDU of their respective FITS file (which is actually counted as 1 because HDU counting starts from 0).
However, if you want the cropped data to be written into the primary (0-th) HDU, run Crop with the --primaryimghdu option.
If the output file already exists by default Crop will re-write it (so that all existing HDUs in it will be deleted). If you want the cropped HDU to be appended to existing HDUs, use --append described below.
The 0-th HDU of each output cropped image will contain the names of the input image(s) it was cut from.
If a name is longer than the 70 character space that the FITS standard allows for header keyword values, the name will be cut into several keywords from the nearest slash (/).
The keywords have the following format: ICFn_m (for Crop File).
Where n is the number of the image used in this crop and m is the part of the name (it can be broken into multiple keywords).
Following the name is another keyword named ICFnPIX which shows the pixel range from that input image in the same syntax as Crop section syntax.
So this string can be directly given to the --section option later.
Once done, a log file can be created in the current directory with the --log option.
This file will have three columns and the same number of rows as the number of cropped images.
There are also comments on the top of the log file explaining basic information about the run and descriptions for the columns.
A short description of the columns is also given below:
0 if the central few pixels (value to the --checkcenter option) are blank and 1 if they are not.
When the crop was not defined by its center (see Crop modes), or --checkcenter was given a value of 0 (see Invoking Crop), the center will not be checked and this column will be given a value of -1.
If the output crop(s) have a single element (pixel in an image) and --oneelemstdout has been called, no output file will be produced! Instead, the single element’s value is printed on the standard output. See the description of --oneelemstdout below for more:
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.
Name of cropped HDU (value to the EXTNAME keyword of FITS).
If not given, a default CROP will be placed there (so the EXTNAME keyword will always be present in the output).
If crop produces many outputs from a catalog, they will be given the same string as EXTNAME (the file names containing the cropped HDU will be different).
If the output file already exists, append the cropped image HDU to the end of any existing HDUs. By default (when this option isn’t given), if an output file already exists, any existing HDU in it will be deleted. If the output file doesn’t exist, this option is redundant.
Write the output into the primary (0-th) HDU/extension of the output. By default, like all Gnuastro’s default outputs, no data is written in the primary extension because the FITS standard suggests keeping that extension free of data and only for metadata.
When a crop only has a single element (a single pixel), print it to the standard output instead of making a file. By default (without this option), a single-pixel crop will be saved to a file, just like a crop of any other size.
When a single crop is requested (either through --center, or a catalog of one row is given), the single value alone is printed with nothing else. This makes it easy to immediately write the value into a shell variable for example:
value=$(astcrop img.fits --mode=wcs --center=1.234,5.678 \
--width=1 --widthinpix --oneelemstdout \
--quiet)
If a catalog of coordinates is given (that would produce multiple crops; or multiple values in this scenario), the solution for a single value will not work! Recall that Crop will do the crops in parallel, therefore each time you run it, the order of the rows will be different and not correspond to the order of the inputs.
To allow identification of each value (which row of the input catalog it corresponds to), Crop will first print the name of the would-be created file name, and print the value after it (separated by an empty SPACE character). In other words, the file in the first column will not actually be created, but the value of the pixel it would have contained (if this option was not called) is printed after it.
Square box width of region in the center of the image to check for blank values. If any of the pixels in this central region of a crop (defined by its center) are blank, then it will not be stored in an output file. If the value to this option is zero, no checking is done. This check is only applied when the cropped region(s) are defined by their center (not by the vertices, see Crop modes).
The units of the value are interpreted based on the --mode value (in WCS or pixel units).
The ultimate checked region size (in pixels) will be an odd integer around the center (converted from WCS, or when an even number of pixels are given to this option).
In WCS mode, the value can be given as fractions, for example, if the WCS units are in degrees, 0.1/3600 will correspond to a check size of 0.1 arcseconds.
Because survey regions do not often have a clean square or rectangle shape, some of the pixels on the sides of the survey FITS image do not commonly have any data and are blank (see Blank pixels). So when the catalog was not generated from the input image, it often happens that the image does not have data over some of the points.
When the given center of a crop falls in such regions or outside the dataset, and this option has a non-zero value, no crop will be created. 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. You can check which crops were created and which were not from the command-line (if --quiet was not called, see Operating mode options), or in Crop’s log file (see Crop output).
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. This option only applies only in Image mode, see Crop modes.
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.
GNU Astronomy Utilities 0.23 manual, July 2024.