DSP API FITS Extensions functions

Modules
	DSP API SDFITS Extension
	DSP API FITSIDI Extension

Classes
struct	dsp_fits_format
	FITS format. More...
struct	dsp_fits_keyword
	FITS keyword. More...
struct	dsp_fits_column
	Binary table FITS extension column. More...
struct	dsp_fits_row
	Binary table FITS extension row. More...
struct	dsp_fits_axis
	Binary table FITS Matrix axis. More...
struct	dsp_fits_matrix
	Binary table FITS Matrix. More...

Macros
#define	its(x)   #x
	Returns non-zero decimal conversion of integer into string.
#define	EXTFITS_ELEMENT_STRING   (dsp_fits_format){"A", TSTRING, 0, 0}
	FITS element types.
#define	EXTFITS_MEASURE_UNIT_HZ   "Hz"
	FITS Measure units.
#define	EXTFITS_KEYWORD_TTYPE(n)   (dsp_fits_keyword){"TTYPE" itostr(n), "8A", "", "", "Set to 'FLUX'", (char*[]){"FLUX", "DATA", ""}}
	Set to 'FLUX' or 'DATA' for matrix buffers.
#define	EXTFITS_KEYWORD_TUNIT(n)   (dsp_fits_keyword){"TUNIT" itostr(n), "8A", "", "", "Shall have the value 'JY' or 'UNCALIB'", (char*[]){""}}
	shall have the value 'K', 'JY' or 'UNCALIB'
#define	EXTFITS_KEYWORD_TDIM(n)   (dsp_fits_keyword){"TDIM" itostr(n), "8A", "", "", "Size in pixels of data buffer", (char*[]){""}}
	Size in pixels of data buffer.
#define	EXTFITS_KEYWORD_TFORM(n)   (dsp_fits_keyword){"TFORM" itostr(n), "8A", "", "", "Shall be a character string", (char*[]){""}}
	shall have the format of the column
#define	EXTFITS_KEYWORD_CTYPE(m)   (dsp_fits_keyword){"CTYPE" itostr(m), EXTFITS_ELEMENT_STRING.typestr, "", "", "Name of regular axis m = 1 to M", (char*[]){""}}
	Name of regular axis m = 1 to M.
#define	EXTFITS_KEYWORD_CDELT(m)   (dsp_fits_keyword){"CDELT" itostr(m), EXTFITS_ELEMENT_FLOAT.typestr, "", "", "Coordinate increment on axis m = 1 to M", (char*[]){""}}
	Coordinate increment on axis m = 1 to M.
#define	EXTFITS_KEYWORD_CRPIX(m)   (dsp_fits_keyword){"CRPIX" itostr(m), EXTFITS_ELEMENT_FLOAT.typestr, "", "", "Reference pixel on axis m = 1 to M", (char*[]){""}}
	Reference pixel on axis m = 1 to M.
#define	EXTFITS_KEYWORD_CRVAL(m)   (dsp_fits_keyword){"CRVAL" itostr(m), EXTFITS_ELEMENT_FLOAT.typestr, "", "", "Coordinate value at reference pixel on axis m = 1 to M", (char*[]){""}}
	Coordinate value at reference pixel on axis m = 1 to M.
#define	EXTFITS_KEYWORD_NMATRIX   (dsp_fits_keyword){"NMATRIX", EXTFITS_ELEMENT_SHORT.typestr, "", "1", "NMATRIX shall be present with the value 1", (char*[]){"1", ""}}
	NMATRIX shall be present with the value 1.
#define	EXTFITS_KEYWORD_TMATX(n)   (dsp_fits_matrix){"TMATX" itostr(n), "8A", "T", "Set to 'T'", {EXTFITS_KEYWORD_TTYPE(n), EXTFITS_KEYWORD_TFORM(n), EXTFITS_KEYWORD_TUNIT(n), EXTFITS_KEYWORD_TDIM(n)}}
	Set to 'T' — column n contains the visibility matrix.
#define	EXTFITS_KEYWORD_MAXIS(m)   (dsp_fits_axis){"MAXIS" itostr(m), EXTFITS_ELEMENT_SHORT.typestr, "", "", "M = number axes in regular matrix, Number pixels on axis m = 1 to M", {EXTFITS_KEYWORD_CTYPE(m), EXTFITS_KEYWORD_CDELT(m), EXTFITS_KEYWORD_CRPIX(m), EXTFITS_KEYWORD_CRVAL(m)}}
	M = number axes in regular matrix, Number pixels on axis m = 1 to M.
#define	EXTFITS_KEYWORD_OBJCTRA   (dsp_fits_column){"OBJCTRA", EXTFITS_ELEMENT_STRING.typestr, EXTFITS_MEASURE_UNIT_DEGREE, "", "Target right ascension coordinate", (char*[]){""}}
	Target right ascension coordinate.
#define	EXTFITS_KEYWORD_OBJCTDEC   (dsp_fits_column){"OBJCTDEC", EXTFITS_ELEMENT_STRING.typestr, EXTFITS_MEASURE_UNIT_DEGREE, "", "Target declination coordinate", (char*[]){""}}
	Target declination coordinate.

Functions
DLL_EXPORT void	dsp_fits_update_fits_key (fitsfile *fptr, int type, char *name, void *value, char *comment, int *status)
	Create or update a new fits header key. More...
DLL_EXPORT long	dsp_fits_alloc_fits_rows (fitsfile *fptr, unsigned long num_rows)
	Convert an RGB color dsp_t array into a dsp_stream_p array each element containing the single components. More...
DLL_EXPORT int	dsp_fits_fill_fits_col (fitsfile *fptr, char *name, unsigned char *buf, int typecode, long num_elements, unsigned long rown)
	Fill a column at the given row position with the valued buffer. More...
DLL_EXPORT int	dsp_fits_append_fits_col (fitsfile *fptr, char *name, char *format)
	Add a column to the binary table. More...
DLL_EXPORT void	dsp_fits_delete_fits_col (fitsfile *fptr, char *name)
	Delete a column from the binary table. More...
DLL_EXPORT size_t	dsp_fits_get_element_size (int typecode)
	Obtain the single element size in bytes. More...
DLL_EXPORT int	dsp_fits_read_typecode (char *typestr, int *typecode, long *width, long *repeat)
	Decode a typecode format string. More...
DLL_EXPORT int	dsp_fits_get_value (fitsfile *fptr, char *column, long rown, void **retval)
	Obtain the value of the specified field. More...
DLL_EXPORT int	dsp_fits_check_column (fitsfile *fptr, char *column, char **expected, long rown)
	Check if the value of the specified field corresponds to a subset of values. More...
DLL_EXPORT fitsfile *	dsp_fits_create_fits (size_t *size, void **buf)
	Create an open fits file pointer to be updated later. More...
DLL_EXPORT int	dsp_fits_add_table (fitsfile *fptr, dsp_fits_column *columns, int ncols, const char *tablename)
	Add a binary table extension into a fits file. More...
DLL_EXPORT int	dsp_fits_close_fits (fitsfile *fptr)
	Close a fits file pointer. More...

Detailed Description

Function Documentation

dsp_fits_add_table()

DLL_EXPORT int dsp_fits_add_table	(	fitsfile *	fptr,
		dsp_fits_column *	columns,
		int	ncols,
		const char *	tablename
	)

Parameters

fptr	Pointer to a fits file
columns	An array of dsp_fits_column structs
ncols	The dsp_fits_column array length
tablename	The extension table name

Returns

non-zero if any error occured

dsp_fits_alloc_fits_rows()

DLL_EXPORT long dsp_fits_alloc_fits_rows	(	fitsfile *	fptr,
		unsigned long	num_rows
	)

Parameters

fptr	The fits file pointer created by dsp_fits_create_fits
num_rows	The number of rows to be allocated

Returns

The number of rows incremented by the allocated ones

See also

dsp_fits_create_fits

dsp_fits_append_fits_col()

DLL_EXPORT int dsp_fits_append_fits_col	(	fitsfile *	fptr,
		char *	name,
		char *	format
	)

Parameters

fptr	The fits file pointer created by dsp_fits_create_fits
name	The name of the column
format	This field should indicate the element size, width of each element and repetition eventually

Returns

non-zero if any error occured

dsp_fits_check_column()

DLL_EXPORT int dsp_fits_check_column	(	fitsfile *	fptr,
		char *	column,
		char **	expected,
		long	rown
	)

Parameters

fptr	The fits file pointer created by dsp_fits_create_fits
column	The column name of the selected field
expected	A buffer array containing expected values, terminating with an empty value
rown	The row position of the field

Returns

zero if any of the values was matched

dsp_fits_close_fits()

DLL_EXPORT int dsp_fits_close_fits

(

fitsfile *

fptr

)

Parameters

fptr	The fits file pointer created by dsp_fits_create_fits

Returns

non-zero if any error occured

dsp_fits_create_fits()

DLL_EXPORT fitsfile* dsp_fits_create_fits	(	size_t *	size,
		void **	buf
	)

Parameters

size	This variable will contain the initial size of the fits file pointer
buf	This buffer will contain the fits memfile

Returns

fitsfile the fits file pointer

dsp_fits_delete_fits_col()

DLL_EXPORT void dsp_fits_delete_fits_col	(	fitsfile *	fptr,
		char *	name
	)

Parameters

fptr	The fits file pointer created by dsp_fits_create_fits
name	The name of the column

dsp_fits_fill_fits_col()

DLL_EXPORT int dsp_fits_fill_fits_col	(	fitsfile *	fptr,
		char *	name,
		unsigned char *	buf,
		int	typecode,
		long	num_elements,
		unsigned long	rown
	)

Parameters

fptr	The fits file pointer created by dsp_fits_create_fits
name	The name of the column
buf	The buffer that will be copied into the selected field.
typecode	The element type size
num_elements	The total field size in elements, this should take into account the width and repeat multipliers
rown	The row number where the field is located

Returns

non-zero if any error occured

See also

dsp_fits_create_fits

dsp_fits_get_element_size()

DLL_EXPORT size_t dsp_fits_get_element_size

(

int

typecode

)

Parameters

typecode

The typecode of each single element

Returns

the size of the single element

dsp_fits_get_value()

DLL_EXPORT int dsp_fits_get_value	(	fitsfile *	fptr,
		char *	column,
		long	rown,
		void **	retval
	)

Parameters

fptr	The fits file pointer created by dsp_fits_create_fits
column	The column name of the selected field
rown	The row position of the field
retval	A preallocated buffer where the field value will be stored into

Returns

non-zero if any error occured

dsp_fits_read_typecode()

DLL_EXPORT int dsp_fits_read_typecode	(	char *	typestr,
		int *	typecode,
		long *	width,
		long *	repeat
	)

Parameters

typestr	The element format string
typecode	This function will return the typecode to this variable
width	This function will return the width to this variable
repeat	This function will return the repeatition count to this variable

Returns

non-zero if any error occured

dsp_fits_update_fits_key()

DLL_EXPORT void dsp_fits_update_fits_key	(	fitsfile *	fptr,
		int	type,
		char *	name,
		void *	value,
		char *	comment,
		int *	status
	)

Parameters

fptr	The fits file pointer created by dsp_fits_create_fits
type	The typecode of the value
name	The keyword to be updated
value	The new value of the specified keyword
comment	The keyword or assigned value description or explanation
status	This variable will be updated with the status of the update operation