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_aips2_test	Test if a directory is an AIPS++ Image file.
foreign_drao_read_dataset_names	Get the names of DRAO datasets in the directory catalogue.
foreign_drao_read	Read a DRAO dataset.
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_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_data	Write data to 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_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_miriad_test2	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_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_write	Write a Miriad Image file.
foreign_miriad_write_iarray	Write a Miriad Image file.
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_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 Sun rasterfile 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_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_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_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

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 "CAD000000.???" 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

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

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

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.

EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * foreign_drao_read (CONST char *setname)

Read a DRAO dataset.

Parameters:

setname : The DRAO dataset name.

Returns: A multi_array descriptor on success, else NULL.
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

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

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

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

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

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

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

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 cmap_stride, double i_min, double i_max)

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.
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_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 Sun rasterfile 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

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

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_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
FA_MIRIAD_READ_DATA_SKIP_BLOCKS flag Skip blocks

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_ATT_GIPSY_READ_HEADER

Name Type Meaning

FA_GIPSY_READ_HEADER_END End of varargs list

foreign_ATT_GIPSY_READ_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

Name Type Meaning

FA_GIPSY_READ_END End of varargs list
FA_GIPSY_READ_NUM_BLANKS unsigned long * Number of blank 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_FILE_FORMAT_GIPSY GIPSY file
FOREIGN_FILE_FORMAT_PGM Portable Grey Map (PGM) file

foreign_ATT_PPM_WRITE

Name Type Meaning

FA_PPM_WRITE_END End of varargs list

foreign_ATT_PPM_READ

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

Name Type Meaning

FA_PGM_READ_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

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services

Name	Type	Meaning

FA_FITS_READ_HEADER_END		End of varargs list
FA_FITS_READ_HEADER_ALLOC_TRUNC	flag	Allow truncated headers

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