next up previous contents index Karma Home Page
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.7.25 , 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 programmes 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 are not in one of the supported formats, you will need to convert it to a supported format like FITS.

1.1.1 Converting Other Data Formats to Karma Format

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

1.1.2 Converting Between Data Formats

There are also command-line utilities which allow you to convert between other data formats, which are provided as a convenience. These are described below:

1.1.3 Loading partial files


Some data formats support loading of partial datasets. With these formats, if part of the data are missing, the part of the dataset that is available can be loaded (if desired). This is useful if you want to see a preview of a dataset that is currently being written by another process.

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_inline4628/.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:
or, alteratively:
which is useful if you want to specify $KARMABASE/site/bin/sdf2karma if the KARMABASE environment variable is defined, otherwise use
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.

Co-ordinate Systems


The Karma data format supports simple regular co-ordinate systems as well as irregularly-spaced co-ordinates. In addition, the curvilinear co-ordinate systems (i.e. Right Ascension/Declination and Galactic Longitude/Galactic Latitude) commonly found in astronomy are supported. Many common projections for these curvilinear co-ordinate systems are supported, as is the polynomial-based ``projection'' used for DSS (Digital Sky Survey) images.

The co-ordinate system support is tightly integrated with much of the Karma internal infrastructure. In general, mixing of data with different projections is handled correctly. For example, displaying overlays and contours over a greyscale image will work correctly even if the datasets have different rotations, scales and projections. Support for mixing different co-ordinate systems (i.e. RA/DEC overlaid with GLON/GLAT) is not yet supported, nor are data of mixed epochs.

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

Richard Gooch
Mon Aug 14 22:25:04 PDT 2006