|
LTL
2.0.x
|
Modules | |
| MArray Stream I/O | |
| MArray ASCII I/O | |
| MArray FITS file I/O | |
Classes and methods for interfacing with ltl::MArray.
ltl::MArray to streams, columnar ASCII files and FITS files. Access to columnar ASCII files and to FITS files is done using the classes ltl::AscFile, ltl::FitsIn, and ltl::FitsOut. Access to streams is realized using ltl::operator>> and ltl::operator<<, in accordance with the standard library.The class ltl::ExprBase<T,N> is interfaced to output streams and ltl::MArray<T,N> to input and output streams using the global operators
These are defined in the file <ltl/marray_io.h> which you will have to additionally include.
The output of operator<< is exactly what operator>> expects as input, so you can use the latter to read what you have written using the former. The rank has to be known a priori when reading from operator<<. The lengths and index ranges are read from the stream. The format generated is human readable and can also serve as pretty printing for MArrays. Each dimension is wrapped in brackets and indented.
For example:
And here's the programs output:
MArray<float,2> ( 7 x 3 ) : (-3,3) (1,3) [[ 1 1 1 1 1 1 1 ] [ 1 1 1 1 1 1 1 ] [ 1 1 1 1 1 1 1 ]]
You can also output the result of the evaluation of an MArray expression directly without using a temp[orary to store the result:
To map between type names and types, see the file <misc/type_name.h>, which provides type traits for this purpose. To add the string representation of a non-primitive type, use the macro LTL_TYPE_NAME:
The class ltl::AscFile provides the interface to columnar ASCII files. It supports arbitrarily delimited columns of numbers, empty lines, comments, and reading a restricted range of lines and columns.
ltl::AscFile( string fname, char delim=0, string comment="#" ), ltl::AscFile( string fname, int firstLine, int lastLine=-1, char delim=0, string comment="#" ): Constructors of the class ltl::AscFile.
Columns in the file can be separated by arbitrary characters, to read whitespace delimited files, specify delim=0, the default, as delimiter. Otherwise set delim to the delimiter char.
Arbitrary strings may be used as comment delimiters. Using the second constructor, the firstLine is the first line to be read, counting from one, lastLine is the last line to be read, (-1 specifies reading until EOF, which is the default). When searching for the first line to be read, all nonempty and non-comment lines are counted, but they may contain arbitrary text, so they don't have to be columnar. When searching for the last line, only data rows are counted. The lines beyond the last line are not read at all.
int ltl::AscFile::rows(), int ltl::AscFile::cols()
Return the number of rows in the whole file, and the number of columns in the first data row, in the case that the complete file is read, or the number of data rows between firstLine and lastLine, i.e. lastLine - firstLine + 1, in case only a restricted range of lines is read. The columns are counted in the first line in the latter case.
MArray<int,1> ltl::AscFile::readIntColumn( col ), MArray<float,1> ltl::AscFile::readFloatColumn( col ), MArray<double,1> ltl::AscFile::readDoubleColumn( col )
Read a column out of the file, into an ltl::MArray, using either int, float, or double type.
MArray<int,2> ltl::AscFile::readIntColumns( int first=1, int last=-1 ), MArray<double,2> ltl::AscFile::readFloatColumns( int first=1, int last=-1 ), MArray<double,2> ltl::AscFile::readDoubleColumns( int first=1, int last=-1 )
Read a range of columns into a 2-dimensional ltl::MArray. The default parameters read from the first to the last column, i.e.
and
are identical.
For reading data into C-style arrays and STL containers, the following overloaded template methods are provided:
template<class T> int ltl::AscFile::readColumn( int col, T* &carray )
Read a single column into a C-style array. The memory is allocated using malloc.
template<class T> int ltl::AscFile::readColumn( int col, T& container )
Read a single column into an arbitrary container supporting a push_back function. In the STL these are vector, list, deque, queue, priority_queue, and stack.
To retrieve a commented header the ltl::AscFile::getHeader function is supplied.
int ltl::AscFile::getHeader( vector<string>& v, bool keepcs=false )
Retrieves the commented header from the file in the vector<string> v and return the number of lines read. The keepcs boolean controls whether the leading comment string is stripped from the returned strings.
| ltl::IOException | These methods throw an object of type ltl::IOException on error. This exception is derived from std::exception. |
The FITS files must conform to FITS definition NOST 100-2.0 with additional restrictions when syntax checking is on (see below).
DATE will be reset with every writeHeader() call (i.e. when writing file). ORIGIN will be reset when writing, string can be set (see below). BLOCKED will discarded when writing EPOCH will be transformed to EQUINOX if not already present, and discarded when writing. BSCALE and BZERO will be applied when reading data, but ignored when writing; since FitsOut erases those cards in construction they have to be set and handled by the user if needed. BLANK is not applied when reading data, the user has to take care of it; it will be discarded when writing BITPIX < 0 (floating point) data . CTYPEn, CRPIXn, CRVAln, CDELTn, CROTAn are ignored when reading, n > naxis erased when writing.The header will be reformatted to NOST 100-2.0 recommendation: Mandatories first, Array keys, DATE, other reserved keys, other keys, COMMENT, HISTORY, (junk keys,) END. Junk keys are keywords with a questionable, but not completely wrong syntax (i.e. other than standard commentary keywords like HIERARCH, DATE keywords with wrong syntax.
To use LTL FITS I/O facilities include
| ltl::FitsException | On errors a ltl::FitsException indicating the error is thrown. This exception is derived from std::exception. |
To read FITS files, use the class ltl::FitsIn. A short description follows:
Construct a ltl::FitsIn instance for reading from file named file. To turn off warnings on stderr one may set quiet = true.
ignore_header = true will cause all cards except the mandatory cards to be treated as junk cards, i.e. no syntax checking is performed. Caveat: BSCALE and BZERO will be ignored in this case!| ltl::FitsException | If the file is unreadable for whatever reason, a ltl::FitsException indicating the error is thrown. |
Shortcuts to obtain the values of BITPIX, NAXIS, and NAXISn
Shortcuts to obtain the values of BSCALE and BZERO.
Print a short summary of the file to be read on given ostream: filename, BITPIX, NAXIS, and naxis parameters.
Gives the number of bytes per pixel.
Gives the offset to the beginning of the data segment, i.e. the total length of the header in bytes.
Gives the number of bytes in the data segment.
Return a Region object displaying the NAXIS settings.
| ltl::FitsException | If a keyword cannot be found a ltl::FitsException is thrown. |
Returns a keyword trimmed to 8 characters, which is required by all methods involving keywords.
Get the value of a keyword.
Returns true if the card is in fixed format.
Retrieve the comment for the given keyword.
Get all COMMENT or HISTORY lines as a string. The individual lines are separated by newline characters.
Set the util::Region region of the file to be read.
Reset to full data.
Read data from the active region in the FITS file in into the MArray A.
If the A has no memory allocated yet, the whole active region is read and new memory is allocated to hold the data. If A already points to a valid memory FitsIn getExtension(const string& xtension, const string& extname, const int extver = 0, const int extlevel = 0); ! Return FitsIn object holding extno 's extension (get by sequential number). FitsIn getExtension(const size_t extno); ! Return the next extension. virtual FitsIn getNextExtension(); chunk, only as much data is read as will fit into A. The next call to operator>> will read the next chunk of data. Tiling is done along NAXIS1 first, then NAXIS2, etc., in a "rectangular" pattern. The user is responsible for choosing appropriate chunk sizes, such that the resulting tiling will cover the whole data.
Reading a whole FITS file into an MArray is, therefore, pretty easy:
Internally, reading the data segment of a FITS file into MArrays is done by mapping the file into memory using mmap(). The mapping is done when the first read occurs. In order to free address space prior to destruction of the ltl::FitsIn object one can use
To read FITS extensions open the file with
instead of a simple ltl::FitsIn.
You can access the primary header and data segment by using the Extension object in the same way as the FitsIn object. To actually get access to the extension header and data you call one of the following methods.
For Image Extensions you just go ahead and use the returned object as a FitsIn object. For BinTable Extensions you have to create a
of the ltl::FitsIn() object returned by any of the ltl::FitsExtensionIn() methods. Use one of the
methods to read a column by name or number into an MArray. Default is to read a whole column, but you may specify the range.
Construct a ltl::FitsOut object, optionally copying the header information from header.
If no header is given, a default will be created, containing only mandatories. Those will be adjusted to reflect what is written when the actual writing is performed.
Note that ltl::FitsIn is derived from ltl::FitsHeader.
Set BITPIX explicitly. If you do this, type conversion to the type specified by BITPIX will be performed when writing. If you do not call this method, BITPIX will be set according to what go passed when actually performing the write operation, and no type conversion will be performed.
Set the ORIGIN keyword, defaults to "LTL FITS IO class".
Add comment or history text. The text will be automatically wrapped and added to the list of COMMENT or HISTORY keywords.
Add a card with a value of given type to the header.
You may also use the methods for reading keywords described above in ltl::FitsIn.
Remove card from header.
Actually writing data from an ltl::MArray in FITS format:
Write data from A to FITS format file. If BITPIX has not been set explicitly using ltl::FitsOut::setBitpixOut(), it will be set according to the type T of the ltl::MArray, otherwise, data of A will be converted to the value specified by ltl::FitsOut::setBitpixOut().
The same options are possible as in reading using ltl::FitsIn, explained above.
Example writing an image to a FITS file:
If you want to write very large FITS-files (i.e. very large primary data segments; for Extensions see further down below) you can split the writing into pieces. For an example look into test/testfitsio.cpp and search for void testwriteregion( void )
For convenience, in case you want to copy (parts of) a FITS file and optionally only want to change header information, there is a version of operator<< using only ltl::FitsOut and ltl::FitsIn:
Copy data from in to out. Regions in in will be respected, so that portions of files can be copied.
For example:
For now only writing of image extensions is supported. FITS Extension files are written sequentially. Example:
Use ltl::FitsIn as some_other_FitsHeader_object if you want to copy a header from an existing file. Use ltl::FitsOut to construct a new header from scratch (the FitsOut object will not create a file unless you feed an MArray into it).
You can use the FITS I/O facilities with C-style arrays, too, without using MArrays.
You may use any FITS I/O methods with ltl/fits.h instead of ltl/fitsio.h.
Additionally, you can perform I/O operations on a per pixel basis:
This is still under development. ltl::FitsIn::setRegion() is ignored for this set of methods. You can use setPosition() and getPosition() instead. No range checking is performed, you must prevent reading past EOF yourself.
1.8.5