AAOGlimpse
Other Links

AAOGlimpse Socket Interface


AAODisp continually listens for connections on a UNIX-domain socket called /tmp/glimpse.socket. It can handle multiple simulataneous connections, and these can be used by other programs to interact with AAOGlimpse. These programs can be written in any language that is able to make calls to a socket library, and such programs can take advantage of the display facilities offered by AAOGlimpse. In particular, the socket interface is how 'plug-out' programs interact with AAOGlimpse.

Simple example


The following trivial. but complete, Python program may give an idea of what can be done:

#!/usr/bin/env python
import socket,string,sys
s=socket.socket(socket.AF_UNIX,socket.SOCK_STREAM)
s.connect("/tmp/glimpse.socket")
commands = string.split(string.join(sys.argv[1:]),',')
for command in commands:
   s.send(string.lstrip(command))
   result = s.recv(256)
   if (result[:2] != "OK"): print command, result

I have this program, named just 'glimpse' in a directory in my path, with its execute bit set. This means that if I type something like this from a command line:

glimpse open /Users/ks/n6770.fits

that Python program will be run, with two command line arguments, one 'open' and the other '/Users/ks/n6770.fits'. The program connects to the AAOGlimpse socket and then sends a string formed by just concatenating all its command arguments to AAOGLimpse (although a comma can be used to delimit multiple sets of arguments). AAOClimpse will read a string containing 'open /Users/ks/n6770.fits' and will respond by opening that file (if it exists) and displaying it. AAOGlimpse will send a single response string, which the Python program reads with the s.recv() call and prints out if it was anything other than the "OK" that indicates that the file existed and was read and displayed without a problem.

So when I type the above command, I should simply see the file displayed. I've used a shell script consisting simply of a succession of such 'glimpse open' commands to run a 'movie' of successive exposures, such as a focus sequence. You can do a lot with just a simple tool. I've used c-shell scripts containing a number of such 'glimpse' commands to implement pre-programmed sequences, particularly for presentations. By putting these in my ~/Glimpse directory, I can run them from the AAOGlimpse 'Plug-outs' menu. More complex programs can be written as Python scripts, or even as C++ programs.

(The program shown above is a slightly extended version of the one originally included in this page. It now allows multiple commands on the one line, separated by commas.)

Protocol


AAOGlimpse accepts commands as nul-terminated ASCII strings, in each case starting with a command name followed if necessary by a space and additional parameters. The parameters, if any, depend on the command. Commands may direct AAOGlimpse to do something, or may make enquiries of it. At the moment, the convention is that all enquiry commands end with a '?' (which unfortunately means they have to be enclosed in quotes if given on a command line using the previous example program, or the '?' needs to be preceded by a '\'). Commands and their parameters (with the exception of file names) are case-insensitive.

AAOGlimpse responds to each enquiry with a single nul-terminated ASCII string. These always start with one of the following:

OK The command executed without problems.
Error: There was an error when executing the command. More details are included, following the 'Error: ' string that starts the response.
A: This is a response to an enquiry. The detailed response follows the 'A: ' string, and depends on the enquiry made.
Q: The request cannot be completed without more details. The rest of the response will be text forming a question that needs an answer. Normally, this would be presented to the user and their response should be sent back to AAOGlimpse. (At the moment, nothing uses this. I  thought a possible example would be an 'open' command that specified a FITS file with multiple images. AAOGlimpse could then ask which image should be opened.)
Message: AAOGLimpse uses this to send text that might be of interest. Normally, the receiving program would output the message and then read the socket again until it gets a terminating response.

Responses starting "OK", "A: " or "Error" terminate AAOGlimpse's responses to a command. (OK, the example Python program should test for these and only quit when it gets one. But the point is that it's actually OK if it doesn't. If it just exits AAOGlimpse will just treat the conversation as closed.)

Commands


At the moment, AAOGlimpse accepts the following commands:

animateTo panX panY panZ aperture theta X Y Z secs Makes AAOGlimpse change the viewing parameters smoothly from the current ones to those specified over a specified time. For demonstrations this generates a much smoother (and reproducible!) animation than can be achieved by hand using the mouse. The pan values are the offset of the view position from the center of the display in surface coordinates (the default AAOGlimpse displays are surfaced in the range -1.0 to +1.0 in all three axes). The aperture is related to the magnification, and theta X Y and Z are an axis-angle orientation specified as for worldRotation. The final parameter is the number of seconds the animation will take. The parameters are almost exactly the same as those displayed when the camera information display is enabled (usually using command-I), except that animateTo has the time in seconds at the end instead of the Z-scale (which - an oversight? - cannot be controlled by animateTo). So the easiest way to determine the parameters to use is to turn the display by hand using the cursor, note the parameters shown when the display looks right, and use those. AAOGlimpse does not send its OK response until the animation completes. The user can terminate the animation prematurely by pressing the enter key.

clipLow option Turns on the low clipping of data - when on, data below the minimum displayed value is completely hidden. This is useful for trying to peer into the structure of 3D data cubes. The option should be either on or off.

copyDataTo2nd Copies the data used for the main display so it becomes the data used for the secondary display.

disable items Disables the display of the various items listed. A number of space separated items can be specified in the one command. Recognised items are axes, surfaces, contours, wires, cameraInfo, highlitBox, highlitCross, highlitEllipse, selectionBox, plotDisplay, and animation. They can be re-enabled using enable.

displayAllData Has the same effect as selecting the 'file' menu option of the same name. The whole range of the current data is displayed.

displayImages list Controls which of the currently loaded images is displayed. List is a space separated set of numbers, with 1 indicating the main image, 2 the secondary. So displayImages 1 will display the main image, displayImages 2 will display the secondary, and displayImages 1 2 will display both. The format allows for support of multiple images, but at present only 1 and 2 are accepted.

displayRange min max Sets the scaled display data range. The data is scaled between the specified minimum and maximum data value.

displaySelectedSubset Has the same effect as selecting the 'file' menu option of the same name. Only the selected subset of the data is displayed.

drawEllipse Xc Yc A B Phi Draws an ellipse at the specified position, centered at Xc,Yc, with A and B the semi-major and semi-minor axes respectively, at at an angle of Phi radians. Xc,Yc,A and B are all in image pixel units (it would be nice to use world coordinates, but that's still to be added.)

enable items Enables the display of the items specified in the list. The items that can be specified are the same as for disable.

invalidateBelow value Invalidates all pixels below the specified data value. Invalid data values are not displayed. The effect is similar to setting the low display value and enabling low clipping, except that the data is actually modified.

invertData Inverts the value of each pixel in the data. New value = 0.0 - old value.

lockColourTable Prevents the colours used from the display from being changed when the display scale is changed. This is mainly useful for JPEG images and is set by default when one is opened. Setting a new colour table overrides the lock.

lut option Sets the colour lookup table used. Regognised options are figaro, skycat, grey, gray, negative and invisible.

newFromSelection Has the same effect as selecting the 'file' menu option of the same name. A new data set is created from the currently selected pixels and is displayed.

open filename Asks AAOGLimpse to open the specified filename. Note that AAOGlimpse doesn't at present have the concept of a default directory - and it almost certainly doesn't have the same default directory as the program sending the command. So the filename should be a complete, absolute filename. The file may be a FITS format file (with an extension of .fits or .fit) or a JPEG file (with an extension of .jpg or .jpeg).

openSecondary filename Is like open, except that the file is opened as the secondary image, allowing it to be compared with the main image, either interactively using the '1','2' or '3' keys or through the displayImages command.

runDemo figure Runs the initial display of a geometrical figure, and provides some control over which figure is used. Possible values for 'figure' are cube or trefoil. The trefoil is the figure usually seen on startup, but a cube can be useful for demonstrating the way the controls work.

scaleFactor factor Sets the Z-axis scaling factor. This has the effect of stretching the display in Z, and is the same effect as is obtained by using the scroll wheel with the shift key held down. Note that this has nothing to do with the scaling of the data as set by, say, displayRange.

selectPixels x1 x2 y1 y2 z1 z2 Has the same effect as selecting the specified range of pixels with the cursor - but makes it much easier to select a precise pixel range. If y1 and y2, or z1 and z2, are omitted, or specified as zero, they are treated as unspecified. The arguments specify integer pixel numbers, and the selection box will enclose the pixel range specified, the numbers being treated as inclusive. Note also that these are pixel numbers (not offsets, like index values in C programs) and they start from 1. The first pixel is pixel number 1. So 'select pixels 1 5 1 10' selects a box of 50 pixels (5 wide in X, 10 wide in Y) starting from the first pixel in the image.

setColour category red green blue Sets the colour used for the specified category to the red, green and blue values specified. The red green and blue values should each be in the range 0.0 to 1.0. The categories recognised are 'background', 'box', 'ellipse', 'stipple', 'plot', 'wires', and 'contours'.

setPercentile percentile Sets the display range to cover the specified percentile of data values. Most images look best displayed at a percentile value in the high 90s. The default for AAOGlimpse is 98.

setZPlanes z1 z2 Sets the first and last of the Z-planes to be displayed. Note also that these are plane numbers (not offsets, like index values in C programs) and they start from 1. (This is subtly different from the effect of the z1,z2 arguments to selectPixels - apart from the fact that those are ignored at the moment! This command immediately affects the display - the data cube is re-displayed with only the specified planes shown - whereas the selectPixels command merely affects the current selection area.)

sigmaFilter cutoff width Passes a sigma rejection filter through the data. This takes two parameters, a cutoffvalue and a width. It runs through each z-plane one by one, looking at each pixel in that plane. For each pixel it imagines a set of boundary pixels around the test pixel. In the simplest case, where Width = 3, the boundary pixels are just the 8 pixels that surround the central pixel. If the pixel value differs from the mean of the boundary pixels by more than Cutoff times the standard deviation of the boundary pixels, the pixel is replaced by the mean of the boundary pixels. By increasing the width, the central pixel is compared with increasingly distant pixels, and this can be used to remove larger features - although the effect is mostly cosmetic, it can get rid of foreground stars in a galaxy image, for example. The 'remove spikes' file menu item is equivalent to sigmaFilter 3.0 3.

subtractFromData value Subtracts the specified data value from each pixel in the currently displayed data.

suppressCameraReset Normally, when a new image is opened, the viewing parameters are reset to a default value. Sometimes this is not what is wanted, particularly when you want to see a new image at exactly the same orientation as the previous one. This command suppresses the reset to default values, just for the next 'open' operation.

waitForKey Asks AAOGlimpse to send its OK response, not immediately, but when the enter/return key is pressed. This can be used in a demonstration script to make the script wait until the user tells it to carry on by pressing the enter key. AAOGLimpse remains active - only the script will wait.

windowSize width height Sets the size of the AAOGlimpse window in screen pixels. Note that this is the overall size of the window, not just the viewing area - it includes the bars at the top and the bottom.

worldRotation theta x y z Sets the orientation of the displayed data using an axis-angle specification, where x y and z define a vector and theta an angle of rotation about that vector. The default orientation used when a file is opened is 180 0 -1 0, that is a rotation of 180 degrees about the Y axis - this is because the OpenGL convention is that the Z axis normally points away from the camera, and this rotation brings the model around to face the viewer. The animateTo command provides a superset of the functions of worldRotation.

write filename Asks AAOGlimpse to write out the currently displayed main data as a FITS file. This is most useful when the current data has been modified since being read in from a FITS file, perhaps using a sigma filter, or when the data originally came from a JPEG file. The FITS conversion used is very basic - almost none but the bare minimum keywords are written, and any coordinate data is lost, so this is most useful for plug-out programs that need to do some simple operation on the displayed data and need it temporarily in FITS format.

dataMatchesFitsFile? Asks AAOGlimpse if there is a FITS file available containing the data currently being displayed. (The response will be "A: Yes" is there is, and "A: No" if the data originally came from a JPEG file, or if the data came from a FITS file but has been modified.) This can be used in a script that checks the answer and uses the write command if necessary to force creation of a suitable FITS file.

filename? Asks AAOGlimpse the name of the file it is currently displaying. It will respond with the full filename in question. If there is no such file - if what is being displayed is the result of a newFromSelection command, for example, then an error respnse is returned. (It seems too complex to try to return the detailed information about the file in question and the subset used in this case.)

selectedPixels? Asks AAOGlimpse to return the 6 numbers giving the currently selected pixel numbers. This should match the selectPixels command - if you give a successful 'selectPixels' command, a subsequent 'selectedPixels?' should return exactly the same set of numbers. Again, these are pixel numbers, starting from 1, and are inclusive. If there is no current selection, the full dimensions of the current image will be returned.

worldRotation? Asks AAOGlimpse for the current world rotation settings, which are returned in a string as "A: Theta X Y Z", where x y and z define a vector and theta an angle of rotation about that vector. See worldRotation for more details.