The "foreign" Package

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

Library: karma
Link With: -lkarma

Functions

foreign_fits_read_header	Read a FITS header.
foreign_fits_read_data	Read data in a FITS file.
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_guess_and_read	Guess file type and read.
foreign_miriad_test	Test if a directory is a Miriad Image file.
foreign_miriad_read_header	Read a Miriad Image file header.
foreign_miriad_read	Read a Miriad image file.
foreign_guess_format_from_filename	Attempt to guess the format of a file by examining its filename.
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_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

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_GUESS	List of attributes for guessing and reading 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_TYPES	List of foreign file types
FOREIGN_ATT_PPM_READ	List of attributes for reading PPM files
FOREIGN_ATT_PPM_WRITE	List of attributes for writing PPM 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

Functions

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

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 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_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_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 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_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, 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_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

multi_array * foreign_guess_and_read (CONST char *filename, unsigned int mmap_option, flag writeable, 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.
writeable : This has the same meaning as for the routine.
ftype : The type of the file that was read in is written here.
... : 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 for a list of defined attributes.

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

flag foreign_miriad_test (CONST char *dirname)

Test if a directory is a Miriad Image file.

Parameters:

dirname : The directory name of the Miriad dataset name.

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

multi_array * foreign_miriad_read_header (Channel channel, 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:

channel : The channel to read from.
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

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_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

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.

Tables

FOREIGN_ATT_FITS_READ_HEADER

Name Type Meaning

FA_FITS_READ_HEADER_END End of varargs list

FOREIGN_ATT_FITS_READ_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

FOREIGN_ATT_GUESS

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_MIRIAD_READ_HEADER

Name Type Meaning

FA_MIRIAD_READ_HEADER_END End of varargs list

FOREIGN_ATT_MIRIAD_READ_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

FOREIGN_ATT_MIRIAD_READ

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_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_ATT_PPM_READ

Name Type Meaning

FA_PPM_READ_END End of varargs list

FOREIGN_ATT_PPM_WRITE

Name Type Meaning

FA_PPM_WRITE_END End of varargs list

FOREIGN_ATT_SUNRAS_READ

Name Type Meaning

FA_SUNRAS_READ_END End of varargs list

FOREIGN_ATT_SUNRAS_WRITE

Name Type Meaning

FA_SUNRAS_WRITE_END End of varargs list
FA_SUNRAS_WRITE_NO_IMAGE flag * No image found in data structure

Contact: Richard Gooch
Web Development: Ariel Internet Services

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

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