Karma Home Page

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:

• volume rendering of data cubes <xray>
• play movies of data cubes <kvis>
• inspecting multiple images and cubes at the same time <kvis>
• slice a cube <kslice_3d>
• superimposing images <kvis> and <kvis>
• interactive position-velocity slices <kpvslice>
• 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:

 
• 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. By default, all map files in the catalogue are shown. You may set the AIPS_ID environment variable to your AIPS user ID to avoid seeing files belonging to other users. 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. Byte-swapped data are automatically detected and corrected

   

• 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

   

• 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. Unlike the DRAO software, Karma requires no environment variable to cope with byte-swapped data; they are automatically detected and corrected. This format supports loading of partial 3-dimensional datasets (section 1.1.3)

   

• 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 are set to all zeros. This format supports loading of partial datasets (section 1.1.3)

   

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

   

• GIPSY this is the format for the GIPSY data reduction package. It is more efficient to use <gipsy2karma> to convert to Karma format first. This format supports loading of partial datasets (section 1.1.3)

   

• IRAF this is the format for the IRAF optical astronomy analysis package. The current implementation requires IRAF to be installed (because it uses the wfits task in IRAF), and will create a temporary file which is automatically deleted

   

• 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

    

• 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

      

• 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

   

• Simple FITS this is a derivative of the FITS format which is easier for the human to manipulate. Lines in the header are separated by newline characters rather than having to be padded to 80 characters. The data directly follows the END keyword and must be in plain ASCII format, a single value per line. The blank value for floating point data is 1e30. The filename extension should be .sfits

   

• 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

   

• 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)

   

• Targa TrueVision (tga files) yet another 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.

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:

• 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 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!

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

  miriad2karma <miriad file> <karma file>

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

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

  gipsy2karma <gipsy file> <karma file>

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

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:

• <miriad2gipsy> will convert from Miriad format to GIPSY format, which is used thus:     

  miriad2gipsy <miriad file> <GIPSY file>

  This programme is obsoleted by the more general <ktranslate>

• <ktranslate> will convert from any format supported by Karma to another format. It is used thus:     

  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.

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

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.

Karma Home Page