SAOImageDS9

SAOImageDS9 is an astronomical imaging and data visualization application (see the official repository and the official website). This repository is a customized version that supports configurable keyboard shortcuts.

Downloads

You can download the compiled binaries from the v8.7_keyboard Release Page.

• macOS (Apple Silicon): Download SAOImageDS9.8.7.dmg.
  • Built specifically for Apple Silicon and compiled on the latest macOS.
  • This is a native Aqua application (using the macOS native GUI) and does not require XQuartz (unlike the Darwin X11 version).
  • Note: If you encounter "unknown developer" or "damaged application" warnings after installation, run:

    xattr -c /Applications/SAOImageDS9.app

• Other Platforms (including Linux): For other platforms, you will need to compile the application yourself from source using make.

Command Line Usage (macOS Aqua)

Although the macOS Aqua port is a native GUI application, this custom version supports direct command-line execution (including via symbolic links in your $PATH):

1. Create a Symbolic Link: Create a symlink to easily call the Aqua version of DS9 from any terminal session:

   ln -s /Applications/SAOImageDS9.app/Contents/MacOS/ds9 /usr/local/bin/ds9

2. Control Range, Scale, and Regions: You can open images, adjust the scale range, and load region files directly from the command line:

   # Open a FITS file, set scale limits from 80 to 300, and load a region file
   ds9 /path/to/image.fits -scalelimits 80 300 -regions /path/to/targets.reg

Launching DS9 via macOS open

You can launch the first instance of the application using the native macOS open command (which launches the bundle as a standard GUI application):

open -a SAOImageDS9

Or to start the program and immediately open a FITS file:

open -a SAOImageDS9 /path/to/image.fits

Controlling an Already Running Instance (XPA)

To load files into an already running instance of DS9 (without launching a new process), use the XPA (X Public Access) utilities (xpaset and xpaget). Since these tools are embedded directly inside the macOS app bundle, you can link them to your path to use them globally:

1. Create Symbolic Links:

   # Create a symlink to easily run the XPA utilities from anywhere
   sudo ln -sf /Applications/SAOImageDS9.app/Contents/Resources/bin/xpaset /usr/local/bin/xpaset
   sudo ln -sf /Applications/SAOImageDS9.app/Contents/Resources/bin/xpaget /usr/local/bin/xpaget

2. Send Commands using Unix Domain Sockets (local method): To bypass potential macOS hostname lookup and firewall port blockages, prefix the commands with XPA_METHOD=local:

   # 1. Create a new frame in the active DS9 instance
   XPA_METHOD=local xpaset -p ds9 frame new
   
   # 2. Load a FITS file
   XPA_METHOD=local xpaset -p ds9 file /path/to/image.fits
   
   # 3. Adjust scale range limits
   XPA_METHOD=local xpaset -p ds9 scale limits 80 300
   
   # 4. Load the region file
   XPA_METHOD=local xpaset -p ds9 regions file /path/to/targets.reg

Custom Features: Keyboard Shortcuts & None Edit Mode Pan

This custom fork of SAOImageDS9 includes custom features designed to streamline data analysis workflows.

1. Customizable Keyboard Shortcuts

You can map keyboard sequences to predefined actions. Shortcuts support multi-key sequences (e.g., press C then 9 to set 90% scale), as well as standard global keyboard accelerators.

Default Bindings & Accelerators

• Ctrl+Shift+C / Cmd+Shift+C: Reset colormap bias/contrast and default colormap (Color -> Reset Colormap).
• Ctrl+Shift+R / Cmd+Shift+R: Delete all regions from all frames and open a region file (Region -> Delete All and Open).
• L / l: Toggle scale and limits lock across all frames.
• I / i: Toggle frame lock by Image (pixel coordinates).
• W / w: Toggle frame lock by WCS (World Coordinate System).
• C9 / c9: Set the scale limits mode to 90%.
• C1 / c1: Set the manual user limits range from -10 to 10.
• C5 / c5: Set the manual user limits range from -5 to 5.
• C2 / c2: Set the manual user limits range from -20 to 20.
• D / d: Delete the current active frame.
• B / b: Switch display to Blink mode.
• S / s: Switch display to Single mode.
• T / t: Switch display to Tile mode.
• P / p: Switch interaction mode to Pan.
• r (lowercase): Switch interaction mode to Region (Pointer).
• R (uppercase): Open a region file (MarkerLoad).
• N / n: Switch interaction mode to None.

Case Sensitivity

Shortcut key sequences are matched case-sensitively first.

• If you define actions for both lowercase and uppercase versions of a key (e.g., r and R), they will execute separate actions.
• If a shortcut is defined for only one case (e.g., lowercase l), the matching logic falls back to case-insensitive matching if the other case is pressed (so pressing L will trigger the shortcut mapped to l).
• Action names (e.g., lock_scale_limits, reset_colormap, delete_all_regions_load, etc.) are case-sensitive.

How to Configure Custom Shortcuts

You can customize these shortcut mappings by modifying or creating a configuration file named shortcuts.cfg. DS9 searches for this configuration file in the following order:

1. The path specified by the environment variable DS9_SHORTCUTS_CFG.
2. $HOME/.ds9/shortcuts.cfg
3. $HOME/.ds9.shortcuts
4. shortcuts.cfg in the current working directory.

Example shortcuts.cfg format:

# Prefix timeout delay in milliseconds (default is 500)
timeout = 500

# Bind keys to actions
L = lock_scale_limits
I = lock_frame image
W = lock_frame wcs
C9 = scale 90
C1 = range -10 10
r = mode region
R = MarkerLoad
c0 = reset_colormap

2. Enhanced Pan Modes & Drag-to-Pan

Pan Zoom Modes

Under Preferences -> Pan Zoom, you can configure how mouse interaction operates in Pan mode:

• Click to Center & Drag to Pan (Default): Hybrid mode providing both interactions seamlessly. Static clicks (< 3px) instantly center the image at the clicked coordinate, while dragging (≥ 3px) smoothly pans the image in real-time.
• Click to Center: Classic DS9 behavior where clicking recenters the frame; dragging does not pan.
• Drag to Pan: Dragging with the mouse smoothly pans the canvas; static clicks do not displace the image.
• Pan then Zoom: Clicking centers the target and successive clicks cycle through zoom magnification levels ($2\times \to 4\times \to 8\times \to 1\times$).

None Edit Mode Drag-to-Pan

When in None interaction mode (configured via the Edit menu or shortcut N), you can directly click and drag with the left mouse button to smoothly pan the image without needing to change tools.

• Static clicks simply select and focus the active frame without unintended displacement.
• To enable or disable this feature, open Preferences -> Pan Zoom -> None Edit Mode and toggle Drag to Pan (enabled by default).

About SAOImageDS9

SAOImageDS9 is an astronomical imaging and data visualization application. DS9 supports FITS images and binary tables, multiple frame buffers, region manipulation, and many scale algorithms and colormaps. It provides for easy communication with external analysis tasks and is highly configurable and extensible via XPA and SAMP.

DS9 is a stand-alone application. It requires no installation or support files. All versions and platforms support a consistent set of GUI and functional capabilities.

DS9 supports advanced features such as 2-D, 3-D and RGB frame buffers, mosaic images, tiling, blinking, geometric markers, colormap manipulation, scaling, arbitrary zoom, cropping, rotation, pan, and a variety of coordinate systems.

The GUI for DS9 is user configurable. GUI elements such as the coordinate display, panner, magnifier, horizontal and vertical graphs, button bar, and color bar can be configured via menus or the command line.

SAOImageDS9 is fully funded by the Chandra X-ray Science Center (CXC) and is licensed in part under the GNU General Public License, version 3.