Karma Home Page
Next: 3 Viewing and Comparing Up: Karma User Manual Previous: 1 Introduction

# 2 Common Features

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.

- Loading Data
- Intensity Scaling
- Sequences of Images
- Hardcopies
- Exporting Data
- Zooming
- Resizing/autoscaling
- Axis Labels
- Magnifying Glass
- Panner
- Spectrum Profiles
- Image Statistics
- Viewing Header Information
- Freezing Events
- Common Image Display Features
- Generating Moment Maps
- Cursor Readout
- GUI Command-line Switches
- Drawing Overlays
- Loading Overlays
- Editing Images

# 2.1 Loading Data

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:

- close close the window
- rescan rescan the directory in case a new file has appeared
- pin enable to force the fileselector window to stay ``pinned'' up even if files are selected. The default is to close the window once a file is selected
- new create a new file browser. The current directory will be independent of the original file browser
- filter if enabled, selected files are not automatically loaded, rather, the LoadAndDecimate widget (section 2.1.1) is displayed

- partial if enabled, support loading of partial files. This is useful if you want to see a preview of a dataset that is currently being written by another process. See the section on partialdata data in the Karma User Manual
- writable if enabled, the file may be modified later (i.e. by the image editing facility)
- pull change the directory in this browser to match the most recent directory change in any browser (i.e. pull the most recent directory change)
- push change the directory in all other browsers to match the directory for this browser (i.e. push this directory to others)

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:

- `$KARMABASE/share/browser-dirbuttons`
- `$KARMABASE/site/share/browser-dirbuttons`
- `$HOME/.karma/browser-dirbuttons`

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.

## 2.1.1 Subsetting/Decimation of Array Data

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:

- Cancel close the window
- Load load the file using the specified parameters
- Abort abort the loading process
- Auto Save if enabled, the decimated subcube is automatically saved to disc
- X Start select the starting position of the subcube in the X dimension
- Y Start select the starting position of the subcube in the Y dimension
- Z Start select the starting position of the subcube in the Z dimension
- X End select the end position of the subcube in the X dimension
- Y End select the end position of the subcube in the Y dimension
- Z End select the end position of the subcube in the Z dimension
- X Skip select the skip factor along the X dimension. The default value of 2 will make every 2 input values along X averaged together
- Y Skip select the skip factor along the Y dimension. The default value of 2 will make every 2 input values along Y averaged together
- Z Skip select the skip factor along the Z dimension. The default value of 2 will make every 2 input values along Z averaged together
- Output filename change this to select the name of the file which is saved to disc

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.

# 2.2 Intensity Scaling

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:

- Close close the window
- Reverse this reverses the colour table; the colours of the minimum and maximum are swapped
- Invert this inverts every colour (e.g. white becomes black, green becomes purple, blue becomes yellow and so on)
- Save this brings up a popup window which allows you to save a colourtable
- Load this brings up a file browser popup which allows you to load a previously saved colourtable

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:

- Close close the window
- Blank enable to blank data outside specified region (not all applications will show this toggle)
- Zoom zoom the histogram display to the range of the current region
- Unzoom unzoom the histogram display to the full range of the data
- Apply apply any changes made to the regions (most applications will then rescale and display their main image)
- Auto Apply enable this to automatically apply every change as they are made
- Subset enable this to use only a subset of the input data. This will speed up the histogram computation, and may avoid unwanted outlier values
- Full Range set the region to the full range of the data
- 95% set the region to clip to the inner 95% of the data values (i.e. clip the lower 5% and upper 5% of the data values). This is very handy when your data contains ``outliers'' (small numbers of data values which lie far away from the real data)
- 98% set the region to clip to the inner 98% of the data values
- 99% set the region to clip to the inner 99% of the data values
- 99.5% set the region to clip to the inner 99.5% of the data values
- 99.9% set the region to clip to the inner 99.9% of the data values
- 99.99% set the region to clip to the inner 99.99% of the data values
- Save save a new file which has been clipped to the specified range
- Output Type Menu change the output type of the array to save (not all applications will show this menu)
- Filename string the name of the file which will be saved. This may be changed prior to saving

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:

- Close this will close the window
- Apply apply control changes and refresh the window
- Auto Refresh if enabled, each control change is automatically applied and the window refreshed
- Auto Intensity Scale if enabled, the intensity range of the (sub)image being viewed is mapped onto the colourmap, otherwise the intensity range of the entire image/movie is mapped onto the colourmap
- Reset Intensity Upon File Load if enabled, the intensity scale is reset when a new dataset is loaded (it is reset to the full data range). If disabled, the intensity scale is not changed on file load
- Intensity Scale Menu this menu allows you to change between different intensity scales. By default, the intensity scale is linear, but you can select a logarithmic intensity scale or a square-root intensity scale. If you are using a logarithmic intensity scale, you can set the Log Cycles value to control the visible dynamic range in powers of 10

A screen snapshot is available here.

# 2.3 Sequences of Images

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:

- Close close the window
- Previous Frame show the previous frame
- Next Frame show the next frame
- Start Movie start the movie
- Stop Movie stop the movie
- Sync wait for each frame to be drawn before sending the next draw request. Normally, this is enabled. You can make movies run a little bit faster (not much) by disabling this, but you run the risk of developing a backlog of display requests in the display machinary. A large backlog will make the interactive response extremely poor
- Spin Mode you can select forward or backward spin, or alternatively spin forwards->backwards->forwards->...
- Anti Flicker remove the flicker observed when overlays (i.e. contours and/or annotations) and/or axis labels are shown. This is normally disabled because it slows down movie playing and interactive display updates. Also, flicker is only noticeable under some conditions (complex overlays and/or slow display hardware)
- Frame Interval the time interval between between frame draws. A low interval will give fast movies
- Skip Factor allows you to skip frames. A skip factor of 2 would skip every second frame
- Goto Frame jump to the frame number shown in the Current Frame control
- Current Frame the current frame number
- Starting Frame the starting frame number in the movie loop
- End Frame the end frame number in the movie loop

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.

# 2.4 Hardcopies

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:

- close this will close the window
- save .ps save a PostScript file
- save .eps save an Encapsulated PostScript file
- print queue directly to a printer
- Tray Menu you can choose between default, paper or transparency trays
- Size Menu you can choose between a variety of media sizes (A3, A4, A5, letter and so on). The ```A4/letter`'' size will fit on both A4 and letter size media. If you select ```user defined`'' then you can define the bounding box using the offset and size controls described below. The default is taken from the ```PAPER_SIZE`'' environment variable
- Keep Aspect if enabled, screen pixels will always be drawn square in the PostScript output
- Orientation Menu you can choose between portrait and landscape orientation, or you can let the choice be automatic so that a best fit is made (e.g. a display window that is much wider than it is high would be displayed in landscape mode on A4 size media)
- hoffset controls the horizontal offset of the output
- voffset controls the vertical offset of the output
- hsize controls the horizontal size of the output
- vsize controls the vertical size of the output
- Auto Increment when enabled, existing PostScript files are not overwritten, rather, the outfile filename has an incrementing sequence number added to it
- Lock Filename when enabled, the application will never automatically change the suggested output filename
- Output file controls the basename of the output file
- Printer queue controls which printer queue to print to. The default is taken from the ```PRINTER`'' environment variable

A screen snapshot is available here.

# 2.5 Exporting Data

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:

- PostScript generate hardcopy output of the contents of the drawing canvas. This will pop up the Postscript widget (section 2.4)
- SunRasterfile export the currently viewed image to Sun Rasterfile format
- PPM Data Image export the currently viewed image data to PPM format. Non-image data (i.e. axis labels and annotations) are not exported. The output is at the resolution of the image data
- PPM Data Movie export the currently viewed cube data to PPM format, similar to `PPM Data Image`. One PPM file is written for each image along the unseen axis
- PPM Data Window export the contents of the window to PPM format. Non-image data (i.e. axis labels and annotations) are also exported. The output is at the resolution of the window, and yields higher quality than using a separate screen-capture tool
- Karma (whole dataset) export the currently viewed dataset to Karma format
- FITS (whole dataset) export the currently viewed dataset to FITS format
- Miriad (whole dataset) export the currently viewed dataset to Miriad Image format
- GIPSY (whole dataset) export the currently viewed dataset to GIPSY format
- Karma (subset) export the currently viewed (sub)image to Karma format. If the subimage being viewed is a cube, the subcube will be saved
- FITS (subset) export the currently viewed (sub)image to FITS format. If the subimage being viewed is a cube, the subcube will be saved
- Miriad Image (subset) export the currently viewed (sub)image to Miriad Image format. If the subimage being viewed is a cube, the subcube will be saved
- GIPSY (subset) export the currently viewed (sub)image to GIPSY format. If the subimage being viewed is a cube, the subcube will be saved

# 2.6 Zooming

Most tools provide a generic 2-dimensional zooming interface. This interface is provided by the ImageDisplay widget (section 2.15).

# 2.7 Resizing/autoscaling

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:

- Close this will close the window
- Apply apply control changes and refresh the window
- Auto Refresh if enabled, each control change is automatically applied and the window refreshed
- Fix Aspect if enabled, the image will be expanded/shrunk with the same factor in both dimensions to fill the window. If disabled, the factors are not necessarily the same (i.e. the pixels will not be square, but the image will fill the window better)
- Allow Truncation if enabled, and the image is too big for the window and integer zooming is enforced, a few rows or columns of data may be discarded to allow the image to be shrunk
- Integer X Zoom if enabled, force zooming in the horizontal dimension do be done in integer multiples. Turning this off allows you to fill the window, but can introduce artefacts
- Integer Y Zoom if enabled, force zooming in the vertical dimension do be done in integer multiples. Turning this off allows you to fill the window, but can introduce artefacts
- Zoom In on Middle Mouse Click if enabled, clicking the middle mouse button will zoom in 2x using the mouse click position as the new centre
- Zoom Out on Right Mouse Click if enabled, clicking the right mouse button will zoom out 2x

A screen snapshot is available here.

# 2.8 Axis Labels

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:

- Close this will close the window
- Enable if enabled, the axis labels are displayed
- Apply apply control changes and refresh the window
- Auto Refresh if enabled, each control change is automatically applied and the window refreshed
- Show Labels if enabled, the axis names are displayed
- Show Scale if enabled, the scale values corresponding to major tick marks are displayed
- Show Top Tick Marks if enabled, the tick marks at the top of the window are displayed
- Show Bottom Tick Marks if enabled, the tick marks at the bottom of the window are displayed
- Show Left Tick Marks if enabled, the tick marks at the left of the window are displayed
- Show Right Tick Marks if enabled, the tick marks at the right of the window are displayed
- Internal Ticks if enabled (the default), the tick marks are placed inside the bounding box, otherwise they are placed outside
- Grid Lines if enabled, the co-ordinate grid is shown
- Screen Colours pressing this will set the background colour of the window to black and the colour of the axis labels to green. If a colourmap is associated with the window, it's Reverse option is turned off
- Paper Colours pressing this will set the background colour of the window to white and the colour of the axis labels to black. If a colourmap is associated with the window, it's Reverse option is turned on
- Change Colourmap if enabled, the Reverse option for the window colourmap Cmapwinpopup widget (section 2.2) is set when you press either Screen Colours or Paper Colours
- Show Colourbar if enabled, a colourbar is displayed. This shows the mapping between data value and colour. Note that currently only linear intensity scales are supported
- Font scale this slider allows you to enlarge or shrink the font scale for the labels

A further set of controls is provided under the red line (most of the time you will not need to use these):

- Background Colour the background colour of the window. You need to press the Apply button for your changes to take effect
- Label Colour the colour the labels are drawn in. You need to press the Apply button for your changes to take effect
- Grid Colour the colour the grid is drawn in

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.

# 2.9 Magnifying Glass

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.

# 2.10 Panner

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.

# 2.11 Spectrum Profiles

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:

- Close this will close the window
- Auto Zoom if enabled, the vertical scale is automatically zoomed to the range of the data in the profile
- Unzoom this will unzoom the window
- Smooth menu, to select what kind of smoothing to apply to the data, prior to display. Both hanning and uniform smoothing kernels are available, with a range of sizes
- Print this will pop up the Postscript widget (section 2.4)
- Overlay this allows you to popup various control panels to control overlay display, including axis labelling (section 2.8)

- Save Data this will pop up a dialog widget which allows you to save the data to a file. The data is saved in a simple ASCII format with a few comment lines followed by two columns of numbers. The first column is for the horizontal axis and the second column is for the vertical axis
- Style menu, to select the drawing style for the data points. The following choices are available:
  - join a straight line is drawn from each point to the next
  - hist a centred column is drawn for each point (aka. ``histogram'' style)
  - cross a small crosshair is drawn for each point

### Zooming in TracePopup Widget

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.

# 2.12 Image Statistics

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

# 2.13 Viewing Header Information

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

# 2.14 Freezing Events

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.

# 2.15 Common Image Display Features

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:

- Set1 sometimes labelled as Files, or Cubes this will popup up the Filepopup widget (section 2.1)
- Intensity menu, this will popup widgets to control the colourmap
  (Cmapwinpopup), intensity policy (IntensityPolicy) and intensity scaling (section 2.2)
- Zoom menu, this allows you to popup a magnifier or a panner, zoom the image in or out 2x or 4x, unzoom, or popup the ZoomPolicy widget (section 2.7)
- Overlays menu, this allows you to popup various control panels to control overlay display. The following choices are available:
  - Axis Labels this will popup controls for the axis labelling (section 2.8)
  - Load Annotations this will bring up a file browser to load a file of ASCII overlay commands. The file format is described in an appendix to the User Manual
  - Editor this will popup the OverlayEditorControl widget (section 2.19) which allows you to interactively draw overlays
  - Remove Last (connection) this will remove the last overlay object sent via a network connection
  - Remove All (connection) this will remove all overlay objects sent via a network connection
  - Contours this will pop up a file browser which allows you to load an image and display it as contours. You can load an unlimited number of images this way
- Export menu, you can export data in a variety of formats. See section 2.5
- View this will popup a control panel used for displaying two datasets (section 4). This is only available in tools like <kvis> and <MultibeamView>
- Edit this will popup the ImageEditorControl widget (section 2.21) which allows you to interactively edit image data
- Quit this will quit the application
- Set2 sometimes labelled as Images this will popup up the Filepopup widget (section 2.1)

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.

### The Magnifier

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.

### The Panner

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.

### Zooming in the ImageDisplay Widget

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.

### Image Statistics in the ImageDisplay Widget

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.

### Viewing Header Information in the ImageDisplay Widget

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.

### Capturing Co-ordinate positions in the ImageDisplay Widget

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.

# 2.16 Generating Moment Maps

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:

- Close this will close the window
- Apply Parameters this will apply the parameters and compute the moment maps
- 1st Moment Algorithm Menu this allows you to choose between a simple ``weighted mean'' algorithm or a more robust ``median'' algorithm
- Lower Clip Level values in the cube lower than this value are not used in the computation of the moments
- Sum Clip Level values in the computed 0th moment map lower than this value are not used in the computation of the 1st moment map
- Start Channel the first channel that will be used in the computation
- End Channel the last channel that will be used in the computation

A screen snapshot is available here.

# 2.17 Cursor Readout

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.

## 2.17.1 Warning for Astronomers

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.

# GUI Command-line Switches

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:

- -private_cmap This option will force the tool to use a private colourmap for its PseudoColour window. Otherwise, the tool trys to allocate colours from the default colourmap
- -num_colours This option specifies the number of colour cells that the tool will try to allocate for its PsuedoColour window upon startup. If less colours are available it allocates as many as possible (minimum 2)
- -cmap_master host:port This option will make the tool use the colourmap of another tool. The host portion of the second argument is the Internet hostname or address where another Karma tool is running. If this is ``unix'' or ``localhost'' the tool to connect to is running on the same machine. The port portion specifies which Karma programme to connect to. You may use the port number which is displayed in the other tools title bar, or you may use the name of the tool (such as ``kvis''), and it will connect to the first ``kvis'' tool you started on that machine
- -fullscreen This option will make the image display window take up the entire screen. This is useful if you wish to make a video of the data. You will need to configure your window manager to cycle the window stacking order when a special key is pressed (e.g. the "Back" key with the Open Look window manager). Alternatively, pressing the right mouse button in the image window will place it underneath other windows. See also the appendix on making videos.

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:

- -display control where the tool is displayed
- -geometry control the size and postion of the tool
- -xrm pass a resource string

## 2.18.1 Avoiding Colourmap Flashing

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.

### Summary

Examples of things you can do:

- `unix% netscape -install`
- If running within the CDE, or other display tools (eg SAOimage),
  `unix% kvis -num_colours 100`
  and reducing the number of colours in the other tools:
  `unix% saoimage -palette 100`
- When running multiple Karma tools at once, even on different machines, you can do this:
  `junior% kvis
  Port allocated: 17545`
  `jumbo% xray -cmap_master junior:17545`

# 2.19 Drawing Overlays

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:

- Close this will close the window
- Remove Last will remove the last overlay that you drew from the list
- Remove All will remove all overlays from the list
- Object Menu allows you to choose between the different types of object that you can draw
- First Coordinate Type Menu sets the co-ordinate type of the first defining point for a geometric object
- Remaining Coordinate Types Menu sets the co-ordinate types of the remaining points which define a geometric object

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

### Drawing Rectangles

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.

### Drawing Ellipses

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.

### Drawing Polygons

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.

# 2.20 Loading Overlays

Many tools provide a facility to load overlays (annotations) from an ASCII file. Please see appendix D for details.

# 2.21 Editing Images

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:

- Close this will close the window
- Undo Last will undo the last edit object that you drew from the list
- Undo All will undo all edit objects from the list
- Apply apply the edit objects to the data (after this you can no longer undo previous edits)
- Brush Width the width of the paint brush in pixels
- Paint Value the data value to paint with
- Minimum set the data value to paint with to the current minimum (clip) value for the display canvas
- Middle set the data value to paint with to halfway between the current minimum and maximum (clip) values for the display canvas
- Maximum set the data value to paint with to the current maximum (clip) value for the display canvas

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
Next: 3 Viewing and Comparing Up: Karma User Manual Previous: 1 Introduction