Chandra X-Ray Observatory
Skip to the navigation links
Last modified: 11 September 2012


Accessing the CSC with DS9 and TOPCAT

CSC Threads



This thread provides step-by-step instructions for accessing CSC data with the SAOImage DS9 and TOPCAT applications separately, and then sending CSC data from DS9 to TOPCAT via SAMP.

DS9 versions 5.6+ feature the Catalog Tool, which supports catalogs such as the CSC in VOTable format. CSC source positions may be loaded into the tool and overlaid onto an uploaded image in DS9, and all selected source properties may be transmitted to TOPCAT and other compatible applications for data manipulation and visualization. CSC data may also be accessed from TOPCAT independently of other applications, as it supports a CSC VO cone search service.

Last Update: 11 Sep 2012 - DS9 screenshot image updated to show the Catalog tool in version 7.02




CSC source data may be loaded into DS9 via the Catalog Tool in the DS9 Analysis menu, available with versions 5.6 and above. The Catalog Tool can load and save catalog data in VOTable format, and this data can be exchanged with compatible applications via the SAMP (Simple Application Messaging Protocol) application, accessible in the DS9 File menu.

To load CSC data into DS9, simply choose Analysis -> Catalogs -> High Energy -> Chandra Source and enter your source search criteria into the Catalog Tool window which opens (note that the Catalog Tool may also be accessed from the top level of the Analysis menu).

[image of ds9 display with Catalog Tool           open]

Figure 1. The DS9 Catalog Tool loads CSC data in VOTable format and displays source regions on a loaded image.

The DS9 Catalog interface is very flexible and provides many options, such as the ability to adjust the shape and color of source data points on an image, as well as match and plot the common sources in multiple catalogs, such as XMM and Chandra. For detailed information on these features, please visit the SAOImage DS9 website.


If you wish to do more with this feature than view CSC source locations overlaid on a previously loaded image, you can send all loaded catalog data from DS9 to a compatible application such as CSCview or TOPCAT, e.g., to take advantage of the wide range of plotting capabilities for astronomical data offered by the latter. This connection is made possible with the SAMP feature in DS9. SAMP is an application which allows FITS images and catalogs to be exchanged between multiple stand-alone applications which support it.

To learn how to exchange data amongst DS9, CSCview, and TOPCAT, see the CSC thread Sending CSC Data to Remote Clients with CSCview.

In this thread, the SAMP option in the DS9 File menu is used to send CSC data loaded into DS9 to TOPCAT, which is an interactive graphical viewer and editor for tabular data. In doing so, you can interact with DS9 and TOPCAT simultaneously, e.g. you can view TOPCAT scatter plots of any combination of catalog source properties for the sources you have selected in DS9.

[SAMP control window]

Figure 2. SAMP Control window displaying a list of connected applications.


TOPCAT has many capabilities, such as 3-D visualization of data, drawing configurable plots of column-based quantities, with plot types including histogram, 2-D scatter plot, Stacked Line Plot, 3-D Cartesian, 3-D spherical polar, and 2-D density map. For the full list of features, see the TOPCAT website.

[TOPCAT features][TOPCAT features][TOPCAT features]

Figure 3. TOPCAT features

TOPCAT is written in the Java language and requires a suitable version of the Java Runtime Environment to run - see the section "Obtaining TOPCAT" on the TOPCAT website for detailed download instructions, as well has how to check your current Java settings.

The CSC VO cone search service is available with the full application of TOPCAT (as opposed to the 'topcat-lite' installation), via the VO -> Cone Search menu option:

[CSC VO cone search service made available with          TOPCAT] [CSC VO cone search service made available with          TOPCAT] [CSC VO cone search service made available with          TOPCAT]

Figure 4. CSC VO cone search service available with TOPCAT

Left: Selecting the Cone Search feature in the TOPCAT VO menu; Middle: 'CSC' keyword query and M31 cone search in TOPCAT Cone Search window; Right: CSC data table added to TOPCAT Table List; viewing actual CSC data with TOPCAT Table Browser.

To access CSC source data in TOPCAT, enter "CSC" into the Keyword field in the Cone Search window, or the CSC VO cone cearch URL directly into the Cone Search URL field under Cone Search Parameters (note that the "CSC" keyword is only resolved by the registry). Then, simply enter an object name or set of RA and Dec. coordinates by which to search the CSC, including the desired search radius for the cone search. The resulting table of search results will contain the list of CSC sources satisfying the search criteria, along with a select number of source properties from the CSC.

Note that it is also possible to load a list of source positions into TOPCAT and then cross-match this list with one of the available catalogs in TOPCAT. For step-by-step instructions on cross-matching a user-input list of source positions against the CSC, see this CSC FAQ.


Here is a QuickTime movie (57 MB) which steps through an example of loading CSC data into DS9, and then sending that data to TOPCAT for plotting via SAMP; a set of accompanying instructions is provided below. To run the .mov file, please be sure you have the appropriate plug-ins and software installed for your web browser and operating system.


Open DS9 and load an image

The first step is to open DS9 and load an image in the usual way (menu item "File->Open"). Detailed information about the DS9 application can be found on the SAOImage DS9 website, as well as in the CIAO thread "Using SAOImage DS9."

Open TOPCAT and start a SAMP hub

Next, open TOPCAT and click the SAMP Status button ([]) in the TOPCAT GUI to start a SAMP hub. Clicking the Connect/Disconnet icon in the SAMP Control window provides the option to select an internal or external hub. An internal hub runs in the same Java Virtual Machine as TOPCAT itself, and an external hub runs in a separate process. An internal hub will shut down when TOPCAT does, while an external hub will keep running until it is explicitly shut down.

Connect DS9 to SAMP

To enable DS9 to 'talk' to TOPCAT - e.g. to produce a TOPCAT scatter plot of any combination of CSC source properties for a subset of sources selected in DS9 - SAMP must be opened on the DS9 end to act as the go-between. This is done by selecting 'File->SAMP->Connect' in DS9.

Load Catalog sources into DS9

At this point you can load into DS9 the CSC data specific to the image previously opened. The menu item 'Analysis->Catalogs->High Energy->Chandra Source' opens a GUI which allows to search for your source in the catalog by source name or position, as well as specify the size of the region to load. A table of CSC source properties is returned; you can choose "all" to view the positions of all sources on the image.

Send Catalog data to TOPCAT via SAMP

To send CSC source data from DS9 to TOPCAT, select 'File->SAMP->Send->topcat'; the Table List in the TOPCAT GUI will populate with an item indicating the loaded table of source data.

View the data in TOPCAT

You can view the table of CSC source data in TOPCAT by clicking the Table Browser icon, or a scatter plot of any combination of selected source properties by clicking the Scatter Plot icon, among many other options.

To select a source in DS9 and have it simultaneously highlighted in a TOPCAT table or plot, select 'Edit->Catalog' in DS9 and click on a source in the image diplay, or on a row in the DS9 catalog table of source properties.

Send source selections in TOPCAT to DS9

To have your TOPCAT source selections appear in DS9, you must set a TOPCAT 'Activation Action' in the TOPCAT GUI. The Transmit Row item of this feature lists 'Target Applications', including 'SAOImage DS9'; select this option, and then your sources in a TOPCAT plot or table. A selected source appears highlighted and centered in the DS9 image display.


08 May 2009 original version
31 Jul 2009 CSC cone search service now available with TOPCAT
11 Aug 2010 updated for DS9 version 6.1.2
11 Sep 2012 DS9 screenshot image updated to show the Catalog tool in version 7.02

Last modified: 11 September 2012
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email: Smithsonian Institution, Copyright © 1998-2014. All rights reserved.