 News |
FAQ
|
| Search
|
Home
|
| Getting Started | Documentation | Glish | Learn More | Programming | Contact Us |
|
| Version 1.8 Build 235 |
|
This chapter describes how to display data with the Viewer tool. You can display images, Glish arrays, measurement sets, and Tables holding source catalogs in a specific format. In the future, display of generic Tables will also be available.
If you are impatient and don't want to know anything about the Viewer, you should look at this 3.13.
There are three different ways to view data using the Viewer tool. The first approach is strictly using graphical user interfaces (GUIs). The second approach shows you how to create Viewer based applications via Glish scripting. The third approach is a combination of these two using the Image tool.
The Viewer tool is available from the Glish command line interface (CLI) and from the Toolmanager GUI. Detailed documentation describing the full interface of the Viewer toolis given in the Viewer module of the Reference Manual. The Viewer tool is made available in Glish with the command
include 'viewer.g'
It will be assumed in all of the code fragment examples that follow, that you have issued this command.
For working through the procedures in this chapter without an image or a Glish array at hand, you may use the following code to generate an example of each:
ar := viewermaketestarray()
im := imagemaketestimage('testimage.im')
Now you have a Glish array in ar and an Image tool in im. If you are interested in a sample source catalog to overlay on your images, you can open the Sources table used in the Measures tool as follows:
msc := vieweropentestskycatalog()
Now you have a table of sources accesses via the Table tool, msc.
It is straightforward to display a raster map of an image or Glish array. A raster map represents pixel intensities in a two-dimensional cross-section of gridded data with colors selected from a finite set of (normally) smooth and continuous colors--a colormap.
Because of the toolkit approach, there are a variety of ways to accomplish our display goals.
First let us see the simplest way to display an image. Do this from an Image tool. If the image you wish to display is already present in Glish as an Image tool, (say, im) then all that is necessary to display the image is:
im.view()
If you haven't yet constructed an Image tool for your image, then do that first, e.g.
include 'image.g'
im := image('testimage.im') # Native aips++ disk image
im.view()
Shortly a display of your image will appear, adorned with a GUI containing a menu bar and various buttons, whose functions are described here. Right now, if you're keen to alter some of the settings of the display, just press the Adjust button near the bottom left of the display! 3.1. The Image.view function uses its own Viewer tool to display the raster map.
Using the Image.view function, while straightforward, imposes some limitations on the flexibility of the display.
We can also easily display a FITS image.
include 'image.g'
im := image('/fits/3c273.fits') # Detects whether aips++ or FITS image
im.view()
The performance of this native-FITS access display will be fine provided you don't reorder the display axes. If you want to reorder axes in the display, then convert the image to native AIPS++ format first.
include 'image.g'
im := imagefromfits('/data/3c273.im', '/fits/3c273.fits')
im.view()
This describes how to use the general Viewer GUI, step by step.
If you are starting from the Unix prompt, you can type:
viewer
this line is just a wrapper which starts Glish and executes the code in the example immediately below. Otherwise, if you are already in the Glish command line, type:
include 'viewer.g' dv.gui()
You will see a GUI which consists of two main windows, entitled viewer - Data Manager (AIPS++) and viewer - Display Panel (AIPS++). The tool dv is made for you when the viewer.g script is loaded. It stands for 'default viewer'. It's always there and generally that's the Viewer tool to use (see below for examples of making your own). Here are the GUI descriptions of the Viewer Data Manager
A Viewer DisplayData is itself a tool which holds both data and functions which can display those data. A Viewer DisplayData for a raster map, for example, has attributes describing what colormap to use, what data range to display, etc.
In the bottom left box called Tool Name of the viewer - Data Manager (AIPS++) window, click on the array (or tool) you want to display.
If the dataset you created on the command line is not visible click the Update button and the list should update, and in it you should see the name of the data you prepared for display. You are now given a list of available display types on the right hand side. Clicking on the button Raster Map will create a Viewer DisplayData of this type.
or
In the viewer - Data Manager (AIPS++) file browser window, select a filename. After clicking on it, you are presented with the available display types for these data. Clicking on the button Raster Map will create a Viewer DisplayData of this type. Follow this link to see a detailed description of the Viewer Data Manager GUI.
The result of this procedure, for the test Glish array generated with the viewermaketestarray function, is shown in Figure 3.1. The array is displayed as a greyscale raster map in the viewer - Display Panel (AIPS++) window. The DisplayData menu is extended in the figure to show that the DisplayData array:mar(Raster Image:1) has been registered for display (i.e. the checkbox is lit).
In Figure 3.1, the main parts of the Viewer DisplayPanel GUI are visible: the menubar along the top; the control buttons down the left side, which are used to assign functions to up to three mouse buttons; the animation buttons down the right hand side which are disabled in this case because the array has only two dimensions; the button bar along the bottom, and just above that, the position information box. These are described in detail here.
This final offering of how to viewer a raster map of some appropriate data, is wholly command-line based. Thus it forms a nice introduction to actually doing some more sophisticated things with the Viewer tool, like using it in your own Glish application.
First, construct a Viewer tool:
mv := viewer();
See the Viewer documentation in the Reference Manual for a description of the parameters that can be supplied to the Viewer tool constructor. Rather than constructing your own Viewer tool, you could also use the default Viewer tool (dv) that we have seen earlier. It is constructed upon inclusion of the viewer.g Glish script. Now construct a Viewer DisplayPanel in which the raster map will be displayed:
mdp := mv.newdisplaypanel();
At this point, you will have a Viewer DisplayPanel on the screen, ready to display data. The tool mdp can be used to control this Viewer DisplayPanel. For example, you could temporarily remove the Viewer DisplayPanel from the screen by entering mdp.unmap() at the command-line. Once again, see the Viewer.newdisplayapanel documentation for the available parameters for the viewer.newdisplaypanel function, and the Viewer displaypanel documentation for the functions available in the newly created Viewer DisplayPanel.
If you have an image to display, then load the data as follows, substituting '/data/3c273.im' for the name of your image file. The quotes are required, and you may need to specify the path to the image if it is not in the current directory.
mdd := mv.loaddata('/data/3c273.im', 'raster');
If instead you have a Glish array to display, then load the data as follows, substituting data for the name of the global Glish variable in which the array is stored (note this time without quotes)
mdd := mv.loaddata(data, 'raster');Note that your image or array should have at least two dimensions.
Once you have completed the above steps, mdd is a Viewer DisplayData, which needs to be registered on a Viewer DisplayPanel (e.g. mdp) so that it can be displayed. This is done like this:
mdp.register(mdd);
and after a brief delay, the length of which is in some way proportional to the size of your image or array, you should see an initial raster map of your image or Glish array.
With only very slight modifications to the above procedures, it is possible to display a contour map generated from an image or Glish array. A contour map shows lines of equal pixel intensity (e.g. flux density) in a two dimensional cross-section of gridded data. Contour maps are particularly useful for overlaying on raster images, so that two different measurements of the same part of the sky can be shown simultaneously.
As in the case of a Raster Image, select the image tool in the Tool Name listbox or the image name in the file browser. Now click on Contour Map instead of Raster Image. Register the Viewer DisplayData on the Viewer DisplayPanel as before using the Register... submenu of the DisplayData menu.
Alternatively, for an image already present in Glish as an image tool, (say, im), use the contour option of Image.view on the command line, i.e.
im.view(contour=T);This will register the image for you automatically.
The procedure via the Viewer tool GUI is easily modified to produce a contour map display: simply select Contour Image where previously you selected Raster Image.
The command-line procedure for creating a raster map display can be modified to create a contour map display by simply replacing the line:
mdd := mv.loaddata('/data/3c273.im', 'raster');
with:
mdd := mv.loaddata('/data/3c273.im', 'contour');
Consider a Complex image or array. At each pixel, this represents an amplitude and phase (position angle). A common method of displaying amplitude and position angle data is via vectors (line-segments) where the length of the vector is proportional to the amplitude. For example, it is usual to view linear polarization data in which the fractional polarization is the vector amplitude and the the linearly-polarized position angle is the vector position angle. This may be overlaid on total-intensity raster displays. Another example might be the display of fluid-flow.
Since amplitude and phase can be conveniently represented as a Complex number, the data source for this kind of vector display is either a Complex image or a Complex Glish array (later we will describe how you might create such data).
However, you can also provide Float images and arrays, in which case the data values specify the position angle and the amplitude is assumed to be unity. The angular units should be specified by the brightness unit of the image. If none, degrees are assumed.
The position angle is measured positive North through East when you display a plane holding a celestial coordinate (the usual astronomical convention). For other axis/coordinate combinations, a positive position angle is measured from +x to +y in the absolute world coordinate frame.
The procedures already described for raster and contour displays are appropriate as well for vector displays.
At present, Image tools can only be associated with Float images. You will get an error if you attempt to associate an Image tool with a Complex image disk file. This will be rectified in the future.
For a Float image, you can make a vector map display via the Image tool function Image.view.
include 'image.g'
im := imagefromshape('zz', [64,64]) # Make empty image
im.set(20) # Set to 20 degrees
im.view(vector=T, axislabels=T) # Display
For Complex images (and optionally for Float images) you must use the native Viewer interface as described below. This also gives you more flexibility in combining displays (raster, contour, vector etc).
The procedure via the Viewer tool GUI is easily modified to produce a vector map display. After selecting an image, Image tool or Glish array (Complex or Float), simply select Vector Map where previously you selected Raster Image.
The command-line procedure for creating a raster image display can be modified to create a vector map display by simply replacing the line:
mdd := mv.loaddata('/data/3c273.im', 'raster');
with:
mdd := mv.loaddata('/data/3c273.im', 'vector');
although in this case drawing vectors of the intensity of
3C273 wouldn't be very illuminating ! You might try
im := imagefromshape('zz', [128,128])
im.set(45.0)
im.setbrightnessunit('deg')
im.done()
mdd := mv.loaddata('zz', 'vector')
mdp.register(mdd);
which will make an image with value 45 deg and then display lots of vectors all of the same length aligned in the same direction.
Complex images are not yet fully supported in AIPS++. Most notably, the Image tool cannot open a Complex image which is unfortunate. This will be rectified in a future release.
However, selected functions of the Imagepol tool do write out Complex disk images which can be used as a data source for the vector displays.
These functions are:
A marker map represents pixel intensities by a particular marker shape and fill style. For example, the marker shape may be a square. The size of the square is proportional to the absolute pixel intensity. If the pixel is positive the square is filled, if the pixel intensity is negative, the square is open.
This kind of display is useful for quantities such as the Rotation Measure. The RM may be positive or negative with a distribution that may well be quite discontinuous. Displaying RM images as rasters is not very useful because the strongly negative values (which are equally important as the strongly positive values) will come out dark. Contouring usually fails because of continuity issues. With the marker map display you are biased against seeing small absolute values (square size becomes smaller). So you really have to decide what you are interested in and what display is most useful.
As in the case of a Raster Image, select the image tool in the Tool Name listbox or the image name in the file browser. Now click on Marker Map instead of Raster Image. Register the Viewer DisplayData on the Viewer DisplayPanel as before using the Register... submenu of the DisplayData menu.
Alternatively, for an image already present in Glish as an image tool, (say, im), use the contour option of Image.view on the command line, i.e.
im.view(marker=T);This will register the image for you automatically.
The procedure via the Viewer tool GUI is easily modified to produce a contour map display: simply select Contour Image where previously you selected Raster Image.
The command-line procedure for creating a raster map display can be modified to create a contour map display by simply replacing the line:
mdd := mv.loaddata('/data/3c273.im', 'raster');
with:
mdd := mv.loaddata('/data/3c273.im', 'marker');
The Viewer can be used to plot overlays of sources from catalogs stored in AIPS++ tables, on raster images or contour maps. Note though, that it is only an overlay feature--you MUST have another DisplayData already registered on a Viewer DisplayPanel in order for the catalog sources to be drawn.3.2
| NED | 16 | 19:44:47 | -14:46:51 | NGC6822 | 159.8 |
| NED | 22 | 01:04:46 | +02:07:04 | IC1613 | 328.1 |
The best way to prepare this file for import is to prepend a header with information about what is in the columns. (Note that this is not necessary and the skycatalog tool can automatically determine the column data and name the columns Column1..ColumnN if no header is present.)
So after inserting the header into your file it looks like this:
| Name | No | RA | DEC | NED-ID | mom0 |
| A | A | A | A | A | R |
| NED | 16 | 19:44:47 | -14:46:51 | NGC6822 | 159.8 |
| NED | 22 | 01:04:46 | +02:07:04 | IC1613 | 328.1 |
The first line specifies the names you would like to use to identify the columns. The second line indicates what data type your column holds. Most commonly you'll only need these:
| A | = | ASCII(String) |
| R | = | Real(Float) |
All you need to do now is:
include 'skycatalog.g'
sca := skycatalog('myscat.tbl')
sca.fromascii(asciifile='mydata.txt',hasheader=T, # tell the tool which columns
longcol='RA',latcol='DEC') # are longitude and latitude
sca.browse() # invokes table browser
sca.done()
You can re-access this skycatalog table in the Viewer Data Manager via the table myscat.tbl.
Look at the skycatalog tool in the reference manual for more details on how to use this tool.
As for viewing raster and contour maps, viewing catalog overlays is pretty straightforward, and can be accomplished a number of ways:
mdd := dv.loaddata('myscat.tbl', 'skycatalog');
mdp.register(mdd);
In this example, mdp is an existing Viewer DisplayPanel with a raster or
contour map already registered.
Once you have a sky catalog overlay registered on a Viewer DisplayPanel you can adjust a number of parameters to obtain the desired display.
You could do the same thing from the command line with:
mv := viewer();
mdp := mv.newdisplaypanel();
mdd := mv.loaddata('mydata.ms', 'raster');
mdp.register(mdd);
You should use the filename rather than the variable name of an ms tool. You should also assure that no other Display Data is registered on the Viewer DisplayPanel.
The only type of display currently available is 'raster', which is similar to msplot's 'Display data as an image' mode (or to TVFLG). A plotting-style Display Data for measurement sets is planned for the future.
Usually, the measurement set data is loaded automatically when the Viewer DisplayData is created. Loading data for large measurement sets can take some time. Look at the AIPS++ console window (rather than the logger) to monitor progress.
For very large measurement sets, you must press 'Apply' on the 'Adjust' panel to load the data yourself. This gives you the opportunity to choose something other than Observed Amplitude, for example, before a time-consuming data load.
A complete description of the 'Adjust' panel interface for controlling display and editing of the measurement set can be found at this link.
On the Viewer DisplayPanel, there is a button at the bottom left labelled Adjust.... If you click it, then for each DisplayData that is currently registered on the Viewer DisplayPanel, a window labelled Adjustment (AIPS++) (and prefixed by the name of the DisplayData so that you know which is which) will appear (a little patience is sometimes needed). Each of these adjustment GUIs consists of a series of roll-up windows, which can be exposed or hidden by clicking the text next to the up or down arrow. The options available for adjustment depend on the type of display. The settings common to raster, contour and vector and are described here Each of them have specific settings as well:
At the bottom of the adjustment window, are a couple of buttons with which you can save current settings, and restore previously saved settings. Just type a unique name which you will remember for this DisplayData, and hit save or restore. The new parameters (if they exist) will be installed and the displays updated accordingly. Note: You have to be in the directory you started the viewer in to be able to retrieve the parameters.
In this section, a few fully-worked examples are given which cover quite advanced uses of the viewer. The examples are generally accomplished from the command-line so that you can easily replicate them yourself.
A common operation is to overlay contours of one image on a raster map of another image to show, for example, the HI emission in relation to the starlight in a galaxy. The Viewer tool can easily produce such a display, provided the two images have the same coordinate type, epoch, projection and projection parameters. Yes, that's a long list of requirements, but most of them will be relaxed in the near future. Since there is only one test image available however, in this example we will overlay contours from the test image on a raster map of the very same image. Let's begin by creating the test image and making a DisplayPanel and two DisplayData:
include 'image.g';
im := imagemaketestimage('test.im');
#
mdp := dv.newdisplaypanel();
mdd1 := dv.loaddata(im.name(), 'raster');
mdd2 := dv.loaddata(im.name(), 'contour');
Immediately we can see the overlay by simply registering the two DisplayData on the DisplayPanel. For a single refresh cycle, we wrap the registration between a hold and release pair:
dv.hold(); mdp.register(mdd1); mdp.register(mdd2); dv.release();
There are plenty of ways to improve the display, by adjusting various parameters for the raster and contour maps. This can be done by pressing the Adjust... button on the Viewer DisplayPanel, and modifying the parameters in the GUI. The GUI can also be displayed for each DisplayData by doing:
tmp := mdd1.gui(); tmp := mdd2.gui();
Why don't you do this now and start playing away ?
In this example, we generate a complex data array, and use some special features of the Viewer tool to visualize the data. Let's commence by taking the standard Viewer tool test array data, and Fourier transform it to obtain a complex array:
myrealdata := viewermaketestarray(180); include 'fftserver.g'; mfft := fftserver(); mycxdata := mfft.realtocomplexfft(myrealdata);
At this point, mycxdata is a complex array, storing the Fourier transform of the real array myrealdata. We can immediately view the complex array with the Viewer tool as follows:
mrdp := dv.newdisplaypanel(); mrdd := dv.loaddata(mycxdata, 'raster'); mrdp.register(mrdd);
The image has a rather high dynamic range, so let's ramp up the ``magnifying'' power of the colormap, and zoom in by a factor of three:
mrdd.setoptions([powercycles=-3.0]); mrdp.zoom(3);
Now, the default behavior of the raster map, when provided with complex data, is to shade pixels according to the magnitude of the pixel values. Valid alternatives are the phase, real and imaginary components. Select which you like according to the following examples:
mrdd.setoptions([complexmode='phase']); # display phase mrdd.setoptions([complexmode='real']); # display real component mrdd.setoptions([complexmode='imaginary']); # display imaginary component mrdd.setoptions([complexmode='magnitude']); # back to magnitude display
Make sure you execute at least the last line here, so that at this point you are back viewing the magnitude of the data. Note that if you have the adjustment panel open for this DisplayData as you are making changes from the command line, you will see the adjustment panel update in response to your changes!
Let's get a little more sophisticated. We can actually display two (or even three) components of the complex data at once, using a multi-channel raster map. Such a map has different data being mapped to either the red, green and blue components of each pixel on the screen, or instead the hue, saturation and value components of each pixel on the screen. First we shall avail ourselves of a different type of Viewer DisplayPanel, an RGB DisplayPanel, and make two new DisplayData:
mcxdp := dv.newdisplaypanel(maptype='rgb'); mcxdd1 := dv.loaddata(mycxdata, 'raster'); mcxdd2 := dv.loaddata(mycxdata, 'raster');
Now we will set the mcxdd1 DisplayData to display the real component of the pixels, and place this on the red channel, and set mcxdd2 to display the imaginary component via the green channel:
mcxdd1.setoptions([complexmode='real', colormode='red']); mcxdd2.setoptions([complexmode='imaginary', colormode='green']);
Now we should be able to make a really cool display by registering both these DisplayData on the one Viewer DisplayPanel. We make use of the hold and release functions of the Viewer tool to do this in one refresh cycle:
dv.hold(); mcxdp.register(mcxdd1); mcxdp.register(mcxdd2); dv.release();Again, let's just improve things by spreading out the colors, switching to a smoother resampling mode, and zooming in:
dv.hold(); mcxdd1.setoptions([powercycles=-1.0, resample='bilinear']); mcxdd2.setoptions([powercycles=-1.0, resample='bilinear']); mcxdp.zoom(5); dv.release();
Finally, we can allocate more colors to the red and green channels by taking them away from the blue channel. Find out the current color cube dimensions:
print mcxdp.status().pixelcanvas.colorcubesize;
Chances are the result will look something like [7 6 6] if you are using an 8-bit screen, or [256 256 256] if you are using a TrueColor screen. If the numbers are low, you can rearrange them as follows:
dv.hold() tmp := mcxdp.setoptions([colorcubeblueaxislength=1]); tmp := mcxdp.setoptions([colorcuberedaxislength=12]); tmp := mcxdp.setoptions([colorcubegreenaxislength=12]); dv.release();
If you are on a TrueColor (24bit) screen, you cannot modify the color allocations at this point.
In the final display, you can now see the areas where the real component is dominant (red-dominant pixels), areas where the imaginary component is dominant (green-dominant pixels), and the in-between areas where the real and imaginary components have roughly the same magnitudes (yellow colored pixels).
The Viewer tool also provides a slightly modified Viewer DisplayPanel, the Viewer Slice DisplayPanel. It has most of the functionality of the Viewer DisplayPanel. You might notice that some of the tools in the control box don't appear. These tools will be available soon. In addition the Viewer Slice DisplayPanel provides an extra tool, the Multi panel crosshair. This controls the slicing action. Dragging it over one of the three different displays of the data will control the animation of the other two. The top-left display will show a XY slice, the top-right a ZY and the bottom-left panel a XZ slice of the data. Note that only a Viewer DisplayData with at least three axes and more than one pixel along the third axis will register on the Viewer Slice DisplayPanel. The slices probably will not fill the panels evenly. This is because the ratio of the pair of displayed axes
The button bar at the bottom of the Viewer Slice DisplayPanel shows a Preload... button. It executes an animation loop on each of the slices of data. By doing this, the display caches all views of the data and will improve the speed of the Multi panel crosshair tool. Note: This can take a while for large data cubes, although it is recommended to use this if you chose to have axis labels.
Note: Don't use FITS images on this DisplayPanel. Convert them to native AIPS++ images first. The access of FITS images with re-ordered axes is very slow.
Let's say we have an image called ngc253.fits:
To start the viewer type viewer at your Unix command line.
The displayed might not show a nice contrast. You can use the colormap fiddling tool to adjust this.
Your axis labels might be cut off right now or you think that there is too much space around them. In this case you should go to point 4, otherwise continue skip this.
or print it directly:
That's it you have successfully create a post-script file of your image. You might have noticed all the other options you have in the Adjust panel. Just play around and look what they do.