Karma Home Page
Some features of different programmes are the same. You may also notice that parts of one programme may also be available as a separate programme or also appear in other programmes. This is due to the modular approach provided by Karma. Most of the window-based control panels you see are in fact ``widgets'', and these are reused many times in the same programme or in different programmes.
Below are some hotlinks to the sections in this chapter.
All programmes have the same interface to load data. Clicking (left) on Load or File or whatever it is called, will show a window with the files that you can load. This will be all files with extension .kf, .fts or .fits. Also subdirectories and the parent directory are shown. Clicking on these changes the directory. If a directory is in fact a Miriad image dataset, clicking on it will load that dataset. Note that GIPSY files consist of two files, one with a .descr extension and another with a .image extension. Most of the software will simply display a .gipsy file instead, since that makes the directory browser look less cluttered.
The Filepopup widget provides the file browsing
interface.
This widget allows the user to browse a directory tree and select
files. All the files and directories the application wants the user to
see are displayed. Any one of these may be selected by clicking the
left mouse button over the filename. The ``D'' character is used to
denote directories, while the ``F'' character is used to denote
ordinary files. Above the list of files and directories is shown the
current directory for the browser. If you edit the text and press
return the current directory is changed appropriately. The ``
''
notation is supported, as well as other simple Bourne Shell-like
expansions of environment variables using the $variable,
${variable} and
${variable:-word} notations. The following controls are provided:
Convenience buttons for jumping to commonly-used directories may be configured by the local Karma administrator or by the user. The following files are searched:
in that order. The format of this file is a sequence of ASCII lines, with each line containing the name of the button followed by the directory to jump to. For example:
survey /nfs/survey mydata /nfs/data1/users/fred
A screen snapshot is available here.
Sometimes, your image or datacube is too big to handle efficiently. If you have a file which is much bigger than your physical memory (RAM), then most of the visualisation tools will run slower than a lame dog. It generally does not make sense to visualise a dataset bigger than RAM. To get around this, the visualisation tools provide a mechanism whereby you can decimate a 2-dimensional (image) or 3-dimensional (cube) array. Decimation involves taking every N values along an axis and averaging them together to produce a single output value, then jumping to the next group of N input values. If you use a decimation factor of 2 for each axis, the output cube is 8 times smaller (4 times smaller for an image). You can also extract a subcube, if you are only interested in a small section of the data.
Note that the decimator allocates some temporary 2-dimensional buffers, so when decimating a 2-dimensional array, the memory requirements may be significantly higher than reported for the output array.
The LoadAndDecimate widget provides the decimation interface. This widget controls the process of loading and decimating a datacube. The user can skip/average data values along each dimension as well as extract a subcube. The following controls are provided:
Under the first row of buttons, the size of the file (in data elements) is displayed and the memory size required by the decimated subcube is displayed. Underneath these, the subcube bottom-left corner (BLC) and top-right corner (TRC) co-ordinates are displayed, and also the pixel increment (INC).
As you change the slider parameters, the memory requirement changes, as do the BLC, TRC and INC values, and these are reported to you. It is wise to not use more than about half the physical RAM (Random Access Memory) available in your machine.
As the file is loaded and decimated, a simple progress meter shows you how much longer you have to wait. Remember: you can always abort.
A screen snapshot is available here.
With many images that you display, you will want to change the colourtable used. The colourtable control appears after selecting the PseudoColour (8 bit) option in the Intensity menu in most tools.
The Cmapwinpopup widget provides the colourtable control interface. This widget controls a colourtable for a ``PseudoColour'' display canvas. Data values are used to index into a table of colours. This is typically used for ``false colour'' image display. The following controls are provided:
You can manipulate the colours in the colourtable by moving the round dot in the big square box (left mouse button). Usually moving the dot horizontally changes the apparent position of the colours, while moving it vertically changes the range of colours.
There are many ``colour functions'' available to set the colourmap, the default one being ``Greyscale1''. Some colour functions produce smoothly-varying colourtables, while others have sharp boundaries.
A final way of manipulating the colourtable is provided by the Red Scale, Green Scale and Blue Scale sliders. With these you can turn down the amount of each primary colour for all the colours in the colourtable.
A screen snapshot is available here.
In many cases you will want to change the intensity scale in an image. This may be because the image has a very large dynamic range or has a few ``outlier'' values, and the control provided by the colourtable is inadequate. Most programmes have an Intensity menu with a selection named IScale for Dataset which will pop up a Dataclip widget.
This widget allows the user to specify a number of data ``regions'' (ranges). It it most often used to give control over a single region, so that an intensity range may be specified. The widget displays a histogram of the data values in the array, with the vertical axis being logarithmic. The following controls are provided:
If you click with the left mouse button in the histogram display, you define the lower boundary of a region. If no region exists, one is created. If you then click with the right mouse button, the upper boundary is defined. Once the lower and upper boundaries are defined, you will see two vertical lines depicting the boundaries, with two diagonal lines joining them. You will also see a circle, the height of which indicates the width of the region relative to the width of the entire histogram. If you click with the middle mouse button, the horizontal cursor position will control the midpoint of the region (i.e. change the lower and upper boundaries at the same time), and the vertical cursor position changes the width of the region. You can drag any of the three mouse buttons to see things continuously change.
If you have not yet defined a region, you may first click with the right button to define the upper boundary. The lower boundary is automatically set to the data minimum. This is a convenience facility when you want to set the lower boundary to the data minimum and set the upper boundary manually. You can get the same effect by pressing Full Range first and then clicking with the right button.
A screen snapshot is available here.
You can also change the intensity control policy by selecting the Intensity Policy option in the Intensity menu. This will pop up an IntensityPolicy widget.
This widget controls the intensity policy to be used for displaying image data on a drawing canvas. The following controls are provided:
A screen snapshot is available here.
If you load a datacube into the <kvis> programme, you may wish to play it as a movie (sequence of images). A window to control this sequence is under View->Animate.
The AnimateControl widget provides the animation control interface. This widget controls movie loops. It allows the user to control the speed and direction of movies, as well as the ability to skip frames. The following controls are provided:
You can also step through the cube by clicking (left) for the previous frame or click (right) for the next frame in the black rectangle which appears below the Goto Frame button. In addition, you can click (middle) and drag in this black rectangle, allowing you to dynamically slide through the movie.
A screen snapshot is available here.
To make a PostPcript hardcopy of the display, click on the menu button Export in the visualisation tools and select PostScript. This will display the Postscript widget. This widget provides controls for generating PostScript hardcopy. It supports different orientations and trays and allows you to queue directly to a printer. The following controls are available:
A screen snapshot is available here.
To save data you are looking at, click(left) and hold the Export button. This will show the ExportMenu widget.
This widget allows you to export the currently displayed data to some other format. The following options are available:
Most tools provide a generic 2-dimensional zooming interface. This interface is provided by the ImageDisplay widget (section 2.15).
To resize a display window, grab the bottom right corner of it and drag to the size that you want. The image is updated automatically. Most programs have a menu Zoom which has a selection Zoom Policy which will show the ZoomPolicy widget which gives you control over how zooming is done.
This widget controls the policy to be used for displaying image data on a drawing canvas. The following controls are provided:
A screen snapshot is available here.
All the standard visualisation tools now support axis labelling. Most programs have an Axis Labels button which will show the DressingControl widget which gives you control over how labelling is done.
This widget controls the way axis labels are drawn onto a canvas. The following controls are available:
A further set of controls is provided under the red line (most of the time you will not need to use these):
Note that the axis labelling currently does not handle co-ordinate systems which have rotations close to 90 degrees or 270 degrees.
A screen snapshot is available here.
Many programmes have a Zoom menu with a Magnifier option which, when selected, will show a magnifying-glass window. As you move the mouse cursor over the main image window, a zoomed-in subsection around the cursor is displayed in the magnifying glass. This view is zoomed in four times the scale of the input image. If the image in the main window is zoomed in ten times, the view in the magnifying glass will actually be smaller!
This widget is a subclass of the SlaveImageDisplayPopup widget.
Many programmes have a Zoom menu with a Panner option which, when selected, will show a panner control window. By pressing the left mouse button in this window, the image in the main window is panned.
This widget is a subclass of the SlaveImageDisplayPopup widget.
Many programmes allow you to point at an image and obtain the corresponding profile along the third axis (usually a spectrum profile). Some programmes provide a Profile button which you need to press first before you will see the profile, while some others will automatically display the profile window when you have loaded a cube of floating-point data. You don't need to press any buttons to update the profile display, simply point the mouse at the desired spot. The ability to display spectrum profiles is provided by the TracePopup widget. This widget will display a line plot of a single trace of one-dimensional data. It is fast, allowing dynamic display of data, and provides zooming and smoothing controls, as well as having the ability to display axis labels. The controls available are:
To zoom a profile, click (left) and drag the mouse (still keeping the left button down) across the window. You will see a ``rubber-banded'' box stretching between the first point and the current mouse cursor position. When you release the button the section of the profile within the box will be zoomed. To unzoom, choose the Unzoom option in the Zoom menu, or press the ``u'' key while the cursor is in the profile window. This will show the entire image.
A screen snapshot is available here.
Many programmes have a facility to compute and display the statistics of the current (sub)image being viewed. This interface is provided by the ImageDisplay widget (section 2.15).
Many programmes allow you to inspect the header of the dataset you are currently viewing as an image. This interface is provided by the ImageDisplay widget (section 2.15).
All drawing operations in Karma tools are performed on a ``canvas'', which is usually a big plain black or white rectangle.
The canvas allows you to freeze ``mouse move'' operations (i.e. things which happen in response to your moving the mouse over the window, but not while pressing any mouse buttons or keyboard keys). This is useful when you have pointed at a certain place, and want to maintain a position or profile display while you move the mouse to some other window (perhaps to print the window). All you need to do is press the spacebar, and any further mouse moves are ignored. If you press the spacebar again the mouse moves once again do something. So that you don't forget that mouse moves are disabled, you will hear a quiet beep every time you move the mouse into the window.
Similar to above, except that when pressing any mouse buttons or keyboard keys the freeze position is used, rather than the real position of the mouse.
Many of the visualisation tools have one or two very similar main windows. This is because they are all derived from the ImageDisplay widget, which provides most of the common functionality. Most of the tools which use this widget provide the following controls:
You will also see a few lines of display under the control buttons, which gives information about the data under the current cursor position.
A screen snapshot is available here.
Wherever you move the mouse over the main image, you will see a magnified portion of that part of the image (the magnification is 4x the data resolution). You can resize the magnifier window.
Simply click with the left mouse button in the panner window and the main window will pan to the desired location. The panner window will display a green rectangle showing you where you have panned to, relative to the entire image. You can resize the panner window. When you select the panner from the Intensity menu, the panner is popped up and the main window is set to panning mode.
To zoom an image, click (left) and drag the mouse (still keeping the left button down) across the window. You will see a ``rubber-banded'' box stretching between the first point and the current mouse cursor position. When you release the button the section of the image within the box will be zoomed. To unzoom, choose the Unzoom option in the Zoom menu, or press the ``u'' key while the cursor is in the image window. This will show the entire image.
You can also press the ``i'' key (zoom in) and the image is zoomed 2x, with the new centre of the image being the position of the mouse when the ``i'' key was pressed. You can zoom in as many times as you like. To unzoom 2x, press the ``o'' key (zoom out). When unzooming it doesn't matter where the mouse is.
If you press and release the left mouse button without moving the mouse in between, the image will be panned so that what is under the mouse cursor is moved to the centre of the image. An extra facility in <kvis> and <MultibeamView> is the ability to zoom in and out using the middle and right mouse buttons, respectively, in a similar fashion to using the ``i'' and ``o'' keys.
Note that these zoom controls are not available when you place the main window in panning mode.
Another key you can press is ``r'' which simply refreshes the window, without changing the zoom area.
Many programmes have a facility to compute and display the statistics of the current (sub)image being viewed. Simply press the ``s'' key in the display window and you will see a summary of the image statistics in the terminal window. This summary includes the number of (non-blank) values, the standard deviation, the mean, minimum, maximum and sum value. Alternatively, you can click (left) and drag the mouse to a new position (still holding the mouse down!) and press the ``s'' key. The statistics are computed over the boxed area. After you press ``s'' you may release the mouse button. This feature saves you from having to zoom in and unzoom every time you wish to compute statistics on a sub-image. Note that the old box remains on the image until something clears it (this is useful when you want to know which regions you have already computed statistics over).
The ``v'' key allows you to see the individual image pixel values, rather than their statistics. This works in a similar fashion to the ``s'' key. The ``V'' key is a variation which shows raw image pixel values. Note that if you press ``v'' or ``V'' without the mouse, all the pixels in the subimage being viewed would be printed. Since this can take a long time with a large number of pixels, a warning message is issued if you attempt this with many pixels. If you definately want to display a large number of pixels, press the control key at the same time.
Many programmes allow you to inspect the header of the dataset you are currently viewing as an image. Simply press the ``h'' key and the header will be displayed in the terminal window. If you press the ``H'' key, you will get the header without the history.
Many programmes allow you to capture the current world co-ordinate position of the mouse, by pressing the ``l'' key in the image window. The output is set to the standard output, which you may redirect to a file prior to starting the programme.
Some of the programmes allow you to generate quick moment maps. This is usually available in tools where you need both a cube and an image of a similar section of sky. To save you the trouble of going into an astromonical reduction package to generate the moment maps, a menu is provided so that you can generate and view a moment map. This is usually the Loaded Image Menu, and has entries like 0th moment and 1st moment. Selecting either one of these will pop up the MomentGenerator widget. This widget allows the user to generate the 0th (total intensity) and 1st (velocity field) moment maps from a cube. The following controls are available:
A screen snapshot is available here.
Most data display windows have cursor readout facilities: simply move the mouse over the display canvas and you will see a few lines of numbers change above the canvas. In most cases positions are shown both in data pixel co-ordinates as well as real-world co-ordinates.
Most astronomical reduction packages count from 1, so the bottom-left corner of an image is at (1,1). This reflects the FORTRAN language from which these packages originated. The Karma software is written in the C language and reflects the C convention of counting from 0. This means that the bottom-left corner of an image is at (0,0) in Karma.
Many of the Graphical User Interface tools have a number of command-line switches which may be used to modify their behaviour. These are listed below:
In addition, the standard Xt command-line switches are supported. Read the manual page for xterm for more details. In particular, the following options are worth noting:
Standard workstations with 8bit ``PseudoColour'' displays only have a single colourmap active at one time. If you start two display tools, each wanting to use a large number of colours, then when you move the mouse between the windows you get that horrible colourmap flashing effect as the window manager updates the hardware colourmap. Also, since the colours used by one tool are likely to be quite different from those used in another tool, the image in one tool will look completely wrong when the mouse is in another tool. It is particularly annoying if colourmap flashing occurs when moving between an image window and the desktop (i.e. normal terminal windows), because often you may want to read something in a terminal window while also looking at an image. There are a number of ways to get around this.
One of the most common problems is a WWW browser (like Netscape) or a display tool (like xv or ghostview) which is started before you start a display tool. You can try to limit the number of colours Netscape uses, but I haven't found that to be all that reliable. You can also use the -install command-line switch, which will force Netscape to use it's own colourmap, rather than stealing colours from the standard one. This will of course mean that as you move the mouse into the Netscape window the colours flash, but in practice this shouldn't matter so much because people tend to use Netscape less often than a visualisation tool.
Another more recent (and more insidious) problem is the ``CDE'' (the Common Desktop Environment), which steals not only too much screen space but also a large number of colours. Unfortunately, users don't get much choice about CDE, as the system administrator often blindly enables it when installing the operating system. If you start a display tool under CDE, the tool will usually have to create its own private colourmap in order to get enough colours. This would give you that colourmap flashing whenever you move between the image window and the desktop. You can try to get around this by using the -num_colours option to Karma tools (see above). Many tools try to allocate 200 colours, but you can use 100 instead and it is usually still workable. In the long run, though, it is probably better to get rid of CDE, or possibly configure it so it only takes a few colours (good luck).
Another problem can be when you use more than one Karma visualisation tool at the same time. The second tool is likely to create its own colourmap because the standard (desktop) colourmap has few colours left. You can either reduce the number of colours required by each tool, or you can share colourmaps using the -cmap_master host:port command-line switch (see above).
Finally, you may be wanting to use a Karma visualisation tool as well as some other display tool. To avoid colourmap flashing, you will need to reduce the number of colours each tool uses. You will need to read the manual for the other tool to see what option controls the colourmap size.
Examples of things you can do:
Many tools provide a facility to draw overlays. This is provided by the OverlayEditorControl widget.
This widget allows you to interactively draw overlays on top of an image. It uses the overlay package which maintains a list of geometric figures which should be drawn.
The following controls are provided:
A screen snapshot is available here.
This widget uses the middle mouse button for its drawing functions. Some tools may already be using this button for other purposes, in which case the tool should provide a control which allows you to disable the normal use of the middle mouse button. For instance, the <kvis> programme provides such a control through the ZoomPolicy widget (section 2.7).
You click down the mouse button to define one corner of the rectangle and move the mouse (keeping the button down) until you have a rectangle to your liking. Once you are happy, release the button and the rectangle will be added to the overlay list.
Click the mouse button to define the centre of the ellipse and move the mouse (keeping the button down) to change the size and shape of the ellipse. If you press and release the 'r' key (still with the button down), this will toggle rotation mode, so that now as you move the mouse the ellipse will rotate. To leave rotate mode, just press the 'r' key again, and you will be back to changing the size and shape of the ellipse. Once you have an ellipse you are happy with, release the mouse button and it will be added to the overlay list.
Click and release the mouse button to define the first and subsequent vertices of the polygon. To close (terminate) the polygon, click and release the button twice without moving the mouse. Once you have closed the polygon it is added to the overlay list.
Many tools provide a facility to load overlays (annotations) from an ASCII file. Please see appendix D for details.
Many tools provide a facility to edit image data. This is provided by the ImageEditorControl widget.
This widget allows you to interactively edit images. It uses the iedit package which maintains a list of geometric figures which can be drawn and then applied to data.
The following controls are provided:
This widget uses the middle mouse button for its drawing functions. Some tools may already be using this button for other purposes, in which case the tool should provide a control which allows you to disable the normal use of the middle mouse button. For instance, the <kvis> programme provides such a control through the ZoomPolicy widget (section 2.7).
The drawing interface is the same as for the OverlayEditorControl widget (section 2.19).
Karma Home Page