# The "foreign" Package

These routines convert between the Karma data format and foreign data formats.

Library: karma
Link With: -lkarma

#### Functions

foreign_aips1_read_dataset_names | Get the names of AIPS1 datasets in the directory catalogue.
foreign_aips1_read | Read an AIPS dataset.
foreign_aips1_read_header | Read an AIPS dataset header.
foreign_aips1_read_data | Read data in an AIPS file.
foreign_aips1_read_history | Read history for an AIPS file.
foreign_aips1_close_data_context | Close a KAIPS1DataContext object.
foreign_aips2_test | Test if a directory is an AIPS++ Image file.
foreign_aips2_run | Fork and execute a programme.
foreign_drao_read_dataset_names | Get the names of DRAO datasets in the directory catalogue.
foreign_drao_read | Read a DRAO dataset.
foreign_drao_read_header | Read a DRAO dataset header.
foreign_drao_read_data | Read data in a DRAO file.
foreign_drao_rewind_data_context | Rewind a KDRAODataContext object.
foreign_drao_close_data_context | Close a KDRAODataContext object.
foreign_filter_get_format | Get the filter format
foreign_filter_test_directory_dataset | Test if a directory is a dataset.
foreign_filter_get_channel | Get the channel for a filtered file.
foreign_filter_read | Read a filtered file.
foreign_filter_register | Register a filter.
foreign_fits_read_header | Read a FITS header.
foreign_fits_read | Read a FITS file.
foreign_fits_read_data | Read data in a FITS file.
foreign_fits_write | Write a FITS file to a channel.
foreign_fits_write_iarray | Write a FITS file to a channel.
foreign_fits_write_header | Write a FITS header to a channel object.
foreign_fits_write_data | Write data to a FITS file.
foreign_fits_write_padding | Write trailing pad bytes up to the card end.
foreign_gildas_read | Read a GILDAS dataset.
foreign_gildas_read_header | Read a GILDAS dataset header.
foreign_gildas_read_data | Read data in a GILDAS file.
foreign_gildas_close_data_context | Close a KGILDASDataContext object.
foreign_gipsy_test | Test if a file is part of a GIPSY file set.
foreign_gipsy_read_header | Read a GIPSY file header.
foreign_gipsy_read_data | Read data in a GIPSY image file.
foreign_gipsy_read | Read a GIPSY file set.
foreign_gipsy_write | Write a GIPSY file.
foreign_gipsy_write_iarray | Write a GIPSY file.
foreign_gipsy_write_header | Write a GIPSY header.
foreign_guess_and_read | Guess file type and read.
foreign_read_and_setup | Read a file and perform some setup.
foreign_guess_write | Write a data structure, guessing the output format.
foreign_idf_test | Test if a file is part of an IDF file set.
foreign_idf_read_header | Read an IDF file header.
foreign_idf_read_data | Read data in an IDF image file.
foreign_idf_read | Read an IDF file set.
foreign_iraf_read | Read an IRAF dataset.
foreign_iraf_read_header | Read an IRAF dataset header.
foreign_iraf_read_data | Read data in an IRAF file.
foreign_iraf_close_data_context | Close a KIRAFDataContext object.
foreign_miriad_test2 | Test if a directory is a Miriad Image file.
foreign_miriad_read_header2 | Read a Miriad Image or Visibility file header.
foreign_miriad_read | Read a Miriad image file.
foreign_miriad_create_data_context | Create a context suitable for reading Miriad Image data.
foreign_miriad_read_data | Read data in a Miriad Image file.
foreign_miriad_close_data_context | Close a KMiriadDataContext object.
foreign_miriad_read_history | Read the history component of a Miriad Image file.
foreign_miriad_read_get_alignment_padding | Compute padding to align to a word boundary.
foreign_miriad_write | Write a Miriad Image file.
foreign_miriad_write_iarray | Write a Miriad Image file.
foreign_miriad_write_header_entry | Write a Miriad header entry.
foreign_guess_format_from_filename | Attempt to guess the format of a file by examining its filename.
foreign_pgm_read | Read a colour image in PGM format from a channel.
foreign_pnm_read_type | Read the type of a PNM file.
foreign_pnm_read | Read a PNM file.
foreign_pnm_read2 | Read a PNM file.
foreign_ppm_read | Read a colour image in PPM format from a channel.
foreign_ppm_write | Write a colour image to a channel in PPM format.
foreign_ppm_write_pseudo | Write a PseudoColor image to a channel in PPM format.
foreign_ppm_write_rgb | Write a TrueColor image to a channel in PPM format.
foreign_sunras_read | Read an image in Sun rasterfile format from a channel.
foreign_sunras_write | Write a colour image to a channel in Sun rasterfile format.
foreign_sunras_write_pseudo | Write a PseudoColor image to a channel in Sun rasterfile format.
foreign_sunras_write_rgb | Write a TrueColor image to a channel in Sun rasterfile format.

#### Tables

foreign_ATT_FITS_READ_HEADER | List of attributes for reading FITS headers
foreign_ATT_FITS_READ_DATA | List of attributes for reading FITS data
foreign_ATT_FITS_READ | List of attributes for reading FITS files (header+data)
foreign_ATT_FITS_WRITE | List of attributes for writing FITS files (header+data)
foreign_ATT_FITS_WRITE_DATA | List of attributes for writing FITS data
foreign_ATT_GUESS_READ | List of attributes for guessing and reading data
foreign_ATT_GUESS_WRITE | List of attributes for guessing and writing data
foreign_ATT_MIRIAD_READ_HEADER | List of attributes for reading Miriad Image headers
foreign_ATT_MIRIAD_READ_DATA | List of attributes for reading Miriad Image data
foreign_ATT_MIRIAD_READ | List of attributes for reading Miriad Image files
foreign_ATT_MIRIAD_WRITE | List of attributes for writing Miriad Image files
foreign_ATT_GIPSY_READ_HEADER | List of attributes for reading GIPSY Image headers
foreign_ATT_GIPSY_READ_DATA | List of attributes for reading GIPSY Image data
foreign_ATT_GIPSY_READ | List of attributes for reading GIPSY Image files
foreign_ATT_GIPSY_WRITE | List of attributes for writing GIPSY Image files
foreign_ATT_GIPSY_WRITE_HEADER | List of attributes for writing GIPSY Image file headers
foreign_TYPES | List of foreign file types
foreign_ATT_PPM_WRITE | List of attributes for writing PPM files
foreign_ATT_PPM_READ | List of attributes for reading PPM files
foreign_ATT_PGM_READ | List of attributes for reading PGM files
foreign_ATT_SUNRAS_READ | List of attributes for reading Sun Rasterfile files
foreign_ATT_SUNRAS_WRITE | List of attributes for writing Sun Rasterfile files
foreign_ATT_IDF_READ_HEADER | List of attributes for reading IDF headers
foreign_ATT_IDF_READ_DATA | List of attributes for reading IDF data
foreign_ATT_IDF_READ | List of attributes for reading IDF files (header+data)
foreign_ATT_DRAO_READ_HEADER | List of attributes for reading DRAO headers
foreign_ATT_DRAO_READ | List of attributes for reading DRAO files (header+data)

## Functions

#### EXPERIMENTAL FUNCTION: subject to change without notice

CONST char * foreign_aips1_read_dataset_names (CONST char *dirname, unsigned int *num_datasets)

This routine will read the "CA*.???;*" catalogue file in the specified directory and extracts the names of the datasets. The "AIPS_ID" environment variable should be set to your AIPS user ID.

Parameters:

- dirname : The directory containing the catalogue file.
- num_datasets : The number of datasets found is written here.

Returns: A pointer to a buffer packed with dataset names. Each dataset name is separated by a '\0' character. The buffer is internally allocated and must not be freed. If no datasets are found NULL is returned.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_aips1_read (CONST char *setname)

Read an AIPS dataset.

Parameters:

- setname : The AIPS dataset name.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_aips1_read_header (CONST char *setname, flag data_alloc, KAIPS1DataContext *context)

Read an AIPS dataset header.

Parameters:

- setname : The AIPS dataset name.
- data_alloc : If TRUE, the data space is allocated.
- context : The data reading context is written here, to be used in subsequent calls to foreign_aips1_read_data. This may be NULL.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_aips1_read_data (KAIPS1DataContext context, char *data, uaddr num_values)

This routine will read the data of an AIPS dataset from a KAIPS1DataContext object. The header section is NOT read.

Parameters:

- context : The context to read from.
- data : The array to write the data into. If this is NULL, input data are skipped and nothing is written.
- num_values : The number of values to read.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_aips1_read_history (KAIPS1DataContext context, multi_array *multi_desc)

Read history for an AIPS file.

Parameters:

- context : The context to read from.
- multi_desc : The multi_array object to write the history to.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void foreign_aips1_close_data_context (KAIPS1DataContext context)

Close a KAIPS1DataContext object.

Parameters:

- context : The context.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_aips2_test (CONST char *dirname, flag test_dir)

Test if a directory is an AIPS++ Image file.

Parameters:

- dirname : The directory name of the AIPS++ dataset name.
- test_dir : If TRUE will first test if the dataset name is a directory. Set this to FALSE only if you know the dataset name is a directory.

Returns: TRUE if the directory is a AIPS++ Image file, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

pid_t foreign_aips2_run (CONST char *filename, int stdout_fd, int close_fd, int *waitflags)

Fork and execute a programme.

Parameters:

- filename : The input filename for the programme.
- stdout_fd : The output file descriptor.
- close_fd : The file descriptor to close.
- waitflags : Special flags to pass to waitpid(2) are written here.

Returns: The child process ID on success, else -1.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

CONST char * foreign_drao_read_dataset_names (CONST char *dirname, unsigned int *num_datasets, unsigned int *max_width)

This routine will read the "deffil.mad" catalogue file in the specified directory and extracts the names of the datasets.

Parameters:

- dirname : The directory containing the catalogue file.
- num_datasets : The number of datasets found is written here.
- max_width : The width of the longest dataset name is written here. This may be NULL.

Returns: A pointer to a buffer packed with dataset names. Each dataset name is separated by a '\0' character. The buffer is internally allocated and must not be freed. If no datasets are found NULL is returned.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_drao_read (CONST char *setname, flag convert_int_to_float, ...)

Read a DRAO dataset.

Parameters:

- setname : The DRAO dataset name.
- convert_int_to_float : If TRUE, integer data are converted to floating point data.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_DRAO_READ_END. See foreign_ATT_DRAO_READ for a list of defined attributes.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_drao_read_header (CONST char *setname, flag data_alloc, flag convert_int_to_float, KDRAODataContext *context, ...)

Read a DRAO dataset header.

Parameters:

- setname : The DRAO dataset name.
- data_alloc : If TRUE, the data space is allocated.
- convert_int_to_float : If TRUE, integer data are converted to floating point data.
- context : The data reading context is written here, to be used in subsequent calls to foreign_drao_read_data. This may be NULL.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_DRAO_READ_HEADER_END. See foreign_ATT_DRAO_READ_HEADER for a list of defined attributes.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_drao_read_data (KDRAODataContext context, char *data, uaddr num_values)

This routine will read the data of a DRAO dataset from a KDRAODataContext object. The header section is NOT read.

Parameters:

- context : The context to read from.
- data : The array to write the data into. If this is NULL, input data is skipped and nothing is written.
- num_values : The number of values to read.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void foreign_drao_rewind_data_context (KDRAODataContext context)

Rewind a KDRAODataContext object.

Parameters:

- context : The context.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void foreign_drao_close_data_context (KDRAODataContext context)

Close a KDRAODataContext object.

Parameters:

- context : The context.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

unsigned int foreign_filter_get_format (CONST char *filename)

Get the filter format

Parameters:

- filename : The name of the file.

Returns: A value indicating the format of the file. The value FOREIGN_FILE_FORMAT_FILTER_KARMA is returned if a data filter to Karma for the file exists. The value FOREIGN_FILE_FORMAT_FILTER_FITS is returned if a data filter to FITS exists. Otherwise FOREIGN_FILE_FORMAT_UNKNOWN is returned.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_filter_test_directory_dataset (CONST char *dirname)

Test if a directory is a dataset.

Parameters:

- dirname : The name of the directory.

Returns: TRUE if the directory is a dataset, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

Channel foreign_filter_get_channel (CONST char *filename)

Get the channel for a filtered file.

Parameters:

- filename : The filename to read.

Returns: A channel object on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_filter_read (CONST char *filename)

Read a filtered file.

Parameters:

- filename : The filename to read.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_filter_register (CONST char *extension,CONST char *converter_prog, pid_t (*run) (CONST char *filename, int stdout_fd, int close_fd, int *waitflags), CONST char *tester_prog, flag (*tester_func) (CONST char *dirname, flag test_dir), unsigned int output_type, CONST char *name)

Register a filter.

Parameters:

- extension : The filename extension. If NULL, the file format is a directory dataset.
- converter_prog : The programme used to convert data.
- run : The function used to run a new programme.
- tester_prog : The programme used to test the data.
- tester_func : The function used to test the data.
- output_type : The output type of the converter.
- name : The name of the data format.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

multi_array * foreign_fits_read_header (Channel channel, flag data_alloc, flag convert_int_to_float, flag sanitise, ...)

This routine will read the header of a FITS file from a channel. The data section is NOT read.

Parameters:

- channel : The channel to read from.
- data_alloc : If TRUE, the data space is allocated.
- convert_int_to_float : If TRUE, integer FITS data is converted to floating point data.
- sanitise : If TRUE, FITS axes with length 1 are ignored. This is highly recommended.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_FITS_READ_HEADER_END. See foreign_ATT_FITS_READ_HEADER for a list of defined attributes.

Returns: A pointer to the multi_array data structure on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_fits_read (CONST char *filename, flag convert_int_to_float, flag sanitise, ...)

Read a FITS file.

Parameters:

- filename : The name of the file.
- convert_int_to_float : If TRUE, integer FITS data is converted to floating point data.
- sanitise : If TRUE, FITS axes with length 1 are ignored. This is highly recommended.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_FITS_READ_END. See foreign_ATT_FITS_READ for a list of defined attributes.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

flag foreign_fits_read_data (Channel channel, multi_array *multi_desc, char *data, uaddr num_values, ...)

This routine will read the data of a FITS file from a channel. The header section is NOT read.

Parameters:

- channel : The channel to read from.
- multi_desc : The Karma data structure to write the data into.
- data : An alternate data array to write the FITS data into. If this is NULL, the routine will write the data into the Karma data structure.
- num_values : The number of values to write into the data array. This is used when data is not NULL or skipping is requested.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_FITS_READ_DATA_END. See foreign_ATT_FITS_READ_DATA for a list of defined attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag foreign_fits_write (Channel channel, multi_array *multi_desc, ...)

This routine will write a Karma data structure to a FITS file. The routine will automatically generate essential keywords such as: "NAXIS", "NAXISn", "CTYPEn", "CRVALn", "CRPIXn", "CDELTn", "BITPIX", "BUNIT", "BSCALE" and "BZERO". Also, existing keywords in the data structure which do not conflict with the generated keywords are copied.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- multi_desc : The multi_array descriptor pointer. The routine will find a n-dimensional array within the data structure.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_FITS_WRITE_END. See foreign_ATT_FITS_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

flag foreign_fits_write_iarray (Channel channel, iarray array, ...)

This routine will write an Intelligent Array to a FITS file. The routine will automatically generate essential keywords such as: "NAXIS", "NAXISn", "CTYPEn", "CRVALn", "CRPIXn", "CDELTn", "BITPIX", "BUNIT", "BSCALE" and "BZERO". Also, existing keywords in the data structure which do not conflict with the generated keywords are copied.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- array : The Intelligent Array.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_FITS_WRITE_END. See foreign_ATT_FITS_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_fits_write_header (Channel channel, CONST multi_array *multi_desc, CONST history *first_hist)

Write a FITS header to a channel object.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- multi_desc : The new header descriptor.
- first_hist : The first history string. This may be NULL. After this history is appended, any history from multi_desc is appended.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_fits_write_data (Channel channel, multi_array *multi_desc, CONST packet_desc *header_pack_desc, CONST char *header_packet, char *data, uaddr num_values, ...)

This routine will write the data section of a FITS file to a channel. The header section is NOT written.

Parameters:

- channel : The channel to write to.
- multi_desc : The Karma data structure containing the data.
- header_pack_desc : The header packet descriptor.
- header_packet : The header packet data.
- data : An alternate data array to read the data from. If this is NULL, the routine will read the data from the Karma data structure.
- num_values : The number of values to write to the FITS file. This is only used when data is not NULL.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_FITS_WRITE_DATA_END. See foreign_ATT_FITS_WRITE_DATA for a list of defined attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_fits_write_padding (Channel channel)

Write trailing pad bytes up to the card end.

Parameters:

- channel : The channel to write to.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_gildas_read (CONST char *setname,unsigned int mmap_option, flag writable)

Read a GILDAS dataset.

Parameters:

- setname : The GILDAS dataset name.
- mmap_option : Control value which determines whether the channel is opened as an ordinary disc file or is mapped. See ch_MAP_CONTROLS for legal values. If the file is not mapped then the routine will attempt to open an ordinary disc channel. If the file is opened as a disc channel the access mode is: "rz".
- writable : If the mapped pages are to be writable, this must be TRUE. If this is FALSE and the memory pages are written to, a segmentation fault occurs.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_gildas_read_header (CONST char *setname, flag data_alloc, unsigned int mmap_option, flag writable, KGILDASDataContext *context)

Read a GILDAS dataset header.

Parameters:

- setname : The GILDAS dataset name.
- data_alloc : If TRUE, the data space is allocated.
- mmap_option : Control value which determines whether the channel is opened as an ordinary disc file or is mapped. See ch_MAP_CONTROLS for legal values. If the file is not mapped then the routine will attempt to open an ordinary disc channel. If the file is opened as a disc channel the access mode is: "rz".
- writable : If the mapped pages are to be writable, this must be TRUE. If this is FALSE and the memory pages are written to, a segmentation fault occurs.
- context : The data reading context is written here, to be used in subsequent calls to foreign_gildas_read_data. This may be NULL.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_gildas_read_data (KGILDASDataContext context, char *data, uaddr num_values)

This routine will read the data of a GILDAS dataset from a KGILDASDataContext object. The header section is NOT read.

Parameters:

- context : The context to read from.
- data : The array to write the data into. If this is NULL, input data are skipped and nothing is written.
- num_values : The number of values to read.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void foreign_gildas_close_data_context (KGILDASDataContext context)

Close a KGILDASDataContext object.

Parameters:

- context : The context.

Returns: Nothing.
Multithreading Level: Unsafe

flag foreign_gipsy_test (CONST char *filename)

Test if a file is part of a GIPSY file set.

Parameters:

- filename : The name of any file in the GIPSY file set.

Returns: TRUE if the file is part of a GIPSY file set, else FALSE.
Multithreading Level: Unsafe

multi_array * foreign_gipsy_read_header (Channel channel, flag data_alloc, flag sanitise, ...)

This routine will read the header of a GIPSY file from a channel. The data section is NOT read.

Parameters:

- channel : The channel to read from.
- data_alloc : If TRUE, the data space is allocated.
- sanitise : If TRUE, GIPSY axes with length 1 are ignored. This is highly recommended.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_GIPSY_READ_HEADER_END. See foreign_ATT_GIPSY_READ_HEADER for a list of defined attributes.

Returns: A pointer to the multi_array data structure on success, else NULL.
Multithreading Level: Unsafe

flag foreign_gipsy_read_data (Channel channel, multi_array *multi_desc, char *data, uaddr num_values, ...)

This routine will read the data of a GIPSY image file from a channel.

Parameters:

- channel : The channel to read from.
- multi_desc : The Karma data structure to write the data into.
- data : An alternate data array to write the FITS data into. If this is NULL, the routine will write the data into the Karma data structure.
- num_values : The number of values to write into the data array. This is used when data is not NULL or skipping is requested.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_GIPSY_READ_DATA_END. See foreign_ATT_GIPSY_READ_DATA for a list of defined attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

multi_array * foreign_gipsy_read (CONST char *filename, flag sanitise, ...)

Read a GIPSY file set.

Parameters:

- filename : The name of any file in the GIPSY file set.
- sanitise : If TRUE, GIPSY axes with length 1 are ignored. This is highly recommended.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_GIPSY_READ_END. See foreign_ATT_GIPSY_READ for a list of defined attributes.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

flag foreign_gipsy_write (CONST char *basename, multi_array *multi_desc, ...)

This routine will write a Karma data structure to a GIPSY file. The routine will automatically generate essential keywords such as: "NAXIS", "NAXISn", "CTYPEn", "CRVALn", "CRPIXn", "CDELTn", "BUNIT", "BSCALE" and "BZERO". Also, existing keywords in the data structure which do not conflict with the generated keywords are copied.

Parameters:

- basename : The base filename of the GIPSY file. The ".descr" and ".image" extensions are added automatically.
- multi_desc : The multi_array descriptor pointer. The routine will find a n-dimensional array within the data structure.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_GIPSY_WRITE_END. See foreign_ATT_GIPSY_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

flag foreign_gipsy_write_iarray (CONST char *basename, iarray array, ...)

This routine will write an Intelligent Array to a GIPSY file. The routine will automatically generate essential keywords such as: "NAXIS", "NAXISn", "CTYPEn", "CRVALn", "CRPIXn", "CDELTn", "BITPIX", "BUNIT", "BSCALE" and "BZERO". Also, existing keywords in the data structure which do not conflict with the generated keywords are copied.

Parameters:

- basename : The base filename of the GIPSY file. The ".descr" and ".image" extensions are added automatically.
- array : The Intelligent Array.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_GIPSY_WRITE_END. See foreign_ATT_GIPSY_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_gipsy_write_header (Channel channel, CONST packet_desc *header_pack_desc, CONST char *header_packet, ...)

Write a GIPSY header.

Parameters:

- channel : The channel object to write the header to.
- header_desc : The FITS-style header packet descriptor.
- header_packet : The FITS-style header packet data.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_GIPSY_WRITE_HEADER_END. See foreign_ATT_GIPSY_WRITE_HEADER for a list of defined attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

multi_array * foreign_guess_and_read (CONST char *filename, unsigned int mmap_option, flag writable, unsigned int *ftype, ...)

This routine will attempt to guess the filetype of a file and in the file, converting to the Karma data format if possible.

Parameters:

- filename : The name of the file to read.
- mmap_option : This has the same meaning as for the routine.
- writable : This has the same meaning as for the routine.
- ftype : The type of the file that was read in is written here. This may be NULL.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must terminated with FA_GUESS_READ_END. See foreign_ATT_GUESS_READ for a list of defined attributes.

Returns: A pointer to the multi_array data structure on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_read_and_setup (CONST char *filename, unsigned int mmap_option, flag writable, unsigned int *ftype, flag inform, unsigned int num_dim, unsigned int preferred_type, flag force_type, iarray *array, double *min, double *max, flag discard_zero_range, KwcsAstro *ap)

This routine will attempt to guess the filetype of a file and in the file, converting to an Intelligent Array if possible. The routine then performs some simple checks and some other convenience functions.

Parameters:

- filename : The name of the file to read.
- mmap_option : This has the same meaning as for the routine.
- writable : This has the same meaning as for the routine.
- ftype : The type of the file that was read in is written here. This may be NULL.
- inform : If TRUE, the routine displays some informative messages.
- num_dim : The number of dimensions required. If this is 0, any number of dimensions is allowed.
- preferred_type : The preferred data type. If this is NONE, then no type is preferred.
- force_type : If TRUE, the routine fails if the preferred data type was not available.
- array : The Intelligent Array is written here. An existing array pointed to by this is deallocated.
- min : The minimum data value in the array is written here. If this is NULL nothing is written here.
- max : The maximum data value in the array is written here. If this is NULL nothing is written here.
- discard_zero_range : If TRUE, and the range of the data is zero, the routine fails.
- ap : The KwcsAstro object is written here. This may be NULL.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_guess_write (CONST char *filename, multi_array *multi_desc, ...)

Write a data structure, guessing the output format.

Parameters:

- filename : The name of the dataset to write.
- multi_desc : The multi_array descriptor pointer. The routine will find a n-dimensional array within the data structure.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_FITS_GUESS_END. See foreign_ATT_GUESS_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_idf_test (CONST char *filename)

Test if a file is part of an IDF file set.

Parameters:

- filename : The name of the ".idf" header file in the IDF file set.

Returns: TRUE if the file is part of an IDF file set, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_idf_read_header (Channel channel, flag data_alloc, flag sanitise, ...)

This routine will read the header of an IDF file from a channel. The data section is NOT read.

Parameters:

- channel : The channel to read from.
- data_alloc : If TRUE, the data space is allocated.
- sanitise : If TRUE, IDF axes with length 1 are ignored. This is highly recommended.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_IDF_READ_HEADER_END. See foreign_ATT_IDF_READ_HEADER for a list of defined attributes.

Returns: A pointer to the multi_array data structure on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_idf_read_data (Channel channel, multi_array *multi_desc, char *data, uaddr num_values, ...)

This routine will read the data of an IDF image file from a channel.

Parameters:

- channel : The channel to read from.
- multi_desc : The Karma data structure to write the data into.
- data : An alternate data array to write the FITS data into. If this is NULL, the routine will write the data into the Karma data structure.
- num_values : The number of values to write into the data array. This is used when data is not NULL or skipping is requested.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_IDF_READ_DATA_END. See foreign_ATT_IDF_READ_DATA for a list of defined attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_idf_read (CONST char *filename, flag sanitise, ...)

Read an IDF file set.

Parameters:

- filename : The name of the ".idf" header file in the IDF file set.
- sanitise : If TRUE, IDF axes with length 1 are ignored. This is highly recommended.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_IDF_READ_END. See foreign_ATT_IDF_READ for a list of defined attributes.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_iraf_read (CONST char *setname)

Read an IRAF dataset.

Parameters:

- setname : The IRAF dataset name.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_iraf_read_header (CONST char *setname, flag data_alloc, KIRAFDataContext *context)

Read an IRAF dataset header.

Parameters:

- setname : The IRAF dataset name.
- data_alloc : If TRUE, the data space is allocated.
- context : The data reading context is written here, to be used in subsequent calls to foreign_iraf_read_data. This may be NULL.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_iraf_read_data (KIRAFDataContext context, char *data, uaddr num_values)

This routine will read the data of an IRAF dataset from a KIRAFDataContext object. The header section is NOT read.

Parameters:

- context : The context to read from.
- data : The array to write the data into. If this is NULL, input data is skipped and nothing is written.
- num_values : The number of values to read.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void foreign_iraf_close_data_context (KIRAFDataContext context)

Close a KIRAFDataContext object.

Parameters:

- context : The context.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_miriad_test2 (CONST char *dirname, flag test_dir)

Test if a directory is a Miriad Image file.

Parameters:

- dirname : The directory name of the Miriad dataset name.
- test_dir : If TRUE will first test if the dataset name is a directory. Set this to FALSE only if you know the dataset name is a directory.

Returns: TRUE if the directory is a Miriad Image file, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_miriad_read_header2 (CONST char *dirname, flag data_alloc, flag sanitise, ...)

This routine will read the header of a Miriad Image file from a channel. The data section is NOT read.

Parameters:

- dirname : The directory name of the Miriad dataset name.
- data_alloc : If TRUE, the data space is allocated.
- sanitise : If TRUE, Miriad axes with length 1 are ignored. This is highly recommended.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_MIRIAD_READ_HEADER_END. See foreign_ATT_MIRIAD_READ_HEADER for a list of defined attributes.

Returns: A pointer to the multi_array data structure on success, else NULL.
Multithreading Level: Unsafe

multi_array * foreign_miriad_read (CONST char *dirname, flag sanitise, ...)

Read a Miriad image file.

Parameters:

- dirname : The directory name of the Miriad dataset name.
- sanitise : If TRUE, Miriad axes with length 1 are ignored. This is highly recommended.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_MIRIAD_READ_END. See foreign_ATT_MIRIAD_READ for a list of defined attributes.

Returns: A multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

KMiriadDataContext foreign_miriad_create_data_context (CONST char *dirname, unsigned int mmap_option, flag writable)

This routine will create a context suitable for reading Miriad Image data. The foreign_miriad_read_data routine may be used to read data sequentially from the context.

Parameters:

- dirname : The directory name of the Miriad dataset name.
- mmap_option : Option to control memory mapping when reading from disc. See ch_MAP_CONTROLS for a list of legal values.
- writable : If TRUE, the mapped structure will be writable. When the data structure data is modified these changes will be reflected in the disc file. The shape of the data structure cannot be changed though mapping. If FALSE and the structure is written to, a segmentation fault occurs.

Returns: A KMiriadDataContext object on success, else NULL (indicating the image file could not be read).
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_miriad_read_data (KMiriadDataContext context, multi_array *multi_desc, char *data, uaddr num_values, ...)

This routine will read the data of a Miriad Image file from a KMiradDataContext object. The header section is NOT read.

Parameters:

- context : The context to read from.
- multi_desc : The Karma data structure to write the data into.
- data : An alternate data array to write the data into. If this is NULL, the routine will write the data into the Karma data structure.
- num_values : The number of values to write into the data array. This is used when data is not NULL or skipping is requested.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_MIRIAD_READ_DATA_END. See foreign_ATT_MIRIAD_READ_DATA for a list of defined attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void foreign_miriad_close_data_context (KMiriadDataContext context)

Close a KMiriadDataContext object.

Parameters:

- context : The context.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_miriad_read_history (CONST char *dirname, multi_array *multi_desc)

Read the history component of a Miriad Image file.

Parameters:

- dirname : The directory name of the Miriad dataset name.
- multi_desc : The multi_array header the history will be written to.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

unsigned int foreign_miriad_read_get_alignment_padding (uaddr position, uaddr size)

Compute padding to align to a word boundary.

Parameters:

- position : The current position.
- size : The size of the word in bytes.

Returns: The number of padding bytes required.
Multithreading Level: Unsafe

flag foreign_miriad_write (CONST char *dirname, multi_array *multi_desc, ...)

This routine will write a Karma data structure to a Miriad Image file. The routine will automatically generate essential keywords such as: "NAXIS", "NAXISn", "CTYPEn", "CRVALn", "CRPIXn", "CDELTn", "BUNIT", "BSCALE" and "BZERO". Also, existing keywords in the data structure which do not conflict with the generated keywords are copied.

Parameters:

- dirname : The directory name of the Miriad Image file.
- multi_desc : The multi_array descriptor pointer. The routine will find a n-dimensional array within the data structure.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_MIRIAD_WRITE_END. See foreign_ATT_MIRIAD_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

flag foreign_miriad_write_iarray (CONST char *dirname, iarray array, ...)

This routine will write an Intelligent Array to a Miriad Image file. The routine will automatically generate essential keywords such as: "NAXIS", "NAXISn", "CTYPEn", "CRVALn", "CRPIXn", "CDELTn", "BITPIX", "BUNIT", "BSCALE" and "BZERO". Also, existing keywords in the data structure which do not conflict with the generated keywords are copied.

Parameters:

- dirname : The directory name of the Miriad Image file.
- array : The Intelligent Array.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_MIRIAD_WRITE_END. See foreign_ATT_MIRIAD_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_miriad_write_header_entry (Channel channel, CONST char *name, unsigned int type, unsigned int num_values, CONST char *data)

Write a Miriad header entry.

Parameters:

- channel : The channel to write to.
- name : The name of the header entry.
- type : The type of the data.
- num_values : The number of data values to write.
- data : The data values.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

unsigned int foreign_guess_format_from_filename (CONST char *filename)

Attempt to guess the format of a file by examining its filename.

Parameters:

- filename : The name of the file.

Returns: A value indicating the format of the file. The value FOREIGN_FILE_FORMAT_KARMA is returned if the extension is ".kf". See foreign_TYPES for a list of possible values.
Multithreading Level: Unsafe

multi_array * foreign_pgm_read (Channel channel, ...)

Read a colour image in PGM format from a channel.

Parameters:

- channel : The channel to read from.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_PGM_READ_END. See foreign_ATT_PGM_READ for a list of defined attributes.

Returns: A pointer to the multi_array data structure on success, else NULL
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

unsigned int foreign_pnm_read_type (Channel channel, flag *binary)

Read the type of a PNM file.

Parameters:

- channel : The channel to read from.
- binary : The value TRUE is written here if the file is in binary format, else FALSE is written here.

Returns: The type of PNM file.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_pnm_read (Channel channel)

Read a PNM file.

Parameters:

- channel : The channel to read from.

Returns: A pointer to the multi_array data structure on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_pnm_read2 (CONST char *filename, unsigned int mmap_option, flag writable)

Read a PNM file.

Parameters:

- channel : The channel to read from.
- mmap_option : This has the same meaning as for the routine.
- writable : This has the same meaning as for the routine.

Returns: A pointer to the multi_array data structure on success, else NULL.
Multithreading Level: Unsafe

multi_array * foreign_ppm_read (Channel channel, ...)

Read a colour image in PPM format from a channel.

Parameters:

- channel : The channel to read from.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_PPM_READ_END. See foreign_ATT_PPM_READ for a list of defined attributes.

Returns: A pointer to the multi_array data structure on success, else NULL
Multithreading Level: Unsafe

flag foreign_ppm_write (Channel channel, multi_array *multi_desc, flag binary, ...)

Write a colour image to a channel in PPM format.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- multi_desc : The multi_array descriptor pointer. The routine will find a TrueColour image or a PseudoColour image within the data structure.
- binary : If TRUE, the pixels will be written in binary mode.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_PPM_WRITE_END. See foreign_ATT_PPM_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_ppm_write_pseudo (Channel channel, flag binary, CONST char *image, unsigned int type, uaddr *hoffsets, uaddr *voffsets, unsigned int inp_width, unsigned int inp_height, unsigned int out_width, unsigned int out_height, CONST unsigned short *cmap_reds, CONST unsigned short *cmap_greens, CONST unsigned short *cmap_blues, unsigned int cmap_size, unsigned int min_sat_index, unsigned int max_sat_index, unsigned int blank_index, unsigned int cmap_stride, double i_min, double i_max, flag (*iscale_func) (), void *iscale_info)

Write a PseudoColor image to a channel in PPM format.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- binary : If TRUE, the pixels will be written in binary mode.
- image : The image data.
- type : The type of the image data.
- hoffsets : The array of horizontal byte offsets.
- voffsets : The array of vertical byte offsets.
- inp_width : The width of the input image.
- inp_height : The height of the input image.
- out_width : The width of the output image. If the input image is smaller than this, then the image will be centred with blank-filling. If the input image is larger than this, the image will be truncated. If this is 0, the output image will be the same width as the input image.
- out_height : The height of the output image. If the input image is smaller than this, then the image will be centred with blank-filling. If the input image is larger than this, the image will be truncated. If this is 0, the output image will be the same height as the input image.
- cmap_reds : The red colourmap values.
- cmap_greens : The green colourmap values.
- cmap_blues : The blue colourmap values.
- cmap_size : The number of colourmap entries.
- min_sat_index : The index into the colourmap for the colour to use when data values are below i_min.
- max_sat_index : The index into the colourmap for the colour to use when data values are above i_max.
- blank_index : The index into the colourmap for the colour to use when data values are blank.
- cmap_stride : The stride (in unsigned shorts) between colourmap values.
- i_min : The minimum image value. Image values below this will be clipped.
- i_max : The maximum image value. Image values above this will be clipped.
- iscale_func : The function to be called when non-linear intensity scaling is required. If NULL, linear intensity scaling is used. The prototype function is imw_PROTO_iscale_func.
- iscale_info : A pointer to arbitrary information for iscale_func.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe.

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_ppm_write_rgb (Channel channel, flag binary, CONST unsigned char *image_red, CONST unsigned char *image_green, CONST unsigned char *image_blue, uaddr *hoffsets, uaddr *voffsets, unsigned int inp_width, unsigned int inp_height, unsigned int out_width, unsigned int out_height, CONST unsigned short *cmap_red, CONST unsigned short *cmap_green, CONST unsigned short *cmap_blue, unsigned int cmap_stride)

Write a TrueColor image to a channel in PPM format.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- binary : If TRUE, the pixels will be written in binary mode.
- red_image : The red image data.
- green_image : The green image data.
- blue_image : The blue image data.
- hoffsets : The array of horizontal byte offsets.
- voffsets : The array of vertical byte offsets.
- inp_width : The width of the input image.
- inp_height : The height of the input image.
- out_width : The width of the output image. If the input image is smaller than this, then the image will be centred with blank-filling. If the input image is larger than this, the image will be truncated. If this is 0, the output image will be the same width as the input image.
- out_height : The height of the output image. If the input image is smaller than this, then the image will be centred with blank-filling. If the input image is larger than this, the image will be truncated. If this is 0, the output image will be the same height as the input image.
- cmap_red : The red component colourmap entries. 256 entries required. If this is NULL a linear mapping is assumed.
- cmap_green : The green component colourmap entries. 256 entries required. If this is NULL a linear mapping is assumed.
- cmap_blue : The blue component colourmap entries. 256 entries required. If this is NULL a linear mapping is assumed.
- cmap_stride : The stride (in unsigned shorts) between colourmap values.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe.

multi_array * foreign_sunras_read (Channel channel, ...)

Read an image in Sun rasterfile format from a channel.

Parameters:

- channel : The channel to read from.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_SUNRAS_READ_END. See foreign_ATT_SUNRAS_READ for a list of defined attributes.

Returns: A pointer to the multi_array data structure on success, else NULL
Multithreading Level: Unsafe

flag foreign_sunras_write (Channel channel, multi_array *multi_desc, ...)

Write a colour image to a channel in Sun rasterfile format.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- multi_desc : The multi_array descriptor pointer. The routine will find a TrueColour image or a PseudoColour image within the data structure.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with FA_SUNRAS_WRITE_END. See foreign_ATT_SUNRAS_WRITE for a list of defined attributes.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe.

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_sunras_write_pseudo (Channel channel, CONST char *image, unsigned int type, uaddr *hoffsets, uaddr *voffsets, unsigned int width, unsigned int height, CONST unsigned short *cmap_reds, CONST unsigned short *cmap_greens, CONST unsigned short *cmap_blues, unsigned int cmap_size, unsigned int cmap_stride, double i_min, double i_max)

Write a PseudoColor image to a channel in Sun rasterfile format.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- image : The image data.
- type : The type of the image data.
- hoffsets : The array of horizontal byte offsets.
- voffsets : The array of vertical byte offsets.
- width : The width of the image.
- height : The height of the image.
- cmap_reds : The red colourmap values.
- cmap_greens : The green colourmap values.
- cmap_blues : The blue colourmap values.
- cmap_size : The number of colourmap entries.
- cmap_stride : The stride (in unsigned shorts) between colourmap values.
- i_min : The minimum image value. Image values below this will be clipped.
- i_max : The maximum image value. Image values above this will be clipped.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe.

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag foreign_sunras_write_rgb (Channel channel, CONST unsigned char *image_red, CONST unsigned char *image_green, CONST unsigned char *image_blue, uaddr *hoffsets, uaddr *voffsets, unsigned int width, unsigned int height, CONST unsigned short *cmap_red, CONST unsigned short *cmap_green, CONST unsigned short *cmap_blue, unsigned int cmap_stride)

Write a TrueColor image to a channel in Sun rasterfile format.

Parameters:

- channel : The channel to write to. The channel is not flushed.
- red_image : The red image data.
- green_image : The green image data.
- blue_image : The blue image data.
- hoffsets : The array of horizontal byte offsets.
- voffsets : The array of vertical byte offsets.
- width : The width of the image.
- height : The height of the image.
- cmap_red : The red component colourmap entries. 256 entries required. If this is NULL a linear mapping is assumed.
- cmap_green : The green component colourmap entries. 256 entries required. If this is NULL a linear mapping is assumed.
- cmap_blue : The blue component colourmap entries. 256 entries required. If this is NULL a linear mapping is assumed.
- cmap_stride : The stride (in unsigned shorts) between colourmap values.

Returns: TRUE on succes, else FALSE.
Multithreading Level: Unsafe.

## Tables

foreign_ATT_FITS_READ_HEADER List of attributes for reading FITS headers

Name | Type | Meaning
FA_FITS_READ_HEADER_END |  | End of varargs list
FA_FITS_READ_HEADER_ALLOC_TRUNC | flag | Allow truncated headers

foreign_ATT_FITS_READ_DATA List of attributes for reading FITS data

Name | Type | Meaning
FA_FITS_READ_DATA_END |  | End of varargs list
FA_FITS_READ_DATA_NUM_BLANKS | unsigned long * | Number of blank values found
FA_FITS_READ_DATA_SKIP_BLOCKS | flag | Skip blocks

foreign_ATT_FITS_READ List of attributes for reading FITS files (header+data)

Name | Type | Meaning
FA_FITS_READ_END |  | End of varargs list
FA_FITS_READ_NUM_BLANKS | unsigned long * | Number of blank values found
FA_FITS_READ_MMAP_OPTION | unsigned int | See ch_MAP_CONTROLS
FA_FITS_READ_WRITABLE | flag | If TRUE array may be written to
FA_FITS_READ_SIMPLE | flag | If TRUE read a ".sfits" file

foreign_ATT_FITS_WRITE List of attributes for writing FITS files (header+data)

Name | Type | Meaning
FA_FITS_WRITE_END |  | End of varargs list

foreign_ATT_FITS_WRITE_DATA List of attributes for writing FITS data

Name | Type | Meaning
FA_FITS_WRITE_DATA_END |  | End of varargs list

foreign_ATT_GUESS_READ List of attributes for guessing and reading data

Name | Type | Meaning
FA_GUESS_READ_END |  | End of varargs list
FA_GUESS_READ_FITS_TO_FLOAT | flag | Convert FITS data to floating point

foreign_ATT_GUESS_WRITE List of attributes for guessing and writing data

Name | Type | Meaning
FA_GUESS_WRITE_END |  | End of varargs list

foreign_ATT_MIRIAD_READ_HEADER List of attributes for reading Miriad Image headers

Name | Type | Meaning
FA_MIRIAD_READ_HEADER_END |  | End of varargs list

foreign_ATT_MIRIAD_READ_DATA List of attributes for reading Miriad Image data

Name | Type | Meaning
FA_MIRIAD_READ_DATA_END |  | End of varargs list
FA_MIRIAD_READ_DATA_NUM_BLANKS | unsigned long * | Number of blank values (includes masked values)
FA_MIRIAD_READ_DATA_NUM_MASKED | unsigned long * | Number of masked values
FA_MIRIAD_READ_DATA_SKIP_BLOCKS | flag | Skip blocks

foreign_ATT_MIRIAD_READ List of attributes for reading Miriad Image files

Name | Type | Meaning
FA_MIRIAD_READ_END |  | End of varargs list
FA_MIRIAD_READ_NUM_BLANKS | unsigned long * | Number of blank values (includes masked values)
FA_MIRIAD_READ_NUM_MASKED | unsigned long * | Number of masked values

foreign_ATT_MIRIAD_WRITE List of attributes for writing Miriad Image files

Name | Type | Meaning
FA_MIRIAD_WRITE_END |  | End of varargs list
FA_MIRIAD_WRITE_EXTRA_HISTORY | flag | Generate extra history

foreign_ATT_GIPSY_READ_HEADER List of attributes for reading GIPSY Image headers

Name | Type | Meaning
FA_GIPSY_READ_HEADER_END |  | End of varargs list

foreign_ATT_GIPSY_READ_DATA List of attributes for reading GIPSY Image data

Name | Type | Meaning
FA_GIPSY_READ_DATA_END |  | End of varargs list
FA_GIPSY_READ_DATA_NUM_BLANKS | unsigned long * | Number of blank values
FA_GIPSY_READ_DATA_SKIP_BLOCKS | flag | Skip blocks

foreign_ATT_GIPSY_READ List of attributes for reading GIPSY Image files

Name | Type | Meaning
FA_GIPSY_READ_END |  | End of varargs list
FA_GIPSY_READ_NUM_BLANKS | unsigned long * | Number of blank values

foreign_ATT_GIPSY_WRITE List of attributes for writing GIPSY Image files

Name | Type | Meaning
FA_GIPSY_WRITE_END |  | End of varargs list

foreign_ATT_GIPSY_WRITE_HEADER List of attributes for writing GIPSY Image file headers

Name | Type | Meaning
FA_GIPSY_WRITE_HEADER_END |  | End of varargs list

foreign_TYPES List of foreign file types

Name | Meaning
FOREIGN_FILE_FORMAT_KARMA | Karma file (native format)
FOREIGN_FILE_FORMAT_UNKNOWN | Unknown format
FOREIGN_FILE_FORMAT_PPM | Portable PixMap format (PPM)
FOREIGN_FILE_FORMAT_FITS | Flexible Image Transport System (FITS)
FOREIGN_FILE_FORMAT_SUNRAS | Sun Rasterfile
FOREIGN_FILE_FORMAT_MIRIAD | Miriad Image file
FOREIGN_FILE_FORMAT_GIPSY | GIPSY file
FOREIGN_FILE_FORMAT_PGM | Portable Grey Map (PGM) file

foreign_ATT_PPM_WRITE List of attributes for writing PPM files

Name | Type | Meaning
FA_PPM_WRITE_END |  | End of varargs list

foreign_ATT_PPM_READ List of attributes for reading PPM files

Name | Type | Meaning
FA_PPM_READ_END |  | End of varargs list
FA_PPM_READ_BINARY | flag | If provided, do not read first line and use flag value

foreign_ATT_PGM_READ List of attributes for reading PGM files

Name | Type | Meaning
FA_PGM_READ_END |  | End of varargs list

foreign_ATT_SUNRAS_READ List of attributes for reading Sun Rasterfile files

Name | Type | Meaning
FA_SUNRAS_READ_END |  | End of varargs list

foreign_ATT_SUNRAS_WRITE List of attributes for writing Sun Rasterfile files

Name | Type | Meaning
FA_SUNRAS_WRITE_END |  | End of varargs list
FA_SUNRAS_WRITE_NO_IMAGE | flag * | No image found in data structure

foreign_ATT_IDF_READ_HEADER List of attributes for reading IDF headers

Name | Type | Meaning
FA_IDF_READ_HEADER_END |  | End of varargs list

foreign_ATT_IDF_READ_DATA List of attributes for reading IDF data

Name | Type | Meaning
FA_IDF_READ_DATA_END |  | End of varargs list
FA_IDF_READ_DATA_NUM_BLANKS | unsigned long * | Number of blank values found
FA_IDF_READ_DATA_SKIP_BLOCKS | flag | Skip blocks

foreign_ATT_IDF_READ List of attributes for reading IDF files (header+data)

Name | Type | Meaning
FA_IDF_READ_END |  | End of varargs list
FA_IDF_READ_NUM_BLANKS | unsigned long * | Number of blank values found

foreign_ATT_DRAO_READ_HEADER List of attributes for reading DRAO headers

Name | Type | Meaning
FA_DRAO_READ_HEADER_END |  | End of varargs list
FA_DRAO_READ_HEADER_PARTIAL | flag | Enable reading of partial data

foreign_ATT_DRAO_READ List of attributes for reading DRAO files (header+data)

Name | Type | Meaning
FA_DRAO_READ_END |  | End of varargs list
FA_DRAO_READ_PARTIAL | flag | Enable reading of partial data

Back to Karma Home Page