Tool Interoperability using SAMP

What is SAMP?

SAMP stands for Simple Application Messaging Protocol. It is a protocol which allows tools on the desktop to communicate with each other. Very briefly, the way it works is that applications can send messages to a central hub process which will then pass them on to other applications which can respond to them in some appropriate way. GAIA can use SAMP to send and receive images, sky position information, and catalogues or identification of rows within them. It can also send extracted spectra. You will require a SAMP hub, either free-standing or integral to some other application, to use these capabilities.

Applications which currently talk SAMP include TOPCAT, SPLAT and DS9, amongst others.

You can find more information about how it works, what applications are compatible, and how it can be useful at the SAMP web page, http://www.ivoa.net/samp/.

How do I use GAIA with SAMP?

In order for SAMP communications to work, a SAMP hub must be running on your machine. This is not part of GAIA and you will have to start it up separately. Several other applications include their own hubs, which may be started automatically or by user request; these include the AstroGrid Desktop, TOPCAT and Aladin. Alternatively you can run a freestanding hub such as JSAMP or SAMPy. See the SAMP web page for links to these.

If the hub is running when GAIA starts up, GAIA will connect to it ("register") automatically. If you start the hub while GAIA is already running, you can connect to it by selecting the "Register" option from GAIA's "Interop" menu. When registered, GAIA will listen out for messages from other applications and act on them. You will also be able to send messages to other applications. If you want to stop GAIA responding to any such messages, you can select "Unregister" from the same menu.

In most cases, sending a SAMP message from GAIA is controlled using one of its "Interop" menus. For a given action these often have two ways to transmit a given message: "Broadcast ..." and "Send to ...". For "Broadcast", all registered applications which understand it are invited to do something with the message. For "Send to" there is a submenu which allows you to choose which single application to direct the message to. Only applications which claim to understand the particular message (in the jargon; which subscribe to the relevant MType) will appear on such submenus; this means that the "Send to ..." submenu may be empty, depending on what other SAMP-aware tools you've got running.

What SAMP facilities does GAIA support?

GAIA can both send and respond to messages in three general application areas: image-related, catalogue-related and spectrum-related. The messages and how to use them are listed below; the MTypes (strings in parentheses) are the formal identifiers for these messages - if you are not an applications programmer you can ignore these.

Image-Related Facilities

Load image (image.load.fits): If an image is sent from another SAMP application to GAIA, it will be displayed in GAIA's existing base image window. You can send an image from one of GAIA's windows to one or all of the other registered applications by using the "Broadcast/Send Image" options in the "Interop" menu on the relevant image window.
Highlight Position (coord.pointAt.sky): If a Highlight Position message is received from another application, it will plot a marker (green circle) at the indicated spot on GAIA's base image window, as long as the point falls within the bounds of the currently displayed image.

Catalogue-Related Facilities

Load catalogue (table.load.votable): If a table is received from another application, it will appear as a new catalogue query window associated with GAIA's base image window. Any positions it contains which are within the bounds of the current image will be plotted as symbols over the image as symbols. This window will have an "Interop" menu which can be used for communicating information about one or more selected rows within the table between GAIA and other SAMP applications which have a copy of it.
Highlight Selection(table.select.rowList): If another application sends this message concerning a catalogue which has already been sent over SAMP, the current selection for that catalogue will change, both the rows visible in the query window and the symbols plotted on the image. You can send a selection of points from the catalogue window to other applications displaying the same catalogue using its "Interop" menu: the "Broadcast/Send current search" options send all the visible rows, and "Broadcast/Send current selection" send only the currently selected ones (rows highlighted in blue in the query window).
Highlight Row (table.highlight.row): If the query window's Interop menu has the "Selection broadcasts row index" checkbox ticked, then if you select a single row either by clicking on it in the query window or by clicking on its symbol in the image, this message will be sent to other applications to invite them to highlight that row. Similarly, if other applications send similar messages about this to GAIA, it will respond by highlighting the relevant row and symbol.
Highlight Position (coord.pointAt.sky): If the query window's Interop menu has the "Selection broadcasts row position" checkbox ticked, then the sky position associated with the row will be broadcast to other applications when a single row is selected. They may respond by highlighting that position on their own sky images. Note that unlike the other catalogue-related messages, this may have an effect for applications which don't have the same catalogue loaded.

Spectrum-related Facilities

Send spectrum (spectrum.load.ssa-generic): When you extract a spectrum from a data cube in GAIA, the spectral plot window which appears has an "Interop" menu. You can use this to send a spectrum to SAMP-aware spectral viewing tools.

PLASTIC support

PLASTIC support has been withdrawn from GAIA. Use SAMP instead.