Commit 578c6d92 authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

provide extended documentation

This is a legacy commit from before 2015-03-01.
It may be incomplete as well as inconsistent.
See COPYING.legacy and README.history for details.


SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/trunk
SVN Revision: 1826
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 6007a138
# this is <Makefile>
# ----------------------------------------------------------------------------
# $Id: Makefile,v 1.17 2005-07-05 08:21:11 tforb Exp $
# $Id: Makefile,v 1.18 2005-07-06 11:49:08 tforb Exp $
#
# Copyright (c) 2004 by Thomas Forbriger (BFO Schiltach)
#
......@@ -58,7 +58,8 @@ CPPFLAGS=-I$(LOCINCLUDEDIR) $(FLAGS)
all: install doxybrief doxyfull
install: install-include libdatreadxx.a
flist: Makefile $(wildcard *.cfg contrib/*.h) $(HEADERS) $(LIBSRC)
flist: Makefile $(wildcard *.cfg contrib/*.h) $(HEADERS) $(LIBSRC) \
README
echo $^ | tr ' ' '\n' | sort > $@
.PHONY: edit
......@@ -123,12 +124,13 @@ install-include: $(INSTHEADER)
DOXYWWWPATH=$(HOME)/public_html/txt/cxx/libdatreadxx
.PHONY: doxyclean doxyview doxybriefview doxyfullconf doxybriefconf
doxyclean: ;/bin/rm -rfv doc docbrief
doxyclean: ;/bin/rm -rfv doc/* docbrief/* doc docbrief
DOXYSRC=$(LIBSRC) $(HEADERS)
DOXYSRC=$(LIBSRC) $(HEADERS) README
doc/%: doxyfull.cfg $(DOXYSRC)
mkdir -vp $(DOXYWWWPATH)
/bin/rm -rfv doc/* doc
ln -sfv $(DOXYWWWPATH) doc
doxygen $<
......
/*! \file libaff/README
* \brief C++ containers for numbers (libaff)
/*! \file libdatreadxx/README
* \brief DATREAD++ library: reading seismic data (libdatreadxx)
*
* ----------------------------------------------------------------------------
*
* $Id: README,v 1.1 2005-07-06 10:38:50 tforb Exp $
* $Id: README,v 1.2 2005-07-06 11:49:08 tforb Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
* C++ containers for numbers (libaff)
* DATREAD++ library: reading seismic data (libdatreadxx)
*
* This file contains:
* - documentation of namespace aff
* - documentation of namespace datread
* - mainpage text
* - documentation for pages:
* - \ref page_design
* - \ref page_using
* - \ref page_notes
* - \ref page_naming
*
* REVISIONS and CHANGES
* - 06/12/2002 V1.0 Thomas Forbriger (copied from libcontxx)
......@@ -26,45 +21,129 @@
/*! \brief Root namespace of library
This namespace contains all modules of the library
(see \ref sec_main_modules).
Here you should find all components, the user needs to work with this
library.
When working with the binary version of the library, you have to use
aff::prebuilt in place of aff (see \ref sec_design_binary).
This namespace contains the generic interface to the library.
It contains several subnamespaces with interfaces to format specific data
reading modules.
*/
namespace aff {
} // namespace aff
namespace datread {
} // namespace datread
/*======================================================================*/
/*! \mainpage
\author Thomas Forbriger
\author Wolfgang Friederich
\since December 2002
\date December 2002
\since March 2004
\date July 2005
\version V1.0
$Id: README,v 1.1 2005-07-06 10:38:50 tforb Exp $
$Id: README,v 1.2 2005-07-06 11:49:08 tforb Exp $
Contents of this page:
- \ref sec_main_aims
- \ref sec_main_modules
- \ref sec_main_modules_basic
- \ref sec_main_modules_extended
- \ref sec_main_peculiar
- \ref sec_concept
- \ref sec_howto
Additional information:
- \ref page_design
- \ref page_using
- \ref page_notes
- \ref page_naming
- \ref page_representation
- \ref page_fortran
- \ref page_changelog
- \ref page_project_status
\section sec_concept Concept of the library
The library provides seismic data file reading modules for several data
formats.
Each format specific module will be placed into its own namespace, like
datread::hpmo.
There you will find specific functions like datread::hpmo::readdata.
The interface provided through these functions is specific to the data
format.
However, for each format we provide a class derived from
datread::idatstream, like datread::ihpmostream.
Being derived from a common base class all these format specific classes
provide a common interface once defined in datread::idastream.
This interface handles data in terms of SFF (Stuttgart File Format) data
elements (like INFO lines and FREE blocks).
Thus the format specific input classes perform the conversion from the
specific format to SFF.
Any data that does not fit into SFF, must be dropped or may be only passed
via the FREE blocks.
All SFF data elements not present in the specific format must be replaced by
default values.
datread::idatstream behaves like an input stream for SFF data elements.
Appropriate input operators are presented in namespace #datread.
All derived classes and datread::ianystream provide the same interface and
operator set.
datread::ianystream is not derived from datread::idatstream.
It rather serves as a handle to any class derived from datread::idatstream.
anyway datread::ianystream provides the same interface.
\section sec_howto HOWTO read data of any supported format
Here I provide an example on how to read seismic data using
datread::ianystream and writing it to a different file via sff::SFFostream.
Consider the names of input files given in
\code
std::list<std::string> infiles;
\endcode
and the name of the output file given in
\code
std::string outfile;
\endcode
The type of the input files are given in
\code
datread::Eformat format;
\endcode
which can be created from a string specifier
\code
std::string type;
\endcode
through
\code
format=datread::anyID(type);
\endcode
We assume that a file FREE block
\code
sff::FREE filefree;
\endcode
was already prepared to be written.
Reading an writing of data will than take place like in the code example
given here:
\code
// create an output file stream
std::ofstream ofs(outfile.c_str());
// create an interfacing SFF output stream
sff::SFFostream<Tseries> os(ofs, opt.debug);
// write the file FREE block to the output file
os << filefree;
// here we could also write an SRCE line
// create iterator to browse list of input files
std::list<std::string>::const_iterator infile=infiles.begin();
while( infile!=infiles.end())
{
// open input stream for reading next file
std::ifstream ifs(infile->c_str());
// create an interface to the input stream
datread::ianystream is(ifs, format);
// cycle through all traces while input stream provides data
while(is.good())
{
// create a double precision series container
datread::Tdseries series;
// read and write the series
is >> series;
os << series;
// create a WID2 line structure
sff::WID2 wid2;
// read and write the WID2 header
is >> wid2;
os << wid2;
// read and write INFO line and trace FREE block is present
if (is.hasinfo()) { sff::INFO info; is >> info; os << info; }
if (is.hasfree()) { sff::FREE free; is >> free; os << free; }
}
// next file
++infile;
}
\endcode
\section sec_main_aims Aims of the library
*/
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: bonjer.h,v 1.5 2004-04-07 08:53:54 tforb Exp $
* $Id: bonjer.h,v 1.6 2005-07-06 11:49:08 tforb Exp $
* \author Thomas Forbriger
* \date 30/03/2004
*
......@@ -23,13 +23,15 @@
#define DATREAD_BONJER_H_VERSION \
"DATREAD_BONJER_H V1.0 "
#define DATREAD_BONJER_H_CVSID \
"$Id: bonjer.h,v 1.5 2004-04-07 08:53:54 tforb Exp $"
"$Id: bonjer.h,v 1.6 2005-07-06 11:49:08 tforb Exp $"
#include<datreadxx/datread.h>
namespace datread {
/*! input stream to read seismic data provided by K. Bonjer
/*! \brief input stream to read seismic data provided by K. Bonjer
*
* \ingroup bonjer
*
* The concept is based on SFF data contents and we will make use of SFF
* structures.
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: readbonjer.h,v 1.3 2004-04-06 20:48:34 tforb Exp $
* $Id: readbonjer.h,v 1.4 2005-07-06 11:49:09 tforb Exp $
* \author Thomas Forbriger
* \date 30/03/2004
*
......@@ -23,7 +23,7 @@
#define DATREAD_READBONJER_H_VERSION \
"DATREAD_READBONJER_H V1.0 "
#define DATREAD_READBONJER_H_CVSID \
"$Id: readbonjer.h,v 1.3 2004-04-06 20:48:34 tforb Exp $"
"$Id: readbonjer.h,v 1.4 2005-07-06 11:49:09 tforb Exp $"
#include<aff/series.h>
#include<iostream>
......@@ -31,6 +31,15 @@
namespace datread {
/*! \brief all functions, classes, etc. to read K. Bonjers data format
*
* \defgroup bonjer Read file format defined by K. Bonjer
*/
/*! \brief all functions, classes, etc. to read K. Bonjers data format
*
* \ingroup bonjer
*/
namespace bonjer {
//! hold file header contents
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: hpmo.h,v 1.9 2004-12-23 12:38:25 tforb Exp $
* $Id: hpmo.h,v 1.10 2005-07-06 11:49:09 tforb Exp $
* \author Thomas Forbriger
* \date 31/03/2004
*
......@@ -23,7 +23,7 @@
#define DATREAD_HPMO_H_VERSION \
"DATREAD_HPMO_H V1.0 "
#define DATREAD_HPMO_H_CVSID \
"$Id: hpmo.h,v 1.9 2004-12-23 12:38:25 tforb Exp $"
"$Id: hpmo.h,v 1.10 2005-07-06 11:49:09 tforb Exp $"
#include<datreadxx/datread.h>
#include<datreadxx/hpmodata.h>
......@@ -31,9 +31,9 @@
namespace datread {
/*! class to read PDAS data
/*! \brief class to read HPMO data
*
* \note Series values in floating point containers will be scaled!
* \ingroup hpmo
*/
class ihpmostream: public idatstream {
public:
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: readhpmo.h,v 1.11 2004-12-23 12:02:35 tforb Exp $
* $Id: readhpmo.h,v 1.12 2005-07-06 11:49:10 tforb Exp $
* \author Thomas Forbriger
* \date 31/03/2004
*
......@@ -23,7 +23,7 @@
#define DATREAD_READHPMO_H_VERSION \
"DATREAD_READHPMO_H V1.0 "
#define DATREAD_READHPMO_H_CVSID \
"$Id: readhpmo.h,v 1.11 2004-12-23 12:02:35 tforb Exp $"
"$Id: readhpmo.h,v 1.12 2005-07-06 11:49:10 tforb Exp $"
#include<iostream>
#include<string>
......@@ -35,20 +35,31 @@
namespace datread {
/*! All classes and functions to extract data from HPMO files
/*! \brief All classes and functions to extract data from HPMO files
*
* \defgroup hpmo HPMO data reading interface
*/
/*! \brief All classes and functions to extract data from HPMO files
*
* \ingroup hpmo
*/
namespace hpmo {
/*! within the inner reading functions, we use vector to hold minute
* blocks
/*! \brief within the inner reading functions, we use vector to hold
* minute blocks
*
* \ingroup hpmo
*/
typedef std::vector<MinuteBlock> Tvecofblocks;
/*----------------------------------------------------------------------*/
/*! this excpetion will be thrown by the Header reading function, in case
* it does not find something that look like a header (i.e. a line with
* more or less than 44 characters)
/*! \brief this excpetion will be thrown by the Header reading function,
* in case it does not find something that look like a header (i.e. a line
* with more or less than 44 characters)
*
* \ingroup hpmo
*/
class NoHeaderException: public datread::Exception {
public:
......@@ -57,7 +68,9 @@ namespace datread {
/*----------------------------------------------------------------------*/
/*! Read, hold and handle one minute block header line
/*! \brief Read, hold and handle one minute block header line
*
* \ingroup hpmo
*/
class Header {
public:
......@@ -78,7 +91,8 @@ namespace datread {
/*----------------------------------------------------------------------*/
//! read one minute block of samples
//! \brief read one minute block of samples
//! \ingroup hpmo
SampleBlock readdata(std::istream& is, const bool& verbose=false);
//! dump one block of samples
......@@ -86,7 +100,8 @@ namespace datread {
/*----------------------------------------------------------------------*/
//! dump one MinueBlock
//! \brief dump one MinueBlock
//! \ingroup hpmo
void dump(std::ostream& os, const MinuteBlock& block);
/*----------------------------------------------------------------------*/
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: mseed.h,v 1.2 2004-07-15 16:29:21 tforb Exp $
* $Id: mseed.h,v 1.3 2005-07-06 11:49:09 tforb Exp $
* \author Thomas Forbriger
* \date 15/07/2004
*
......@@ -23,13 +23,16 @@
#define TF_MSEED_H_VERSION \
"TF_MSEED_H V1.0 "
#define TF_MSEED_H_CVSID \
"$Id: mseed.h,v 1.2 2004-07-15 16:29:21 tforb Exp $"
"$Id: mseed.h,v 1.3 2005-07-06 11:49:09 tforb Exp $"
#include<datreadxx/datread.h>
namespace datread {
//! class to read mini-SEED data
/*! \brief class to read mini-SEED data
*
* \ingroup mseed
*/
class imseedstream: public idatstream {
public:
typedef idatstream Tbase;
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: mseedread.h,v 1.2 2004-07-19 07:22:02 tforb Exp $
* $Id: mseedread.h,v 1.3 2005-07-06 11:49:10 tforb Exp $
* \author Thomas Forbriger
* \date 15/07/2004
*
......@@ -23,16 +23,23 @@
#define TF_MSEEDREAD_H_VERSION \
"TF_MSEEDREAD_H V1.0 "
#define TF_MSEEDREAD_H_CVSID \
"$Id: mseedread.h,v 1.2 2004-07-19 07:22:02 tforb Exp $"
"$Id: mseedread.h,v 1.3 2005-07-06 11:49:10 tforb Exp $"
#include<datreadxx/seedstructs.h>
namespace datread {
/*! all the stuff to read mini-SEED data
/*! \brief all the stuff to read mini-SEED data
*
* \defgroup mseed Read mini-SEED data
*/
/*! \brief all the stuff to read mini-SEED data
*
* this module is predominantly coded to extract data from a SeisComP or
* COMSERV system.
*
* \ingroup mseed
*/
namespace mseed {
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: pdas.h,v 1.6 2004-10-20 14:40:48 tforb Exp $
* $Id: pdas.h,v 1.7 2005-07-06 11:49:09 tforb Exp $
* \author Thomas Forbriger
* \date 30/03/2004
*
......@@ -24,7 +24,7 @@
#define DATREAD_PDAS_H_VERSION \
"DATREAD_PDAS_H V1.1 "
#define DATREAD_PDAS_H_CVSID \
"$Id: pdas.h,v 1.6 2004-10-20 14:40:48 tforb Exp $"
"$Id: pdas.h,v 1.7 2005-07-06 11:49:09 tforb Exp $"
#include<datreadxx/datread.h>
#include<datreadxx/pdasflags.h>
......@@ -32,8 +32,9 @@
namespace datread {
/*! class to read PDAS data
/*! \brief class to read PDAS data
*
* \ingroup pdas
* \note Series values in floating point containers will be scaled!
*/
class ipdasstream: public idatstream {
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: pdasread.h,v 1.6 2004-10-20 14:40:48 tforb Exp $
* $Id: pdasread.h,v 1.7 2005-07-06 11:49:10 tforb Exp $
* \author Thomas Forbriger
* \date 30/03/2004
*
......@@ -25,7 +25,7 @@
#define DATREAD_PDASREAD_H_VERSION \
"DATREAD_PDASREAD_H V1.2 "
#define DATREAD_PDASREAD_H_CVSID \
"$Id: pdasread.h,v 1.6 2004-10-20 14:40:48 tforb Exp $"
"$Id: pdasread.h,v 1.7 2005-07-06 11:49:10 tforb Exp $"
#include<vector>
#include<istream>
......@@ -34,6 +34,15 @@
namespace datread {
/*! \brief all functions, classes etc. to read PDAS data
*
* \defroup pdas Read PDAS data
*/
/*! \brief all functions, classes etc. to read PDAS data
*
* \ingroup pdas
*/
namespace pdas {
//! struct to hold content of header line
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: sff.h,v 1.5 2005-01-26 17:51:43 tforb Exp $
* $Id: sff.h,v 1.6 2005-07-06 11:49:09 tforb Exp $
* \author Thomas Forbriger
* \date 30/03/2004
*
......@@ -23,13 +23,21 @@
#define DATREAD_SFF_H_VERSION \
"DATREAD_SFF_H V1.0 "
#define DATREAD_SFF_H_CVSID \
"$Id: sff.h,v 1.5 2005-01-26 17:51:43 tforb Exp $"
"$Id: sff.h,v 1.6 2005-07-06 11:49:09 tforb Exp $"
#include<datreadxx/datread.h>
namespace datread {
//! class to read SFF data
/*! \brief SFF reading interface
*
* \defgroup sff Read SFF data
*/
/*! \brief class to read SFF data
*
* \ingroup sff
*/
class isffstream: public idatstream {
public:
typedef idatstream Tbase;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment