Last modified: 14 April 2020


Accessing the CSC with DS9 and TOPCAT

CSC Threads



This thread provides step-by-step instructions for accessing CSC2 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 CSC2 in VOTable format. CSC2 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. CSC2 data may also be accessed from TOPCAT independently of other applications, as it supports a CSC VO cone search service.

Last Update: 14 Apr 2020 - DS9 screenshot image updated to show the Catalog tool in version 8.1 on a Mac OS X El Capitan (v. 10.11.6)




CSC2 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 AnalysisCatalogsHigh EnergyChandra 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 CSC2 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 CSC2 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 VOCone 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. CSC2 VO cone search service available with TOPCAT

Left: Selecting the Cone Search feature in the TOPCAT VO menu; Middle: 'Chandra Source Catalog' keyword query and NGC4649 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 "Chandra Source Catalog" into the Keyword field in the Cone Search window. Then, simply enter an object name or set of RA and Dec. coordinates by which to search the CSC2, including the desired search radius for the cone search. The resulting table of search results will contain the list of CSC2 sources satisfying the search criteria, along with a select number of source properties from the CSC2.

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.


The video below steps through how to browse the CSC2 starting with the catalog's Worldwide Telescope interface, from there sending L3 stack files and catalogs to DS9 via SAMP, to TOPCAT and then browsing the same data in the CSCview application.

The video may also be downloaded as a QuickTime (611 MB) or MP4 (30 MB) movie file. To view the movie, 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 FileOpen). 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 FileSAMPConnect in DS9.

Load Catalog sources into DS9

At this point you can load into DS9 the CSC2 data specific to the image previously opened. The menu item AnalysisCatalogsHigh EnergyChandra 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 CSC2 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 CSC2 source data from DS9 to TOPCAT, select FileSAMPSendtopcat; 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 CSC2 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 EditCatalog 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
14 Apr 2020 DS9 screenshot image updated to show the Catalog tool in version 8.1 on a Mac OS X El Capitan (v. 10.11.6)