522 lines
19 KiB
C
522 lines
19 KiB
C
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@file tfits.h
|
|
@author Yves Jung
|
|
@date July 1999
|
|
@version $Revision: 1.25 $
|
|
@brief FITS table handling
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
|
|
/*
|
|
$Id: tfits.h,v 1.25 2003/11/24 09:44:53 yjung Exp $
|
|
$Author: yjung $
|
|
$Date: 2003/11/24 09:44:53 $
|
|
$Revision: 1.25 $
|
|
*/
|
|
|
|
#ifndef TFITS_H
|
|
#define TFITS_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
/*-----------------------------------------------------------------------------
|
|
Includes
|
|
-----------------------------------------------------------------------------*/
|
|
|
|
#include <stdio.h>
|
|
#include <string.h>
|
|
#include <stdlib.h>
|
|
#include <unistd.h>
|
|
|
|
#include "fits_h.h"
|
|
#include "static_sz.h"
|
|
|
|
/* <dox> */
|
|
/*-----------------------------------------------------------------------------
|
|
Defines
|
|
-----------------------------------------------------------------------------*/
|
|
|
|
/* The following defines the maximum acceptable size for a FITS value */
|
|
#define FITSVALSZ 60
|
|
|
|
#define QFITS_INVALIDTABLE 0
|
|
#define QFITS_BINTABLE 1
|
|
#define QFITS_ASCIITABLE 2
|
|
|
|
/*-----------------------------------------------------------------------------
|
|
New types
|
|
-----------------------------------------------------------------------------*/
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Column data type
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
typedef enum _TFITS_DATA_TYPE_
|
|
{
|
|
TFITS_ASCII_TYPE_A,
|
|
TFITS_ASCII_TYPE_D,
|
|
TFITS_ASCII_TYPE_E,
|
|
TFITS_ASCII_TYPE_F,
|
|
TFITS_ASCII_TYPE_I,
|
|
TFITS_BIN_TYPE_A,
|
|
TFITS_BIN_TYPE_B,
|
|
TFITS_BIN_TYPE_C,
|
|
TFITS_BIN_TYPE_D,
|
|
TFITS_BIN_TYPE_E,
|
|
TFITS_BIN_TYPE_I,
|
|
TFITS_BIN_TYPE_J,
|
|
TFITS_BIN_TYPE_L,
|
|
TFITS_BIN_TYPE_M,
|
|
TFITS_BIN_TYPE_P,
|
|
TFITS_BIN_TYPE_X,
|
|
TFITS_BIN_TYPE_UNKNOWN
|
|
} tfits_type;
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Column object
|
|
|
|
This structure contains all information needed to read a column in a table.
|
|
These informations come from the header.
|
|
The qfits_table object contains a list of qfits_col objects.
|
|
|
|
This structure has to be created from scratch and filled if one want to
|
|
generate a FITS table.
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
typedef struct qfits_col
|
|
{
|
|
/**
|
|
Number of atoms in one field.
|
|
In ASCII tables, it is the number of characters in the field as defined
|
|
in TFORM%d keyword.
|
|
In BIN tables, it is the number of atoms in each field. For type 'A',
|
|
it is the number of characters. A field with two complex object will
|
|
have atom_nb = 4.
|
|
*/
|
|
int atom_nb;
|
|
|
|
/**
|
|
Number of decimals in a ASCII field.
|
|
This value is always 0 for BIN tables
|
|
*/
|
|
int atom_dec_nb;
|
|
|
|
/**
|
|
Size of one element in bytes. In ASCII tables, atom_size is the size
|
|
of the element once it has been converted in its 'destination' type.
|
|
For example, if "123" is contained in an ASCII table in a column
|
|
defined as I type, atom_nb=3, atom_size=4.
|
|
In ASCII tables:
|
|
- type 'A' : atom_size = atom_nb = number of chars
|
|
- type 'I', 'F' or 'E' : atom_size = 4
|
|
- type 'D' : atom_size = 8
|
|
In BIN tables :
|
|
- type 'A', 'L', 'X', 'B': atom_size = 1
|
|
- type 'I' : atom_size = 2
|
|
- type 'E', 'J', 'C', 'P' : atom_size = 4
|
|
- type 'D', 'M' : atom_size = 8
|
|
In ASCII table, there is one element per field. The size in bytes and
|
|
in number of characters is atom_nb, and the size in bytes after
|
|
conversion of the field is atom_size.
|
|
In BIN tables, the size in bytes of a field is always atom_nb*atom_size.
|
|
*/
|
|
int atom_size;
|
|
|
|
/**
|
|
Type of data in the column as specified in TFORM keyword
|
|
In ASCII tables : TFITS_ASCII_TYPE_* with *=A, I, F, E or D
|
|
In BIN tables : TFITS_BIN_TYPE_* with *=L, X, B, I, J, A, E, D, C, M or P
|
|
*/
|
|
tfits_type atom_type;
|
|
|
|
/** Label of the column */
|
|
char tlabel[FITSVALSZ];
|
|
|
|
/** Unit of the data */
|
|
char tunit[FITSVALSZ];
|
|
|
|
/** Null value */
|
|
char nullval[FITSVALSZ];
|
|
|
|
/** Display format */
|
|
char tdisp[FITSVALSZ];
|
|
|
|
/**
|
|
zero and scale are used when the quantity in the field does not
|
|
represent a true physical quantity. Basically, thez should be used
|
|
when they are present: physical_value = zero + scale * field_value
|
|
They are read from TZERO and TSCAL in the header
|
|
*/
|
|
int zero_present;
|
|
float zero;
|
|
int scale_present;
|
|
float scale;
|
|
|
|
/** Offset between the beg. of the table and the beg. of the column. */
|
|
int off_beg;
|
|
|
|
/** Flag to know if the column is readable. An empty col is not readable */
|
|
int readable;
|
|
} qfits_col;
|
|
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Table object
|
|
|
|
This structure contains all information needed to read a FITS table.
|
|
These information come from the header. The object is created by
|
|
qfits_open().
|
|
|
|
To read a FITS table, here is a code example:
|
|
@code
|
|
int main(int argc, char* argv[])
|
|
{
|
|
qfits_table * table ;
|
|
int n_ext ;
|
|
int i ;
|
|
|
|
// Query the number of extensions
|
|
n_ext = qfits_query_n_ext(argv[1]) ;
|
|
|
|
// For each extension
|
|
for (i=0 ; i<n_ext ; i++) {
|
|
// Read all the infos about the current table
|
|
table = qfits_table_open(argv[1], i+1) ;
|
|
// Display the current table
|
|
dump_extension(table, stdout, '|', 1, 1) ;
|
|
}
|
|
return ;
|
|
}
|
|
@endcode
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
typedef struct qfits_table
|
|
{
|
|
/**
|
|
Name of the file the table comes from or it is intended to end to
|
|
*/
|
|
char filename[FILENAMESZ];
|
|
/**
|
|
Table type.
|
|
Possible values: QFITS_INVALIDTABLE, QFITS_BINTABLE, QFITS_ASCIITABLE
|
|
*/
|
|
int tab_t;
|
|
/** Width in bytes of the table */
|
|
int tab_w;
|
|
/** Number of columns */
|
|
int nc;
|
|
/** Number of raws */
|
|
int nr;
|
|
/** Array of qfits_col objects */
|
|
qfits_col *col;
|
|
} qfits_table;
|
|
|
|
/*-----------------------------------------------------------------------------
|
|
Function prototypes
|
|
-----------------------------------------------------------------------------*/
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Identify a file as containing a FITS table in extension.
|
|
@param filename Name of the FITS file to examine.
|
|
@param xtnum Extension number to check (starting from 1).
|
|
@return int 1 if the extension contains a table, 0 else.
|
|
|
|
Examines the requested extension and identifies the presence of a
|
|
FITS table.
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
int qfits_is_table (char *filename, int xtnum);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Generate a default primary header to store tables
|
|
@return the header object
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
qfits_header *qfits_table_prim_header_default (void);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Generate a default extension header to store tables
|
|
@return the header object
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
qfits_header *qfits_table_ext_header_default (qfits_table *);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Table object constructor
|
|
@param filename Name of the FITS file associated to the table
|
|
@param table_type Type of the table (QFITS_ASCIITABLE or QFITS_BINTABLE)
|
|
@param table_width Width in bytes of the table
|
|
@param nb_cols Number of columns
|
|
@param nb_raws Number of raws
|
|
@return The table object
|
|
The columns are also allocated. The object has to be freed with
|
|
qfits_table_close()
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
qfits_table *qfits_table_new (char *filename,
|
|
int table_type,
|
|
int table_width, int nb_cols, int nb_raws);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Fill a column object with some provided informations
|
|
@param qc Pointer to the column that has to be filled
|
|
@param unit Unit of the data
|
|
@param label Label of the column
|
|
@param disp Way to display the data
|
|
@param nullval Null value
|
|
@param atom_nb Number of atoms per field. According to the type, an atom
|
|
is a double, an int, a char, ...
|
|
@param atom_dec_nb Number of decimals as specified in TFORM
|
|
@param 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)
|
|
@param atom_type Type of data (11 types for BIN, 5 for ASCII)
|
|
@param zero_present Flag to use or not zero
|
|
@param zero Zero value
|
|
@param scale_present Flag to use or not scale
|
|
@param scale Scale value
|
|
@param offset_beg Gives the position of the column
|
|
@return -1 in error case, 0 otherwise
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
int qfits_col_fill (qfits_col * qc,
|
|
int atom_nb,
|
|
int atom_dec_nb,
|
|
int atom_size,
|
|
tfits_type atom_type,
|
|
char *label,
|
|
char *unit,
|
|
char *nullval,
|
|
char *disp,
|
|
int zero_present,
|
|
float zero,
|
|
int scale_present, float scale, int offset_beg);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Read a FITS extension.
|
|
@param filename Name of the FITS file to examine.
|
|
@param xtnum Extension number to read (starting from 1).
|
|
@return 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_table *qfits_table_open (char *filename, int xtnum);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Free a FITS table and associated pointers
|
|
@param t qfits_table to free
|
|
@return void
|
|
Frees all memory associated to a qfits_table structure.
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
void qfits_table_close (qfits_table * t);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Extract data from a column in a FITS table
|
|
@param th Allocated qfits_table
|
|
@param colnum Number of the column to extract (from 0 to colnum-1)
|
|
@param selection boolean array to define the selected rows
|
|
@return 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 buffer has been allocated using one of the special memory
|
|
operators present in xmemory.c. To deallocate the buffer, you must call
|
|
the version of free() offered by xmemory, not the usual system free(). It
|
|
is enough to include "xmemory.h" in your code before you make calls to
|
|
the pixel loader here.
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
unsigned char *qfits_query_column (qfits_table * th,
|
|
int colnum, int *selection);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Extract consequtive values from a column in a FITS table
|
|
@param th Allocated qfits_table
|
|
@param colnum Number of the column to extract (from 0 to colnum-1)
|
|
@param start_ind Index of the first row (0 for the first)
|
|
@param nb_rows Number of rows to extract
|
|
@return 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
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
unsigned char *qfits_query_column_seq (qfits_table * th,
|
|
int colnum,
|
|
int start_ind, int nb_rows);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Compute the table width in bytes from the columns infos
|
|
@param th Allocated qfits_table
|
|
@return the width (-1 in error case)
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
int qfits_compute_table_width (qfits_table * th);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Extract binary data from a column in a FITS table
|
|
@param th Allocated qfits_table
|
|
@param colnum Number of the column to extract (from 0 to colnum-1)
|
|
@param selection bollean array to identify selected rows
|
|
@param null_value Value to return when a NULL value comes
|
|
@return 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 buffer has been allocated using one of the special memory
|
|
operators present in xmemory.c. To deallocate the buffer, you must call
|
|
the version of free() offered by xmemory, not the usual system free(). It
|
|
is enough to include "xmemory.h" in your code before you make calls to
|
|
the pixel loader here.
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
void *qfits_query_column_data (qfits_table * th,
|
|
int colnum,
|
|
int *selection, void *null_value);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Extract binary data from a column in a FITS table
|
|
@param th Allocated qfits_table
|
|
@param colnum Number of the column to extract (from 0 to colnum-1)
|
|
@param start_ind Index of the first row (0 for the first)
|
|
@param nb_rows Number of rows to extract
|
|
@param null_value Value to return when a NULL value comes
|
|
@return 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
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
void *qfits_query_column_seq_data (qfits_table * th,
|
|
int colnum,
|
|
int start_ind,
|
|
int nb_rows, void *null_value);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Detect NULL values in a column
|
|
@param th Allocated qfits_table
|
|
@param colnum Number of the column to check (from 0 to colnum-1)
|
|
@param selection Array to identify selected rows
|
|
@param nb_vals Gives the size of the output array
|
|
@param nb_nulls Gives the number of detected null values
|
|
@return array with 1 for NULLs and 0 for non-NULLs
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
int *qfits_query_column_nulls (qfits_table * th,
|
|
int colnum,
|
|
int *selection, int *nb_vals, int *nb_nulls);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Save a table to a FITS file with a given FITS header.
|
|
@param array Data array.
|
|
@param table table
|
|
@param fh FITS header to insert in the output file.
|
|
@return -1 in error case, 0 otherwise
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
int qfits_save_table_hdrdump (void **array,
|
|
qfits_table * table, qfits_header * fh);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Appends a std extension header + data to a FITS table file.
|
|
@param outfile Pointer to (opened) file ready for writing.
|
|
@param t Pointer to qfits_table
|
|
@param data Table data to write
|
|
@return 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 (FILE * outfile,
|
|
qfits_table * t, void **data);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief Appends a specified extension header + data to a FITS table file.
|
|
@param outfile Pointer to (opened) file ready for writing.
|
|
@param t Pointer to qfits_table
|
|
@param data Table data to write
|
|
@param hdr Specified extension header
|
|
@return 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.
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
int qfits_table_append_xtension_hdr (FILE * outfile,
|
|
qfits_table * t,
|
|
void **data, qfits_header * hdr);
|
|
|
|
/*----------------------------------------------------------------------------*/
|
|
/**
|
|
@brief given a col and a row, find out the string to write for display
|
|
@param table table structure
|
|
@param col_id col id (0 -> nbcol-1)
|
|
@param row_id row id (0 -> nrow-1)
|
|
@param use_zero_scale Flag to use or not zero and scale
|
|
@return the string to write
|
|
*/
|
|
/*----------------------------------------------------------------------------*/
|
|
char *qfits_table_field_to_string (qfits_table * table,
|
|
int col_id,
|
|
int row_id, int use_zero_scale);
|
|
|
|
/* </dox> */
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|
|
/* vim: set ts=4 et sw=4 tw=75 */
|