---

4.1.2.1 Input/Output options ¶

These options are to do with the input and outputs of the various programs.

--stdintimeout ¶

Number of micro-seconds to wait for writing/typing in the first line of standard input from the command-line (see Standard input). This is only relevant for programs that also accept input from the standard input, and you want to manually write/type the contents on the terminal. When the standard input is already connected to a pipe (output of another program), there will not be any waiting (hence no timeout, thus making this option redundant).

If the first line-break (for example, with the ENTER key) is not provided before the timeout, the program will abort with an error that no input was given. Note that this time interval is only for the first line that you type. Once the first line is given, the program will assume that more data will come and accept rest of your inputs without any time limit. You need to specify the ending of the standard input, for example, by pressing CTRL-D after a new line.

Note that any input you write/type into a program on the command-line with Standard input will be discarded (lost) once the program is finished. It is only recoverable manually from your command-line (where you actually typed) as long as the terminal is open. So only use this feature when you are sure that you do not need the dataset (or have a copy of it somewhere else).

-h STR/INT ¶

--hdu=STR/INT ¶

The name or number of the desired Header Data Unit, or HDU, in the FITS image. A FITS file can store multiple HDUs or extensions, each with either an image or a table or nothing at all (only a header). Note that counting of the extensions starts from 0(zero), not 1(one). Counting from 0 is forced on us by CFITSIO which directly reads the value you give with this option (see CFITSIO). When specifying the name, case is not important so IMAGE, image or ImAgE are equivalent.

CFITSIO has many capabilities to help you find the extension you want, far beyond the simple extension number and name. See CFITSIO manual’s “HDU Location Specification” section for a very complete explanation with several examples. A # is appended to the string you specify for the HDU¹⁰⁸ and the result is put in square brackets and appended to the FITS file name before calling CFITSIO to read the contents of the HDU for all the programs in Gnuastro.

Default HDU is HDU number 1 (counting from 0): by default, Gnuastro’s programs assume that their (main/first) input is in HDU number 1 (counting from zero). So if you don’t specify the HDU number, the program will read the input from this HDU. For programs that can take multiple FITS datasets as input (like Arithmetic) this default HDU applies to the first input, you still need to call --hdu for the other inputs. Generally, all Gnuastro’s programs write their outputs in HDU number 1 (HDU 0 is reserved for metadata like the configuration parameters that the program was run with). For more on this, see Fits.

-s STR ¶

--searchin=STR ¶

Where to match/search for columns when the column identifier was not a number, see Selecting table columns. The acceptable values are name, unit, or comment. This option is only relevant for programs that take table columns as input.

-I ¶

--ignorecase ¶

Ignore case while matching/searching column meta-data (in the field specified by the --searchin). The FITS standard suggests to treat the column names as case insensitive, which is strongly recommended here also but is not enforced. This option is only relevant for programs that take table columns as input.

This option is not relevant to BuildProgram, hence in that program the short option -I is used for include directories, not to ignore case.

-o STR ¶

--output=STR ¶

The name of the output file or directory. With this option the automatic output names explained in Automatic output are ignored.

-T STR ¶

--type=STR ¶

The data type of the output depending on the program context. This option is not applicable to some programs like Fits and will be ignored by them. The different acceptable values to this option are fully described in Numeric data types.

-D ¶

--dontdelete ¶

By default, if the output file already exists, Gnuastro’s programs will silently delete it and put their own outputs in its place. When this option is activated, if the output file already exists, the programs will not delete it, will warn you, and will abort.

-K ¶

--keepinputdir ¶

In automatic output names, do not remove the directory information of the input file names. As explained in Automatic output, if no output name is specified (with --output), then the output name will be made in the existing directory based on your input’s file name (ignoring the directory of the input). If you call this option, the directory information of the input will be kept and the automatically generated output name will be in the same directory as the input (usually with a suffix added). Note that his is only relevant if you are running the program in a different directory than the input data.

-t STR ¶

--tableformat=STR ¶

The output table’s type. This option is only relevant when the output is a table and its format cannot be deduced from its filename. For example, if a name ending in .fits was given to --output, then the program knows you want a FITS table. But there are two types of FITS tables: FITS ASCII, and FITS binary. Thus, with this option, the program is able to identify which type you want. The currently recognized values to this option are:

--wcslinearmatrix=STR ¶

Select the linear transformation matrix of the output’s WCS. This option only takes two values: pc (for the PCi_j formalism) and cd (for CDi_j). For more on the different formalisms, please see Section 8.1 of the FITS standard¹⁰⁹, version 4.0.

In short, in the PCi_j formalism, we only keep the linear rotation matrix in these keywords and put the scaling factor (or the pixel scale in astronomical imaging) in the CDELTi keywords. In the CDi_j formalism, we blend the scaling into the rotation into a single matrix and keep that matrix in these FITS keywords. By default, Gnuastro uses the PCi_j formalism, because it greatly helps in human readability of the raw keywords and is also the default mode of WCSLIB. However, in some circumstances it may be necessary to have the keywords in the CD format; for example, when you need to feed the outputs into other software that do not follow the full FITS standard and only recognize the CDi_j formalism.

txt

A plain text table with white-space characters between the columns (see Gnuastro text table format).

fits-ascii

A FITS ASCII table (see Recognized table formats).

fits-binary

A FITS binary table (see Recognized table formats).

--outfitsnoconfig ¶

Do not write any of the program’s metadata (option values or versions and dates) into the 0-th HDU of the output FITS file, see Output FITS files.

--outfitsnodate ¶

Do not write the DATE or DATEUTC keywords into the 0-th HDU of the output FITS file, see Output FITS files.

--outfitsnocommit ¶

Do not write the COMMIT keyword into the 0-th HDU of the output FITS file, see Output FITS files.

--outfitsnoversions ¶

Do not write the versions of any dependency software into the 0-th HDU of the output FITS file, see Output FITS files.