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:
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.
A number of command-line utilities are provided to convert between other data formats and Karma. These are described below:
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 rgooch/">Richard Gooch, 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!
miriad2karma <miriad file> <karma file>
This programme also tries to tile data like <fits2karma> does.
gipsy2karma <gipsy file> <karma file>
This programme also tries to tile data like <fits2karma> does
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:
miriad2gipsy <miriad file> <GIPSY file>
This programme is obsoleted by the more general <ktranslate>
ktranslate <input file> <output file>
The input and output formats are guessed by the programme, based on the filename extensions. You can force the format if you wish. An example of this is:
ktranslate -intype fits -outtype miriad - <input file> <output file>
The choice of supported output formats is limited to Karma, PPM, FITS, Sun Rasterfile, Miriad and GIPSY. If possible, the conversion process is ``streamed'', to avoid the need to allocate large amounts of virtual memory.
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.
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,
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.
Karma follows the FITS conventions for units. In other words, SI units are used. Please see the FITS standard for more information.
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.