----------------------------------------------------------------------- The Duchamp Source Finder ----------------------------------------------------------------------- Duchamp 1.0.5 -- 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@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, 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 Duchamp can be built 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) This way, configure should find all the necessary libraries, but if the above-mentioned libraries have been installed in non-standard locations, you can specify additional directories to look in. There are separate options for library files (eg. libcpgplot.a) and header files (eg. cpgplot.h). For example, suppose wcslib had been locally installed in /home/mduchamp/wcslib. There will then be two libraries created that are likely to be in separate subdirectories: C/ and pgsbox/. Each subdirectory needs to be searched for library and header files, so one could build Duchamp by typing: > ./configure \ LIBDIRS="/home/mduchamp/wcslib/C /home/mduchamp/wcslib/pgsbox" \ INCDIRS="/home/mduchamp/wcslib/C /home/mduchamp/wcslib/pgsbox" And then just run make in the usual fashion: > make 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 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 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! Author: Matthew Whiting, Australia Telescope National Facility, September 2006 Matthew.Whiting@csiro.au