source: trunk/README @ 382

-----------------------------------------------------------------------
               The Duchamp Source Finder
-----------------------------------------------------------------------
Duchamp 1.1.2 -- an object finder for spectral-line data cubes
Copyright (C) 2006, Matthew Whiting, ATNF

Duchamp is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

Duchamp is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License
along with Duchamp; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA

Correspondence concerning Duchamp may be directed to:
   Internet email: Matthew.Whiting [at] atnf.csiro.au
   Postal address: Dr. Matthew Whiting
                   Australia Telescope National Facility, CSIRO
                   PO Box 76
                   Epping NSW 1710
                   AUSTRALIA
-----------------------------------------------------------------------

Introduction
============

Duchamp is a stand-alone program designed to find objects in
astronomical data cubes, particularly spectral-line observations. Its
features include a wavelet-based reconstruction technique for reducing
the noise in the cube (and thereby enhancing detectability of
sources), easy-to-use text-based interface, flexibility to control all
relevant parameters such as detection thresholds, and a useful range
of text- and graphics-based output.

Duchamp works on any FITS image using the CFITSIO package, and uses
Mark Calabretta's WCSLIB library to provide accurate position and
velocity information for all detected sources.


Obtaining and Building Duchamp
==============================

The Duchamp web page is at 
http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp
where you can download a gzipped tar archive of the source code.

Duchamp uses three main external libraries: pgplot (although see note
below), cfitsio (version 2.5 and greater, version 3+ preferred) and
wcslib. If you do not have the libraries, they can be downloaded from
the following locations:

PGPLOT -- http://www.astro.caltech.edu/~tjp/pgplot/ 
cfitsio -- http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html 
wcslib -- http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html

Note that PGPLOT is optional. Duchamp can be compiled and run without
PGPLOT, but you will miss out on the useful graphical outputs!  The
other two libraries, cftisio and wcslib, are essential.


Basic Compilation and Installation
----------------------------------

Duchamp can be built and installed on Unix systems by typing (note
that the terminal prompt here is represented by > -- don't type this
character!):

 >  ./configure
 >  make
 >  make clean (optional -- to remove the object files from the src
                directory)
 >  make install 

This default setup will search in standard locations for the necessary
libraries, and install the executable ("Duchamp") in /usr/local/bin (a
copy will also be in the current directory). If you want this to go
somewhere else, eg if you don't have write-access to that directory,
or you need to tweak the libraries, see the next section. Otherwise,
jump to the testing section.


Tweaking the installation setup
-------------------------------

To install Duchamp in a directory other than /usr/local/bin, use the
--prefix option with configure, specifying the directory above the
\texttt{bin/} directory. eg:

 >  ./configure --prefix=/home/mduchamp

which, if you run "make" and "make install", will result in the binary
being put in the directory /home/mduchamp/bin.

If the above-mentioned libraries have been installed in non-standard
locations, or you have more than one version installed on your system,
you can specify specific locations by using the --with-cfitsio=<dir>,
--with-wcslib=<dir> or --with-pgplot=<dir> flags. For example:

 >  ./configure --with-wcslib=/home/mduchamp/wcslib-4.2 
And then just run make in the usual fashion:
 >  make

Duchamp can be compiled without PGPLOT if it is not installed on your
system -- the searching and text-based output remains the same, but
you will not have any graphical output. 
To manually specify this option, use the --without-pgplot flag, eg:

 >  ./configure --without-pgplot

(Note that CFITSIO and WCSLIB are essential, however, so
--without-wcslib or --without-cfitsio will not work.).
Even if you do not give the --without-pgplot option, and the PGPLOT
library is not found, Duchamp will still compile (albeit without
graphical capabilities).


Installing on Mac OS X with gfortran
------------------------------------

Some recent testing on a Mac with OS X and gfortran has shown that
slight tweaking needs to be done with the use of configure. In
addition to the options noted above, configure should be run with F77
set to the desired fortran compiler command. Note that this should be
the same as that used to compile the pgplot package, if you are using
it: gfortran is probably the best choice. 
This is done simply by:

 >  ./configure F77=gfortran ...[other options]...


Testing
=======

There is a script included in the distribution that allows you to make
sure Duchamp is running correctly. It will use a dummy FITS image in
the verification/ directory -- this image has some Gaussian random
noise, with five Gaussian sources present, plus a dummy WCS. The
script runs Duchamp on this image with three different sets of inputs,
and compares to known results, looking for differences and reporting
any. There should be none reported if everything is working
correctly. To run, enter the command

 >  ./VerifyDuchamp.sh

Once you know it is working, you can install Duchamp on your system
with the command 

 > make install

You can also use the dummy image for your own testing if you like (for
instance, testing different thresholds to get a feel for how the
program works). 


Using Duchamp
=============

There are two possible ways to run Duchamp. The first is:

 >  Duchamp -f image.fits

where image.fits is the data cube to be searched. This method simply
uses the default values of all parameters.

The second method allows some determination of the parameter values by
the user. Type:

 >  Duchamp -p parameterFile 

where parameterFile is a file with the input parameters, including the
name of the cube you want to search. There are two example input files
included with the distribution. The smaller one, InputExample, shows
the typical parameters one might want to set. The large one,
InputComplete, lists all possible parameters that can be entered, and
a brief description of them. To get going quickly, just replace the
"your-file-here" in InputExample with your image name, and type 

 >  Duchamp -p InputExample

By default, a map of detections is displayed in a PGPLOT
X-window. This can be disabled by using the flagXOutput parameter, or
using the -x command-line option along with the -f or -p options. The
-x option will override the setting in the parameter file.

A User's Guide in the docs/ directory provides complete
documentation. It comes in both postscript and portable document
format (pdf -- note that this contains hyperlinks). This guide will
provide full descriptions of all parameters, and of all steps in the
execution of Duchamp.

Any questions, please contact me. To report problems or bugs, or to
suggest improvements, please go to the Duchamp Trac wiki site:
http://svn.atnf.csiro.au/trac/duchamp/newticket 
and submit a "ticket", or view previously submitted reports.

Acknowledging the use of Duchamp
================================

Duchamp is provided in the hope that it will be useful for your
research. If you find that it is, I would ask that you acknowledge it
in your publication by using the following:
"This research made use of the Duchamp source finder, produced at
the Australia Telescope National Facility, CSIRO, by M. Whiting."

There is a journal paper under preparation that describes Duchamp, but
until that is published, you can refer to the following conference
proceedings paper:
"Astronomers! Do you know where your galaxies are?", M.Whiting,
proceedings of Local Volume meeting (held July 8-13 2007),
Astrophysics & Space Science, Eds. B.Koribalski & H.Jerjen, in press.

-------
Author: 
  Matthew Whiting, Australia Telescope National Facility, November 2007
  Matthew.Whiting [at] csiro.au