---

12.3.9 Array input output ¶

Getting arrays (commonly images or cubes) from a file into your program or writing them after the processing into an output file are some of the most common operations. The functions in this section are designed for such operations with the known file types. The functions here are thus just wrappers around functions of lower-level file type functions of this library, for example, FITS files (fits.h) or TIFF files (tiff.h). If the file type of the input/output file is already known, you can use the functions in those sections respectively.

Function:
int
gal_array_name_recognized (char *filename) ¶

Return 1 if the given file name corresponds to one of the recognized file types for reading arrays.

Function:
int
gal_array_name_recognized_multiext (char *filename) ¶

Return 1 if the given file name corresponds to one of the recognized file types for reading arrays which may contain multiple extensions (for example FITS or TIFF) formats.

Function:
int
gal_array_file_recognized (char *filename) ¶

Similar to gal_array_name_recognized, but for FITS files, it will also check the contents of the file if the recognized file name suffix is not found. See the description of gal_fits_file_recognized for more (FITS Macros, errors and filenames).

Function:
gal_data_t
gal_array_read (char *filename, char *extension, gal_list_str_t *lines, size_t minmapsize, int quietmmap, char *hdu_option_name) ¶

Read the array within the given extension (extension) of filename, or the lines list (see below). If the array is larger than minmapsize bytes, then it will not be read into RAM, but a file on the HDD/SSD (no difference for the programmer). Messages about the memory-mapped file can be disabled with quietmmap.

extension will be ignored for files that do not support them (for example JPEG or text). For FITS files, extension can be a number or a string (name of the extension), but for TIFF files, it has to be number. In both cases, counting starts from zero.

For multi-channel formats (like RGB images in JPEG or TIFF), this function will return a List of gal_data_t: one data structure per channel. Thus if you just want a single array (and want to check if the user has not given a multi-channel input), you can check the next pointer of the returned gal_data_t.

lines is a list of strings with each node representing one line (including the new-line character), see List of strings. It will mostly be the output of gal_txt_stdin_read, which is used to read the program’s input as separate lines from the standard input (see Text files (txt.h)). Note that filename and lines are mutually exclusive and one of them must be NULL.

hdu_option_name is used in error messages related to extensions (e.g., HDUs in FITS) and is expected to be the command-line option name that users of your program can specify to select an input HDU for this particular input; for example, if the kernel is used as the input, users should determine --khdu for this option. If the given extension doesn’t exist in filename, a descriptive error message is printed instructing the users how to find and fix the problem. This error message also suggests the option to use in order to help users of your program to inform them what option they should give a HDU to. If you don’t have an option that is configured by the users of your program, you can set this to NONE or NULL.

Function:
void
gal_array_read_to_type (char *filename, char *extension, gal_list_str_t *lines, uint8_t type, size_t minmapsize, int quietmmap, char *hdu_option_name) ¶

Similar to gal_array_read, but the output data structure(s) will have a numeric data type of type, see Numeric data types.

Function:
void
gal_array_read_one_ch (char *filename, char *extension, gal_list_str_t *lines, size_t minmapsize, int quietmmap, char *hdu_option_name) ¶

Read the dataset within filename (extension/hdu/dir extension) and make sure it is only a single channel. This is just a simple wrapper around gal_array_read that checks if there was more than one dataset and aborts with an informative error if there is more than one channel in the dataset.

Formats like JPEG or TIFF support multiple channels per input, but it may happen that your program only works on a single dataset. This function can be a convenient way to make sure that the data that comes into your program is only one channel.

Regarding *hdu_option_name, see the description for the same argument in the description of gal_array_read.

Function:
void
gal_array_read_one_ch_to_type (char *filename, char *extension, gal_list_str_t *lines, uint8_t type, size_t minmapsize, int quietmmap, char *hdu_option_name) ¶

Similar to gal_array_read_one_ch, but the output data structure will has a numeric data type of type, see Numeric data types.