Karma Home Page
Karma has a number of command-line tools to manipulate data files. There are tools for converting from foreign data formats to Karma format, tools to convert from Karma to foreign formats as well as tools to manipulate data files in various ways (i.e. regridding).
All of the command-line tools use the panel package in the Karma library to implement a common ``feel''. This package defines a set of panel items which are simply parameters you can set or actions you can take. The tools may be started in interactive mode by giving no arguments to the tool, or they may be started in batch mode, giving a set of arguments to the tool. Once the tool has completed processing, it exits.
To start a tool in interactive mode, just type in its name at the shell prompt. You should then see a prompt with the name of the tool followed by a ``> ''. In this discussion it is assumed that you will press the return key after typing something in.
Probably the first thing you will want to do is press ? to see a list of parameters and actions. On the left hand side you will see all the parameter and action names. For parameters, you will then see zero or more values after the parameter name. For actions, you will not see any values. Finally, you will see a ``#'' character usually followed by a short description of the parameter or action.
To specify a parameter or action, type in its name, followed by any arguments required. You can type shorter, non-ambiguous name if you wish. You can only specify a single parameter or action on one line.
Actions are things that happen when you type their name. Some actions require no further arguments (such as the exit action), while others may require any number of arguments. The brief description for the action should indicate what arguments are needed.
These are parameters which take as argument a single scalar value or string. After typing in the name of the parameter, followed by a space, you must type in the value or string.
Strings do not need to be enclosed in quotes unless they contain a space. You may use either single or double quotes to enclose a string. Naturally, you must use the same type of quote character to close the string as you used to open it. To encase a quote character inside a string, just type it if you used the other type of quote character to enclose the string, or type the quote character twice if the string is enclosed by the same type of quote.
Scalar values may be integer or floating point, and may be real or complex depending on the type of the parameter. If it is a complex value, the real and imaginary components must be separated by a space.
A vector parameter is an array of scalar parameters. The parameter is displayed with a trailing [n..m] after its name. The value n is the minimum number of elements in the array and the value m is the maximum number of elements in the array.
After typing in the name of the parameter, you must type in the array of scalar elements. Elements in the array must be separated by a space. You must type in at least the minimum number of elements, otherwise your input is rejected. If you type in more than the maximum number of elements allowed, the excess elements are discarded.
If you wish to append elements to an existing array, simply type + followed by the parameter name and then followed by the scalar elements.
If you want to empty out the contents of an array, just type the name of the parameter without any elements after it. This does not work if the minimum number of elements is greater than 1.
A choice parameter allows you to choose from a selection of possibilities. If you wish to see what all the possibilities are, type ?? and you will see a list of choices for each choice parameter.
After typing in the name of the parameter, type in your choice. You can type the minimum non-ambiguous choice string if you wish.
There are a few actions which are common to all tools, which allow you to exit the ``panel'' (exit the tool), with or without saving parameters, and others which manipulate the communications infrastructure.
Most tools define some other arguments which are not parameters or actions. They are usually filenames to process, although they can be other things too (like dimension to filter along). An unlimited number of other arguments may be typed in one line.
Some tools will show the other arguments by printing ``General usage: '' followed by the arguments.
The abort action will abort the tool without saving any parameters. The exit and quit actions will exit the tool after saving parameters. Pressing control-D has the same effect as typing exit.
Another term for ``batch mode'' is ``shell mode'', which just means that the tool is started from the shell, with arguments, and exits when it has completed. From the shell, you can pass in any number of parameters and actions. The limitation in interactive mode of only typing a single parameter or action is removed.
You simply need to place the - character in front of the name of the parameter or action (with no intervening space). This marks the start of a new parameter or action. All subsequent shell arguments are treated arguments for the action or parameter, until the the list is broken. A new parameter or action name with a preceeding - will break the list, as will a solitary - character. The solitary - character marks the start of remaining ``other arguments'', after which there can be no further action or parameters.
If a string contains spaces, you should enclose it in quotes on the shell command line. If you are familiar with how most shells work, you will know that it removes enclosing quotes before passing them onto the programme. Karma deals with this by checking if a shell argument has a space in it, and if it does, it puts a pair of double quotes around the argument again. This should be transparent to you unless you start doing esoteric things with embedded quotes.
Passing in a negative number is not a problem, because this case is trapped (note all parameter or action names must begin with an alphabetic character). If you wish to pass in a string with a preceeding - then you should type in - at the shell command line. The double minus will be reduced to a single minus before being used.
If you do not pass in any parameters or actions, then you can just type in the other arguments as you would in interactive mode. However, if you preceed the other arguments with parameters or actions, you need to type a solitary - between the last argument to the last parameter or action and the first ``other argument''. This solitary - should be surrounded by at least one space on either side.
Each of the command-line tools will look for a file called ``. name.defaults'', where name is the name of the programme. This file (the ``defaults'' file) contains saved parameters which will be read by the tool as it starts. First the current working directory is searched, and then each parent directory in turn, until either a defaults file is found, or the root directory is reached. If still a defaults file is not found, then the tool will look in the .karma/module-defaults directory under the users home directory, and then finally it looks in the $KARMABASE/defaults directory. If no defaults file can be found then internally hard-coded defaults are used.
Upon normal exit, each tool will write its defaults file in the current working directory.
This tool will change the length of a dimension in a Karma file. You can increase the length of a dimension by zero-padding or resampling and decrease the length by truncating, windowing or resampling. The option parameter controls whether a dimension is resampled, truncated or padded. The resampling option is the same as a one-dimensional regridding.
If you have chosen to resample a dimension, then the resample_option parameter controls whether a nearest neighbour copy or linear interpolation is performed.
The general usage for the programme is:
chlen infile dimension_name
where infile is the input data file and dimension_name is the name of the dimension to change. Note that the input file may be of any format.
If you had a spectral-line datacube and you wanted to resample the velocity axis to, say, 600 data pixels, the following options would be needed:
resample_option linear_interpolation option resample num_coordinates 600
and then you would type something like:
mycube VELO-HEL
This tool will convert multiple images of any format into a Karma cube. This tool is not implemented with the panel and hence does not have settable parameters or an interactive mode. The usage for this programme is:
images2karma infiles [...] outfile
The input images must be of the same shape, size and type, but do not need to be of the same file format.
This tool will convert a Karma image or cube file into one or more PPM (Portable Pixel Map) files. The PPM format is a 24bit TrueColour image format. A Karma image or cube (movie) may be either TrueColour or PseudoColour with an associated colourmap in the file.
If the input image or cube is greyscale (i.e. no colour information is available), then it is still possible to write out a PPM file if you supply a colourmap file, previously saved with a Cmapwinpopup widget (section 2.2). You specify the colourmap file using the cmapfile parameter.
The general usage for this programme is:
karma2ppm infile outfile
where infile is the input Karma file and outfile is the output PPM file. If the input file is a 3-dimensional array, a sequence of numbered output files will be written.
You can also use <karma2ppm> to write out images in other popular formats, such as GIF, TIFF, Targa TrueVision and so on. To do this requires that you have the NetPBM tools installed. These tools are freely available and very popular, as they allow conversion between many different image formats. To use this facility, you need to set the converter and extension parameters. The converter is the name of the programme which converts PPM/PNM images to the image format you desire. The extension is the conventional filename extension for that image format.
For example, if you wanted to convert a Karma image or cube to
a TIFF image or sequence of images, you would need the
following settings:
converter pnmtotiff
extension tiff
On the other hand, if you wanted to generate GIF images, you
would need the following settings:
converter ppmtogif
extension gif
Notice how the the TIFF converter seems to require PNM files whereas the GIF converter seems to require 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.
If you wish to write out images of a different size from your input image/cube, then you will need to use the out_width and out_height parameters. If your input is smaller than this, the image will be blank-filled and centred onto the desired output image size. If the input is larger than this, it will be centred and truncated. No pixel averaging or replication is performed.
This tool will decimate a cube, averaging a specified number of values along an axis to produce a single value. This decimation is performed along all 3 axes. This tool provides a simplified version of the LoadAndDecimate widget (section 2.1.1). The only reason to use it is if you are developing batch mode scripts to process large number of datacubes.
The general usage for this programme is:
kdecimate infile outfile
This tool will show the minimum and maximum value in a datafile. It will also display the number of blank values (TOOBIGs) and the number of illegal values. Note that illegal values should never occur, and are the result of an incorrectly written file. Illegal values will cause problems for Karma programmes (such as a segmentation fault or other crash). Hence this programme is an excellent diagnostic to determine if the data you are giving to a programme is legal.
This programme supports many data formats. The general usage for this programme is:
kminmax infile dataname
where infile is the file to load and dataname is the name of the data elements to process (this is usually the same as the unit name, for example ``JY/BEAM'' or ``HZ'').
This tool will show the header in a datafile. It supports many data formats. The general usage for this programme is:
kprinthead infile
where infile is the file to print the header for.
This tool will regrid one or more input images or a cube onto an output image or cube. It is possible to use this tool to mosaic several images or cubes together onto a new grid. The general usage for this programme is:
kregrid infile
where infile is the input file to regrid or is a file containing a list of files to regrid and mosaic. The output filename will be ``kregrid_infile.kf''
This tool will rotate (by regridding) an image or cube such that the longitude axis (Right Ascension or Galactic Longitude) is aligned with the horizontal axis. This is often used to rotate images to a more convenient or familiar orientation (e.g. images from the Hubble Space Telescope). The general usage for this programme is:
krotate infile outfile
where infile is the input file to rotate and outfile is the name of the output (rotated) file you wish to create. If you specify an extension of .fits then a FITS file will be written, otherwise a Karma file will be written. You may use the projection option to control the output projection (the default is to use the same projection as the input).
This tool allows you to send commands to various GUI tools. The commands include loading a file, writing PostScript to a file, setting display ranges and so on. This can be useful for batch processing many different datasets using the same control settings.
If you wanted to load the files mom0 and mom1 into the <kvis> programme, displaying mom0 as an image and mom1 as contours and then write PostScript to the ps file, you would first need to start <kvis> and set up the controls appropriately to display contours. Then you can use the command:
ksend -add_connection unix kvis multi_array -load ARRAY:FILE0 mom0
-load ARRAY:FILE0 mom1 -print ps
A variation of this would be to generate a Portable Pixel Map (PPM) file with name fred.ppm:
ksend -add_connection unix kvis multi_array -load ARRAY:FILE0 mom0
-load ARRAY:FILE0 mom1 -ppm fred.ppm
You can use the above command many times, each time specifying different files, and hence obtain batch mode operation.
If you wanted to set the intensity display range to 1.0 and 1.5 for dataset 1 you would do something like this:
ksend -add_connection unix kvis multi_array
-rclip "Dataset 1" 1.0 1.5
Alternatively, if you wanted to set the intensity display range to 95% of the data, you would do something like this:
ksend -add_connection unix kvis multi_array
-hclip "Dataset 1" 0.95
This tool allows you to load an image and compute contour overlays which may then be sent to any GUI programme for display. This facility is only useful when you want to add contours to a tool which doesn't already have built-in support.
For each extra dataset you wish to display as contours, you need to run a copy of the <send-contours> programme. To start the programme, type:
send-contours
Once in the tool, you will need to specify the desired contours levels. This interface is quite primitive, requiring you to enter the actual values for each level. For example, if you have a 1st moment map with interesting contours at 1.419 GHz and 1.420 GHz, you would type the following:
contour_levels 1.419e9 1.420e9
You then need to specify the input file containing the image data:
in_file infile
where infile is the input filename. Next you need to make a connection from the tool to a GUI tool. Typically, this will be the <kvis> programme which is running on the same machine. For example, type:
add_connection unix 7605 2D_overlay
The number 7605 is the Karma port number of the GUI tool, and is displayed in the title bar of the GUI tool. Other GUI tools will have different port numbers. Once you have done all this setup, type go and you should see your new contours. The normal GUI functions for zooming are supported. You can use the empty_list command to remove the contours and clean up the display.
Karma Home Page