IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Changeset 1031


Ignore:
Timestamp:
Jun 14, 2004, 11:53:42 AM (22 years ago)
Author:
harman
Message:

Updated main page documentation and installation instructions

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/psLib/src/mainpage.dox

    r974 r1031  
    1 /** @mainpage Image Processing Pipeline
     1/** @mainpage psLib Image Processing Library
     2
    23
    34@section intro Introduction
    45
    5 The Image Processing Pipeline (IPP) encapsulates a software infrastructure
    6 for processing of Pan-STARRS imagery.
     6This library contains the Pan-STARRS Image Processing Pipeline (IPP) toolkit,
     7psLib. The intended use is to provide a library of basic software functions which
     8can be used throughout the Pan-STARRS project to simplify programming tasks. Among
     9the benefits are: reuse of code, simplification of testing, streamlining of code,
     10and isolation of functionality that may be subject to change.     
    711
    8 The image processing pipeline software supports three interfaces:<ul>
    9   <li>C</li>
    10   <li>Simple execution scripts (see simple engine)</li>
    11   <li>Perl (see complex engine)</li>
    12 </ul>
     12The capabilities provided by psLib are grouped into the following areas which are
     13also reflected in the file system directory structure:
     14 - System Utilities
     15 - Data Collections
     16 - Data Manipulation
    1317
    14 @section install How to Build from source:
     18This list is sorted in hierarchical order: The later entries depend on the functions and
     19data types of the earlier entries.
    1520
    16 Before building the IPP from source, it is required that the 'opt' directory
    17 tree from cvs be downloaded and built.  The steps are approximately as follows:
    18 <pre>
    19 $ cvs -d:ext:username@gforge.mhpcc.hawaii.edu:/cvsroot/panstarrs co opt
    20 $ cd opt
    21 $ make
    22 $ cd ..
    23 </pre>
     21The installed code for psLib consists of header files and binary libraries in the form of static
     22(libpslib.a) and shared (libpslib.so or libpslib.dylib for OX/X.) Assuming these components
     23have been built and installed in the standard library path, psLib may be used within a program by
     24including the line #include <pslib.h> and linking with -lpslib.
    2425
    25 If you desire to install the opt package output in another location, say in
    26 a standard UNIX location like /opt or /usr/local, then add 'PREFIX=path' to
    27 the make statement.  Note, the path given here should be set to the environment
    28 variable OPTDIR so that the IPP code can find it.
     26
     27
     28@section extinstall Required 3rd Party Libraries
     29
     30Before building psLib from source, several 3rd party software libraries must be installed.
     31These include:
     32
     33<ol>
     34<li>GNU Scientific Library (GSL), Available at http://www.gnu.org/software/gsl</li>
     35<li>Fastest Fourier Transform in the West (FFTW), Available at http://www.fftw.org</li>
     36<li>C Flexible Image Transport System Input output (CFITSIO), Available at http://heasarc.gsfc.nasa.gov/docs/software/fitsio</li>
     37</ol>
    2938
    3039If you on a Darwin (Mac OS X) system, a dlfcn compatability library needs to be
    … …  
    3544this version of Darwin.
    3645
    37 Next, the IPP code needs to be downloaded from either the tar file posted on:
    38     https://gforge.mhpcc.hawaii.edu/projects/panstarrs/
    39 or directly from the CVS server with the following command:
     46
     47@section install How to Build from Source
     48
     49The psLib code should to be downloaded from either the tar file posted on:
     50https://gforge.mhpcc.hawaii.edu/projects/panstarrs/ or directly from the CVS server
     51with the following command:
    4052<pre>
    41 $ cvs -d:ext:username@gforge.mhpcc.hawaii.edu:/cvsroot/panstarrs co -r rel4 IPP
     53$ cvs -d:ext:username@gforge.mhpcc.hawaii.edu:data/panstarrs/cvsroot co -P psLib
    4254</pre>
     55
    4356   
    44 The source should build from the Makefile in the IPP/src directory.  The
     57The source should build from the Makefile in the psLib/src directory.  The
    4558recommended steps are:
    4659<pre>
    47 $ cd IPP/src
    48 $ make distclean
     60$ cd psLib/src
     61$ make clean
    4962</pre>
    50 <blockquote>
    51 <i>This deletes any old object and target files</i>
    52 </blockquote>
     63<i>This deletes any old object and target files.</i>
    5364<pre>
    5465$ make
    5566$ make install
    5667</pre>
    57 <i>this installs all the executables and shared objects to $INSTALLDIR/bin
    58 and $INSTALLDIR/lib, respectively.  If the environment-variable INSTALLDIR is
    59 not set, the path to the top-level IPP directory is used.</i>
    60 
    61 The environment variable CC can be set to specify what C compiler to use.  If
    62 the opt module is not checked out in the same parent directory as IPP, the
    63 OPTDIR environment variable should be set to the path of the opt directory.
    64 
    65 @section run How to Run
    66 
    67 The package consists of an executable called IPP as well as a Perl module
    68 version of a great many functions, either can be used as the 'engine' as
    69 described in the SRS.
    70 
    71 @subsection complexengine "Simple Engine":
    72 
    73 The IPP executable tself does no image processing.  It just parses a simple
    74 pipeline scripting language that describes the processing steps of the pipeline.
    75 Each line of this text file, starts with either a keyword or a module name
    76 followed by a list of parameters in the form 'name=value'.  Keywords currently
    77 supported in the pipeline scripting language are 'GlobalParameters' and
    78 'Message'.  'GlobalParameters' adds the parameters that follow to the
    79 parameter list of every module that is called.  'Message' prints out the 'text'
    80 parameter that follows.
    81 
    82 Modules are all loaded at the beginning of the process and then are called
    83 sequentially.  Data is passed between modules via their name, so modules
    84 generally allow the specification of the name of the image input and output
    85 names.
    86 
    87 The directory IPP/testsuite contains a sample pipeline configuration file that
    88 performs all the stages of the pilot project.  It assumes that the test data is
    89 in a directory called testData that is at the same level as IPP.  One can
    90 download these files via cvs via 'cvs co testData', assuming the CVSROOT is set
    91 for downloading the IPP from the MHPCC gForge server.
    92 
    93 @subsection simpleengine "Complex Engine":
    94 
    95 The Perl module is called 'imCal' and allows the image processing pipeline
    96 functions to be accessed from a Perl script.  A script should have the following
    97 lines before the use of any of the pipeline functions:
    98     use lib "path-to-IPP-module/bin";
    99     use imCal;
    100    
    101 An example Perl script of the pipeline is as follows:
    102 
    103 <table border=3><tr><td><pre>
    104 #! /usr/bin/perl
    105 # just a basic end-to-end test of the 'simple engine' Perl extensions.
    106 #
    107 use lib "../lib";
    108 use imCal;
    109 
    110 $dataPath = '/data/panstarrs/testData';
    111 $detectorGain = 1.0;
    112 $readoutNoise = 1.0;
    113 $bitPix = -32;
    114 $bZero = 0.0;
    115 $bScale = 1.0;
     68<i>This builds and installs files to psLib/lib and psLib/include.</i>
    11669
    11770
    118 # read in the calibration data
    119 print "Reading flat field data\n";
    120 $flatField = readFits("$dataPath/calflat.i.o00.T0.fits");
    121 print "Reading bad pixel mask data\n";
    122 $badPixels = readFitsMask("$dataPath/badpix.i.o00.T0.fits");
    123 print "Reading sky fringe image\n";
    124 $sky[0] = readFits("$dataPath/sky0.i.o00.T0.fits");
     71@section run How to Run Tests
    12572
    126 # read in the image.
    127 print "Reading imagery data\n";
    128 $img = readFits("$dataPath/e00000.o00.T0.fits");
     73Since psLib is a library, there is no executable, per se. However, to test the installation, users
     74may execute the FullUnitTest script:
     75<pre>
     76$ cd psLib/test
     77$ FullUnitTest
     78</pre>
     79<i>This builds and executes test files for each of the psLib functional areas.</i>
    12980
    130 print "Calling debias\n";
    131 debias($img,$CONSTANT_BIAS_METHOD,$MEAN_STAT_METHOD);
    13281
    133 print "Calling removeBadPixels\n";
    134 removeBadPixels($img,$badPixels);
     82@section doc How to Create Documentation
    13583
    136 print "Calling divideByFlat\n";
    137 divideByFlat($img,$flatField);
    138 
    139 print "Writing resulting image data\n";
    140 writeFitsOta($img,"swig_cal.fits",$bitPix,$bZero,$bScale,0);
    141 
    142 print "Calling subtractBackground\n";
    143 subtractBackground($img,\@sky,1,$detectorGain,$readoutNoise);
    144 writeFitsOta($img,"swig_subtractBackground.fits",$bitPix,$bZero,$bScale,0);
    145 
    146 print "Finding objects\n";
    147 findObjects($img,"objects.txt",3,3,5);
    148 </pre></td></tr></table>
     84Both HTML and man page documentation may also be generated:
     85<pre>
     86$ cd psLib/src
     87$ make docs
     88</pre>
     89<i>This places documentation in psLib/docs.</i>
    14990
    15091*/
Note: See TracChangeset for help on using the changeset viewer.