 News |
FAQ
|
| Search
|
Home
|
| Getting Started | Documentation | Glish | Learn More | Programming | Contact Us |
|
| Version 1.9 Build 1556 |
|
The technique for accessing data will be illustrated using the FITS primary array, as implemented by the PrimaryArray class. This class fully supports arrays of arbitrary dimensionality, up to the FITS limit of 999 dimensions. For a PrimaryArray, dims() gives the number of dimensions and dim(i) gives the value of the i-th dimension. FITS multi-dimensional arrays are stored in FORTRAN order, not in C order. Options on the store, copy, and move functions exist to convert from one order to the other, if that is necessary. The PrimaryArray class is a template class, with the TYPE parameter being the type of data in the FITS array. The public portion of the PrimaryArray class is shown below.
template <class TYPE>
class PrimaryArray : public HeaderDataUnit {
public:
PrimaryArray(FitsInput &, ostream & = cout);
PrimaryArray(FitsKeywordList &, ostream & = cout);
virtual ~PrimaryArray();
double bscale() const;
double bzero() const;
char *bunit() const;
Bool isablank() const;
Int blank() const;
char *ctype(int n) const;
double crpix(int n) const;
double crota(int n) const;
double crval(int n) const;
double cdelt(int n) const;
double datamax() const;
double datamin() const;
uInt nelements() const;
double operator () (int, int, int ...) const; // return physical data
double operator () (int, int) const;
double operator () (int) const;
TYPE & data(int, int, int ...); // access raw data
TYPE & data(int, int);
TYPE & data(int);
int store(const TYPE *source, FITS::FitsArrayOption = FITS::NoOpt);
void copy(double *target, FITS::FitsArrayOption = FITS::NoOpt) const;
void copy(float *target, FITS::FitsArrayOption = FITS::NoOpt) const;
void move(TYPE *target, FITS::FitsArrayOption = FITS::NoOpt) const;
virtual int read(); // read entire array into memory
virtual int read(int); // read next N elements into memory
virtual int write(FitsOutput &); // write current data
virtual int set_next(int); // prepare to write next N elements
};
The overloaded operator functions `()' all return physical data, i. e., data to which bscale() and bzero() have been applied, via the formula:
physical_data[i] = bscale() * raw_data[i] + bzero().
The various `data()' functions allow one to access and set the raw data
itself.
The `store()', `move()' and `copy()' functions allow bulk data transfer between the internal FITS array and an external data storage area. The external storage must have already been allocated and it is assumed that the entire data array is in memory. `Store()' transfers raw data at `source' into the FITS array; an allowable option is CtoF, which specifies to convert the array from C-order to Fortran-order. `Move()' is the opposite of `store()'. `Move()' transfers raw data from the FITS array to `target'; an allowable option is FtoC, which specifies to convert the array from Fortran-order to C-order. `Copy()' is similar to `move()' except that what is copied is physical data and not raw data; the physical data can be either double or float.
The `read()' and `write()' functions control reading and writing data from the external FITS I/O medium into the FITS array. Appropriate conversions are made between FITS and local data representations. One can read the entire array into memory, or one can only read portions of the array. In the latter case, one must specify that the next N elements are to be read or written. Note that the number of elements must be specified, NOT the number of bytes. If one reads portions of the array, as opposed to the entire array, only that portion is in memory at a given time. One can still access the elements of the array via the `()' and `data()' functions, as if the entire array was in memory; obviously care must be taken in this case to access only those portions that are actually in memory.
It is important to understand the proper sequence of operations with respect to I/O and data access. For input, the `read()' functions allocate an internal buffer of the appropriate size, if not already allocated, as well as reading and converting data; a `read()' function must be performed prior to accessing the data, i. e. before executing any `()', `data()', `copy()', or `move()' function. For output, the `store()' function similarly allocates an internal buffer before transferring data, and must be executed prior to any data access or `write()' function.
Writing portions of an array at a time, rather than the entire array, is a special case. The `set_next()' function is provided for this purpose. It declares the intention to write out the next N elements and must be executed prior to any `data()' function. It allocates a buffer of appropriate size, if not already allocated. Again, via the `data()' functions, one accesses the array as if the entire array were in memory. The `write()' function always writes the number of current elements in the internal buffer. The sequence of operations for each portion of the array written would be: 1) `set_next(N)', 2) fill the array using `data(N)' or other `data()' functions, and 3) `write(fout)'. The `set_next()' function must NOT be used with `read()' or `store()' functions; unpredictable results will occur. The following example illustrates the output cases.
Suppose we have an image array with 512 rows and 1024 columns stored in C-order. The C declaration would be:
int source[1024][512];
To write out the entire array:
FitsOutput fout; // some properly constructed FitsOutput
PrimaryArray<int> pa; // some properly constructed PrimaryArray
pa.store(source,FITS::CtoF);
pa.write(fout);
Suppose we wanted to write out the two-dimensional image array a column at a time, rather than write out the entire array. For FITS, dim(0) is 512, dim(1) is 1024. The following code fragment writes one column at a time in the proper FITS Fortran-order.
for (i = 0; i < dim(1); ++i) {
pa.set_next(dim(0));
for (j = 0; j < dim(0); ++j)
data(j,i) = source[i][j];
pa.write(fout);
}