liminfoSAOImage DS9 Reference
Free reference guide: SAOImage DS9 Reference
About SAOImage DS9 Reference
The SAOImage DS9 Reference is a practical quick-reference guide for astronomers covering 27 essential topics across the DS9 FITS image viewer. It covers basic usage (launching DS9 with FITS files, crosshair mode, image export to PNG/JPEG/TIFF), display controls (Linear/Log/Sqrt/ZScale scaling, colormap selection including Grey/Heat/Cool/Rainbow, zoom/pan with keyboard shortcuts, multi-frame tiling and blink comparison, and RGB 3-color composite creation for narrowband imaging).
The reference provides thorough coverage of the World Coordinate System (WCS) with FK5, ICRS, Galactic, and Ecliptic coordinate systems, sexagesimal and degree formats, coordinate grid overlays, and multi-frame WCS alignment and locking. The regions section covers circle, box, polygon, and annulus region types with their properties (center coordinates, radii, angles), the .reg file text format with DS9/CIAO/SAOtng/FITS output options, and coordinate system specifications (fk5, image, physical).
For data analysis and automation, the reference covers statistical analysis within selected regions (sum, mean, median, standard deviation), radial profile generation for PSF analysis, contour overlays with Gaussian smoothing, pixel value histograms, and image smoothing filters (Gaussian, Boxcar, Tophat kernels). The scripting section includes XPA protocol commands for remote DS9 control, pyds9 Python integration for programmatic operation, 3D FITS cube navigation, VizieR catalog overlays (2MASS, SDSS, Gaia), and SAMP protocol integration with SIMBAD, Aladin, and TOPCAT.
Key Features
- FITS image display controls: Linear/Log/Sqrt/Power scaling with MinMax/ZScale/99.5% limits and manual min/max setting
- Colormap options (Grey, Heat, Cool, Rainbow) with inversion toggle and independent per-channel RGB composite scaling
- WCS coordinate display in FK5, ICRS, Galactic, Ecliptic systems with sexagesimal/degree formats and grid overlays
- Region creation for circle, box, polygon, and annulus shapes with .reg file save/load in DS9/CIAO/FITS formats
- Statistical analysis (sum, mean, median, StdDev, min, max) and radial profile generation for point source PSF analysis
- XPA remote control commands (xpaset/xpaget) and pyds9 Python scripting with numpy array extraction
- Multi-frame management with tile arrangement, blink comparison, WCS frame locking, and 3D FITS cube viewer
- VizieR catalog overlay (2MASS, SDSS, Gaia) with FOV-based automatic queries and SAMP integration for Aladin/TOPCAT
Frequently Asked Questions
How do I open a FITS file in DS9 with specific settings?
Use the command line: "ds9 image.fits -zoom 2 -scale log" to open with 2x zoom and logarithmic scaling. For multiple files side by side, use "ds9 -tile image1.fits image2.fits". For multi-extension FITS, use "ds9 -multiframe multi.fits". All display settings (scale, colormap, zoom) can also be set via command-line flags.
What image scaling options are available?
DS9 offers Linear, Log, Sqrt, Squared, and Power scaling modes accessible via Scale menu. For limits, choose MinMax (full range), ZScale (optimal contrast for astronomical images), or 99.5% clip. Manual min/max values can be set through Scale > Parameters. Command-line example: "ds9 -scale log -scale limits 0 100".
How do I work with WCS coordinates in DS9?
Enable coordinate grids via WCS > Grid. Choose coordinate systems (FK5, ICRS, Galactic, Ecliptic) and display formats (Sexagesimal for RA/Dec, Degrees). The status bar shows real-time RA/Dec at the cursor position. For multi-frame work, use Frame > Lock > WCS to synchronize coordinate systems across frames, and Match > Frame > WCS to align views.
What region types can I create and how do I save them?
DS9 supports circle (center + radius), box (center + width/height + rotation angle), polygon (vertex coordinates), and annulus (center + inner/outer radii for background estimation and aperture photometry). Save via Region > Save Regions as .reg files in DS9, CIAO, SAOtng, or FITS formats. Coordinate systems include fk5 (sky), image (pixel), and physical.
How does the .reg file format work?
The .reg text format starts with a coordinate system declaration (e.g., "fk5"), followed by region definitions: circle(RA,Dec,radius"), box(RA,Dec,width",height",angle), polygon(RA,Dec,...). Prefix with "-" to create exclusion regions (e.g., "-circle(12:30:49,+12:23:28,10")"). Comments use the "#" character.
How can I control DS9 from Python?
Using pyds9: import pyds9, create a connection with d = pyds9.DS9(), then use d.set() for commands like d.set("file image.fits"), d.set("scale log"), d.set("cmap heat"), d.set("zoom 4"). Extract image data as a numpy array with d.get_arr2np(). XPA commands (xpaset/xpaget) provide shell-level remote control for scripting pipelines.
How do I create an RGB composite image?
Go to Frame > RGB to enter RGB mode. Load different FITS files into each channel, for example: Red for H-alpha, Green for OIII, Blue for SII narrowband filters. Each channel can be independently scaled (Linear, Log, etc.) and have separate min/max limits to optimize the color balance of the composite image.
What analysis tools does DS9 provide?
DS9 offers several analysis tools: Statistics (sum, mean, median, StdDev within a selected region), Radial Profile (concentric circle averages for PSF analysis), Contours (overlaid isophotes with Gaussian smoothing and configurable levels), Histogram (pixel value distribution with adjustable bins and log scale), Smooth (Gaussian/Boxcar/Tophat kernel filtering), and Catalog overlay (VizieR queries for 2MASS, SDSS, Gaia sources within the field of view).