1 Introduction

Karma is a general purpose programmer's toolkit and contains KarmaLib (the structured library and API) and a large number of modules (applications) to perform many standard tasks. This manual describes the many visualisation tools which are distributed with the Karma library.

This document is written for Karma version 1.6.26 , which is probably my ``experimental'' version. Most of this manual will still be relevant to the previously released binary-only (or ``beta'') version, since binary releases come every few weeks or so. Full public releases come once or twice a year, so this document may talk about several new things not available in the last public release of Karma.

Click here to get a compressed PostScript version of this document. Click here to get a fancy colour front cover for this document in compressed PostScript.

Separate on-line documents (the Karma Reference and Programming Manuals) are available from the Karma Home Page. Most of the visualisation tools are available via the Karma home page or you can go directly to the Karma ftp site.

The programs available at the moment are:

• volume rendering of data cubes <xray>
• play movies of data cubes <kview>
• inspecting two cubes at the same time <kview>
• slice a cube <kslice_3d>
• superimposing images <khuei> and <kview>
• interactive position-velocity slices <kpvslice>
• interactive ``renzograms'' <krenzo>
• look for expanding shells <kshell>
• interactive co-ordinate placement <koords>
• rectangular to polar gridding of images <kpolar>

  

1.1 Supported Data Formats

 

All the visualisation tools support a variety of data formats, including:

 
• Karma this is the native data format. Reading and writing Karma files is the most efficient. These files may be memory-mapped upon load, which can give enormous speed benefits and reduce swap (virtual memory) requirements. Note that Karma files have the extension .kf and that this extension is automatically produced by any Karma software

   

• FITS this is a popular format amongst astronomers, allowing you to move data between many different software packages. It is more efficient to use <fits2karma> to convert to Karma format first. For the file browser to recognise a FITS file, the extension should be either .fits, .fit, .fts or uppercase versions. Files with extension .efits are treated specially, in that only the header is read. These are called ``empty'' FITS files, where the image data is set to all zeros

    

• Miriad this is the image format used by the Miriad data reduction package. It is more efficient to use <miriad2karma> to convert to Karma format first. If your Miriad file has no mask attached to it, then the file may be memory-mapped just like a Karma file, which means loading may be just as fast as loading Karma files. For this reason, it is worthwhile to avoid creating masks for Miriad files if you can help it

   

• GIPSY this is the format for the GIPSY data reduction package. It is more efficient to use <gipsy2karma> to convert to Karma format first.

   

• DRAO this is the format produced by the Dominion Radio Astronomy Observatory (Penticton, B.C., Canada) reduction software. This data format uses a catalogue file which is automatically scanned by the file browser and each available dataset (whether a single image file or a ``family'' of files for a cube) is given one entry in the browser, with the string ``DRAO'' shown in the left-hand column. Because the DRAO format is not portable across different architectures, you need to run the visualisation tools on the same kind of machine as the data was written from

   

• AIPS this is the format used by the AIPS package (Astronomical Image Processing System), sometimes called ``Classic AIPS'' or ``AIPS1'', not to be confused with ``AIPS++'' (which is sometimes called ``AIPS2''). This data format uses a catalogue file which is automatically scanned by the file browser and each available dataset is given an entry in the browser, with the string ``AIPS'' shown in the left-hand column. You need to set the AIPS_ID environment variable with your AIPS user ID. If you do not set this variable, the file /AIPS/AIPSUSERS is scanned in an attempt to determine your AIPS user ID. Note that you can only view the datasets for a single user ID at a time. If you want to see someone else's AIPS files, you will need to set AIPS_ID to their AIPS user ID. To see AIPS files on an AIPS disc, you will need to change directory to the AIPS data area (i.e. where all those odd-looking ``CBD??????.???;'' files are kept). You can use the file browser to change directories. Because the AIPS format is not portable across different architectures, you need to run the visualisation tools on the same kind of machine as the data was written from

   

• AIPS++ this is the format used by the AIPS++ package (Astronomical Information Processing System), not to be confused with ``AIPS''. This is a directory-based data format like Miriad. It is a new package still under development. The Karma support for AIPS++ requires the <image2fits> programme to be in your PATH. The source code is located somewhere in the AIPS++ source tree. A precompiled binary is available here for your convenience

   

• Starlink Image this an astronomical reduction package used by many optical astronomers. The file extension is .sdf and requires the <sdf2karma> programme to be in your PATH. A precompiled binary is available here for your convenience

      

• PNM/PPM/PGM this is a common image interchange format. The format does not support anything fancy like co-ordinate systems, but it is useful for converting between the many different image formats out there

   

• Sun Rasterfile another popular image format, having the distinct advantage of not using a patented compression algorithm (unfortunately the GIF format uses a patented image compression algorithm)

   

• GIF another popular image format. This requires the NetPBM tools to be installed on your machine

   

• TIFF another popular image format. This requires the NetPBM tools to be installed on your machine

   

• Targa TrueVision (tga files) yet another image format. This requires the NetPBM tools to be installed on your machine

In addition, the automatic decompression of gzipped and bzip2'ed Karma and FITS files is also supported by the file browser Filepopup widget (section 2.1).

If your data is not in one of the supported formats, you will need to convert it to a supported format like FITS.

1.1.1 Converting Data Formats

A number of command-line utilities are provided to convert between other data formats and Karma. These are described below:

• FITS requires the <fits2karma> programme, which is used: 

  fits2karma <fits file> <karma file>

  <fits2karma> will attempt to trap most deviations from standard FITS and continue gracefully. However, a truly bizzare FITS file may cause <fits2karma> to reject the conversion. In this rare case, please notify Richard Gooch (rgooch@atnf.csiro.au), who will attempt to add a trap so that the data can be converted.

  Also note that <fits2karma> will by default truncate axes so that they are divisible by 4 or larger. The reason for this is that this then allows the programme to tile the data (tiling is a way of organising data so that most ways of accessing it are faster). If you really don't want to loose up to 3 co-ordinate points along an axis, you can run <fits2karma> as follows:

  fits2karma -allow_truncation off <fits file> <karma file>

  But remember: for the sake of a little bit of data, you may be throwing away enormous speed benefits!

• Miriad requires the <miriad2karma> programme, which is used: 

  miriad2karma <miriad file> <karma file>

  This programme also tries to tile data like <fits2karma> does. Note there is also a <miriad2gipsy> programme which converts directly from Miriad format to GIPSY format, which is used thus: 

  miriad2gipsy <miriad file> <GIPSY file>

• GIPSY requires the <gipsy2karma> programme, which is used: 

  gipsy2arma <gipsy file> <karma file>

  This programme also tries to tile data like <fits2karma> does

1.2 Adding your own Data Formats

   

The visualisation tools also provide a mechanism for you to add support for other data formats not already supported by the Karma library. You will need a programme that converts from your data format to either Karma, FITS or PNM format, and for some data formats (in particular directory-based formats) you will need to provide a tester programme which determines if a dataset is of a particular type.

To set this up, you need to have a file /.karma/data-filters which contains rules on how to convert data formats. A system-wide file maintained by your local Karma installer is also searched, and is called
$KARMABASE/site/share/data-filters. Finally, the file
$KARMABASE/share/data-filters is scanned to load any filters which come with the Karma distribution. Your own data filters override the system data filters, which in turn override the Karma distribution filters.

A typical file would contain:

# Extension     Converter       Tester          Output  Format Name
imh             iraf2fits       -               FITS    IRAF Image
sdf             sdf2karma       -               Karma   Starlink Image
DIRECTORY       dd2fits         isdd            FITS    A directory dataset
DIRECTORY       aips++2fits     isaips++        FITS    AIPS++ Image
gif             giftopnm        -               PNM     GIF Image
tga             tgatoppm        -               PNM     Targa TrueVision

This would use the <iraf2fits> programme to convert files with .imh extensions to FITS. The FITS data would then be read in with the standard FITS reader in Karma. Similarly, files with .sdf extensions would be converted to Karma format using the <sdf2karma> programme, which would write out Karma data. Note that it is much more efficient to have a filter which generates Karma than FITS.

Note the <giftopnm> and <tgatoppm> filters are both registered as producing PNM files, whereas <tgatoppm> appears to produce PPM files. This is not a problem, since PNM (Portable aNy Map) is the generic format and PPM (Portable Pixel Map) is a specific subset of PNM.

The converter programmes are called with a single argument, that being the name of the input file. The output Karma, FITS or PNM data must be written to the standard output.

You will note that the tester programme supplied for the .imh and .sdf formats is - which means no tester is needed for these formats.

The special extension name DIRECTORY signifies that this data format is a directory-based one (examples of such formats are Miriad and AIPS++ images). Directory-based formats require a tester programme in order to determine if the directory contains a dataset (in which case it should be loaded) or just a plain directory which should be entered. The tester programme must exit with status 0 if it recognises the dataset, otherwise it should exit with some other value. If it returns the value 16 no warning will be given. It is given the name of the dataset directory as a single argument.

The file browser described in section 2.1 will show all files which are supported by data filters, making the loading of extra data formats transparent to the user.

If you want to write your own data filters, see the section on datafilters in the Karma Programming Manual.

The converter and tester programmes may be specified with absolute pathnames or you may give a plain filename and the PATH is searched. As well as the normal absolute pathnames (i.e. those with a leading ``/'' character) you may also specify an expression, such as:
$KARMABASE/site/$MACHINE_OS/bin/sdf2karma
or, alteratively:
${KARMABASE:-/usr/local/karma}/site/bin/sdf2karma
which is useful if you want to specify $KARMABASE/site/bin/sdf2karma if the KARMABASE environment variable is defined, otherwise use
/usr/local/karma/site/bin/sdf2karma
instead. This is a good way of providing a default location.

1.3 Units

 

Karma follows the FITS conventions for units. In other words, SI units are used. Please see the FITS standard for more information.