FITS table handling


Functions

int qfits_is_table (const char *filename, int xtnum)
 Identify a file as containing a FITS table in extension.
qfits_header * qfits_table_prim_header_default (void)
 Generate a default primary header to store tables.
qfits_header * qfits_table_ext_header_default (const qfits_table *t)
 Generate a default extension header to store tables.
qfits_table * qfits_table_new (const char *filename, int table_type, int table_width, int nb_cols, int nb_raws)
 Table object constructor.
int qfits_col_fill (qfits_col *qc, int atom_nb, int atom_dec_nb, int atom_size, tfits_type atom_type, const char *label, const char *unit, const char *nullval, const char *disp, int zero_present, float zero, int scale_present, float scale, int offset_beg)
 Fill a column object with some provided informations.
qfits_table * qfits_table_open (const char *filename, int xtnum)
 Read a FITS extension.
void qfits_table_close (qfits_table *t)
 Free a FITS table and associated pointers.
unsigned char * qfits_query_column (const qfits_table *th, int colnum, const int *selection)
 Extract data from a column in a FITS table.
unsigned char * qfits_query_column_seq (const qfits_table *th, int colnum, int start_ind, int nb_rows)
 Extract consequtive values from a column in a FITS table.
void * qfits_query_column_data (const qfits_table *th, int colnum, const int *selection, const void *null_value)
 Extract binary data from a column in a FITS table.
void * qfits_query_column_seq_data (const qfits_table *th, int colnum, int start_ind, int nb_rows, const void *null_value)
 Extract binary data from a column in a FITS table.
int * qfits_query_column_nulls (const qfits_table *th, int colnum, const int *selection, int *nb_vals, int *nb_nulls)
 Detect NULL values in a column.
int qfits_save_table_hdrdump (const void **array, const qfits_table *table, const qfits_header *fh)
 Save a table to a FITS file with a given FITS header.
int qfits_table_append_xtension (FILE *outfile, const qfits_table *t, const void **data)
 Appends a std extension header + data to a FITS table file.
int qfits_table_append_xtension_hdr (FILE *outfile, const qfits_table *t, const void **data, const qfits_header *hdr)
 Appends a specified extension header + data to a FITS table file.
char * qfits_table_field_to_string (const qfits_table *table, int col_id, int row_id, int use_zero_scale)
 given a col and a row, find out the string to write for display

Function Documentation

int qfits_col_fill (  qfits_col *  qc,
int  atom_nb,
int  atom_dec_nb,
int  atom_size,
tfits_type  atom_type,
const char *  label,
const char *  unit,
const char *  nullval,
const char *  disp,
int  zero_present,
float  zero,
int  scale_present,
float  scale,
int  offset_beg
) 
 

Fill a column object with some provided informations.

Parameters:
qc Pointer to the column that has to be filled
unit Unit of the data
label Label of the column
disp Way to display the data
nullval Null value
atom_nb Number of atoms per field. According to the type, an atom is a double, an int, a char, ...
atom_dec_nb Number of decimals as specified in TFORM
atom_size Size in bytes of the field for ASCII tables, and of an atom for BIN tables. ASCII tables only contain 1 atom per field (except for A type where you can of course have more than one char per field)
atom_type Type of data (11 types for BIN, 5 for ASCII)
zero_present Flag to use or not zero
zero Zero value
scale_present Flag to use or not scale
scale Scale value
offset_beg Gives the position of the column
Returns:
-1 in error case, 0 otherwise

int qfits_is_table (  const char *  filename,
int  xtnum
) 
 

Identify a file as containing a FITS table in extension.

Parameters:
filename Name of the FITS file to examine.
xtnum Extension number to check (starting from 1).
Returns:
int 1 if the extension contains a table, 0 else. Examines the requested extension and identifies the presence of a FITS table.

unsigned char* qfits_query_column (  const qfits_table *  th,
int  colnum,
const int *  selection
) 
 

Extract data from a column in a FITS table.

Parameters:
th Allocated qfits_table
colnum Number of the column to extract (from 0 to colnum-1)
selection boolean array to define the selected rows
Returns:
unsigned char array
If selection is NULL, select the complete column.

Extract a column from a FITS table and return the data as a bytes array. The returned array type and size are determined by the column object in the qfits_table and by the selection parameter.

Returned array size in bytes is: nbselected * col->natoms * col->atom_size

Numeric types are correctly understood and byte-swapped if needed, to be converted to the local machine type.

NULL values have to be handled by the caller.

The returned object must be deallocated with qfits_free().

void* qfits_query_column_data (  const qfits_table *  th,
int  colnum,
const int *  selection,
const void *  null_value
) 
 

Extract binary data from a column in a FITS table.

Parameters:
th Allocated qfits_table
colnum Number of the column to extract (from 0 to colnum-1)
selection bollean array to identify selected rows
null_value Value to return when a NULL value comes
Returns:
Pointer to void *
Extract a column from a FITS table and return the data as a generic void* array. The returned array type and size are determined by the column object in the qfits_table.

Returned array size in bytes is: nb_selected * col->atom_nb * col->atom_size

NULL values are recognized and replaced by the specified value. The returned object must be deallocated with qfits_free().

int* qfits_query_column_nulls (  const qfits_table *  th,
int  colnum,
const int *  selection,
int *  nb_vals,
int *  nb_nulls
) 
 

Detect NULL values in a column.

Parameters:
th Allocated qfits_table
colnum Number of the column to check (from 0 to colnum-1)
selection Array to identify selected rows
nb_vals Gives the size of the output array
nb_nulls Gives the number of detected null values
Returns:
array with 1 for NULLs and 0 for non-NULLs The returned object must be deallocated with qfits_free().

unsigned char* qfits_query_column_seq (  const qfits_table *  th,
int  colnum,
int  start_ind,
int  nb_rows
) 
 

Extract consequtive values from a column in a FITS table.

Parameters:
th Allocated qfits_table
colnum Number of the column to extract (from 0 to colnum-1)
start_ind Index of the first row (0 for the first)
nb_rows Number of rows to extract
Returns:
unsigned char array Does the same as qfits_query_column() but on a consequtive sequence of rows Spares the overhead of the selection object allocation The returned object must be deallocated with qfits_free().

void* qfits_query_column_seq_data (  const qfits_table *  th,
int  colnum,
int  start_ind,
int  nb_rows,
const void *  null_value
) 
 

Extract binary data from a column in a FITS table.

Parameters:
th Allocated qfits_table
colnum Number of the column to extract (from 0 to colnum-1)
start_ind Index of the first row (0 for the first)
nb_rows Number of rows to extract
null_value Value to return when a NULL value comes
Returns:
Pointer to void * Does the same as qfits_query_column_data() but on a consequtive sequence of rows. Spares the overhead of the selection object allocation The returned object must be deallocated with qfits_free().

int qfits_save_table_hdrdump (  const void **  array,
const qfits_table *  table,
const qfits_header *  fh
) 
 

Save a table to a FITS file with a given FITS header.

Parameters:
array Data array.
table table
fh FITS header to insert in the output file.
Returns:
-1 in error case, 0 otherwise

int qfits_table_append_xtension (  FILE *  outfile,
const qfits_table *  t,
const void **  data
) 
 

Appends a std extension header + data to a FITS table file.

Parameters:
outfile Pointer to (opened) file ready for writing.
t Pointer to qfits_table
data Table data to write
Returns:
int 0 if Ok, -1 otherwise
Dumps a FITS table to a file. The whole table described by qfits_table, and the data arrays contained in 'data' are dumped to the file. An extension header is produced with all keywords needed to describe the table, then the data is dumped to the file. The output is then padded to reach a multiple of 2880 bytes in size. Notice that no main header is produced, only the extension part.

int qfits_table_append_xtension_hdr (  FILE *  outfile,
const qfits_table *  t,
const void **  data,
const qfits_header *  hdr
) 
 

Appends a specified extension header + data to a FITS table file.

Parameters:
outfile Pointer to (opened) file ready for writing.
t Pointer to qfits_table
data Table data to write
hdr Specified extension header
Returns:
int 0 if Ok, -1 otherwise
Dumps a FITS table to a file. The whole table described by qfits_table, and the data arrays contained in 'data' are dumped to the file following the specified fits header. The output is then padded to reach a multiple of 2880 bytes in size. Notice that no main header is produced, only the extension part.

void qfits_table_close (  qfits_table *  t  ) 
 

Free a FITS table and associated pointers.

Parameters:
t qfits_table to free
Returns:
void Frees all memory associated to a qfits_table structure.

qfits_header* qfits_table_ext_header_default (  const qfits_table *  t  ) 
 

Generate a default extension header to store tables.

Returns:
the header object

char* qfits_table_field_to_string (  const qfits_table *  table,
int  col_id,
int  row_id,
int  use_zero_scale
) 
 

given a col and a row, find out the string to write for display

Parameters:
table table structure
col_id col id (0 -> nbcol-1)
row_id row id (0 -> nrow-1)
use_zero_scale Flag to use or not zero and scale
Returns:
the string
This function is highly inefficient, it should not be used in loops to display a complete table. It is more to get one field from time to time, or for debugging puposes. The returned object must be deallocated with qfits_free().

qfits_table* qfits_table_new (  const char *  filename,
int  table_type,
int  table_width,
int  nb_cols,
int  nb_raws
) 
 

Table object constructor.

Parameters:
filename Name of the FITS file associated to the table
table_type Type of the table (QFITS_ASCIITABLE or QFITS_BINTABLE)
table_width Width in bytes of the table
nb_cols Number of columns
nb_raws Number of raws
Returns:
The table object The columns are also allocated. The object has to be deallocated with qfits_table_close()

qfits_table* qfits_table_open (  const char *  filename,
int  xtnum
) 
 

Read a FITS extension.

Parameters:
filename Name of the FITS file to examine.
xtnum Extension number to read (starting from 1).
Returns:
Pointer to newly allocated qfits_table structure.
Read a FITS table from a given file name and extension, and return a newly allocated qfits_table structure.

qfits_header* qfits_table_prim_header_default (  void   ) 
 

Generate a default primary header to store tables.

Returns:
the header object