spacecruft
/
qfits
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
qfits/qfits/html/index.html

500 lines
30 KiB
HTML
Raw Blame History

<html>
<head>
<meta name="keywords" content="eso, FITS format, C library">
<link href="doxygen.css" rel="stylesheet" type="text/css">
<title>qfits 4.3.3</title>
</head>
<body text="#000000" bgcolor="#ffffff">
<!-- Generated by Doxygen 1.2.5 on Wed Nov 5 16:04:35 2003 -->
<h1>qfits Reference manual</h1>
<p>
<h3 align="center">4.3.3</h3>
<p>
<hr>
<p>
<a name="welcome"><h2>Introduction</h2></a>
<p>
<b>qfits</b> is a stand-alone library written in C to interact with files complying with the FITS format. It is fast and portable over any kind of POSIX-compliant platform.
<p>
Rather than going through the FITS format specification and trying to implement some support for everything that is described there, this library was built day after day upon request. This guarantees that all the functions you will find in the library have been written for some purpose in the VLT pipeline context, and all of them are used daily in a production environment.
<p>
Functionalities offered by this library are:
<p>
<ul>
<li>Header queries (get keywords, values).<li>Header manipulation (load/modify/save).<li>Header/data offset queries.<li>Pixel loading/saving to memory.<li>Support for files of any dimension (NAXIS).<li>Support for FITS extensions, including ASCII and binary tables.</ul>
This library also comes with a limited set of interfaces to Python to make some of its functionalities usable from this language. See the compilation instructions to build it as a Python module. The Qfits.py module contains its own doc.
<p>
<hr>
<p>
<a name="history"><h2>History</h2></a>
<p>
<b>qfits</b> was born from the need to have a simple but powerful C library to handle FITS file access. There are already many libraries on the Net to handle FITS files, but they tend to be bloated with far too many features and may raise portability and maintenance issues.
<p>
<b>qfits</b> was written to take care of all low-level aspects of the FITS format, and only these. You will find there a wealth of optimized functions to access everything inside FITS files, but nothing about what you could do with the data: this is left to other (e.g. image processing) libraries. There is no suggested image or cube type, and the table object only loads the data without trying to interpret them.
<p>
The idea is that people wanting to work with FITS might have different requirements: somebody writing an image viewer might just want to load a pixel buffer, somebody handling headers only might want to have easy access to header information without touching pixel data. <b>qfits</b> allows you to get your hands on what is contained in a FITS file but does not force you to use any specific high-level data type to describe your data.
<p>
<hr>
<p>
<a name="authors"><h2>Authors</h2></a>
<p>
Nicolas Devillard and Yves Jung, ESO.
<p>
<hr>
<p>
<a name="header"><h2>Header handling</h2></a>
<p>
This section gives you an overview of the functionalities offered to work on FITS headers with <b>qfits</b>. For a complete reference, check out the reference manual: <a class="el" href="qfits_h.html">qfits.h</a>.
<p>
FITS headers are simply formatted as 80-char lines (<em>cards)</em> containing ancillary data represented in ASCII format like:
<p>
keyword = value / comment
<p>
If you want to retrieve data from a FITS file header, you will find various useful query routines to get a keyword value from main or extension headers. Values are returned as strings and not coerced to any particular (e.g. numerical) type. See e.g.
<p>
<ul>
<li><a class="el" href="qfits_h.html#a76">qfits_query_hdr</a>() to query the main header.<li><a class="el" href="qfits_h.html#a77">qfits_query_ext</a>() to query an extension header.<li><a class="el" href="qfits_h.html#a78">qfits_query_n_ext</a>() to get the number of extensions.</ul>
You may also want to handle file inputs by yourself and have FITS cards split into their components key/value/comment. See e.g.
<p>
<ul>
<li><a class="el" href="qfits_h.html#a50">qfits_getkey</a>() to extract the key from a FITS line.<li><a class="el" href="qfits_h.html#a51">qfits_getvalue</a>() to extract the value.<li><a class="el" href="qfits_h.html#a52">qfits_getcomment</a>() to extract the comment.</ul>
Since all FITS values are returned as strings, you may need to identify types. See e.g.
<p>
<ul>
<li><a class="el" href="qfits_h.html#a86">qfits_get_type</a>() to identify a value type<li><a class="el" href="qfits_h.html#a81">qfits_is_boolean</a>()<li><a class="el" href="qfits_h.html#a82">qfits_is_int</a>()<li><a class="el" href="qfits_h.html#a83">qfits_is_float</a>()<li><a class="el" href="qfits_h.html#a84">qfits_is_complex</a>()<li><a class="el" href="qfits_h.html#a85">qfits_is_string</a>()</ul>
Of course, you can use the usual <code>atof()</code>, <code>atoi()</code> and <code>scanf()</code> functions to convert a string to a numerical type.
<p>
You may also want to perform more complex operations on FITS headers, like loading one, modifying it and saving it back to a new file. The <a class="el" href="struct_qfits_header.html">qfits_header</a> data structure is offered for that purpose. It comes with utilities like:
<p>
<ul>
<li><a class="el" href="qfits_h.html#a53">qfits_header_read</a>() to load a header.<li><a class="el" href="qfits_h.html#a54">qfits_header_readext</a>() same from an extension.<li><a class="el" href="qfits_h.html#a47">qfits_header_dump</a>() to save a header to a file.<li>...</ul>
And of course all manipulation tools you can think of:
<p>
<ul>
<li><a class="el" href="qfits_h.html#a29">qfits_header_add</a>()<li><a class="el" href="qfits_h.html#a30">qfits_header_add_after</a>()<li><a class="el" href="qfits_h.html#a31">qfits_header_append</a>()<li><a class="el" href="qfits_h.html#a33">qfits_header_mod</a>()<li><a class="el" href="qfits_h.html#a32">qfits_header_del</a>()<li>...</ul>
There are other functions to create new FITS cards, dump a header to screen for debugging purposes, etc. See the reference manual (<a class="el" href="qfits_h.html">qfits.h</a>) for an exhaustive description.
<p>
An important feature of the <a class="el" href="struct_qfits_header.html">qfits_header</a> object when loaded from a file, is that it keeps the memory of the initial FITS card. The data structure that is carried around for each FITS card contains:
<p>
<ul>
<li>Identified keyword<li>Identified value<li>Possible comment<li>Line as read from initial file when applicable.</ul>
This feature is fairly useful if you want to perform header manipulation without getting too intrusive. You can use this to load a header, modify a couple of cards and dump all back to disk. The dumped header will only be modified for the cards you have touched, all others will be forwarded verbatim as they appeared in the initial file. This least-modification policy ensures that you will not modify the lines you do not need to touch.
<p>
This feature can be turned off by "touching" all lines in a header using <a class="el" href="qfits_h.html#a35">qfits_header_touchall</a>(), which removes all initial line information from a <a class="el" href="struct_qfits_header.html">qfits_header</a> object. This is useful to force a reformatting of a FITS header e.g. when the file header is damaged.
<p>
Notice that ESO's <code>HIERARCH</code> keywords and DICB ordering are natively supported by <b>qfits</b>, i.e. when you work with <a class="el" href="struct_qfits_header.html">qfits_header</a> objects you can be sure that they will properly recognize and sort keywords following ESO conventions.
<p>
<hr>
<p>
<a name="data"><h2>Data handling</h2></a>
<p>
This section gives you an overview of the functionalities offered to work on FITS data segments with <b>qfits</b>. For a complete reference, check out the reference manual (<a class="el" href="qfits_h.html">qfits.h</a>).
<p>
Data segments are quite simply stored: they always contain data contiguously in uncompressed format, so reading them is mostly a matter of applying an <code>fread()</code> statement at the right place in the file, with the right size. To find out about offsets to data and header parts in a FITS file (possibly containing several extensions), you can make use of:
<p>
<ul>
<li><a class="el" href="qfits_h.html#a87">qfits_get_hdrinfo</a>() to return information about a header position and size (in bytes) in a file.<li><a class="el" href="qfits_h.html#a88">qfits_get_datinfo</a>() to return information about a data segment position and size (in bytes) in a file.</ul>
<b>qfits</b> includes a caching mechanism to speed up accesses to large files to an optimal access time (only one parsing of the file is needed, even with multiple queries on the same file). This mechanism is internal to this module and invisible to the programmer using <b>qfits</b>. This means that you can loop on all sections on a huge file to retrieve file offsets for each extension, and pay the price of file parsing only at the first call.
<p>
If you want to dive further into data loading, you may want to have a look at table and image handling functionalities.
<p>
<a name="table"><h3>Table handling</h3></a>
<p>
A table is stored in a FITS file in an extension. The extension header contains all needed informations to read the data (number of columns, the column types, the columns labels, the columns unit, etc...).
<p>
A FITS table is composed by columns. Within one column there can only be data of one defined type, but you can store several values by field.
<p>
In BINARY tables, you can find 11 different data types, in ASCII tables, there are 5 different types. All these types are supported by <b>qfits</b>:<ul>
<li>ASCII tables:<ul>
<li>TFITS_ASCII_TYPE_A : Characters (1 byte)<li>TFITS_ASCII_TYPE_D : Double (8 bytes)<li>TFITS_ASCII_TYPE_E : Float (4 bytes)<li>TFITS_ASCII_TYPE_F : Float (4 bytes)<li>TFITS_ASCII_TYPE_I : Integer (4 bytes)</ul>
<li>BIN tables:<ul>
<li>TFITS_BIN_TYPE_A : Characters (1 byte)<li>TFITS_BIN_TYPE_B : Unsigned byte (1 byte)<li>TFITS_BIN_TYPE_C : Float complex (2 * 4 bytes)<li>TFITS_BIN_TYPE_D : Double (8 bytes)<li>TFITS_BIN_TYPE_E : Float (4 bytes)<li>TFITS_BIN_TYPE_I : Short (2 bytes)<li>TFITS_BIN_TYPE_J : Integer (4 bytes)<li>TFITS_BIN_TYPE_L : Logical (1 byte)<li>TFITS_BIN_TYPE_M : Double complex (2 * 8 bytes)<li>TFITS_BIN_TYPE_P : Array descriptor (2 * 4 bytes)<li>TFITS_BIN_TYPE_X : Bit (1 bit)</ul>
</ul>
The <a class="el" href="struct_qfits_table.html">qfits_table</a> object provided by <b>qfits</b> contains all necessary informations to define how the data are stored in the file: the name of the file it comes from, the table type (QFITS_BINTABLE or QFITS_ASCIITABLE), the number of columns and for each column a pointer to a <a class="el" href="struct_qfits_col.html">qfits_col</a> object.
<p>
Each <a class="el" href="struct_qfits_col.html">qfits_col</a> object contains informations defining the associated column: the type (e.g. TFITS_BIN_TYPE_L), the number of rows, the number of atoms per field, the label, the unit, etc...).
<p>
This <a class="el" href="struct_qfits_table.html">qfits_table</a> object is returned by <a class="el" href="qfits_h.html#a100">qfits_table_open</a>() and should only be destroyed with <a class="el" href="qfits_h.html#a101">qfits_table_close</a>().
<p>
This <a class="el" href="struct_qfits_table.html">qfits_table</a> object does not contain the table data, but has to be used to load the data with functions like:
<p>
<ul>
<li><a class="el" href="qfits_h.html#a102">qfits_query_column</a>()<li><a class="el" href="qfits_h.html#a105">qfits_query_column_data</a>()<li><a class="el" href="qfits_h.html#a107">qfits_query_column_nulls</a>()</ul>
<a class="el" href="qfits_h.html#a102">qfits_query_column</a>() returns you simply the data (byte swapped if necessary) as they were read in the file as a byte array. It is up to the user to interpret the data (e.g. to try to find out where the NULL values are).
<p>
<a class="el" href="qfits_h.html#a105">qfits_query_column_data</a>() does the same, but identifies the NULL values and replaces them by a user-provided value. In this case, the returned array is an array of data of the right type. It is returned as a void*, the user just has to cast it to a double*, a short* or what is needed.
<p>
For example, if you require in a table that contains 15 rows a column where you can find 3 values of type TFITS_BIN_TYPE_M (double complex), <a class="el" href="qfits_h.html#a105">qfits_query_column_data</a>() will return an array of 15 * 3 * 2 double values.
<p>
<b>qfits</b> also provides functions to write a table to a FITS file (<a class="el" href="qfits_h.html#a108">qfits_save_table_hdrdump</a>()), or to print out a table value or a complete table on the screen or in a file (<a class="el" href="qfits_h.html#a111">qfits_table_field_to_string</a>()).
<p>
<a name="image"><h3>Image handling</h3></a>
<p>
The <a class="el" href="struct_qfitsloader.html">qfitsloader</a> and <a class="el" href="struct_qfitsdumper.html">qfitsdumper</a> objects are offered to simplify the action of reading/writing image data. The corresponding operators take care of retrieving all necessary ancillary information (image size, pixel type, buffer position), perform a memory allocation or mapping and read the file into memory. See the following functions:
<p>
<ul>
<li><a class="el" href="qfits_h.html#a64">qfitsloader_init</a>() to initialize a loader object.<li><a class="el" href="qfits_h.html#a65">qfits_loadpix</a>() to load pixel data into memory.<li><a class="el" href="qfits_h.html#a69">qfits_pixdump</a>() to save pixel data to disk.</ul>
As for tables, the idea is that you first launch an analysis of the file to get back a number of informations about what is present there. In the case of images, you use <a class="el" href="qfits_h.html#a64">qfitsloader_init</a>() to see if pixel loading could be done, then use <a class="el" href="qfits_h.html#a65">qfits_loadpix</a>() to perform the actual load.
<p>
Pixel I/O are taking place in float, int or double format. See the corresponding functions:
<p>
<ul>
<li><a class="el" href="qfits_h.html#a66">qfits_pixin_float</a>()<li><a class="el" href="qfits_h.html#a67">qfits_pixin_int</a>()<li><a class="el" href="qfits_h.html#a68">qfits_pixin_double</a>()<li><a class="el" href="qfits_h.html#a70">qfits_pixdump_float</a>()<li><a class="el" href="qfits_h.html#a71">qfits_pixdump_int</a>()<li><a class="el" href="qfits_h.html#a72">qfits_pixdump_double</a>()</ul>
Loading pixels as floats means that whichever pixel format (BITPIX) is used in your input FITS file, all pixels will be converted to your local representation of float upon loading. The 3 offered types basically allow you to work with 3 kinds of pixels internally, choose the one that best suits your needs. 'int' is not recommended for loss of precision, and 'double' for memory and performance issues.
<p>
Saving pixels can be done with any BITPIX setting. There are 3 pixel dumpers as there are 3 pixel loaders, because there are 3 possible types for pixel buffers in memory (int, float, double). All pixels are converted on the fly to the requested BITPIX setting.
<p>
Notice that as soon as you start using pixel loading functions, you must comply with the <b>qfits</b> memory model. This basically means that you should not only include <code><a class="el" href="qfits_h.html">qfits.h</a></code> in your program, but also <code>xmemory.h</code> to get the proper definitions for memory allocation functions.
<p>
<a name="utils"><h2>Other utilities</h2></a>
<p>
Some additional functions are offered in <b>qfits</b>, they are useful in the VLT context. See:
<p>
<ul>
<li><a class="el" href="qfits_h.html#a91">date_now</a>()<li><a class="el" href="qfits_h.html#a92">time_now</a>()<li><a class="el" href="qfits_h.html#a93">get_date_iso8601</a>()<li><a class="el" href="qfits_h.html#a94">get_datetime_iso8601</a>()</ul>
<hr>
<p>
<a name="features"><h2>Features</h2></a>
<p>
This section describes various unique features of <b>qfits</b>.
<p>
<a name="portability"><h3>Portability</h3></a>
<p>
This library has been ported and tested on the following platforms:
<p>
<ul>
<li>Linux x86 and alpha<li>Solaris 2.5, 2.6 and 2.8<li>HPUX 8, 9, 10, 11<li>AIX<li>BSD compatible, including Darwin (Mac OS X)<li>OSF/1 or Tru64</ul>
Since <b>qfits</b> depends on POSIX system routines, there is little chance it could compile natively on Windows, except with the help from GNU porting tools from Cygnus. This has never been attempted so far.
<p>
<a name="speed"><h3>Speed</h3></a>
<p>
The offered routines make use of caching mechanisms and memory-mapping system calls to enhance FITS file parsing and speed up the code.
<p>
<a name="interfaces"><h3>Interfaces to C++/Python</h3></a>
<p>
You should be able to compile this library with a C++ compiler, the header files include the usual blurb to allow that without warning from the compiler. You might have problems due to pointer casts and other various incompatibilities due to the variety of C++ dialects and compilers, though. If you really need to hook this library into C++ code, your best bet is probably to compile the library as a standard C library and link your C++ code against it.
<p>
A limited set of interfaces to Python is offered. See the INSTALL file in the main distribution directory for instructions about installing this library as a Python module.
<p>
<a name="precision"><h3>Numerical precision</h3></a>
<p>
Since FITS headers are stored as strings, numerical precision is limited by the number of digits used to write a number in a FITS card, which is in theory larger than what a 32-bit floating-point can store. Using <b>qfits</b>, these values are available to a C programmer as a string, making sure that precision has at least not be lost in the reading process.
<p>
<a name="conservative"><h3>Conservative headers</h3></a>
<p>
As mentioned above, if you only need to load a header, modify a card and save it back, you will find out that <em>only</em> the card you touched has been modified, the rest was verbatim transferred. This is useful to ensure that the library formatting does not disturb your format.
<p>
<a name="hierarch"><h3>Native HIERARCH support</h3></a>
<p>
Native support for ESO's <code>HIERARCH</code> keywords, as well as keywords of any length (up to 80 chars per line).
<p>
<a name="dicb"><h3>ESO/DICB keyword ordering</h3></a>
<p>
Native support for DICB (ESO only) ordering of keywords in the headers. FITS files created with this library will be DICB compliant with respect to keyword ordering.
<p>
<a name="xmemory"><h3>Memory model</h3></a>
<p>
<b>qfits</b> does not only offer pixel loading mechanisms, it also comes bundled with a memory module based on a model optimized for the handling of very large data segments. In practice, it means that as soon as you have included <code>xmemory.h</code>, your calls to malloc/calloc/free are re-directed to specific versions which put your program on steroids. Calls to memory allocators will yield valid data pointers past the hardware limits of your machine, up to 2 or 4 Gb on a 32-bit workstation and insanely high values on 64-bit processors.
<p>
This memory module is also distributed as a stand-alone module which can be downloaded and used without <b>qfits</b>. It is mandatory to use this module when using <b>qfits</b> pixel loaders, to get the advantages of large memory handling.
<p>
If you are only interested in header manipulation, you do not need to include <code>xmemory.h</code>.
<p>
<hr>
<p>
<a name="install"><h2>Installation instructions</h2></a>
<p>
In the main <b>qfits</b> directory, type:
<p>
<div class="fragment"><pre>
./configure ; make
</div></pre>
<p>
To use the library in your programs, add the following line on top of your module:
<p>
<div class="fragment"><pre><font class="preprocessor">#include "<a class="code" href="qfits_h.html">qfits.h</a>"</font></div></pre>
<p>
And link your program with the <b>qfits</b> library by adding <code>-lqfits</code> to the compile line.
<p>
If you ever need to make calls to one of the <b>qfits</b> pixel loaders, you need to include the memory model definitions also with:
<p>
<div class="fragment"><pre><font class="preprocessor">#include "xmemory.h"</font></div></pre>
<p>
Including this file is needed so that you can safely <code>free()</code> the pointer returned by a pixel loader. See the documentation about pixel loaders for more information.
<p>
To compile <b>qfits</b> as a Python module, you need to have Python installed on your machine and available in your PATH. Type:
<p>
<div class="fragment"><pre>
% python setup.py install
</div></pre>
<p>
This should build the module and install it in your default library path. This makes use of the distutils package, standardized since Python 2.0. This means that you need Python 2.0 at least to compile and run this module. If you are running Python 1.5 or 1.6, you may want to install the <code>distutils</code> package on your platform, which will handle the <b>qfits</b> module installation.
<p>
<hr>
<p>
<a name="python"><h2>Python module documentation</h2></a>
<p>
The following documentation has been directly extracted from the qfits Python module (Qfits.py) by running:
<p>
<div class="fragment"><pre>
% pydoc Qfits.py
</div></pre>
<p>
Once Qfits.py is installed in your Python distribution, you should also be able to browse this documentation using <code>pydoc</code>.
<p>
<div class="fragment"><pre>
Python Library Documentation: module Qfits
NAME
Qfits - Qfits.py: a module to read header information from a FITS file.
FILE
Qfits.py
DESCRIPTION
This module offers a function to read all headers in a given
FITS file and return them as a list of strings.
CLASSES
fitsinfo
class fitsinfo
| The fitsinfo class encapsulates queries into a FITS header.
|
| Initialize an instance by giving the name of a file, the following
| fields are then filled in:
|
| - filename - Name of the file
| - n_ext - Number of FITS extensions in file
| - hdrs - List of headers
| - xtnum - Current extension number for get()
|
| The following methods are offered:
|
| * get()
| This method retrieves keyword information in a given instance.
| Provide one or more keywords to look for and this function will
| browse the hdrs list for matching keywords. This method returns a
| string if you requested only 1 keyword or a list of strings if you
| requested several keywords. A failed match returns None.
|
| This method will only search for keywords in the xtnum extension.
|
| get() supports the shortFITS notation, in which A.B.C is transformed
| into HIERARCH ESO A B C before lookup in the FITS header. Notice that
| the given strings are also converted to uppercase before the search
| is launched. See the function expand_keyword() in this module.
|
| Returned string values are always pretty-formatted, i.e. something
| stored into a FITS string as 'o''hara' will be returned as o'hara.
|
| Examples:
|
| q = fitsinfo('vltframe.fits')
| q.get('simple') # returns 'T'
| q.get('simple', 'naxis') # returns ('T', '2')
|
| To search for keywords in the 3rd extension:
|
| q = fitsinfo('wfiframe.fits')
| q.xtnum = 3
| q.get('xtension') # returns 'IMAGE'
| q.get('det.chip3.id', 'bitpix')
| # returns ('ccd52', '16')
|
| * datamd5()
| This method computes the MD5 signature of all the data parts of the
| given FITS file and returns it as a 32-char string containing a
| hexadecimal number on 128 bits.
|
| Methods defined here:
|
| __init__(self, filename)
| Provide a filename to initialize the object.
|
| __repr__(self)
|
| datamd5(self)
|
| get(self, *keywords)
| Get a list of keyword values and return it as a list. If only one
| keyword is requested, the returned value is a single string (or
| None if the keyword was not found). If several keywords are passed,
| the returned value is a list of found values.
|
| The search is only performed in the current extension (xtnum field
| in the class).
|
| ----------------------------------------------------------------------
FUNCTIONS
datamd5(filename)
This function computes the MD5 signature of all data parts in a FITS
file and returns a 32-char string containing the signature as an
hexadecimal number (128 bits). It raises an IOError exception if the
given filename does not correspond to a valid FITS file.
expand_keyword(key)
This function is useful to expand a given keyword into
its FITS equivalent. What it does is simply bring the
word to uppercase, then expand shortFITS words to HIERARCH
ESO notation, like:
simple -&gt; SIMPLE
NaXiS -&gt; NAXIS
det.dit -&gt; HIERARCH ESO DET DIT
get_headers(filename)
This function is the main operator in this module.
Given a file name, it returns all header informations
in a list of lists. The top list contains one element
per found header, i.e. if the given file has 8 extensions,
the top list contains 9 items (1 for the main header,
8 for the extension headers). Each list contains
in turn all informations about the corresponding
headers as a list of tuples like
(key, value, comment)
Example:
The given FITS file contains 1 main header and 2
extension headers given as follows:
--- main header
SIMPLE = T / FITS format
BITPIX = 8 / Bits per pixel
NAXIS = 0 / No data
...
END
--- extension 1
XTENSION = 'IMAGE' / Image extension
BITPIX = 16 / Bits per pixel
...
END
--- extension 2
XTENSION = 'IMAGE' / Image extension
BITPIX = -32 / Bits per pixel
...
END
The returned list contains three items.
The first one is a list corresponding to the
main header, then come the two extension
headers. The first list looks like:
[ ('SIMPLE','T','FITS format'),
('BITPIX', '8', 'Bits per pixel'),
('NAXIS', '0', 'No data'),
...
('END', '', '') ]
The extension lists look like this:
[ ('XTENSION', 'IMAGE', 'Image extension'),
('BITPIX', '16', 'Bits per pixel'),
...
('END', '', '') ]
[ ('XTENSION', 'IMAGE', 'Image extension'),
('BITPIX', '-32', 'Bits per pixel'),
...
('END', '', '') ]
In summary, if you want to get all FITS header informations
from a FITS file, call this function with:
hdr = qfits.get_headers(filename)
This function will raise an IOError exception if the provided
filename does not correspond to a valid file, and None if
the file is not FITS.
If the load succeeded, you can access individual keywords
with the following syntax:
hdr[extension][row][index]
Where:
extension runs from 0 to N_EXT (inclusive)
row is the row number of the card
index is 0 for the keyword, 1 for the value, 2 for the comment.
The number of FITS extensions found in the file is simply:
len(hdr)-1
version()
This function returns the version number of the
underlying qfits module.
</div></pre>
<p>
<hr>
<p>
<a name="faq"><h2>Frequently Asked Questions</h2></a>
<p>
<a name="faq1"><h3>Where should I start to use qfits?</h3></a>
<p>
Try to build the library on your system first. You should then have a new library file called libqfits.a. To use the library functionalities in your programs, you must add the following include in your list of includes:
<p>
<div class="fragment"><pre>
#include "qfits.h"
</div></pre>
<p>
And then compile your program adding the correct flags to indicate where the <b><a class="el" href="qfits_h.html">qfits.h</a></b> header file is, where the libqfits.a file is, and that you want to link against libqfits. Example: if the header file is in /usr/local/include and the library in /usr/local/lib, you would use:
<p>
<div class="fragment"><pre>
% cc -o myprog myprog.c -I/usr/local/include -L/usr/local/lib -lqfits
</div></pre>
<p>
If you need to use pixel loaders/dumpers, you also need to include the <b>qfits</b> memory-handling module:
<p>
<div class="fragment"><pre>
#include "xmemory.h"
</div></pre>
<p>
Now you are all set. Refer to this documentation for more information about the offered data structures and associated methods.
<p>
<a name="faq2"><h3>What should I know about the cache mechanism?</h3></a>
<p>
Parsing FITS files to find extensions is a lengthy process, because the FITS format does not declare in the main header where the following extensions are located in the file. Any access to a FITS file with this library will cache a number of offset pointers in the file to allow fast access to extensions. This means that the file is parsed completely only once, the first time it is accessed through any of the <b>qfits</b> functions.
<p>
The cache is implemented (since version 4.2) as a rotating buffer of modest size: 128 FITS file information structures can be held simultaneously. If you do need to perform accesses on a list of more than 128 files and want to use the caching mechanism at its best, it is recommended to isolate all your FITS requests to a given file in the same code area.
<p>
As a programmer, you do not need to initialize or shutdown the cache, this is done automatically.
<p>
The rotating buffer is a global data structure private to the cache module. The immediate side-effect is that the library is thread-unsafe. If you are concerned about writing multi-threaded applications, you should use a mutex upon accessing this library. Making a thread-safe compliant version of this library should not be too hard, but the need has not been felt yet.
<p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink