next up previous contents index
Next: 2 Common Features Up: Karma User Manual Previous: Contents

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:

  

1.1 Supported Data Formats

 

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

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:

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 tex2html_wrap_inline3833/.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.


next up previous contents index
Next: 2 Common Features Up: Karma User Manual Previous: Contents

Richard Gooch
Wed Sep 2 12:43:13 EST 1998