Changeset 23924 for trunk/extsrc/gpcsw/gpcsrc/fits/libfh/fh.h

Timestamp:

Apr 18, 2009, 11:11:15 AM (17 years ago)

Author:

eugene

Message:

import updates from camera group (fits table outputs, fixes to persistent trails); modify import to avoid libpsf (fortran)

File:

• trunk/extsrc/gpcsw/gpcsrc/fits/libfh/fh.h (modified) (3 diffs)

trunk/extsrc/gpcsw/gpcsrc/fits/libfh/fh.h

@@ -36 +36 @@
 #define FH_COUNT_CARDS "@FH_COUNT_CARDS@"  /* See also: fh_count_cards() */
 
+/* Size of buffer in fhTableCol structure for format string. */
+#define FH_TABLE_FORMAT_STR_LEN 20
+
 typedef enum /* fh_result -- Result Code for most functions in this library: */
 {  FH_SUCCESS = 0,
@@ -64 +67 @@
 } fh_bool;                      /* Value for "logical" FITS cards */
 
+/* The possible field formats in an ASCII table extension. */
+typedef enum
+{
+   FH_TABLE_FORMAT_CHAR = 'A',   /* Designates a string field. */
+   FH_TABLE_FORMAT_INT = 'I',    /* Integer field. */
+   FH_TABLE_FORMAT_FLOAT = 'F',  /* Float field. */
+   FH_TABLE_FORMAT_DOUBLE = 'D'  /* Double field. */
+} fhTableFormat;
+
+typedef struct
+{
+  char * name;    /* Short string identifying this column's data. */ 
+  char * comment; /* Longer blurb about this column's data. */
+  char * units;   /* Units for column's data. */
+  fhTableFormat format; /* Type of data held in this column. */
+  int width;      /* Width of this column's data, in characters. */
+  int dec_places; /* For doubles, etc, the number of decimal places to write. */
+  /* Everything below this line is generated by fh_table_init(). These 
+   * do not need to be filled out by hand. */
+  int first_char_pos; /* Position of first character in this column. Calculated on the fly. */
+  char format_string[FH_TABLE_FORMAT_STR_LEN]; /* Format string for printf. */
+} fhTableCol;
+
+/* Describes the layout of an ASCII table. */
+typedef struct
+{
+  char * extname;    /* Name of table extension. */
+  int num_cols;      /* Number of rows in table. */
+  int num_rows;      /* Number of columns in table. */
+  fhTableCol * cols; /* Array of cols columns. */
+  /* Everything below this line is generated by fh_table_init(). These 
+   * do not need to be filled out by hand. */
+  int widest_col;    /* Width of widest column. */
+  char * strbuf;     /* Will point to buf of widest_col + 1 chars. */
+  int row_width;     /* Number of characters in a table tow. */
+  int table_size;    /* Total size of table data, in bytes. */
+} fhTable;
+
 typedef void* HeaderUnit; /* Handle to a list of FITS cards allocated by fh_create. */
 
@@ -345 +386 @@
 double fh_idx(HeaderUnit hu); /* idx of the last card returned by fh_next */
 fh_result fh_merge(HeaderUnit hu, const HeaderUnit source); /* source unchanged */
+
+/* ---------------------------------------------------------
+ * Reading and writing tables
+ * ---------------------------------------------------------
+ */
+
+fh_result
+fh_table_init(fhTable * table);
+/* Call once to initialise information about a given table. This will
+ * walk through all of the columns and fill out starting character
+ * positions and so forth, and will calculate the size of each row
+ * and the size of the table as a whole, and so forth. */
+
+fh_result
+fh_table_populate_header(HeaderUnit hu, fhTable * table);
+/* Sets up keywords for a table extension header, including all 
+ * of the column information, etc. This will initialise the table
+ * structure if necessary. This does not include any fh_write... 
+ * calls to write the header to the file. */
+
+fh_result
+fh_reserve_padded_table(HeaderUnit hu, int fd);
+/* Analogous to fh_reserve_padded_image() for tables. This reserves 
+ * space for the table based on the information in the passed extension
+ * header at the current location in the file. The header must therefore
+ * be populated prior to calling this function (use 
+ * fh_table_populate_header() to build a header from a table structure.
+ */
+
+fh_result
+fh_map_table(HeaderUnit hu, void** data, int size);
+fh_result
+fh_munmap_table(HeaderUnit hu);
+/* Analogous to fh_map_raw_image() and fh_munmap_image() for tables. 
+ * These calls give the calling program access to a memory mapped pointer
+ * to the data in the FITS file.  The data format is equivalent to what
+ * would be produced by fh_read_image() with typesize=FH_TYPESIZE_RAW.
+ * Whether or not the file can be modified through the memory-mapped
+ * pointer depends on whether fh_mode=FH_FILE_RDONLY or FH_FILE_RDWR
+ * in the call to fh_file() that opened the file.  Be sure to use
+ * fh_munmap_table() when done.
+ *
+ * `size' must match the exact number bytes of data which should be in
+ * the file, according to its NAXIS and BITPIX values, excluding padding.
+ *
+ * %%% TODO: FH_FILE_RDWR is completely unimplemented!
+ *
+ * %%% TODO: File locking is not handled properly yet.  For now, use
+ * FH_FILE_RDONLY_NOLOCK and FH_FILE_RDWR_NOLOCK, especially on MEF
+ * files where the locks are left in place until the file is closed
+ * otherwise!
+ */
+
+fh_result
+fh_table_read_value(fhTable * table, void * data,
+                    int row, int col, void * value);
+/* Reads a single value from an existing table at (row, column). 
+ * The table field is interpreted based on the format of that
+ * column in the table structure, and is passed back via the
+ * 'value' pointer. It is the caller's responsibility to ensure
+ * that 'value' points to a location with sufficient space for
+ * the data in the field, and that any casting to & from a void
+ * pointer is done correctly.
+ */
+
+fh_result
+fh_table_write_value(fhTable * table, void * data, 
+                     int row, int col, void * value);
+/* Similar to read_value() above, this function overwrites a field
+ * in a table at the given location.  The caller is repsonsible 
+ * for casting the location of the stored data to a void pointer. 
+ */
+
+
 #endif /* _INCLUDED_fh */