index : tk.git	adc028c8d0 ajuba_ajuba2_2_1_base_synthetic androwish apn_win_filedialogs bindScriptCount bug_011706ec42 bug_011706ec42_without_busy_wait bug_069c9e43c4 bug_06c1433906 bug_1080198fff bug_1082213fff bug_1096580fff bug_109865fa01 bug_1192095 bug_1217222 bug_1247115fff bug_1288433fff bug_1292219 bug_1292219fff bug_1305128fff bug_1414025 bug_1501749fff bug_1510538fff bug_1520118fff bug_1581435fff bug_1581955fff bug_1630251 bug_1630254 bug_1630262 bug_1630271 bug_1669632fff bug_1700065fff bug_1714535fff bug_1739605fff bug_18c08df753 bug_1913750 bug_1927212fff bug_1997299fff bug_1e0db2400c bug_2049429fff bug_2160206fff bug_220854fff bug_2262543fff bug_2262711fff bug_22ace0d494 bug_2368195fff bug_2433781 bug_2443069 bug_2546087 bug_280089486e bug_280089486e_bis bug_2874226 bug_2886436fff_option1 bug_2886436fff_option2 bug_28a3c366e6 bug_28a4535fa2 bug_28d0b8fb2f bug_2912962fff bug_2945130fff bug_2945130fff_shift bug_297442da29 bug_2981253fff bug_2a70627a03 bug_2cf3d6942c bug_2cf3d6942c_mistake bug_2f78c7c5ea bug_3021557 bug_3062331 bug_308940fff bug_3102228fff bug_3137232fff bug_3216070 bug_3217462 bug_3295446 bug_3404541 bug_3406785 bug_3410609 bug_3417012fff bug_3475627 bug_3486474 bug_3508771 bug_3511806 bug_3512539fff bug_3512824 bug_3529885fff bug_3545457 bug_3554052fff bug_3554273 bug_3555644 bug_3566106 bug_3567779 bug_3567786 bug_3582795 bug_3585396 bug_3588460fff bug_3588824 bug_3592454fff bug_3592736 bug_3599312 bug_3600390 bug_3601604fff bug_3602901fff bug_3604346 bug_3607248 bug_3607250 bug_3607830 bug_3608074 bug_3613668 bug_3613759 bug_382da038c9 bug_38dc27bd1d0ecd68 bug_3df559ef7c bug_3e3e25f483 bug_3ee76e41c2 bug_3f1f79abcf bug_3f323bf2b4 bug_434d294df bug_450bb0ecad bug_453518fff bug_487861ffff bug_4955f5d8a4 bug_4966cad4d4 bug_4cb3dab4eb bug_514ff64dd0 bug_5239fd749b bug_533519 bug_533519_alt bug_542199fff bug_545f10fcf3 bug_55b95f578a bug_562118ce41 bug_5660d11c3f bug_62c5b7a1d7 bug_62f1343ad2 bug_6976e4b3b2 bug_6aea69fccb bug_720879afe9 bug_720879afe9_alt bug_73ba07efcd bug_7703f947aa bug_77527326e5 bug_793909fff bug_79549a9134 bug_7a838c38a1 bug_7c7e8f957e bug_7d967c68 bug_810c43d789 bug_8277e1a906 bug_841280ffff bug_857686bb3d bug_89a638af38 bug_8c4216dca9 bug_92e028b41b bug_960391ffff bug_99b84e49ff_8_5 bug_99b84e49ff_trunk bug_9e487e9f15 bug_9fcc519a7c bug_a2abc45ee6 bug_a5ba1c9764 bug_adc028c8d0 bug_ae32eb7e10 bug_b362182e45 bug_b601ce3ab1 bug_bb6b4032d2 bug_bc43fd20cf bug_c0dbdd3ff3 bug_c12af74765 bug_c199ef90a6 bug_c24b97d905 bug_c492c96aa2 bug_c95d4691ff bug_c95d4691ff_mistake bug_cbab0f88d7 bug_d0c55bd78a bug_d4fb4e80d2 bug_d4fb4e80d2_alt bug_d6b95ce4 bug_d6b95ce492_alt bug_d6fd19e4e5 bug_d7bad57c43 bug_d95e5d8f16 bug_d9fdfa435d bug_dac92f194c bug_dd9667635d bug_de156e9efe bug_e36963bfe8 bug_e4336bef5d bug_e4ed00a954 bug_e8a111970a bug_e9112ef96e bug_eb26817783 bug_ed22529c92 bug_ee40fd1fce bug_f0188aca9e bug_f1a3ca09d2 bug_f214b8 bug_f214b8ad5b bug_f2655bb0ec bug_f60c54bec6 bug_fa32290898 bug_fab5fed65e bug_fd3a4dc111 bug_ff8a1e55a2 cocoa_full_merge_review_8_5 contrib_patrick_fradin_code_cleanup core_8_0_2_synthetic core_8_0_5_branch core_8_0_6_branch core_8_1_0_branch core_8_1_0_synthetic core_8_1_a2_synthetic core_8_1_b1_synthetic core_8_1_b2_synthetic core_8_1_b3_synthetic core_8_1_branch_old core_8_2_1_branch core_8_2_b3_branch core_8_3_1_branch core_8_4_20_rc core_8_4_9_branch core_8_4_branch core_8_4_win_speedup core_8_5_10_rc core_8_5_11_rc core_8_5_12_rc core_8_5_13_rc core_8_5_14rc core_8_5_15_rc core_8_5_16_rc core_8_5_17_rc core_8_5_18_rc core_8_5_19_rc core_8_5_a5_synthetic core_8_5_branch core_8_6_0_rc core_8_6_1_rc core_8_6_2_rc core_8_6_3_rc core_8_6_4_rc core_8_6_5_rc core_8_6_6_rc core_8_6_7_rc core_8_6_b2_rc core_8_6_b3_rc core_8_6_branch core_8_7_a1_rc core_stabilizer_branch core_stabilizer_merge_synthetic core_zip_vfs dev_8_1_stubs_branch dev_stubs_branch dgp_Tcl_requirement dgp_backportcocoaforget dgp_modernize_init dgp_privates_into_namespace dgp_review dgp_support_tcl_8_6_build editorconfig finddline frq_3536507 frq_3555324 hitheme initsubsystems2 irontcl jn_cocoa_full_merge_8_5 jn_web_colors little macosx_8_4_branch macosx_button_segfault master mistachkin_dev_branch mistake mistake__off_trunk multiscreens multiscreens_exp1 new_icons novem_support novem_support_85 option_readfile patch_3471873 patch_3479498 pspjuth_canvas pspjuth_touch revised_text revised_text_ober rfe_22ace0d494 rfe_2636558 rfe_2863003fff rfe_3503317 rfe_38dc27bd rfe_3f456a5bb9 rfe_499526180d rfe_6c0d7aec67 rfe_e9a842a3c5 scriptics_sc_1_0_branch scriptics_sc_1_1_branch scriptics_tclpro_1_3_b2_branch scrollbar_obj_cmd send_obj_cmd tagoptions tclpro_1_4_0_synthetic tclpro_1_4_1_synthetic tclpro_1_5_0_synthetic text_elided tip_166 tip_382 tip_389 tip_415 tip_437 tip_438 tip_438_bettercode tip_438_events tip_441 tip_442 tip_443 tip_446 tip_446_canundo tip_446_experimental tip_446_undodepth tip_449 tip_454 tip_464 tk_cocoa_8_5_backport tk_errorcodes tk_stu_pkg tobetested ttk_range_widget vc_reform win32_arm winFixes z_modifier
	Tk is a free and open-source, cross-platform widget toolkit that provides a library of basic elements of GUI widgets for building a graphical user interface (GUI) in many programming languages.

summaryrefslogtreecommitdiffstats

log msg author committer range

path: root/generic/tkScale.c

	Commit message (Expand)	Author	Age	Files	Lines
*	Replaced SCCS strings, fixed binary files	stanton	1998-09-14	1	-1/+1
*	Initial revision	rjohnson	1998-04-01	1	-0/+1143

generated by cgit v0.12 at 2024-10-06 14:28:41 (GMT)

SAOImage DS9 Acknowledgment

+

SAOImage DS9 development has been made possible by funding from + the Chandra X-ray Science Center (CXC) (NAS8-03060) and the High + Energy Astrophysics Science Archive Center (HEASARC) (NCC5-568). + Additional funding was provided by the JWST Mission office at + Space Telescope Science Institute (NAS-03127) to improve + capabilities for 3-D data visualization.
+

+

If you have found SAOImage DS9 to be helpful in your research, + the following acknowledgment would be appreciated

+

+

+

"This research has made use of SAOImage DS9, developed by + Smithsonian Astrophysical Observatory"

+

+

or reference the following paper2003adass..12..489J

+

SAOImage DS9 FAQ

+

This FAQ is a new, on going project, and it is far from being + complete. But as common questions on DS9 are received, the FAQ + will be updated.

+

Contents

+

Copyright
+ General
+ Fonts
+ Linux
+ Windows
+ MacOSX
+ X11
+ IRAF
+ Coordinates
+ Regions
+ Printing
+ XPA
+ VO
+

+

+

Copyright

+

+

SAOImage DS9 is composed of approximately 20 open source + packages, all of which are distributed under their own open + source license agreements, usually GPL, LGPL, or BSD. In + addition, several open source packages have been developed + here at the Smithsonian Astrophysical Observatory, Cambridge, + MA, USA and are distributed under the terms of the GNU General + Public License as published by the Free Software Foundation. + As long as you continue to adhere to the provisions of the + licenses, you are free to distribute SAOImage DS9 along with + your software.

+

The GNU site + contains an excellent FAQ on the the dos and donts of GPL.

+

+

General

+

+

The web browser, catalog tool, image server, and other + Analysis functions don't appear to work. Whats going on?
+

+

For a number of the Analysis functions, DS9 requires + temporary disk space to download and store data. By default, + this directory is defined by the TMP or TEMP environment + variable. This is usually defined as /tmp for Linux + and MacOSX users. For Windows users, this will vary, depending + on which version of Windows you have. In any case, if the temp + directory is not writable, or you have specified an invalid + directory in the preferences, these functions will fail with a + variety of error messages.
+

+

My system admin stripped the DS9 binary and now DS9 fails + to start with the following error message:

+

Application initialization failed: Can't find a usable + tk.tcl in the following directories...

+

DS9 is based on tcl/tk which is a scripting language which + requires many support files. To create a stand alone + application, we fool tcl/tk into thinking that it has + a valid installation. To do this, DS9 is really an + application, along with an zip archive attached. The first + thing DS9 does is to create a virtual file system in memory + and unpack that archive into memory. The application DS9 is + already stripped of debugging symbols when built.

+

It appears that the strip command is stripping + part of the archive, hence DS9 is unable to un-compress it. In + summary, don't strip the DS9 binary and everything + works fine.

+

When I open my FITS image, all I see is 'white'. Yet + everything, including the color bar seems to work?

+

New with version 2.1, is support for the DATASEC keyword. + This keyword specifies what portion of the image is valid + data, for calculating min / max and for displaying. This is + very important for images created from CCDs with over scan and + bias strips. By default, this support is enabled. However, a + number of fits images with this keyword, have invalid values. + Therefor, when DS9 opens the image, it finds no valid data to + display. To correct this problem, either disable DATASEC + support, via the Scale menu, or correct the the value of + DATASEC in the fits header. You can also change the default + behavior by disabling DATASEC from the preferences menu.
+

+

+

Fonts

+

+

Where is the Symbol Font? How do I enter special + characters into an entry dialog?

+

The concept of a separate SYMBOL font is no longer + implemented with the latest OS font and scripting support, + especially with scalable anti-alias fonts such as Xft for + Linux. Most newer fonts (if not all) now have greek characters + as part of the font. The greek chars start at unicode \u0391 + for 'A' and \u03b1 for 'a'. Each OS has a tool used to build + and copy a string of characters. Then use the Edit:Paste menu + of DS9 to insert the character string.

+

Linux- Gnome: gucharmap
+ Linux- KDE: kcharselect
+ MacOSX: Character Viewer (Select Edit:Special + Characters) Now click and drag the characters to a + terminal window. Then select the string and select Edit:Copy.
+ Windows: Character Map (from Start button, + select All Programs, Accessories, System + + + + + Tools and then Character Map)
+

+

+

Linux

+

+

My /tmp directory is mounted -noexec and bin table + filtering does not work.

+

Set the environment variable FILTER_TMPDIR to a directory + that is both writable and can execute.
+

+

I have Red Hat 7, and I'm running KDE. The magnifier keeps + going blank after a few seconds, what's going on?

+

The problem was in KDE. If the user has decided to hide the + panel taskbar and  sets a delay time for when it appears + if the mouse is moved to the panel  location, then it + appears that KDE creates mouse events that fool DS9 into  + thinking the mouse is outside and it blanks the magnifier. By + turning off the  hide panel, the effect goes away. The + alternative is to update to KDE2.1Beta  where this method + of dealing with the hidden panel is not used and all is  + well, as it was for KDE

+

I have FreeBSD. When I run ds9, I get the following error: +   ELF binary type "0" not known Whats + + + + + + going on?

+

The solution was to use the brandelf utility + on the file to ensure that the machine understood that it +  was a Linux program.

+

% brandelf -t Linux (file name)
+

+

+

+

Windows

+

+

When I do Save Image, I get the same result (and this is + true for either .gif, .jpeg, .tiff, .png and .ppm) : it + saves only a stripe at the top of my image.
+

+

This problem seems to be caused by running DS9 in Windows XP + compatibility mode. Please un-check the compatibility option + in the properties dialog.
+

+

How can I open a FITS file with an extension name?

+

By default, the windows port of DS9 uses the Windows + standard dialog box to open and save files. This can be a + problem in that the native Windows dialog will not allow + extensions to the file name, such as foo.fits[2]. + You must use the Unix like standard dialogs to be able to + specify an extension. Select Edit->Preferences->General:Dialogbox + to change the default standard dialog.

+

Every time I create an auxiliary window in ds9, such as a + Pixel Table, or Analysis Plot, it will retreat behind the + main ds9 window. Then, when I bring the auxiliary window to + the front and move the mouse out of it, it automatically + goes behind the main ds9 window again. What can I do to fix + things so that the auxiliary window stays on top of the ds9 + window?

+

To fix things so that the auxiliary window stays on top of + the ds9 window, do the following:

+

+

Go to the icon task bar at the bottom of the screen. + Bring the auxiliary window to the front by clicking on its + icon in the icon task bar. While the mouse still + is on the aux window icon, press the mouse button, and + keeping it pressed, move the mouse off the task bar. + Release the mouse while off the task bar. The + auxiliary window will now stay on top of the main ds9 + window.

+

+

+

+

MacOSX
+

+

+

I can't invoke the 'Save Image' function from the MacOSX + X11 version. I get an error message "An error has occurred + while creating the image. Please make sure entire image is + visible on screen."
+

+ Up until MacOSX 10.8 (Mountain Lion), Apple provided their own + version of a X11 server. At first, it was based on XFree86 + (X11R6.6) and available with versions up to MacOSX 10.4. Later + with MacOSX versions 10.5 to 10.7, the Apple's X11 server was + based upon X.org (X11R7.2).
+
+ The Apple version of X11 server for MacOSX 10.5 to 10.7 contains + a bug which fails if you invoke certain X11 calls on a window if + its location is not at 0,0 on the screen. Hence, within DS9, if + you 'Save Image' and your window is not exactly in the upper + left corner, it will fail.
+
+ Again, this only affects users of MacOSX 10.5 to 10.7.
+
+ Starting with MacOSX 10.8, Apple no longer provides a X11 window + server. The user must go to the XQuartz site and + download/install directly. The current version is 2.7.3.
+

When I invoke DS9 MacOSX Aqua from the command line, I get + weird errors such as:

+

+

The document "foo.fits" could not be opened. SAOImage + DS9 cannot open files in the "Flexible Image Transport + System" format.

+

+

When opening MacOSX Aqua from the command + line, it is better to use the OPEN application as + opposed to specifying the binary directly. The OPEN + application sets up the environment just as it is when a user + double clicks.

+ # good
+ % open /Applications/SAOImage\ DS9.app foo.fits
+
+ # bad
+ % /Applications/SAOImage\ DS9.app/Contents/MacOS/ds9 bar.fits
+

How can I open a FITS file with an extension name?

+

By default, DS9 MacOSX Aqua uses the MacOSX standard + dialog box to open and save files. This can be a problem in + that the native MacOSX dialog will not allow extensions to the + file name, such as foo.fits[2]. You must use the + Unix like standard dialogs to be able to specify an extension. + Select Edit->Preferences->General to change + the default standard dialog.

+

How do I set my PATH environment variable under MacOSX for + use with external analysis programs, such as funtools?
+

+

When you double click on a MacOSX application, it does not + parse any shell startup files, such as ~/.profile. Instead, + the environment is defined using a special environment file, .MacOSX/environment.plist. + This file can be created with the MacOSX utility /Developer/Applications/PropertyListEditor.app. + + + + + For further information, please click here.
+

+

+

+

X11
+

+

+

Is it possible to work in batch mode without a physical + display?
+

+

DS9 is written as an interactive, window client program, and + as a result, does require a window server to be available for + rendering (X11, Windows, or MacOSX).
+
+ Therefore, using DS9 as a batch process can be cumbersome. We + recommend using xvfb under X11. Just set up a + virtual display buffer, reset your DISPLAY variable, then + invoke DS9 with a number of command line options or use xpa + from a shell script as a batch processor. Example:
+

+

% export DISPLAY=:1
+ % Xvfb :1 -screen 0 1024x768x16 &
+ % ds9 -file cmap.fits -zoom to fit -cmap b -grid + skyformat degrees -grid yes -regions ../EMS-names.reg + -saveimage png mytest.png -exit
+

+

When I start DS9, I get the following error message:

+ _X11TransSocketINETConnect: Can't get address for + foo.bar.edu
+ couldn't connect to display "foo.bar.edu:0.0"  
+

DS9 is unable to determine a valid X11 Display server, + because of a number of reasons. Most often this is seen when + you have a laptop configured for a network, but is not + physically connected. You need to set the DISPLAY environment + variable to :0.0

+

$ xhost +
+ $ set DISPLAY=:0.0
+ $ export DISPLAY
+

+

Under Solaris, when I start DS9, my twm window manager + crashes!

+

TWM distributed with X11R5 had a major bug, that was + corrected around 1996. DS9 will trigger this bug, and will + cause TWM to crash. If you are running Solaris, and have X11R5 + installed, be sure that /usr/openwin/bin is in your path + before X11R5/bin. This will insure that you are running the + correct version of TWM .

+

When I run ds9 with the tvtwm window manager, sometimes + the open file dialog box does not appear?

+

If you are running tvtwm, and you are currently viewing a + virtual screen other than the first, when you open a file, the + dialog box will appear in the first virtual screen, not your + current. This is a bug with tvtwm and not ds9.

+

+

+

+

+

+

IRAF

+

+

+

+

+

+

I can't use more than 9 frames with the IMEXAMINE task?
+

+

The task IMEXAMINE can not be used with frame + numbers greater than 9.

+

Can I display from IRAF to DS9 running under Windows or + MacOSX?

+

Yes, DS9 for Windows and MacOSX is also a fully functional + IRAF display server. To direct image output from IRAF to DS9 + running under Windows or MacOSX, use the IMTDEV environment + variable. For example, if the machine is named 'foo.bar.edu', + define IMTDEV to the follow value before entering IRAF.

+

$ setenv IMTDEV inet:5137:foo.bar.edu
+ $ cl
+ cl> display dev$pix
+

+

+

+

+

I'm having problems with mscred task msczero?

+ DS9 now supports IRAF's new IIS image display protocol. However, + there is one minor problem with the mscred task msczero. + Before using msczero, issue the following command in the + cl:
+
+ cl> set disable_wcs_maps=""
+ cl> flpr
+

I find that there is a frustrating delay in performing + operations on images displayed from IRAF - there's a wait of + a second or two before an image is (re)displayed, whereas saoimage + reacts virtually instantly for the same type of operation. + This makes running imexamine on a batch of images a pain, + and using the mouse to change color gamma/bias to desired + values basically impossible.

+

DS9 and saoimage are similar in speed when working + with IRAF. In fact, DS9 uses  the same code to interface + with IRAF as saoimage and ximtool. The only  difference + is that DS9 is double buffered, whereas, saoimage and + ximtool only  use a single buffer. So with saoimage + and ximtool, you see incremental progress,  where + DS9 will render the image all at one time. However, the + overall time to  finish rendering should almost be the + same.

+

DS9 runs in both 8 bit and 24 bit environments, but saoimage + is restricted to 8 bit. If you are running DS9 and saoimage + at the same time, then you must be in 8 bit mode. You should + not see any  delay in changing the color bias/contrast + between the two.

+

However, if you are running DS9 in 24 bit mode, then you will + see slower  performance in changing the bias/contrast, as + compared to 8 bit mode. Instead of  changing a color look + up table, as in 8 bit mode, DS9 has to update every + pixel  on the screen. If your cpu speed is slow, you can + select the  Edit:Preferences:True Colorbar to tell DS9 + not to update the entire screen,  only a part of the + screen. This should only be needed if your machine is + slower  than 200 MHz. Again saoimage does not + even run in 24 bit mode, so there are no  comparisons.

+

I try to display an image from IRAF and I get the + following error message:

+

Cannot open device (node!imtool,,512,512)

+

+

DS9 works the same way as ximtool, saoimage, + and saotng. No special scripts  should be + needed. If you have one of the above currently working, DS9 + should  work out of the box.

+

IRAF can use one of three methods to communicate with DS9: + fifo, socket, and unix  domain name. The DS9 defaults + are:

+

fifo /dev/imt1
+ port 5137
+ unix /tmp/.IMT%d

+

If your IRAF configuration is set up different (i.e., a + different port number, or  via a fifo), you need to tell + DS9 how to communicate with iraf. DS9 uses the same  + command line options as XIMTOOL:

+

-fifo
+ -fifo_only
+ -inet_only
+ -port
+ -port_only
+ -unix
+ -unix_only

+

+

+

+

I try to display an image, I see something, but it's + corrupted and I get multiple error messages from DS9...

+

An IRAF image server (ximtool, saoimage, + DS9, etc...) uses a configuration file  to specify the + number of available buffers and their sizes. What actually + passes  from IRAF is not the buffer size, but an index + number into this file.

+

So when an image server starts (DS9), it will attempt to + locate this file as  $HOME/.imtoolrc and + /usr/local/lib/imtoolrc. If not found, it will look for + shell  environment variables IMTOOLRC and imtoolrc, that + contains the name of the configuration file.

+

If no configuration file is found, DS9 will assume the + following default configuration:

+

 1  2  512  512  # + imt1|imt512
+  2  2  800  800  # imt2|imt800
+  3  2 1024 1024  # imt3|imt1024
+  4  1 1600 1600  # imt4|imt1600
+  5  1 2048 2048  # imt5|imt2048
+  6  1 4096 4096  # imt6|imt4096
+  7  1 8192 8192  # imt7|imt8192
+  8  1 1024 4096  # imt8|imt1x4
+  9  2 1144  880  # imt9|imtfs full + screen (1152x900 minus frame)
+ 10  2 1144  764  # imt10|imtfs35 full + screen at 35mm film aspect ratio
+ 11  2  128  128  # imt11|imt128
+ 12  2  256  256  # imt12|imt256
+ 13  2  128 1056  # imt13|imttall128 tall + & narrow for spectro.
+ 14  2  256 1056  # imt14|imttall256 tall + & wider for spectro.
+ 15  2 1056  128  # imt15|imtwide128 wide + & thin for spectro.
+ 16  2 1056  256  # imt16|imtwide256 wide + & fatter for spectro.
+ 17  2 1008  648  # imt17|imtssy Solitaire + fmt w/ imtool border
+ 18  2 1024  680  # imt18|imtssn Solitaire + fmt w/out imtool border
+ 19  1 4096 1024  # imt19|imt4x1
+

+

If on the other hand, IRAF assumes a different buffer size, + the image will appear corrupted and DS9 may issue a number of + error messages.

+

Another problem is that this file must be in sync with + dev$graphcap. If your  system administrator has made + changes to graphcap, they must also be implemented in + imtoolrc.

+

Here is a note from NOAO:

+

+

The messages means that there is no + /usr/local/lib/imtoolrc file on the machine. + This is created as a symlink to dev$imtoolrc by the iraf + + + + + install script but only if the /usr/local/lib dir already + exists on the machine. The fix is the create the + dir and rerun the install script or else make + the link by hand.  Users can also just copy + dev$imtoolrc to $HOME/.imtoolrc and restart the + server to also workaround it. Note that an + existing .imtoolrc might define old frame buffer configs + which might confuse things, so if the system + file exists check for a private copy screwing + things up.

+

+

+

+

+

Where do I find this .imtoolrc file?

+

Again, here a note from NOAO concerning this issue:

+

+

In a smooth installation the imtoolrc file is installed + as a /usr/local/lib/imtoolrc symlink pointing to + the dev$imtoolrc file in the iraf system.  + This is normally what's used but XImtool (and DS9?) also allow + + + + + a $HOME/.imtoolrc and IMTOOLRC environment variable + defining the path as fallbacks.  There are + several practical problems with  this:  for some + + + + + reason (I'm trying to fix) the imtoolrc link won't be + created if the /usr/local/lib directory doesn't + exist when the install script is run on the + machine, even though it's run as root and the file can be + directory easily.  On PC-IRAF systems there is + also a typo in the install script (extra logical + or at line 515) which causes it to exit before the + + + + + display setup is run (i.e. no /dev fifos or imtoolrc). If + users don't catch this or see it in the README + file they'll think everything went fine. Lastly, + the local iraf admin might not have run the install script + on the local iraf NFS client machine at all.

+

+

+

+

+

When I display an image from IRAF, the SCALE menu option + is not active, Why?

+

When you display an image from IRAF into DS9, IRAF actually + does the color scale  distribution. In Display, use the + ztrans and z1,z2 parameters to set the upper/lower bounds and + distribution. You can also use the zscale parameter to auto + determine z1,z2.Here are the DISPLAY parameters in question:

+

ztrans=[linear|log|none|user]
+ z1=min
+ z2=max
+ zscale=[yes|no]

+

What actually is sent from IRAF to DS9 is one byte per pixel, + values 0-200,  which already has applied both the upper + and lower clipping bounds and the distribution. So this is + why, the SCALE menu is disabled in DS9 when it receives a + image from IRAF.

+

+

+

Coordinates

+

+

+

Why don't I see PHYSICAL/WCS/WCSA...WCSZ coordinates + displayed when I load my image?

+

DS9 supports the following coordinate systems:

+

WCS Sky coords (fk4,fk5,icrs,galactic,ecliptic) +
+ WCS Linear coords
+ Image (also known as Logical)
+ Physical (also known as CCD)
+ Detector
+ Amplifier  
+

+

DS9 uses the following FITS keywords in the header to define + a coordinate system:  

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Coordinate System	Keyword Values
WCS / WCSA...WCSZ	CRVAL,CRPIX,CRDELT,CD... (for images) + TCRVL,TCRPX,TCDLT,... (for tables)
Image	none required
Physical	WCSNAMEP='PHYSICAL' or LTMx_x/LTVx
Detector +	DTMx_x/DTVx +
Amplifier +	ATMx_x/ATVx +

+ +

+

If the required keywords are not present, values for those + coordinates are not displayed.

+

Note: For PHYSICAL, DS9 will first look for an alternative + WCS with WCSNAMEx='PHYSICAL'. If not found, DS9 will then look + for the LTMx_x LTVx keywords.

+

+

+

Regions

+

+

How do I indicate distance on my printed images?  +

+

You have two choices, the RULER region and the LINE region. + The ruler region is mainly used for interactive measurements. + For printed output, use the LINE region to create a distance + indicator. In the line region dialog, there is a read-only + entry that indicates the length in pixels, degrees, arcmin, or + arcsec. Edit to the desired distance and enter the desired + label, including ' or ", in the region text labile entry. You + have the option of arrows at each end of the line.

+

+

+

Printing

+

+

I can make some wonderful color images in DS9 and save + them as postscript files that look great, but often when I + print them they appear washed out or very different than + they do on the screen. My question then is what, if + anything, can I do about this?

+

The problem is that you create an image on a display, which + is the product of  RGB colors (red, green, and blue) and + print the image on a printer, which is the  product of + CMYK colors (cyan, yellow, magenta, and black). Furthermore, + every  monitor is different in how it will display a + certain color, and every printing  technology is + different in how well it will reproduce that color. And + finally,  the translation between RGB and CMYK is not + symmetric, i.e. its not possible to  translate some + colors back and forth.

+

It's possible to calibrate your monitor and your printer, to + create a  translation matrix, to correct for problems + outlined above (in the Macintosh  world, this is what + ColorSync does). The idea is to apply a gamma + correction to the output of DS9, so  that it will print + much more in line with what you expect. To do this you'd + need  special software and hardware, and its only valid + for your monitor and your  printer.

+

In summary, its not worth it. Especially in the case of + publication, such as ApJ,  where you have no idea on what + printing technology will be used to reproduce  your + image. So the only control you have is to calibrate your + monitor and to  hope for the best.

+

However, there are some rules of thumb that might + help. First, printers have a very hard time with blues + and purples, as they tend to be washed out. Either + avoid these colors, or over compensate these colors. 

+

ApJ has a good idea in that you send in both an electronic + version and a hard copy of your color image. That way, they + can manually adjust the printers to  try to match your + output.

+

NOTE: Even though ApJ requests images in CMYK, we + recommend RGB. From personal experience, if you send RGB, + the printed results will be closer to the original.

+

We used DS9 to generate 300 dpi CMYK eps figures, as per + the ApJ specifications, but the color scheme on  our + proofs is wrong.  In the proofs, the violet is washed + out and looks similar to the black, and the blue is not + nearly as intense.

+

There are two issues here: first,  color + printers are notorious for failure to reproduce blues and + purples correctly. Second,  not all colors in RGB space + can be reproduced correctly in CMYK space, blues being the + prime example. Below is an excerpt from an industry pamphlet:

+

+

Be aware that it is possible to see colors in RGB that + you can't make with CMYK. They are said to be "out of the + CMYK color gamut". What happens is that the RGB-to-CMYK + translator just gets as close as possible to the + appearance of the original and that's as good as it can + be. It's something that everyone in the industry puts up + with. So it's best to select any colors you use for fonts + or other design elements in your layout using CMYK + definitions instead of RGB. That way, you will have a + better idea of how they will appear in your printed piece. + Here's a common example: many programs translate the 100% + Blue in RGB into a somewhat purple-looking color in CMYK. + We recommend a CMYK value of 100-65-0-0 to get a nice + clean blue.
+

+

+

For this reason, you may wish to use the RGB color space or + colormaps without deep blues and purples, such as BB + or Heat.

+

+

+

XPA

+

+

How can I use XPA to display from a client machine to DS9 + on a server machine?
+

+

Assuming you have direct IP reachability between the machines + (i.e. one host can successfully connect() to the other), XPA + does allow you to have an XPA-enabled server like DS9 on one + machine and a client on another. To make this work, you need + to do two things (let's assume DS9 is running on a machine + called "server_host" and you want to send xpa commands from + "client_host"):
+

+

+
1. The XPA server program (i.e. DS9) must allow the client + host to send XPA commands. Access can be permitted in one of + two ways:
   +
   +
   1. Send the XPA server an acl request by running xpaset + on the same host on which the server is running (i.e. on + the server_host):
      +
      + % xpaset -p ds9 + -acl client_host +
      +
      +
   +
   2. For more permanent access, add permissions in + ~acls.xpa:
      +
      + % cat > + ~/acls.xpa
      + DS9:ds9 + client_host +
      +
      + You can check the acls for an XPA server using xpaget:
      +
      + % xpaget ds9 -acl
      +
      +
   +
   +
+
2. On the client side, the client needs to communicate with + the xpansname server program on the server machine to find + the XPA server communication info. This also can be done in + two ways:
   +
   +
   1. use the -i [host] switch to override XPA_NSINET for + this execution (The default port is 14285):
      +
      + % xpaget -i 'server_host:14285' ds9
      +
      +
   +
   2. Set the XPA_NSINET + variable for more permanent selection of xpans on the + server host:
      +
      + % setenv + XPA_NSINET 'server_host:14285'
      +
   +
   +
+

+

Once these two setup steps are performed, you should be able + to send commands to DS9 and receive data from DS9. You can + look at the xpaacl + man page for more information.

+

I have a laptop, that most of the time, is connected to a + network. DS9 runs fine. However, when I'm not connected to a + network and I start DS9, it hangs. What's going on?

+

 DS9 uses XPA for interprocess communication. When DS9 + starts, XPA initializes itself. XPA uses either IP sockets or + UNIX sockets, based if your machine is configured to connect + to the internet. In the case where your machine is configured + for the internet, but you are not currently connected, XPA + gets very confused. So, you can define a shell variable, + XPA_METHOD, that tells XPA which method to use.

+

The following is from the XPA documentation:

+

+

Determines the socket connection method used by this + session of XPA. The choices are: inet (to use INET or + Internet-based sockets) and local (unix) (to use UNIX + sockets). The default is INET. Using the inet method will + allow access from other machines (subject to access + controls) but using local will not. Local is most useful + for private access and when the machine in question is not + connected to the Internet

+

+

More information is available on XPA shell variables at: The XPA + Environment
+

+

+

+

+

+

+

+

VO

+

+

I can't connect to any of the virtual observatories. What + do I do now?

+

The DS9 help facility now contains a tutorial on how to + configure DS9 to by pass network firewalls. See Virtual Observatory Reference for + more information.

+

+

+SAOImage DS9 Help Desk

+

If you encounter any problems or have suggestions with +SAOImage DS9, +please +contact us:
+saord @ cfa.harvard.edu

+

William Joye
+Smithsonian Astrophysical Observatory
+60 Garden St.
+Cambridge, MA 02138 USA +

+

+SAOImage DS9 Installation Instructions
+

+

+

Solaris / Linux Installation

+DS9 for Solaris and Linux is a self contained application and does not +require any installation procedures or support files.
+

+
1. Download DS9. This is a gzip'ed tar file.
   +
+
2. Use the following command line to extract DS9:
   +
+ $ gzcat ds9.<port>.<version>.tar.gz | tar -xvf - +
3. Move +the DS9 executable into a directory in your path.
+

+

MacOSX

+There are versions of DS9 for 10.4 (Tiger) and 10.5 (Leopard)
+

+

+

+
1. Download DS9 for MacOSX. This is an universal application +that contains binaries for both PPC and Intel Macs. Drag to your +Applications folder.
   +
+

+

Darwin

+There are versions of DS9 for 10.4 (Tiger) and 10.5 (Leopard). Darwin +is only recommended for experienced users of unix and +linux. For other users, we recommend DS9 for MacOSX.
+
+DS9 Darwin requires X11.  DS9 for Darwin is a +unix executable and +must be run from the command line of a Terminal window.
+

+
1. Download DS9 for Darwin. This is a gzip'ed tar file.
+
2. Open a Terminal window.
+
3. Use the following command line to extract DS9:
   +
+ $ gzcat ds9.darwin<arch>.<version>.tar.gz | tar +-xvf - +
4. (Optional) +Move the DS9 executable into a directory in your path.
   +
+

+

Windows 7/Vista/XP
+

+

+

+

+
1. Download DS9 for Windows NT/2000/XP. This is a WinZip.exe +install file.
+
2. Execute the install file. DS9 will be installed by default in + C:\Program Files\ds9. It will contain two files, the +DS9 application and cygwin.dll.
+
3. To run, go to C:\Program Files\ds9 and double click +on the DS9 icon.
+

+

+

SAOImage DS9 Version 7 New Features

+

Version 7.3
+

+

+

64 bit Applications
+

+

DS9 now fully supports 64 bit applications across all + platforms. New support for 64 bit MacOSX Aqua has been added, + along with 64 bit Windows Cygwin.

+

2D Plots

+

+

New and improved GUI
+ Support for data set legend
+ Improvements in rendering
+ Error bar caps are now supported

+

+

Mouse Mode

+

The default mouse mode is now NONE and not REGION + or POINTER. This prevents unwanted region + creation went bringing the DS9 window to the front in most + Window managers.

+

Other Enhancements

+

+

Improved rendering of rotated text
+ Support for ENVI data format
+ 3D Image caching
+ 3D Background Image rendering
+ Dramatic improvements in analysis speed of large 3D data sets
+ New Segment region

+

+

Version 7.2
+

+

+

FITS

+

+

+

DS9 now fully supports complex FITS images such as data + cubes, multiple extension data cubes, mosaics, RGB images, and + 3D images. In addition, DS9 can be use to create complex FITS + images from multiple FITS files and other image formats. + Furthermore, complex FITS images can be easily disassembled + into individual images and saved in FITS or other image + formats.

+

+

+

Common API

+

+

+

XPA and SAMP now share the same API as the command line + interface. Backward compatibility is maintained to previous + versions of DS9.

+

+

+

Other Enhancements

+

+

More robust handling of SEGV and SIGBUS events
+ DS9 now distinguishes between BLANK/NAN/INF values
+ saveimage now supports EPS
+ Support for NRRD (Nearly RAW Raster Data) data format
+ Added support for exporting RGB images in TIFF, JPEG, or PNG
+ Improvement for FITS compression support
+ Released under GPL v3
+

+ +

Version 7.1
+

+

+

Catalog Matching
+

+

DS9 now supports catalog matching. From the Catalog menu + option, the user selects two currently loaded catalogs, an + error radius, and matching function. The user may request all + sources that are present in both catalogs, or in one catalog + and not in the other. Each catalog need not to be specified in + the same world coordinate system.
+

+

Enhanced Plot Tool
+

+

In addition to a Line Plot Tool, DS9 now supports additional + Bar and Scatter Plots Tools. The GUI for the Plot Tools have + been enhanced and new features have been added including + statistics and data lists. Each Plot Tool supports multiple + data sets and custom plotting options.

+

Catalog Scatter Plots
+

+

The user may now plot the results of two columns of a loaded + catalog as a scatter plot. A selected region on the image will + highlight the corresponding row and plot point. Likewise, a + selected row or plot point will highlight the corresponding + image region.
+

+

Interactive Region Analysis
+

+

DS9 regions now support interactive region analysis. The + analysis tasks are enabled by selecting the Analysis Menu in a + region's dialog box. Interactive analysis tasks includes + statistics, data cuts in 2D and 3D, and radial profiles.
+

+

Other Enhancements
+

+

+

3D scaling along the z axis of data cubes
+ Lock/Match Smoothing option
+ WCS dialog support for non-linear projections such as TAN-SIP + and SCAMP
+ Support for FITS files larger than 2Gb has been improved
+

+

+

Version 7.0
+

+

+

3-D Data Visualization
+

+

Previous versions of SAOImage DS9 would allow users to load + 3-D data into traditional 2-D frames, and would allow users to + step through successive z-dimension pixel slices of the data + cube. To visualize 3-D data in DS9 v. 7.0, a new module, + encompassed by the new Frame 3D option, allows users + to load and view data cubes in multiple dimensions.

+

The new module implements a simple ray-trace algorithm. For + each pixel on the screen, a ray is projected back into the + view volume, based on the current viewing parameters, + returning a data value if the ray intersects the FITS data + cube. To determine the value returned, there are 2 methods + available, Maximum Intensity Projection (MIP) and Average + Intensity Projection (AIP). MIP returns the maximum value + encountered, AIP returns an average of all values encountered. + At this point, normal DS9 operations are applied, such as + scaling, clipping and applying a color map.
+

+

Rendering time is independent of the actual data cube size. + Instead, the time it takes to render is based on how many rays + are needed to project the data cube upon the screen in the + view volume and the current zoom factor. The new module + requires no special hardware or graphical processor unit (GPU) + and the rendering time is adequate for interactive GUI + manipulation on most computers. The rendering engine is + developed using the POSIX thread library, allowing multiple + light weight processes to be spawned to complete an image in + parallel. The number of threads actually generated is a user + specified parameter. Since all modern hardware contain + multiple CPU cores, the default value is 8 threads. For larger + work stations, this number can be increase. For every doubling + in the number of CPU cores available, rendering times decrease + approximately 75%.
+

+

The new module is support on all hardware platforms currently + supported by DS9, including 32-bit and 64-bit versions of + Linux and MacOSX, and 32-bit versions of Windows and Solaris.
+

+

All 2-D graphics, regions, cross hairs, contours, and + coordinate grids, are applied to the current slice, which is + selected by the user. When the user wishes to match or lock a + 2-D image and to a 3-D data cube, the current slice is used to + determine the rendering solution. The user can crop the data + cube for all 3 axes via the command line or the GUI. The new + module also supports FITS event files binned into a data cube.
+

+

All printing support has been extended to the new 3-D module. + The user may generate 3-D images in Postscript, JPEG, TIFF, + and other formats, just as in the 2-D case. Furthermore, + native printing is supported for the Windows version.
+

+

DS9 analysis macros have been enhanced to fully support the + new 3-D module, allowing the user to invoke external analysis + tasks based on the current view parameters and to return + results back into DS9 in the form of text, plot, 2-D image, or + 3-D image.
+

+

Funding for 3-D data visualization was provided by the JWST + Mission office at Space Telescope Science Institute + (NAS-03127)

+

Color Tags
+

+ The purpose of color tags are to highlight (or hide) certain + values of data, regardless of the color map selected. The user + creates, edits, and deletes color tags via the GUI. To create a + color tag, enter the Colorbar Mode, and click once on the + colorbar. This creates a default color tag. Click and drag to + change the values. Click and drag on one side to increase or + decrease the value. Double click to manually edit the values and + color. Place the cursor over the color tag and press the delete + key to delete it. From the color parameters dialog, the user can + load, save, and delete all color tags for that frame.
+

Regions
+

+ Regions now support analysis tasks unique to each region type. + In the menu of the region dialog, the Analysis menu + will contain any type specific analysis tasks. The Circle, + Ellipse, Box, Polygon, and Point + regions now support interactive 1-D cuts along the 3rd axis of + 3-D data cubes. The Line, Vector, and Projection + regions support 2-D cuts through the current slice of 2-D and + 3-D data. The Auto Plot option under the regions + preferences can be used to specify if a plot is automatically + generated when the region is created.
+

Analysis
+

+ DS9 analysis macros have been enhanced to fully support the new + 3-D module, allowing the user to invoke external analysis tasks + on the current slice of 3-D data cube. The macro $z is + now supported for 3-D data. In support of Funtools, + the PLANE keyword is supported.
+

Slice
+

+ DS9 now allows the user to load a 3-D data cube one slice at a + time via the GUI or from the command line. Use the option -slice + + + + + + + to specify that all following 2-D files are to be + interpreted as a slice of a 3-D data cube.
+

Photo
+

+ DS9 can now load images in TIFF, JPEG, and PNG file format + directly. When loaded into a Frame, the average of the + luminosity is used. When loaded into a Frame RGB, each + channel is loaded directly. Use the -photo command + line option to specify that all following files are to be + interpreted as a photo image.
+

Export
+

+ DS9 will export the current image in TIFF, JPEG, or PNG file + format with the current colorbar parameters applied. The entire + image is exported (not just the visible portion) at the native + resolution.
+

Lock/Match
+

+ The support for the Lock/Match functionality of DS9 has been + greatly enhanced. The user may choose to lock/match frames, the + cross hair, cropping, the current slice, binning parameters, + scale parameters, or color map parameters.
+

Crop
+

+ DS9 now supports cropping the current image, via the GUI, + command line, or XPA/SAMP in both 2-D and 3-D. The user may + specify a rectangular region of the image data as a center and + width/height in any coordinate system via the Crop Dialog, or + can interactively select the region of the image to display by + clicking and dragging while in Crop Mode. For 3-D frames, the shift-click + to change the front clip plane, and control-click to + change the back clip plane. From the command line, cropping + parameters can be specified in IRAF format.
+

ASINH Scale
+

+ A new scale function has been added, ashinh, based on + the arc sinh function. This new function has similar properties + as the log function, with a=10.
+

All new GUI
+

+

DS9 now supports basic GUI elements (buttons, menus, etc) via + the native window manager API. Each port of DS9 will have a + native look and feel of each hardware platform. DS9 will take + advantage of the current user selected Theme if + supported by the native windowing system.
+

+

Postscript
+

+ DS9 now generates identical postscript code for a particular + image, regardless of which hardware platform was used to + generate the image.
+

Catalogs
+

+ The user may now specify coordinates in any equatorial system + (not just FK5) for a catalog search and receive results in any + equatorial system, to be plotted or saved. Local catalogs in any + equatorial system are now supported.
+

New WCS support
+

+

New WCS support for non-FITS WCS projections have been added + to DS9: TNX, ZPX, SCAMP, SIP and HEALPIX.  The keyword + WCSDEP is now supported.
+

+

Enhancements and improvements have been made in the support + for the following FITS WCS projections: COD, COO, COE, COP, + ZEA, and CAR.
+

+

DS9 now supports non-equatorial long/lat coordinate systems + in the form of xLON/xLAT and xyLN/xyLT. This includes solar + WCS HPLN/HPLT, HGLN/HGLT, and HRLN/HRLT systems.
+

+

DS9 now fully supports multiple alternative celestial WCS, if + specified. All cut/paste/copy operations, catalog, image + server, contour, regions, and coordinate grids will now use + the default WCS as selected by the user, via the WCS menu + item.
+

+

HEALPIX
+

+

DS9 now supports native HEALPIX maps, in both FITS binary + table and ascii table form. Any table with keyword + PIXTYPE=HEALPIX or NSIDE=x will be processed as an HEALPIX + image. The user may specify HEALPIX parameters within the file + specification to indicate RING (default) or NESTED order, + Coordinate System (default is Unknown),  Quadrant + (default is first), and Equator (default), North, or South + layout. The appropriate WCS is generated for the image.
+

+

External Analysis Files
+

+ DS9 will now look for external analysis files in the following + locations at start up: the current directory, $HOME/bin, + /usr/local/bin, /opt/local/bin, and /soft/saord/bin + in the form of *.ds9. If found, they will be + automatically loaded. Users may disable this feature via the + presences analysis panel. DS9 will continue to load ds9.ans + and ds9.analysis if found, and users specified + analysis files as before. DS9 will verify that the same analysis + file is not loaded twice to avoid duplication of analysis menus. +

+

For more detailed information, Please see Release Notes

+

3-D Frames
+

+

Previous versions of SAOImage DS9 would allow users to load 3-D + data into the traditional 2-D frames, and would allow users to + step through successive z-dimension pixel slices of the data + cube. To visualize the 3-D data in DS9 v. 7.0, a new module, + encompassed by the new Frame 3D option, allows users + to load and view data cubes in multiple dimensions.
+

+

The new module implements a simple ray-trace algorithm. For + each pixel on the screen, a ray is projected back into the view + volume, based on the current viewing parameters, returning a + data value if the ray intersects the FITS data cube. To + determine the value returned, there are 2 methods available, + Maximum Intensity Projection (MIP) and Average Intensity + Projection (AIP). MIP returns the maximum value encountered, AIP + returns an average of all values encountered. At this point, + normal DS9 operations are applied, such as scaling, clipping and + applying a color map.
+

+

Rendering time is independent upon the actual data cube size. + Instead, the time it takes to render is based on how many rays + are needed to project the data cube upon the screen in the view + volume and the current zoom factor. The new module requires no + special hardware or graphical processor unit (GPU) and the + rendering time is adequate for interactive GUI manipulation on + most computers. The rendering engine is developed using the + POSIX thread library, allowing multiple light weight processes + to be spawned to complete an image in parallel. The number of + threads actually generated is a user specified parameter. Since + all modern hardware contain multiple CPU cores, the default + value is 8 threads. For larger work stations, this number can be + increase. For every doubling in the number of CPU cores + available, rendering times decrease approximately 75%.
+

+

Example:
+ # create 3d frame, load fits file
+ # set view angle to az 45 el 30 deg
+ # set rendering method to Average Intensity Projection
+
+ % ds9 -3d mycube.fits -3d vp 45 30 -3d + method aip
+
+ % xpaset -p ds9 3d
+ % xpaset -p ds9 file mycube.fits
+ % xpaset -p ds9 3d vp 45 30
+ % xpaset -p ds9 3d method aip

+

+ All 2-D graphics, regions, cross hairs, contours, and coordinate + grids, are applied to the current slice, which is selected by the + user. When the user wishes to match or lock a 2-D image and to a + 3-D data cube, the current slice is used to determine the + rendering solution. The user can crop the data cube for all 3 axes + via the command line or the GUI. The new module also supports FITS + event files binned into a data cube.
+
+ All printing support has been extended to the new 3-D module. The + user may generate 3-D images in Postscript, JPEG, TIFF, and other + formats, just as in the 2-D case. Furthermore, native printing is + supported for the Windows version.
+
+ DS9 analysis macros have been enhanced to fully support the new + 3-D module, allowing the user to invoke external analysis tasks + based on the current view parameters and to return results back + into DS9 in the form of text, plot, 2-D image, or 3-D image.

Analysis

+

Each file type known to DS9 can have user-defined analysis + commands associated with it. These analysis commands are defined + at start-up time , or loaded by the user, by means of an ASCII + analysis description file. The analysis commands are available + for execution, either via the Analysis Menu or the XPA + point Analysis. In addition, commands may be bound + to events, such as keystrokes or mouse clicks. This type of + command is called a bind command.
+

+

DS9 searches for an analysis file named ds9.ans or ds9.analysis + in the current directory and $HOME to be loaded at + startup. In addition, DS9 will search the following directories + for any analysis files to be loaded at startup in the form of *.ds9: + the current directory, $HOME/bin, /usr/local/bin, + /opt/local/bin, and /soft/saord/bin. Finally, + the user may specify analysis files to be loaded at startup in + the preferences analysis panel. The user may also load or clear + current analysis commands via command line options or the Analysis + + + + menu.

+

When activated, either from the menu, XPA, or bound event, an + analysis command first is macro-expanded to fill in user-defined + arguments and then is executed externally. Results may be + displayed in a separate text window, plot window, or in a image + frame.

+ Syntax
+ Command Type
+ Macros
+ Help
+ Parameters
+ Hierarchical Menus
+ Sample +

Syntax

+ The analysis file that defines the known analysis commands + consists of one or more file descriptors, each of which has the + following format: +

Menu label to be used
+ A space separated list of file templates
+ Command type [menu | bind <event>]
+ The command line for the analysis program

+

Task names may contain space characters. All lines may be + indented. Also, the '#' character is a comment character. A + separator can be inserted in the menu by specifying the + following sequence '---'.

+ Example: +

# this will insert a menu separator
+ ---

+

Command Type

+

The third line indicates the type of command.

+

+

menu

+

A menu command creates an menu option under the Analysis + + + + + + + menu option, and can be invoked by the user via the GUI or + XPA.

+ Example: +

# Menu command example
+ My Analysis Task
+ *.fits
+ menu
+ $data | doit | $text

+

bind

+

A bind command is a command that is bound to an + event. When the event occurs, the command is executed. Types + of events available include all TK events, including all keystrokes + and mouse clicks. If a command is bound to an event + other that a keystroke, care must be taken to not to + interfere with other internal DS9 events.

+

To bind to a key stroke, use the following command type:

+

bind <keystroke>
+

+ Example: +

# Bind command example
+ Print coordinates
+ *.fits
+ bind x
+ echo "$x $y" | $text
+

+

web

+

A web command allows the user to invoke the + internal web browser from the analysis menu.

+ Example: +

# web command example
+ HTTP based
+ *
+ web
+ http://hea-www.harvard.edu/RD/ds9/ref/index.html
+
+ File based
+ *
+ web
+ file:/home/joye/index.html
+

+

+

Macros

+

The following macros are macro-expanded to fill in user-defined + arguments before the command is executed. Strings that contain + $<macroname> that user does not want to be expanded may be + escaped by using $$<macroname>. All strings that contain + $<string>  that are not a macro name will not be + affected.

+

For example:

+

echo "$$data $foo" | $text
+

+

will display a text dialog that contains "$data $foo"

+

$width
+ $height
+ $depth

+

Substitute the width, height, or depth of the data file in the + command line.

+ Syntax:
+     $width
+     $height
+
+ Example:
+     echo "$width $height $depth" | $text +
+

$bitpix

+

Substitute the bitpix of the data file in the command line.

+ Syntax:
+     $bitpix
+
+ Example:
+     echo "$bitpix" | $text +

$data

+

Data from the current frame becomes the input data to the + command string. This data is in the form of a FITS image. This + macro can only used at the beginning of the command string.

+ Syntax:
+     $data
+
+ Example:
+     $data | dosomething | $text +

$entry

+

Display an entry modal dialog. The returned string is + substituted. If cancel is selected, the command line + is not executed.

+ Syntax:
+     $entry(<message>)
+
+ Example:
+     echo "$entry(Enter something here)" + | $text +

$env

+

Substitute the value of a shell environment variable.

+ Syntax:
+     $env(<shell variable>)
+
+ Example:
+     echo "$env(PATH)" | $text +

$filedialog

+

Display the standard file dialog. Substitutes the returned + pathname. Argument specifies if an open file or save file dialog + is invoked.

+ Syntax:
+     $filedialog([open|save])
+
+ Example:
+     echo "$filedialog(open)" | $text
+

$filename

+

Substitute the filename of the data file in the command line. A + full filename includes any absolute or relative path. A root + filename contains no path. A (2D) subsection defines a subimage + from xmin,ymin to xmax,ymax. For Frame3D, a + 2D subsection will also include the current slice (PLANE=) + parameter if not 1. A 3D subsection defines a subimage from xmin,ymin,zmin + to xmax,ymax,zmax and no PLANE parameter.
+

+ Syntax:
+     $filename # filename with extname, + (2d) subsections, filters
+     $filename(root|root,base) # root filename + with with extname, no subsections, no + filters)
+     $filename(full|full,base) # full filename with + + extname, no subsections, no filters)
+
+ Example:
+     dosomething $filename | $text
+     dosomething $filename(root) | $text
+
+ $filename[$regions] +

Combination of $filename and $regions macros. + +Generates +a + + + + + series of filenames, each with a region.

+ Syntax:
+     $filename[$regions]
+     $filename[$regions(<options>)]
+
+ Example:
+     dosomething $filename[$regions] | + $text +

$geturl

+

This macro differs from all other macros, including $url, + in that no subprocess pipe is created. Only HTTP is supported. + The contents of the url are retrieved and sent to $text, + $plot, or $image. No other processing is + allowed. The primary purpose of this macro is to support + external analysis for the Windows platform, which has no + subprocess support.

+ Syntax:
+     + $geturl(http://<hostname>:<port>/<query>) +
+
+ Example:
+     $geturl(http://foo.bar.edu/foo.html) + | $text
+

$image

+

The resulting image data is display in a DS9 frame. This macro + should be the last macro of a command line. Optional parameter + indicates if a new frame and what type of frame is created for + the new data. The macro is removed from the command line before + execution.

+ Syntax:
+     $image
+     $image([new|rgb|3d|current])
+
+ Example:
+     doit | $image(new) +

$message

+

Display a message dialog box, with option buttons.  After + displaying the message, the macro is removed from the command + line before execution. If cancel or no is + selected, the command line is not executed.

+ Syntax:
+     $message(<message>)
+     + $message([ok|okcancel|yesno],<message>)
+
+ Example:
+     $message(okcancel,This is a + Message)| doit | $text +

$null

+

Expect no output or results from analysis task. Note: no error + message will be returned if the analysis task fails to execute + correctly.

+ Syntax:
+     $null
+
+ Example:
+     echo "Hello, world" > foo | $null +

$pan

+

Substitute current pan location of the particular data file are + returned. The default coordinate system is physical.

+ Syntax:
+     $pan
+     $pan(<coordinate + system>,<format>)
+

where:

+     coordinate system = + [image|physical|detector|amplifier|wcs|wcsa...wcsz]
+     sky + frame         = + [fk4|fk5|icrs|galactic|ecliptic]
+     sky + format        = + [hms|sexagesimal|degrees]
+
+ Example:
+     echo $pan(fk5,sexagesimal) | $text
+

$plot

+

Display data in plot window. This macro should be the last + macro of a command line. The data is read via STDIN + and consist of a pair of coordinates, with option error values. + (xy, xyex, xyey, xyexey) Default dimension is xy. + The macro is removed from the command line before execution.

+

For $plot(stdin) only:

+

The title, x axis label, and y axis label are assumed to be on + the first line of input, delimited with a new-line. However, if + the data starts with $BEGINTEXT, all text between $BEGINTEXT + and $ENDTEXT will be removed from the data and + displayed in a separate text dialog window, with the remaining + data, including the title, x axis label, and y axis label, will + be displayed in a plot window. Furthermore, if the data contains + the string $ERROR, an error is assumed to have occurred + and a text dialog window is displayed only.

+ Syntax:
+     $plot
+     $plot(,,,)
+     $plot(<title>,<x axis + label>,<y axis label>,[xy|xyex|xyey|xyexey])
+     $plot(stdin)
+
+ Example:
+     doit | $plot(This is aTitle,X Axis,Y + Axis)
+     doit | $plot(stdin) +

$regions

+

Substitute region definition in specified region format, + coordinate system, and coordinate format. The default coordinate + system is physical, default coordinate format degrees, + and default region format DS9. Arguments may appear in + any order, as long as they are separated by ',' and no spaces. + If one or  more properties are specified, only regions with + all of the specified properties will be substituted.

+ Syntax:
+     $regions
+     $regions(<options>) +

where options are one of the following:

+     regions format    = + [ds9|ciao|saotng|saoimage|pros|xy]
+     + property          = + [include|exclude|source|background]
+     coordinate system = + [image|physical|detector|amplifier|wcs]
+     sky + frame         = + [fk4|fk5|icrs|galactic|ecliptic]
+     sky + format        = + [sexagesimal|degrees] +

also, the old SAOTNG formats are also supported:

+     $regions_pixels
+     $regions_degrees
+     $regions_hms
+     $include_regions
+     $include_regions_pixels
+     $include_regions_degrees
+     $include_regions_hms
+     $exclude_regions
+     $exclude_regions_pixels
+     $exclude_regions_degrees
+     $exclude_regions_hms
+
+ Example:
+     dosomething $regions | $text
+     dosomething $regions(pros) | $text
+     dosomething $regions(source,wcs,fk5) | + $text
+     dosomething + $regions(saotng,background,exclude,ecliptic,sexagesimal) | $text +

$text

+

Display text in a text dialog window. This macro should be the + last macro of a command line. To display text from only STDOUT + use '|' as the pipe command. To display text from both STDOUT + and STDERR, use '|&' as the pipe command. No parameters are + required. The macro is removed from the command line before + execution.

+ Syntax:
+     $text
+
+ Example:
+     doit | $text # stdout
+     doit |& $text # stdout and stderr
+ +

$url

+

URLs are processed and stored in a temporary file. Only HTTP + and anonymous FTP are supported.

+ Syntax:
+     + $url(http://<hostname>:<port>/<query>)
+     + $url(ftp://<hostname>/<filename>)
+
+ Example:
+     + $url(http://legacy.gsfc.nasa.gov/rosat/data/p000s26b.img.Z) | + uncompress | $image
+     + $url(ftp://legacy.gsfc.nasa.gov/rosat/data/hri/images/rh100193_img.fits) + | $image
+ +

$vo_method

+

Returns the vo method.

+ Syntax:
+     $vo_method
+
+ Example:
+     echo '$vo_method' | $text
+

$value
+

+

Substitute the value at the location of the cursor of an bind + event.
+

+ Syntax:
+     $value
+
+ Example:
+     echo "$value" | $text
+

$x
+ $y
+ $z
+

+

Substitute coordinates of an bind event. When a bind event is + triggered, the x,y coordinates of the mouse of the + particular data file are returned. The default coordinate system + is physical. This macro is only available for bind + commands. For datacubes, the z coordinate is returned based on + the current slice selected.
+

+ Syntax:
+     $x
+     $x(<coordinate + system>,<format>)
+     $y
+     $y(<coordinate + system>,<format>)
+     $z
+     $z(<coordinate system>)
+ +

where:

+     coordinate system = + [image|physical|detector|amplifier|wcs|wcsa...wcsz]
+     sky + frame         = + [fk4|fk5|icrs|galactic|ecliptic]
+     sky + format        = + [hms|sexagesimal|degrees]
+
+ Example:
+     echo "$x $y" | $text
+     echo "$x $y $z" | $text
+     echo "$x(fk5,sexagesimal) + $y(fk5,sexagesimal)" | $text
+     echo "$x(wcs) $y(wcs) $z(wcs)" | $text
+

$xpa

+

Returns the xpa access point name.

+ Syntax:
+     $xpa
+
+ Example:
+     echo '$xpa' | $text +

$xpa_method

+

Returns the xpa method.

+ Syntax:
+     $xpa_method
+
+ Example:
+     echo '$xpa_method' | $text +

Help

+

The user may define his own HELP message. This + message will be available to the user as a menu item. An + optional label maybe specified. The default label is Help. + When invoked, an text dialog window will appear, containing the + message. Multiple HELP items maybe defined within a + menu or across hierarchical menus.

+ Example: +

help Main Help
+ A help message may contain
+ multiple lines of description of the tasks
+ in the menu or menus
+ endhelp

+

Parameters

+

The user may define his own macros or parameters to be + evaluated before the command line is executed. To do this, the + user defines a param segment that is referenced in the command + line. The param definition has the follow format:

+

param <name>
+ <variable> <entry | checkbox | menu> + <title> <default> <{comment}>
+ ...
+ endparam

+

or

+

param <name>
+ @<iraf param filename>
+ end

+

The definition either consisted of a number of variables, one + per row, or the name of a IRAF style parameter file. DS9 will + look for the IRAF parameter file in:

+

./<filename>
+ $UPARM/<filename>
+ $HOME/iraf/<filename>

+ Example:
+ +

param foobar
+ var1 entry {Variable 1} default {this is a entry}
+ var2 checkbox {Variable 2} 1 {this is a checkbox}
+ var3 menu {Variable 3} AAA|BBB|CCC {this is a menu}
+ endparam

+

To use parameters, specify the param name at the beginning of + your command line:

+

Parameter Test
+ *
+ menu
+ $param(foobar); echo "$var1 $var2 $var3" | $text

+

When the menu item is selected, the user will be presented with + a dialog box that contains entry, checkbox, or menu choices + + + + + for each variable specified. If the user clicks ok, the values + are substituted in the command line before execution.

+

Hierarchical Menus

+

The user may define hierarchical menus. Use this to organized + crowded menus. To do this, frame menu entries with hmenu + <label> and endhmenu. Hierarchical menu + labels may contain spaces. Multiple levels maybe implemented.

+ Example:
+ +

hmenu Stuff
+     hello
+     *
+     menu
+     echo "Hello" | $text +

    world
+     *
+     menu
+     echo "World" | $text

+

    hmenu More Stuff
+         hello world +
+         *
+         menu
+         echo "Hello + World" | $text
+     endhmenu
+ endhmenu

+

+

Will create an hierarchical menu with two members, hello + and world.

+

Sample

+ #
+ # Analysis command descriptions:
+ #       menu label
+ #       file templates
+ #    menu/bind
+ #       analysis command line
+
+ param foo
+     var1 entry entry 40 {this is a entry}
+     var2 checkbox checkbox 1 {this is a checkbox}
+     var3 menu menu AAA|BBB|CCC {this is a menu}
+ endparam
+
+ param bar
+     @analysis.par
+ endparam
+
+ param foobar
+     @tvdisply.par
+ endparam
+
+ param ltc
+     bins entry "Enter number of [t1:t2:]bins" 0 + "('0' for default number of bins)"
+ endparam
+
+ # Help Main Help
+
+ help Main Help
+ These menus contain a test for each possible feature
+
+ supported by the ds9 (blank line above)
+ endhelp
+ ---
+
+ hmenu Test Web
+     help Web Help
+     Help for web features
+     endhelp
+
+     Web Test url
+     *
+     web
+     http://hea-www.harvard.edu/RD/ds9/
+
+     Web Test file
+     *
+     web
+     file:/home/joye/saods9/ds9/tests/hv.html
+ endhmenu
+
+ hmenu Test Basics
+     help Basic Help
+     Help for basic features
+     endhelp
+     ---
+     Test escape char # this is a comment
+     *
+     menu
+     echo "this is not a macro $$xpa" | $text
+
+     Test pass thru # this is a comment
+     *
+     menu
+     echo "this is not a macro $foo" | $text
+
+     Test $xpa # this is a comment
+     *
+     menu
+     echo $xpa | $text
+
+     Test $xpa_method
+     *
+     menu
+     echo $xpa_method | $text
+
+     Test $vo_method
+     *
+     menu
+     echo $vo_method | $text
+
+     Test $filename
+     *.fits
+     menu
+     echo $filename | $text
+
+     Test $filename(root)
+     *.fits
+     menu
+     echo $filename(root) | $text
+
+     Test $xdim $ydim $bitpix
+     *.fits
+     menu
+     echo "$xdim $ydim $bitpix" | $text
+
+     Test $xcen $ycen
+     *.fits
+     menu
+     echo "$xcen $ycen" | $text
+
+     Test $env
+     *
+     menu
+     echo $env(PATH) | $text
+ endhmenu
+
+ hmenu Test Regions
+     help Regions Help
+     Help for regions features
+     endhelp
+     ---
+     Test $regions
+     *.fits
+     menu
+     echo "$regions + ds9_s:$regions(ds9,source,image) + ciao_b:$regions(ciao,background) + saotng_i:$regions(saotng,include,wcs,fk5) + pros_e:$regions(pros,exclude,wcs,fk5,sexagesimal) + xy_be:$regions(xy,background,exclude,wcs,fk4,hms)" | $text
+
+     Test $regions wcs
+     *.fits
+     menu
+     echo "$regions(ds9,wcs) + $regions(ds9,wcs,fk5,sexagesimal) $regions(ds9,wcsa) " | $text
+
+     Test $include_regions_pixels
+     *.fits
+     menu
+     echo "ds9_s: $source_regions ds9_b: + $background_regions_pixels ds9_i: $include_regions_degrees + ds9_e: $exclude_regions_hms" | $text
+
+     Test $filename $regions
+     *.fits
+     menu
+     echo "$filename[$regions]" | $text
+
+     Test $filename $regions()
+     *.fits
+     menu
+     echo "$filename[$regions()]" | $text
+ endhmenu
+
+ hmenu Test Output
+     help Output Help
+     Help for output features
+     endhelp
+     ---
+     Test $null
+     *
+     menu
+     echo "This is Text" > /dev/null | $null
+
+     Test $text
+     *
+     menu
+     echo "This is Text" | $text
+
+     Test $text stderr
+     *
+     menu
+     ls foofoofoo | $text
+
+     Test $plot
+     *
+     menu
+     cat xy.dat | $plot
+
+     Test $plot(title,x,y,xyey)
+     *
+     menu
+     cat xye.dat | $plot(Title,X Axis,Y Axis,xyey)
+
+     Test $plot(title,x,y,xyexey)
+     *
+     menu
+     cat xyee.dat | $plot(Title,X Axis,Y + Axis,xyexey)
+
+     Test $plot(title,x,y,4)
+     *
+     menu
+     cat xyey.dat | $plot(Title,X Axis,Y Axis,4)
+
+     Test $plot(title,x,y,5)
+     *
+     menu
+     cat xyeye.dat | $plot(Title,X Axis,Y Axis,5)
+
+     Test $plot(stdin)
+     *
+     menu
+     cat xye.stdin.dat | $plot(stdin)
+
+     Test $plot(stdin) text
+     *
+     menu
+     cat xye.stdin.text.dat | $plot(stdin)
+
+     Test $plot(stdin) error
+     *
+     menu
+     cat xy.stdin.error.dat | $plot(stdin)
+
+     Test $data
+     *.fits
+     menu
+     $data | $image(new)
+
+     Test $image
+     *
+     menu
+     cat img16.fits | $image
+ endhmenu
+
+ hmenu Test Dialogs
+     help Dialogs Help
+     Help for dialog features
+     endhelp
+     ---
+     Test $message(message)
+     *
+     menu
+     $message(ok,This is a Message) | echo "hello" + | $text
+
+     Test $message(ok,message)
+     *
+     menu
+     $message(ok,This is a Message) | echo "World" + | $text
+
+     Test $entry(message)
+     *
+     menu
+     echo "$entry(Enter Something)" | $text
+ endhmenu
+
+ hmenu Test Params
+     help Param Help
+     Help for param features
+     endhelp
+     ---
+     Test $param
+     *
+     menu
+     $param(foo); echo "$var1 $var2 $var3" | $text
+
+     Test $param @file
+     *
+     menu
+     $param(bar); echo "$var1 $var2 $var3" | $text
+ endhmenu
+
+ hmenu Test Network
+     help Network Help
+     Help for network features
+     endhelp
+     ---
+     Test $url(http://)
+     *
+     menu
+     + $url(http://legacy.gsfc.nasa.gov/FTP/rosat/data/cdrom/vol1/IMAGES/00h/p000s26b.img.Z) + +| +gunzip + + + + + | $image
+
+     Test $url(ftp://)
+     *
+     menu
+     + $url(ftp://legacy.gsfc.nasa.gov/rosat/data/hri/images/fits/rh100193_img.fits) + + + + + | $image
+
+     Test $geturl $text
+     *
+     menu
+     +$geturl(http://hea-www.harvard.edu/RD/saord-cgi/funtools?funcnts+$filename+$regions(source,,)+$regions(background,,))|$text
+
+     Test $geturl $plotstd
+     *
+     menu
+     $param(ltc); +$geturl(http://hea-www.harvard.edu/RD/saord-cgi/funtools?funhist_plot+$filename[$regions]+time+$bins)|$plot(stdin)
+ endhmenu
+
+ hmenu Test Other
+     help Other Help
+     Help for other features
+     endhelp
+     ---
+     Test $param @tvdisply
+     *
+     menu
+     $param(foobar); echo "$frame $erase" | $text
+
+     hmenu Test MultiLevel
+         test
+         *
+         menu
+         echo "Hello World" | $text
+     endhmenu
+ endhmenu
+
+ $x $y
+ *.fits
+ bind x
+ echo "$x $y" | $text
+
+ $x(fk5,hms) $y(fk5,hms)
+ *.fits
+ bind y
+ echo "$x(fk5,hms) $y(fk5,hms)" | $text
+
+ $x(wcs,fk5,hms) $y(wcs,fk5,hms)
+ *.fits
+ bind z
+ echo "$x(wcs,fk5,hms) $y(wcs,fk5,hms)" | $text
+

Backup and Restore

+

DS9 now supports Backup and Restore. When a backup is invoked, + DS9 will save in a backup save set all files needed to restore + DS9 to that state, including geometry, data files, colormaps, + catalogs, contours, and regions.
+

+

Backup Save Set

+

A backup save set consists of a text file, called a backup + script, and an optional directory, which will contain auxiliary + data files needed to restore DS9 to a previous state. The backup + file and the auxiliary directory maybe moved across file + systems, or even platforms, but must remain together in the same + directory.
+

+

Image data files

+

By default, all data image files are save within the backup + save set. However, the user has the option, via the Preferences, + to only save only an absolute pathname to the data file, and not + the data file itself. This option will dramatically reduce the + size of a backup save set, but will restrict the usage to a + particular file system and platform.
+

+

Image files that have been loaded into DS9 via XPA, SAMP, or + from URL will always be saved into the save set.
+

+

Caveats

+

There are several caveats in the usage of Backup and Restore. + In particular:
+

+

+

Currently, there is no support for masks.
+ External Analysis menus will not be saved.
+ Plot Tool windows will not be saved.
+ IIS frames (IRAF) will not be saved.
+ SAMP and XPA sessions will not be saved.

+

+

And finally, if the image data had been loaded into DS9 via + XPA, SAMP, or from a URL, the following complex load operations + are not supported:

+

Open Mosaic IRAF Image
+ Open Mosaic IRAF Segment Open Mosaic WCS Image
+ Open Mosaic WCS Segment Open Mosaic WFPC2 Open RGB Fits Image + Open RGB Fits Cube Open RGB Array Open Multi Ext Data Cube + Open Multi Ext Multiple Frames

+

Binning

+

To create an image from a FITS Bin Table, the user needs to + specify a binning factor, binning buffer size, and the binning + function.
+

+

The Binning (or Block) Factor is defined as the following: A + value greater or equal to zero. This value indicates the number + of pixel values that will fall into a particular bin.
+

+

The Bin Buffer Size is overall size of the image generated. + This has no relation to min and max values of the columns used + to create the image.
+

+

The Bin Function is defined as the following: Average - all + pixel values that fall into one pixel bin are averaged. Sum - + all pixel values that fall into one pixel bin are summed.
+

+

Bin to Fit Frame will calculate a bin block factor as a power + of 2 that will allow the entire data space to be displayed in + the current frame.

+

By default, DS9 will bin about the center of the image. To + determine the center of the image, DS9 will look for the + following keywords in order:

+

TDMIN/TDMAX
+ TLMIN/TLMAX
+ TALEN
+ AXLEN

+

If no valid keywords are found, DS9 will define the center as + the middle of the possible data space based on the coordinate + data type.

+
+

+

+

+

+

+
+

Catalogs

+

DS9 provides full support for loading, displaying, filtering, + and saving catalogs. DS9 allows you to overlay symbols from + multiple catalogs on the current image.

+

Local and on-line catalog access is supported. Most major + catalogs can be retrieved from online servers. Both the CDS and + SDSS catalog servers are now supported. Local catalog files in + starbase (rdb) or CSV (with or without header) are supported.

+

On-line catalogs are available via services provided by the + VizieR catalog access tool, CDS, Strasbourg, France (VizieR is a + joint effort of the Centre de Donnees Astronomiques de + Strasbourg and ESA-ESRIN Information Systems Division) and by + the Sloan Digital Sky Survey.

+

A selection of popular catalogs is provided in the Analysis + menu. In addition, you can search for other catalogs based on + title, keywords, mission, wavelength, and object type.

+

When a catalog is overlayed on an image, each displayed catalog + symbol consists of a shape, color, and text. An advanced symbol + editor is available that allows you to specify the shape, size, + color, and text of each symbol, based on catalog column values. + These symbol expressions can be saved for future use.

+

Along with the overlay display, a catalog list is provided in a + separate window. It displays the column values for each catalog + object. The catalog list can be sorted and filtered, and the + catalog display will be automatically updated. Advanced + filtering options are available. Catalogs can be loaded and + saved as local files in ASCII Starbase format. Each catalog + contains header information which can be displayed. The list can + be printed separately from the image.

+

An interactive connection between the displayed catalog symbols + and the catalog list is provided. When you select one or more + rows within the catalog list, the corresponding symbols are + highlighted on the image display. Conversely, selecting multiple + symbols on the image display will highlight the corresponding + rows within the catalog list. Catalog symbols can be converted + to regions for use with analysis tasks.

+

Filter Option

+

The catalog list can be sorted and filtered, and the catalog + display will be automatically updated. A filter is conditional + expression, when evaluated for each row of the catalog, if true, + the row is displayed, and if false, the row is not displayed. + The conditional expression can be any valid TCL expression. The + value of a column may be indicated with $<column + name>.

+

$_RAJ2000>180. && $_RAJ2000<270.
+ $Jmag>11
+ log($Kmag*10)<.3
+ [string equal $OTYPE_S SNR]
+

+

Advanced Symbol Editor

+

An advanced symbol editor is available that allows you to + specify the shape, size, color, and text of each symbol, based + on catalog column values. For each row of the catalog, one or + more conditional expressions are evaluated. For the first + expression to evaluate true, a given symbol is displayed, with + the specified shape, color, size and text properties. As with + the filter, the value of a particular column can be indicated as + $<column name>.

+

For the condition entry, the expression you type in is + automatically evaluated via TCL expr after macro + expansion.

+

1                               # + + + always
+ 0                               # + + + never
+ true                            # + + + always
+ false                           # + + + never
+ $Jmag>2                         # + + + conditional
+ sin($Jmag)>.5 +                   + + + # conditional
+ [string equal $Class + SNR]       # conditional
+ [regexp {*SNR*} + $Class]         # + conditional
+

+

For the size, size2, and angle entries, the expression you type + in is also automatically evaluated via TCL expr after + macro expansion.

+

2               # + + + value of '2' is used
+ $Jmag           # + + + value of column Jmag is used
+ $Jmag/2.        # + value of column Jmag div 2 is used
+ (4+2)/3         # + + + value of '2' is used
+

+

For the text portion, this is not true. It is assumed to be + text, unless you explicitly use an expr operator.

+

foo             # + + + will put 'foo' above the symbol
+ $Jmag           # + + + will put the value of column Jmag above the symbol
+ (4+2)/3         # + + + will put the text '(4+2)/3' above the symbol
+ [expr (4+2)/3]  # will put the text '2' above the + symbol
+ [expr $Jmag/2.] # will take the value of Jmag and div + by 2
+

+

And finally, one special case for shape = text and text = + empty. In this case, the row number is displayed.

+  

Colorbar
+

+

Color Tags

+

The purpose of color tags are to highlight (or hide) certain + values of data, regardless of the color map selected. The user + creates, edits, and deletes color tags via the GUI. To create a + color tag, enter the Colorbar Mode, and click once on the + colorbar. This creates a default color tag. Click and drag to + change the values. Click and drag on one side to increase or + decrease the value. Double click to manually edit the values and + color. Place the cursor over the color tag and press the delete + key to delete it. From the color parameters dialog, the user can + load, save, and delete all color tags for that frame.
+

+

Visuals

+

DS9 supports a number of color environments. Not all color + environments, or visuals, are available on most machines. In + fact, you may be restricted to one or two, base on the color + graphics hardware your computer has. A color visual is composed + of two parts, the color model and the bit depth. Pseudo color + uses a color lookup table to derive the correct color, True + color uses the value directly as a RGB triplet, to derive the + correct color. The follow is a list of the color visuals DS9 + currently supports:

+

pseudo color, 8 bit
+ true color, 8 bit
+ true color, 15 bit
+ true color, 16 bit
+ true color, 24 bit

+

You can use the xdpyinfo command to see if one of + these visual are available. NOTE: Linux Users-- if your desired + visual is not available, use the Xconfigarator command (Red Hat) + or similar command under other versions of linux, to configure + your X window visuals.

+

When DS9 is invoked, by default, it will use the default + visual. You can find out what the default visual is by using the + xdpyinfo command. You can also force DS9 to use another + visual by command line option. If you specify a visual, and it + is not available, DS9 will exit with an error message.

+

$ds9                      + + + # default visual, default depth
+ $ds9 -visual pseudo       # + pseudo color, default depth
+ $ds9 -visual pseudocolor  # pseudo color, default depth
+ $ds9 -visual pseudocolor8 # pseudo color 8
+ $ds9 -visual + true         # true + color, default depth
+ $ds9 -visual truecolor    # true color, default + depth
+ $ds9 -visual truecolor8   # true color 8
+ $ds9 -visual truecolor16  # true color 16
+ $ds9 -visual truecolor24  # true color 24

+

Command Line Options

+

DS9 will process each command line option, one at a time, as + the last step in the initialization process. Therefore, it is + possible to use command line options as a little script. For + example, the following command line option is used:

+ $ds9 -tile foo.fits -cmap Heat -zscale bar.fits -cmap I8 +

First DS9 is put in tile mode, then foo.fits is + loaded. Then the colormap for foo.fits is changed to Heat + and the scale changed to zscale. Next, bar.fits + is loaded and the colormap for bar.fits is changed to + I8.

+ 2mass
+ 3d
+ about
+ align
+ analysis
+ array
+ asinh
+ background
+ backup
+ bin
+ blink
+ block
+ blue
+ catalog
+ cd
+ cmap
+ colorbar
+ console
+ contour
+ crop
+ crosshair
+ cube
+ cursor
+ dsssao
+ dsseso
+ dssstsci
+ envi
+ exit
+ export
+ fifo
+ fifo_only
+ fits
+ frame
+ geometry
+ gif
+ green
+ grid
+ header
+ height
+ help
+ histequ
+ iconify
+ import
+ inet_only
+ invert
+ iis
+ jpeg
+ language
+ linear
+ lock
+ log
+ lower
+ magnifier
+ mask
+ match
+ mecube
+ minmax
+ mode
+ mosaic
+ mosaicimage
+ movie
+ msg
+ multiframe
+ nameserver
+ nan
+ nrrd
+ nvss
+ orient
+ pagesetup
+ pan
+ pixeltable
+ plot
+ png
+ prefs
+ preserve
+ psprint
+ print
+ private
+ port
+ port_only
+ pow
+ quit
+ raise
+ regions
+ red
+ restore
+ rgb
+ rgbarray
+ rgbcube
+ rgbimage
+ rotate
+ samp
+ save
+ saveimage
+ scale
+ shm
+ sia
+ single
+ sinh
+ skyview
+ sleep
+ slice
+ smooth
+ squared
+ sqrt
+ source
+ tcl
+ threads
+ tiff
+ tile
+ title
+ unix
+ unix_only
+ update
+ url
+ version
+ view
+ visual
+ vla
+ vlss
+ vo
+ wcs
+ web
+ width
+ xpa
+ zmax
+ zoom
+ zscale
+ +

2mass

+

Support for 2MASS Digital Sky Survey.

+ Syntax:
+ -2mass []
+        [<object>]
+        [name <object>]
+        [coord <ra> + <dec> degrees|sexagesimal] # in wcs fk5
+        [size <width> + <height> degrees|arcmin|arcsec]
+        [save yes|no]
+        [frame new|current]
+        [update frame|crosshair]
+        [survey j|h|k]
+        [open|close]
+  
+ Example:
+ $ds9 -2mass
+ $ds9 -2mass m31
+ $ds9 -2mass name m31
+ $ds9 -2mass coord 00:42:44.404 +41:16:08.78 sexagesimal
+ $ds9 -2mass size 60 60 arcmin
+ $ds9 -2mass save yes
+ $ds9 -2mass frame current
+ $ds9 -2mass update frame
+ $ds9 -2mass survey j
+ $ds9 -2mass open
+ $ds9 -2mass close
+ +

3d

+

Support for 3D frame.

+ Syntax:
+ -3d []
+     [view <az> <el>]
+     [az <az>]
+     [el <el>]
+     [scale <scale>]
+     [method mip|aip]
+     [background none|azimuth|elevation]
+     [border yes|no]
+     [border color]
+     [highlite yes|no]
+     [highlite color]
+     [open|close]
+  
+ Example:
+ $ds9 -3d # create new 3D frame
+ $ds9 -3d view 45 30
+ $ds9 -3d az 45
+ $ds9 -3d el 30
+ $ds9 -3d scale 10
+ $ds9 -3d method mip
+ $ds9 -3d background azimuth
+ $ds9 -3d border yes
+ $ds9 -3d border color red
+ $ds9 -3d highlite yes
+ $ds9 -3d highlite color red
+ $ds9 -3d open
+ $ds9 -3d close
+

about

+

Get DS9 credits.

+ Syntax:
+ -about
+  
+ Example:
+ $ds9 -about
+ +

align

+

Controls the World Coordinate System alignment for the current + frame.

+ Syntax:
+ -align [yes|no]
+  
+ Example:
+ $ds9 -align yes
+ +

analysis

+

Control external analysis tasks. Tasks are numbered as they are + loaded, starting with 0. Can also be used to display a message + and display text in the text dialog window.

+ Syntax:
+ -analysis [<task number>]
+           + [<filename>]
+           [task <task + number>|<task name>]
+           [load + <filename>]
+           [clear]
+           + [clear][load <filename>]
+           [message + ok|okcancel|yesno <message>]
+           [entry + <message>]
+           [text]
+  
+ Example:
+ $ds9 -analysis 0 # invoke first analysis task
+ $ds9 -analysis task 0
+ $ds9 -analysis task foobar
+ $ds9 -analysis task "{foo bar}"
+ $ds9 -analysis my.ans
+ $ds9 -analysis load my.ans
+ $ds9 -analysis clear
+ $ds9 -analysis clear load my.ans
+ $ds9 -analysis message '{This is a message}'
+ $ds9 -analysis message okcancel '{This is a message}'
+ $ds9 -analysis text '{This is text}'
+ +

array

+

Load raw data array into current frame.
+

+ Syntax:
+ -array +<filename>[[xdim=<x>,ydim=<y>|dim=<dim>],zdim=<z>,bitpix=<b>,skip=<s>,endian=[little|big]]
+  
+ Example:
+ $ds9 -array foo.arr[dim=512,bitpix=-32,endian=little]
+ $cat foo.arr | ds9 -array -[dim=512,bitpix=-32,endian=little]
+ +

asinh

+

Select ASINH scale function for the current frame.

+ Syntax:
+ -asinh
+  
+ Example:
+ $ds9 -asinh
+

bg
+ background

+

Set image background color.

+ Syntax:
+ -bg <color>
+  
+ Example:
+ $ds9 -background red
+ $ds9 -bg red
+

backup

+

Create a backup save set.

+ Syntax:
+ -backup <filename>
+  
+ Example:
+ $ds9 -backup ds9.bck
+

bin

+

Controls binning factor, binning buffer size, and  binning + function for binning FITS bin tables.

+ Syntax:
+ -bin [about <x> <y>]
+      [about center]
+      [buffersize <value>]
+      [cols <x> <y>]
+      [colsz <x> <y> <z>]
+      [factor <value> [<value>]] +
+      [depth <value>]
+      [filter <string>]
+      [function average|sum]
+      [in]
+      [out]
+      [to fit]
+      [match]
+      [lock [yes|no]]
+      [open|close]
+  
+ Example:
+ $ds9 -bin about 4096 4096
+ $ds9 -bin about center
+ $ds9 -bin buffersize 512
+ $ds9 -bin cols detx dety
+ $ds9 -bin colsz detx dety time
+ $ds9 -bin factor 4
+ $ds9 -bin factor 4 2
+ $ds9 -bin depth 10
+ $ds9 -bin filter 'pha > 5'
+ $ds9 -bin filter ''
+ $ds9 -bin function sum
+ $ds9 -bin in
+ $ds9 -bin out
+ $ds9 -bin to fit
+ $ds9 -bin match
+ $ds9 -bin lock yes
+ $ds9 -bin open
+ $ds9 -bin close
+ +

blink

+

Blink mode parameters. Interval is in seconds.

+ Syntax:
+ -blink []
+        [yes|no]
+        [interval <value>]
+  
+ Example:
+ $ds9 -blink
+ $ds9 -blink yes
+ $ds9 -blink interval 1
+

block

+

Controls blocking parameters.

+ Syntax:
+ -block [<value>]
+        [<value> + <value>]
+        [to <value>]
+        [to <value> + <value>]
+        [in]
+        [out]
+        [to fit]
+        [match]
+        [lock [yes|no]]
+        [open|close]
+  
+ Example:
+ $ds9 -block 4
+ $ds9 -block 4 2
+ $ds9 -block to 4
+ $ds9 -block to 4 2
+ $ds9 -block in
+ $ds9 -block + out
+ $ds9 -block to fit
+ $ds9 -block match
+ $ds9 -block lock yes
+ $ds9 -block open
+ $ds9 -block close
+ +

blue

+

For RGB frames, sets the current color channel to blue.

+ Syntax:
+ -blue
+  
+ Example:
+ $ds9 -blue foo.fits
+ +

catalog
+ cat

+

Support for catalogs. The first three commands will create a + new catalog search. All other commands operated on the last + search created, unless indicated otherwise.

+ Syntax:
+ -catalog []
+         + [ned|simbad|denis|skybot]
+         + [ascss|cmc|gsc1|gsc2|gsc3|ac|nomad|ppmx|sao|sdss5|sdss6|sdss7|sdss8|tycho|ua2|ub1|ucac2]
+         [2mass|iras]
+         [csc|xmm|rosat]
+         [first|nvss]
+         + [chandralog|cfhtlog|esolog|stlog|xmmlog]
+         [cds <catalogname>]
+         [cds + <catalogid>]
+
+         [load <filename>]
+         [import sb|tsv + <filename>]
+
+         [<ref>] [allcols]
+         + [<ref>] [allrows]
+         [<ref>] + [cancel]
+         [<ref>] + [clear]
+         [<ref>] [close]
+         [<ref>] + [coordinate <ra> <dec> <coordsys>]
+         [<ref>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [crosshair]
+         [<ref>] [dec + <col>]
+         [<ref>] [edit + yes|no]
+         [<ref>] + [export sb|tsv <filename>]
+         [<ref>] + [filter <string>]
+         [<ref>] [filter load + <filename>]
+         [<ref>] + [header]
+         [<ref>] [hide]
+         [<ref>] [location + <code>]
+         [<ref>] + [match <ref> <ref>]
+         [<ref>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [match error <value> degrees|arcmin|arcsec]
+         [<ref>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [match function 1and2|1not2|2not1]
+         [<ref>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [match return 1and2|1only|2only]
+         [<ref>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [match unique yes|no]
+         [<ref>] [maxrows + <number>]
+         [<ref>] [name + <object>]
+         [<ref>] + [panto yes|no]
+         [<ref>] [plot + <xcol> <ycol> <xerrcol> <yerrcol>]
+         [<ref>] [print]
+         [<ref>] [psky + <skyframe>]
+         [<ref>] [psystem + <coordsys>]
+         [<ref>] [ra + <col>]
+         [<ref>] + [regions]
+         [<ref>] + [retrieve]
+         [<ref>] + [samp]
+         [<ref>] [samp + broadcast]
+         [<ref>] [samp + send <application>]
+         [<ref>] + [save <filename>]
+         [<ref>] + [server cds|sao|cadc|adac|iucaa|bejing|cambridge|ukirt]
+         [<ref>] [show]
+         [<ref>] [size + <width> <height> degrees|arcmin|arcsec]
+         [<ref>] + [sky <skyframe>]
+         [<ref>] + [skyformat <skyformat>]
+         [<ref>] [sort + <col> incr|decr]
+         [<ref>] [symbol + [#] + condition|shape|color|text|font|fontsize|fontweight|fontslant + <value>]
+         [<ref>] + [symbol [#] text|size|size2|units|angle <value>]
+         [<ref>] + [symbol shape {circle point}|{box point}|{diamond point}|
+             +         {cross point}|{x + point}|{arrow point}|{boxcircle point}|
+              +        circle|ellipse|box|text]
+         [<ref>] [symbol + add| [#] remove]
+         [<ref>] [symbol + save|load <filename>]
+         [<ref>] [system + <coordsys>]
+         [<ref>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [update]
+         [<ref>] [x + <col>]
+         [<ref>] [y + <col>]
+
+ Example:
+ $ds9 -catalog
+ $ds9 -catalog 2mass
+ $ds9 -catalog cds 2mass
+ $ds9 -catalog cds "I/252"
+
+ $ds9 -catalog load foo.xml
+ $ds9 -catalog import tsv foo.tsv
+
+ $ds9 -catalog allrows
+ $ds9 -catalog allcols
+ $ds9 -catalog cancel
+ $ds9 -catalog clear
+ $ds9 -catalog close
+ $ds9 -catalog coordinate 202.48 47.21 fk5
+ $ds9 -catalog crosshair
+ $ds9 -catalog dec DEC
+ $ds9 -catalog edit yes
+ $ds9 -catalog export tsv bar.tsv
+ $ds9 -catalog filter '\$Jmag>15'
+ $ds9 -catalog filter load foo.flt
+ $ds9 -catalog header
+ $ds9 -catalog hide
+ $ds9 -catalog location 500
+ $ds9 -catalog match error 2 arcsec
+ $ds9 -catalog match function 1and2
+ $ds9 -catalog match unique no
+ $ds9 -catalog match return 1only
+ $ds9 -catalog match 2mass csc
+ $ds9 -catalog maxrows 2000
+ $ds9 -catalog name m51
+ $ds9 -catalog panto no
+ $ds9 -catalog plot '\$Jmag' '\$Hmag' '\$e_Jmag' + '\$e_Hmag'
+ $ds9 -catalog print
+ $ds9 -catalog psky fk5
+ $ds9 -catalog psystem wcs
+ $ds9 -catalog ra RA
+ $ds9 -catalog regions
+ $ds9 -catalog retrieve
+ $ds9 -catalog samp broadcast
+ $ds9 -catalog samp send aladin
+ $ds9 -catalog save foo.xml
+ $ds9 -catalog server sao
+ $ds9 -catalog show
+ $ds9 -catalog size 1 1 degrees
+ $ds9 -catalog symbol condition '\$Jmag>15'
+ $ds9 -catalog symbol 2 shape "boxcircle point"
+ $ds9 -catalog symbol color red
+ $ds9 -catalog symbol font times
+ $ds9 -catalog symbol fontsize 14
+ $ds9 -catalog symbol fontweight bold
+ $ds9 -catalog symbol fontslant italic
+ $ds9 -catalog symbol add
+ $ds9 -catalog symbol 2 remove
+ $ds9 -catalog symbol load foo.sym
+ $ds9 -catalog symbol save bar.sym
+ $ds9 -catalog sky fk5
+ $ds9 -catalog skyformat degrees
+ $ds9 -catalog sort "Jmag" incr
+ $ds9 -catalog system wcs
+ $ds9 -catalog update
+ $ds9 -catalog x RA
+ $ds9 -catalog y DEC
+

cd

+

Sets the current working directory.

+ Syntax:
+ cd [<directory>]
+  
+ Example:
+ $ds9 -cd /home/mrbill
+ +

cmap

+

Controls the colormap for the current frame. The colormap name + is not case sensitive. A valid contrast value is  from 0 to + 10 and bias value from 0 to 1.

+ Syntax:
+ -cmap [<colormap>]
+       [file]
+       [load <filename>]
+       [save <filename>]
+       [invert yes|no]
+       [value <contrast> + <bias>]
+       [tag [load|save] + <filename>]
+       [tag delete]
+       [match]
+       [lock [yes|no]]
+       [open|close]
+  
+ Example:
+ $ds9 -cmap Heat
+ $ds9 -cmap load foo.sao
+ $ds9 -cmap save bar.sao
+ $ds9 -cmap invert yes
+ $ds9 -cmap value 5 .5
+ $ds9 -cmap tag load foo.tag
+ $ds9 -cmap tag save foo.tag
+ $ds9 -cmap tag delete
+ $ds9 -cmap match
+ $ds9 -cmap lock yes
+ $ds9 -cmap open
+ $ds9 -cmap close
+ +

colorbar

+

Controls colorbar parameters.

+ Syntax:
+ -colorbar []
+           [yes|no]
+           + [horizontal|vertical]
+           [orientation + horizontal|vertical]
+           [numerics + yes|no]
+           [space + value|distance]
+           [font + times|helvetica|courier]
+           [fontsize + <value>]
+           + [fontweight normal|bold]
+           [fontslant + roman|italic]
+           [size]
+           [ticks]
+  
+ Example:
+ $ds9 -colorbar yes
+ $ds9 -colorbar vertical
+ $ds9 -colorbar orientation vertical
+ $ds9 -colorbar numerics yes
+ $ds9 -colorbar space value
+ $ds9 -colorbar font times
+ $ds9 -colorbar fontsize 14
+ $ds9 -colorbar fontweight bold
+ $ds9 -colorbar fontslant italic
+ $ds9 -colorbar size 20
+ $ds9 -colorbar ticks 11
+ +

console

+

Display tcl console window.

+ Syntax:
+ -console
+  
+ Example:
+ $ds9 -console
+ +

contour
+

+

Controls contours in the current frame.

+ Syntax:
+ -contour []
+          [yes|no]
+          [clear]
+          [generate]
+          [load + <filename> [<color> <width> yes|no]]
+          [save + <filename> <coordsys> <skyframe>]
+          [convert]
+          [loadlevels + <filename>]
+          + [savelevels <filename>]
+          [copy]
+          [paste + <coordsys> [<color> <width> yes|no]]
+          [color + <color>]
+          [width + <width>]
+          [dash yes|no]
+          [smooth + <smooth>]
+          [method + block|smooth]
+          [nlevels <number + of levels>]
+          [scale + linear|log|pow|squared|sqrt|asinh|sinh|histequ]
+          [log exp + <value>]
+          [mode + minmax|<value>|zscale|zmax]
+          [limits <min> + <max>]
+          [levels + <value value value...>]
+          [open|close]
+  
+ Example:
+ $ds9 -contour
+ $ds9 -contour yes
+ $ds9 -contour generate
+ $ds9 -contour clear
+ $ds9 -contour load ds9.ctr
+ $ds9 -contour load ds9.ctr red 2 yes
+ $ds9 -contour save ds9.ctr wcs fk5
+ $ds9 -contour convert
+ $ds9 -contour loadlevels ds9.ctr
+ $ds9 -contour savelevels ds9.lev
+ $ds9 -contour copy
+ $ds9 -contour paste wcs red 2 no
+ $ds9 -contour color yellow
+ $ds9 -contour width 2
+ $ds9 -contour dash yes
+ $ds9 -contour smooth 5
+ $ds9 -contour method smooth
+ $ds9 -contour nlevels 10
+ $ds9 -contour scale sqrt
+ $ds9 -contour log exp 1000
+ $ds9 -contour mode zscale
+ $ds9 -contour limits 1 100
+ $ds9 -contour levels "1 10 100 1000"
+ $ds9 -contour open
+ $ds9 -contour close
+ +

crop

+

Set current image display area.

+ Syntax:
+ -crop [<x> <y> <width> <height> +[<coordsys>][<skyframe>][<skyformat>][degrees|arcmin|arcsec]
+       [match <coordsys>]
+       [lock <coordsys>|none] +
+  
+ Example:
+ $ds9 foo.fits -crop 40 30 10 20 # set crop in physical coords
+ $ds9 foo.fits -crop +104:51:06.915 +68:33:40.761  28.144405 + 22.000204 wcs galactic arcsec
+ $ds9 foo.fits -crop match wcs
+ $ds9 foo.fits -crop lock wcs
+ +

crosshair

+

Controls the current position of the crosshair in the current + frame. DS9 is placed in crosshair mode when the crosshair is + set.

+ Syntax:
+ -crosshair [<x> <h> <coordsys> + [<skyframe>][<skyformat>]]
+            + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [match <coordsys>]
+            [lock + <coordsys>|none]
+  
+ Example:
+ $ds9 -crosshair 100 100 physical # set crosshair in physical
+ $ds9 -crosshair 345 58.8 wcs fk5 # set crosshair in wcs coords
+ $ds9 -crosshair 23:01:00 +58:52:51 wcs fk5
+ $ds9 -crosshair match
+ $ds9 -crosshair lock wcs
+ +

cube
+

+

Controls FITS cube.

+ Syntax:
+ -cube [play|stop|next|prev|first|last]
+       [<slice> + [<coordsys>][<axis>]]
+       [interval <numeric>]
+       [axis <axis>]
+       [match <coordsys>]
+       [lock <coordsys>|none]
+       [order 123|132|213|231|312|321]
+       [axes lock [yes|no]]
+       [open|close]
+  
+ Example:
+ $ds9 -cube play
+ $ds9 -cube last
+ $ds9 -cube 3
+ $ds9 -cube 4.5 wcs 3
+ $ds9 -cube interval 2
+ $ds9 -cube axis 3
+ $ds9 -cube match wcs
+ $ds9 -cube lock wcs
+ $ds9 -cube order 123
+ $ds9 -cube axes lock yes
+ $ds9 -cube open
+ $ds9 -cube close
+

cursor

+

Move mouse pointer or crosshair in image pixels in the current + frame. Note, this will move selected Regions also.

+ Syntax:
+ -cursor [<x> <h>]
+  
+ Example:
+ $ds9 -cursor 10 10
+ +

dsssao
+ dss
+

+

Support for Digital Sky Survey at SAO.

+ Syntax:
+ -dsssao []
+         [<object>]
+         [name <object>]
+         [coord <ra> + <dec> degrees|sexagesimal] # in wcs fk5
+         [size <width> + <height> degrees|arcmin|arcsec]
+         [save yes|no]
+         [frame new|current]
+         [update + frame|crosshair]
+         [open|close]
+  
+ Example:
+ $ds9 -dsssao
+ $ds9 -dsssao m31
+ $ds9 -dsssao name m31
+ $ds9 -dsssao coord 00:42:44.404 +41:16:08.78 sexagesimal
+ $ds9 -dsssao size 60 60 arcmin
+ $ds9 -dsssao save yes
+ $ds9 -dsssao frame current
+ $ds9 -dsssao update frame
+ $ds9 -dsssao open
+ $ds9 -dsssao close
+ +

dsseso

+

Support for Digital Sky Survey at ESO.

+ Syntax:
+ -dsseso []
+         [<object>]
+         [name <object>]
+         [coord <ra> + <dec> degrees|sexagesimal] # in wcs fk5
+         [size <width> + <height> degrees|arcmin|arcsec]
+         [save yes|no]
+         [frame new|current]
+         [update + frame|crosshair]
+         [survey + DSS1|DSS2-red|DSS2-blue|DSS2-infrared]
+         [open|close]
+  
+ Example:
+ $ds9 -dsseso
+ $ds9 -dsseso m31
+ $ds9 -dsseso name m31
+ $ds9 -dsseso coord 00:42:44.404 +41:16:08.78 sexagesimal
+ $ds9 -dsseso size 60 60 arcmin
+ $ds9 -dsseso save yes
+ $ds9 -dsseso frame current
+ $ds9 -dsseso update frame
+ $ds9 -dsseso survey DSS2-red
+ $ds9 -dsseso open
+ $ds9 -dsseso close
+

dssstsci

+

Support for Digital Sky Survey at STSCI.

+ Syntax:
+ -dssstsci []
+           [<object>]
+           [name + <object>]
+           [coord + <ra> <dec> degrees|sexagesimal] # in wcs fk5
+           [size + <width> <height> degrees|arcmin|arcsec]
+           [save + yes|no]
+           [frame + new|current]
+           [update + frame|crosshair]
+           [survey + poss2ukstu_red|poss2ukstu_ir|poss2ukstu_blue]
+           [survey + poss1_blue|poss1_red]
+           [survey + all|quickv|phase2_gsc2|phase2_gsc1]
+           [open|close]
+  
+ Example:
+ $ds9 -dssstsci
+ $ds9 -dssstsci m31
+ $ds9 -dssstsci name m31
+ $ds9 -dssstsci coord 00:42:44.404 +41:16:08.78 sexagesimal
+ $ds9 -dssstsci size 60 60 arcmin
+ $ds9 -dssstsci save yes
+ $ds9 -dssstsci frame current
+ $ds9 -dssstsci update frame
+ $ds9 -dssstsci survey all
+ $ds9 -dssstsci open
+ $ds9 -dssstsci close
+

envi

+

Load an ENVI header and file. Optional parameter: array endian.
+

+ Syntax:
+ -envi <header> [<filename>]
+  
+ Example:
+ $ds9 -envi foo.hdr
+ $ds9 -envi + foo.hdr foo.bsq
+ +

exit
+ quit

+

Quits DS9.

+ Syntax:
+ -exit
+ -quit
+  
+ Example:
+ $ds9 -exit
+ +

export
+

+

Export loaded image data of current frame in specified image + format, at native resolution, using current colormap and + contrast/bias settings. NOTE: not scaling, rotation, or + translation is applied. If no format specified, the file name + extension is used to determine the output format. Optional + parameters: jpeg quality (1-100) and tiff compression method.
+

+ Syntax:
+ -export [array|nrrd|envi|gif|tiff|jpeg|png] <filename>
+ -export array <filename> [big|little|native]
+ -export nrrd <filename> [big|little|native]
+ -export envi <header> [<filename>] [big|little|native] +
+ -export <filename>.jpeg [1-100]
+ -export <filename>.tiff + [none|jpeg|packbits|deflate]
+  
+ Example:
+ $ds9 -export array foo.arr little
+ $ds9 -export nrrd foo.nrrd little
+ $ds9 -export envi foo.hdr little
+ $ds9 -export envi foo.hdr foo.bsq little
+ $ds9 -export tiff foo.tiff jpeg
+ $ds9 -export jpeg foo.jpeg 75
+ $ds9 -export png foo.png
+

fifo

+

Set the name of the IRAF input and output fifos. The default is + /dev/imt1. These fifos are used by IRAF to communicate with DS9. +

+ Syntax:
+ -fifo name
+  
+ Example:
+ $ds9 -fifo /dev/imt1 +

fifo_only

+

Only use IRAF input and output fifos. Same as -port 0 -unix + none.

+ Syntax:
+ -fifo_only
+  
+ Example:
+ $ds9 -fifo_only
+ +

fits

+

Load a FITS image into the current frame.
+

+ Syntax:
+ -fits <filename>
+  
+ Example:
+ $ds9 -fits foo.fits
+ $ds9 -fits bar.fits[bin=detx,dety]
+ $cat foo.fits | ds9 -fits -
+ $cat bar.fits | ds9 -fits -[bin=detx,dety]
+ +

frame

+

Controls frame functions. Frames may be created, deleted, + reset, and centered. While return the current frame number. If + you goto a frame that does not exists, it will be created. If + the frame is hidden, it will be shown. The 'frameno' option is + available for backward compatibility.

+ Syntax:
+ -frame [center [#|all]]
+        [clear [#|all]]
+        [new [rgb]]
+        [delete [#|all]]
+        [reset [#|all]]
+        [refresh [#|all]]
+        [hide [#|all]]
+        [show [#|all]]
+        [move first]
+        [move back]
+        [move forward]
+        [move last]
+        [first]
+        [prev]
+        [next]
+        [last]
+        [frameno #]
+        [#]
+        [match <coordsys>]
+        [lock + <coordsys>|none]
+  
+ Example:
+ $ds9 -frame center # center current frame
+ $ds9 -frame center 1 # center 'Frame1'
+ $ds9 -frame center all # center all frames
+ $ds9 -frame clear # clear current frame
+ $ds9 -frame new # create new frame
+ $ds9 -frame new rgb # create new rgb frame
+ $ds9 -frame delete # delete current frame
+ $ds9 -frame reset # reset current frame
+ $ds9 -frame refresh # refresh current frame
+ $ds9 -frame hide # hide current frame
+ $ds9 -frame show 1 # show frame 'Frame1'
+ $ds9 -frame move first # move frame to first in order
+ $ds9 -frame move back # move frame back in order
+ $ds9 -frame move forward # move frame forward in order
+ $ds9 -frame move last # move frame to last in order
+ $ds9 -frame first # goto first frame
+ $ds9 -frame prev # goto prev frame
+ $ds9 -frame next # goto next frame
+ $ds9 -frame last # goto last frame
+ $ds9 -frame frameno 4 # goto frame 'Frame4', create if needed
+ $ds9 -frame 3 # goto frame 'Frame3', create if needed
+ $ds9 -frame lock wcs
+

gif

+

Import gif file.

+ Syntax:
+ -gif <filename>
+  
+ Example:
+ $ds9 -gif foo.gif
+ $cat foo.gif | ds9 -gif -
+ +

geometry

+

Define the initial window geometry. This includes all of the + ds9 window, not just the image space. see X(1).

+ Syntax:
+ -geometry value
+  
+ Example:
+ $ds9 -geometry 640x480 +

green

+

For RGB frames, sets the current color channel to green.

+ Syntax:
+ -green
+  
+ Example:
+ $ds9 -green foo.fits +

grid

+

Controls coordinate grid. For grid numeric format syntax,  + click here.

+ Syntax:
+ -grid []
+       [yes|no]
+       [type analysis|publication]
+       [system <coordsys>]
+       [sky <skyframe>]
+       [skyformat <skyformat>]
+       [grid yes|no]
+       [grid color <color>]
+       [grid width <value>]
+       [grid style 0|1]
+       [grid gap1 <value>]
+       [grid gap2 <value>]
+       [axes yes|no]
+       [axes color <color>]
+       [axes width <value>]
+       [axes style 0|1]
+       [axes type interior|exterior]
+       [axes origin + lll|llu|lul|luu|ull|ulu|uul|uuu]
+       [format1 <format>]
+       [format2 <format>]
+       [tickmarks yes|no]
+       [tickmarks color <color>]
+       [tickmarks width <value>]
+       [tickmarks style 0|1]
+       [border yes|no]
+       [border color <color>]
+       [border width <value>]
+       [border style 0|1]
+       [numerics yes|no]
+       [numerics font + times|helvetica|courier]
+       [numerics fontsize <value>]
+       [numerics fontweight normal|bold]
+       [numerics fontslant roman|italic]
+       [numerics color <color>]
+       [numerics gap1 <value>]
+       [numerics gap2 <value>]
+       [numerics type interior|exterior]
+       [numerics vertical yes|no]
+       [title yes|no]
+       [title text <text>]
+       [title def yes|no]
+       [title gap <value>]
+       [title font + times|helvetica|courier]
+       [title fontsize <value>]
+       [title fontweight normal|bold]
+       [title fontslant roman|italic]
+       [title color <color>]
+       [labels yes|no]
+       [labels text1 <text>]
+       [labels def1 yes|no]
+       [labels gap1 <value>]
+       [labels text2 <text>]
+       [labels def2 yes|no]
+       [labels gap2 <value>]
+       [labels font + times|helvetica|courier]
+       [labels fontsize <value>]
+       [labels fontweight normal|bold]
+       [labels fontslant roman|italic]
+       [labels color <color>]
+       [reset]
+       [load <filename>]
+       [save <filename>]
+       [open|close]
+  
+ Example:
+ $ds9 -grid
+ $ds9 -grid yes
+ $ds9 -grid type analysis
+ $ds9 -grid system wcs
+ $ds9 -grid sky fk5
+ $ds9 -grid skyformat degrees
+ $ds9 -grid grid yes
+ $ds9 -grid grid color red
+ $ds9 -grid grid width 2
+ $ds9 -grid grid style 1
+ $ds9 -grid grid gap1 10
+ $ds9 -grid grid gap2 10
+ $ds9 -grid axes yes
+ $ds9 -grid axes color red
+ $ds9 -grid axes width 2
+ $ds9 -grid axes style 1
+ $ds9 -grid axes type exterior
+ $ds9 -grid axes origin lll
+ $ds9 -grid format1 d.2
+ $ds9 -grid format2 d.2
+ $ds9 -grid tickmarks yes
+ $ds9 -grid tickmarks color red
+ $ds9 -grid tickmarks width 2
+ $ds9 -grid tickmarks style 1
+ $ds9 -grid border yes
+ $ds9 -grid border color red
+ $ds9 -grid border width 2
+ $ds9 -grid border style 1
+ $ds9 -grid numerics yes
+ $ds9 -grid numerics font courier
+ $ds9 -grid numerics fontsize 12
+ $ds9 -grid numerics fontweight bold
+ $ds9 -grid numerics fontslant italic
+ $ds9 -grid numerics color red
+ $ds9 -grid numerics gap1 10
+ $ds9 -grid numerics gap2 10
+ $ds9 -grid numerics type exterior
+ $ds9 -grid numerics vertical yes
+ $ds9 -grid title yes
+ $ds9 -grid title text {Hello World}
+ $ds9 -grid title def yes
+ $ds9 -grid title gap 10
+ $ds9 -grid title font courier
+ $ds9 -grid title fontsize 12
+ $ds9 -grid title fontweight bold
+ $ds9 -grid title fontslant italic
+ $ds9 -grid title color red
+ $ds9 -grid labels yes
+ $ds9 -grid labels text1 {Hello World}
+ $ds9 -grid labels def1 yes
+ $ds9 -grid labels gap1 10
+ $ds9 -grid labels text2 {Hello World}
+ $ds9 -grid labels def2 yes
+ $ds9 -grid labels gap2 10
+ $ds9 -grid labels font courier
+ $ds9 -grid labels fontsize 12
+ $ds9 -grid labels fontweight bold
+ $ds9 -grid labels fontslant italic
+ $ds9 -grid labels color red
+ $ds9 -grid reset
+ $ds9 -grid load foo.grd
+ $ds9 -grid save foo.grd
+ $ds9 -grid open
+ $ds9 -grid close
+ +

header

+

Display current fits header dialog. Optional extension number + maybe specified.

+ Syntax:
+ -header [<ext>]
+         [close [<ext>]]
+         [save [<ext>] + <filename>]
+  
+ Example:
+ $ds9 -header
+ $ds9 -header 2
+ $ds9 -header close
+ $ds9 -header save 1 foo.txt
+ +

height

+

Set the height of the image display window. Use the geometry command to set the + overall width and height of the ds9 window.

+ Syntax:
+ -height [<value>]
+  
+ Example:
+ $ds9 -height 512
+ +

help

+

Display help information. To maintain backward compatibility, + -help will display a brief help message and exit. --help will + display all command line options within the built-in help + facility.

+ Syntax:
+ -help # Display brief help message and exit.
+ --help # Display command line options within help facility.
+ -? # Display command line options within help facility.
+  
+ Example:
+ $ds9 -help # Display brief help message and exit.
+ $ds9 --help # Display command line options within help facility
+ $ds9 -? # Display command line options within help facility.
+ +

histequ

+

Select histogram equalization scale function for the current + frame.

+ Syntax:
+ -histequ
+  
+ Example:
+ $ds9 -histequ
+ +

iconify

+

Toggles iconification.

+ Syntax:
+ -iconify []
+          [yes|no]
+  
+ Example:
+ $ds9 -iconify
+ $ds9 -iconify yes
+

invert

+

Invert Colormap.

+ Syntax:
+ -invert
+  
+ Example:
+ $ds9 -invert
+ +

iis

+

Set IIS Filename. Optional mosaic number maybe supplied.

+ Syntax:
+ -iis [filename <filename> [#]]
+  
+ Example:
+ $ds9 -iis filename foo.fits
+ $ds9 -iis filename bar.fits 4
+

jpeg

+

Load JPEG image into current frame.

+ Syntax:
+ -jpeg <filename>
+  
+ Example:
+ $ds9 -jpeg foo.jpeg
+ $cat foo.jpeg | ds9 -jpeg -
+

language

+

Select current language.

+ Syntax:
+ -language [locale|da|de|es|en|fr|ja|pt]
+  
+ Example:
+ $ds9 -language fr
+ +

linear

+

Select linear scale function for the current frame.

+ Syntax:
+ -linear
+  
+ Example:
+ $ds9 -linear +

lock

+

Lock all other frames to the current frame.

+ Syntax:
+ -lock [frame <coordsys>|none]
+       [crosshair + <coordsys>|none]
+       [crop <coordsys>|none]
+       [slice <coordsys>|none]
+       [bin [yes|no]]
+       [axes [yes|no]]
+       [scale [yes|no]]
+       [scalelimits [yes|no]]
+       [colorbar [yes|no]]
+       [block [yes|no]]
+       [smooth [yes|no]]
+
+ Example:
+ $ds9 -lock frame wcs
+ $ds9 -lock crosshair wcs
+ $ds9 -lock crop wcs
+ $ds9 -lock slice wcs
+ $ds9 -lock bin yes
+ $ds9 -lock axes yes
+ $ds9 -lock scale yes
+ $ds9 -lock scalelimits yes
+ $ds9 -lock colorbar yes
+ $ds9 -lock block yes
+ $ds9 -lock smooth yes
+ +

log

+

Select log scale function for the current frame.
+

+ Syntax:
+ -log
+  
+ Example:
+ $ds9 -log +

lower

+

Lower in the window stacking order.

+ Syntax:
+ -lower
+  
+ Example:
+ $ds9 -lower
+ +

magnifier

+

Controls the magnifier settings.

+ Syntax:
+ magnifier [color <color>]
+           [zoom + <value>]
+           [cursor + yes|no]
+           [region + yes|no]
+  
+ Example:
+ $ds9 -magnifier color yellow
+ $ds9 -magnifier zoom 2
+ $ds9 -magnifier cursor no
+ $ds9 -magnifier region no
+ +

mask
+ nomask
+

+

Controls mask parameters.

+ Syntax:
+ -mask [color <color>]
+       [mark 1|0]
+       [transparency <value>]
+       [clear]
+       [open|close]
+ -nomask
+  
+ Example:
+ $ds9 -mask color red
+ $ds9 -mask mark 0
+ $ds9 -mask transparency 50
+ $ds9 -mask clear
+ $ds9 -mask open
+ $ds9 -mask close
+ $ds9 -nomask
+ +

match

+

Match all other frames to the current frame.

+ Syntax:
+ -match [frame <coordsys>]
+        [crosshair + <coordsys>]
+        [crop + <coordsys>]
+        [slice <coordsys>]
+        [bin]
+        [axes]
+        [scale]
+        [scalelimits]
+        [colorbar]
+        [block]
+        [smooth]
+  
+ Example:
+ $ds9 -match frame wcs
+ $ds9 -match crosshair wcs
+ $ds9 -match crop wcs
+ $ds9 -match slice wcs
+ $ds9 -match bin
+ $ds9 -match axes
+ $ds9 -match scale
+ $ds9 -match scalelimits
+ $ds9 -match colorbar
+ $ds9 -match block
+ $ds9 -match smooth
+
+ mecube +

Load FITS multiple extension file as data cube.
+

+ Syntax:
+ mecube <filename>
+  
+ Example:
+ $ds9 -mecube foo.fits
+ $cat foo.fits | ds9 -mecube -
+

minmax

+

This is how DS9 determines  the min and max data values + from the data. SCAN will scan all data.

+ Syntax:
+ -minmax [scan|sample|datamin|irafmin]
+         [mode + scan|sample|datamin|irafmin]
+         [interval #]
+  
+ Example:
+ $ds9 -minmax scan
+ $ds9 -minmax mode scan
+ $ds9 -minmax interval 100
+ +

mode

+

Select the current mode.

+ Syntax:
+ -mode + [none|region|crosshair|colorbar|pan|zoom|rotate|catalog|examine] +
+  
+ Example:
+ $ds9 -mode crosshair
+

mosaic

+

Load FITS mosaic segment into current frame.

+ Syntax:
+ -mosaic [wcs|wcsa...wcsz|iraf] <filename>
+  
+ Example:
+ $ds9 -mosaic foo.fits
+ $ds9 -mosaic wcs foo.fits
+ $cat foo.fits | ds9 -mosaic -
+ $cat foo.fits | ds9 -mosaic wcs -
+ +

mosaicimage

+

Load FITS mosaic image into current frame.

+ Syntax:
+ -mosaicimage [wcs|wcsa...wcsz|iraf|wfpc2] <filename>
+  
+ Example:
+ $ds9 -mosaicimage foo.fits
+ $ds9 -mosaicimage wcs foo.fits
+ $cat foo.fits | ds9 -mosaicimage
+ $cat foo.fits | ds9 -mosaiimage wcs
+ +

movie
+ savempeg
+

+

Create mpeg1 movie from snap shots of the DS9 window. A slice + movie cycles though all slices of a cube. A frame + movie cycles through all active frames. A 3d movie + cycles through specified viewing angles. The default is frame. + Optional parameters for 3d: number of frames, azimuth + from/to, elevation from/to, slice from/to, oscillate/repeat + times.
+

+ Syntax:
+ -movie [slice|frame|3d] <filename>
+ -movie 3d <filename> + [number|azfrom|azto|elfrom|elto|slfrom|slto|oscillate|repeat + <#>]
+  
+ Example:
+ $ds9 -movie slice ds9.mpg
+ $ds9 -movie 3d ds9.mpg number 10 azfrom -60 azto 60 oscillate 1
+

msg

+

Specify a directory of translation tables to be loaded.

+ Syntax:
+ -msg <directory>
+  
+ Example:
+ $ds9 -msg $HOME/msgs
+

multiframe

+

Load FITS multiple extension file as multiple images.
+

+ Syntax:
+ multiframe <filename>
+  
+ Example:
+ $ds9 -multiframe foo.fits
+ $cat foo.fits | ds9 -multiframe -
+ +

nameserver

+

Support Name Server functions. Coordinates are in fk5.

+ Syntax:
+ -nameserver [<object>]
+             [name <object>]
+             [server + ned-sao|ned-eso|simbad-sao|simbad-eso]
+             [skyformat + degrees|sexagesimal]
+             + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [pan]
+             + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [crosshair]
+             + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [open|close]
+  
+ Example:
+ $ds9 -nameserver m31
+ $ds9 -nameserver name m31
+ $ds9 -nameserver server ned-sao
+ $ds9 -nameserver skyformat sexagesimal
+ $ds9 -nameserver pan
+ $ds9 -nameserver crosshair
+ $ds9 -nameserver open
+ $ds9 -nameserver close
+ +

nan

+

Set image not-a-number color.

+ Syntax:
+ -nan <color>
+  
+ Example:
+ $ds9 -nan red
+

nrrd

+

Load an NRRD (Nearly Raw Raster Data) file.
+

+ Syntax:
+ -nrrd <filename>
+  
+ Example:
+ $ds9 -nrrd foo.nrrd
+ $cat foo.nrrd | xpaset ds9 -nrrd -
+ +

nvss

+

Support for NRAO VLA Sky Survey.

+ Syntax:
+ -nvss []
+       [<object>]
+       [name <object>]
+       [coord <ra> <dec> + degrees|sexagesimal] # in wcs fk5
+       [size <width> + <height> degrees|arcmin|arcsec]
+       [save yes|no]
+       [frame new|current]
+       [update frame|crosshair]
+       [open|close]
+  
+ Example:
+ $ds9 -nvss
+ $ds9 -nvss m31
+ $ds9 -nvss name m31
+ $ds9 -nvss coord 00:42:44.404 +41:16:08.78 sexagesimal
+ $ds9 -nvss size 60 60 arcmin
+ $ds9 -nvss save yes
+ $ds9 -nvss frame current
+ $ds9 -nvss update frame
+ $ds9 -nvss open
+ $ds9 -nvess close
+ +

orient

+

Controls the orientation of the current frame.

+ Syntax:
+ -orient [none|x|y|xy]
+         [open|close]
+  
+ Example:
+ $ds9 -orient xy
+ $ds9 -orient open
+ $ds9 -orient close
+ +

pagesetup

+

Controls Page Setup options.
+

+ Syntax:
+ -pagesetup [orient portrait|landscape]
+            + [scale <numberic>]
+            + [size letter|legal|tabloid|poster|a4]
+  
+ Example:
+ $ds9 -pagesetup orient portrait
+ $ds9 -pagesetup scale 50
+ $ds9 -pagesetup size poster
+

pan

+

Controls the current image cursor location for the current + frame.

+ Syntax:
+ -pan [<x> <h> <coordsys> + [<skyframe>][<skyformat>] # relative
+      [to <x> <h> + <coordsys> [<skyframe>][<skyformat>] # + absolute
+      [open|close]
+  
+ Example:
+ $ds9 -pan 200 200 image # pan relative
+ $ds9 -pan to 400 400 physical # pan to physical + coords
+ $ds9 -pan to 13:29:55 47:11:50 wcs fk # pan to wcs + coords
+ $ds9 -pan open
+ $ds9 -pan close
+

pixeltable

+

Display/Hide the pixel table.

+ Syntax:
+ -pixeltable []
+             + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [yes|open]
+             + [no|close]
+  
+ Example:
+ $ds9 -pixeltable
+ $ds9 -pixeltable yes
+ $ds9 -pixeltable open
+ $ds9 -pixeltable close
+ +

plot

+
+

Display and configure data plots. All plot commands take an + optional second command, the plot name. If no plot name is + specified, the last plot created is assumed. Plot data is + assumed to be a pair of coordinates, with optional error values. + The follow are valid data descriptions:

+

xy        x and y coordinates
+ xyex      x,y coordinates with x errors
+ xyey      x,y coordinates with y errors
+ xyexey    x,y coordinates with  x and y + errors
+

+

To create a new plot, use the plot new command.

+ Syntax:
+ # create new empty plot window
+ -plot
+ -plot [bar|scatter]
+       [new [name <plotname>] + [line|bar|scatter]]
+       [new [name <plotname>] + [line|bar|scatter] <title> <xaxis label> <yaxis + label> xy|xyex|xyey|xyexey]
+
+ -plot [<plotname>] load <filename> + [xy|xyex|xyey|xyexey]
+       [<plotname>] save + <filename>
+       [<plotname>] clear
+       [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + duplicate
+    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +    [<plotname>] stats
+       [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + list
+       [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + loadconfig <filename>
+       [<plotname>] saveconfig + <filename>
+    +    [<plotname>] pagesetup orient + [portrait|landscape]
+       [<plotname>] pagesetup size + [letter|legal|tabloid|poster|a4]
+    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +    [<plotname>] print
+       [<plotname>] print + destination [printer|file]
+       [<plotname>] print + command <command>
+       [<plotname>] print + filename <filename>
+       [<plotname>] print color + [rgb|gray]
+       [<plotname>] close
+
+ -plot [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + mode [pointer|zoom]
+
+ # configure graph
+ -plot [<plotname>] axis [x|y] grid [yes|no]
+       [<plotname>] axis [x|y] log + [yes|no]
+       [<plotname>] axis [x|y] + flip [yes|no]
+       [<plotname>] axis [x|y] auto + [yes|no]
+       [<plotname>] axis [x|y] min + <value>
+       [<plotname>] axis [x|y] + max <value>
+       [<plotname>] axis [x|y] format + <string>
+       [<plotname>] + legend [yes|no]
+       [<plotname>] legend position + [right|left|top|bottom]
+       [<plotname>] font + [title|labels|numbers] font [times|helvetica|courier]
+       [<plotname>] font [title|labels|numbers] + size <value>
+       [<plotname>] font [title|labels|numbers] + weight [normal|bold]
+       [<plotname>] font [title|labels|numbers] + slant [roman|italic]
+       [<plotname>] title + <string>
+       [<plotname>] title [x|y] + <string>
+       [<plotname>] barmode + [normal|stacked|aligned|overlap]
+
+ # configure current dataset
+ -plot [<plotname>] show [yes|no]
+       [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + shape + [circle|square|diamond|plus|splus|scross|triangle|arrow]
+       [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + shape fill [yes|no]
+       + [<plotname>] + shape color <value>
+   + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +     [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + smooth + [step|linear|cubic|quadratic|catrom]
+    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +    + [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + color + <value>
+     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +   [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + width + <value>
+   + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + dash [yes|no]
+    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +    + [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + error [yes|no]
+   + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +     + [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + error color + <value>
+    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +    + [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + error width + <value>
+     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +   [<plotname>] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + name + <string>
+ # select current dataset
+ -plot [<plotname>] select <value>
+  
+ Example:
+ # create new empty plot window
+ $ds9 -plot
+ $ds9 -plot scatter
+ $ds9 -plot new
+ $ds9 -plot new bar
+ $ds9 -plot new name foo
+ $ds9 -plot new name foo scatter
+
+ $ds9 -plot load foo.dat xy # load new dataset with dimension + xy
+ $ds9 -plot save bar.dat # save current dataset
+ $ds9 -plot clear # clear all datasets
+ $ds9 -plot duplicate # duplicate current dataset
+ $ds9 -plot stats # display current dataset statistics
+ $ds9 -plot list # list current dataset
+ $ds9 -plot loadconfig foo.plt # load plot + configuration
+ $ds9 -plot saveconfig bar.plt # save current plot + configuration
+ $ds9 -plot pagesetup orient portrait
+ $ds9 -plot pagesetup size letter
+ $ds9 -plot print
+ $ds9 -plot print destination file
+ $ds9 -plot print command "lp"
+ $ds9 -plot print filename "foo.ps"
+ $ds9 -plot print color rgb
+ $ds9 -plot close # close current plot
+
+ $ds9 -plot mode pointer
+
+ # configure plot
+ $ds9 -plot axis x grid yes
+ $ds9 -plot axis x log yes
+ $ds9 -plot axis x flip yes
+ $ds9 -plot axis x auto no
+ $ds9 -plot axis x min 0
+ $ds9 -plot axis x max 100
+ $ds9 -plot axis x format {%f}
+ $ds9 -plot legend yes # show legend
+ $ds9 -plot legend position left
+ $ds9 -plot font numbers font times
+ $ds9 -plot font numbers size 12
+ $ds9 -plot font numbers weight bold
+ $ds9 -plot font numbers slant italic
+ $ds9 -plot title {The Title}
+ $ds9 -plot title x {X Axis}
+ $ds9 -plot barmode aligned
+
+ # configure current dataset
+ $ds9 -plot show yes
+ $ds9 -plot shape circle
+ $ds9 -plot shape fill no
+ $ds9 -plot shape color cyan
+ $ds9 -plot smooth step
+ $ds9 -plot color red
+ $ds9 -plot width 2
+ $ds9 -plot dash yes
+ $ds9 -plot error yes
+ $ds9 -plot error color red
+ $ds9 -plot error width 2
+ $ds9 -plot name {My Data}
+
+ # select current dataset
+ $ds9 -plot select 2 +

png

+

Load PNG image into current frame.
+

+ Syntax:
+ -png <filename>
+  
+ Example:
+ $ds9 png foo.png
+ $cat foo.png | ds9 -png -
+ +

port

+

Set the IRAF port number, used by IRAF to communicate with DS9. + The default is 5137, the standard IRAF port used by ximtool. +

+ Syntax:
+ -port number
+  
+ Example:
+ $ds9 -port 5137 +

port_only
+ inet_only

+

Only use the IRAF port number. This is the same as -fifo none + -unix none.

+ Syntax:
+ -port_only
+  
+ Example:
+ $ds9 -port_only
+ +

pow

+

Select power scale function for the current frame.

+ Syntax:
+ -pow
+  
+ Example:
+ $ds9 -pow +

prefs

+

Controls various preference settings.

+ Syntax:
+ -prefs [clear]
+        [irafalign yes|no]
+  
+ Example:
+ $ds9 -prefs clear
+ $ds9 -prefs irafalign yes
+ +

preserve

+

Preserve the follow attributes while loading a new image.

+ Syntax:
+ preserve [pan yes|no]
+          [regions yes|no]
+  
+ Example:
+ $ds9 -preserve pan yes
+ $ds9 -preserve regions yes
+ +

psprint

+

Invokes postscript printing. Please see print + for further details.

+

print

+

Controls printing. Use print option to set printing options.
+

+ Syntax:
+ -print [destination printer|file]
+        [command <command>]
+        [filename <filename>] +
+        [color + rgb|cmyk|gray]
+        [level 1|2]
+        [resolution + 53|72|75|150|300|600]
+  
+ Example:
+ $ds9 -print
+ $ds9 -print destination file
+ $ds9 -print command 'gv -'
+ $ds9 -print filename foo.ps
+ $ds9 -print color cmyk
+ $ds9 -print level 2
+ $ds9 -print resolution 75 +

private

+

use private colormap, valid for pseudocolor 8 mode.

+ Syntax:
+ -private
+  
+ Example:
+ $ds9 -private +

raise

+

Raise in the window stacking order.

+ Syntax:
+ -raise
+  
+ Example:
+ $ds9 -raise
+ +

regions

+

Controls regions in the current frame.

+ Syntax:
+ -regions [<filename>]
+          [load [all] + <filename>]
+          [save + <filename>]
+          [list [close]]
+          [epsilon + <integer>]
+          [show yes|no]
+          [showtext yes|no]
+          [centroid]
+          [centroid auto + yes|no]
+          [centroid + radius <value>|iteration <value>]
+          [getinfo]
+          [move front]
+          [move back]
+          [select all]
+          [select none]
+          [select invert]
+          [delete all]
+          [delete select]
+          [format + ds9|xml|ciao|saotng|saoimage|pros|xy]
+          [system + image|physical|wcs|wcsa...wcsz]
+          [sky + fk4|fk5|icrs|galactic|ecliptic]
+          [skyformat + degrees|sexagesimal]
+          [strip yes|no]
+          [shape + <shape>]
+          [color + <color>
+          [width + <width>]
+          + [fixed|edit|rotate|delete yes|no]
+          + [include|exclude|source|background]
+          [delim + [nl|<char>]]
+          [command + <marker command>]
+          [composite]
+          [dissolve]
+          [template + <filename>]
+          [template + <filename> at <ra> <dec> <coordsys> + <skyframe>]
+          [savetemplate + <filename>]
+          [group new]
+          [group + <tag> new]
+          [group + <tag> update]
+          [group + <tag> select]
+          [group + <tag> color <color>]
+          [group <tag> + copy]
+          [group <tag> + delete]
+          [group <tag> + cut]
+          [group <tag> + font <font>]
+          [group <tag> + move <int> <int>]
+          [group <tag> + movefront]
+          [group <tag> + moveback]
+          [group <tag> + property <property> yes|no]
+          [copy]
+          [cut]
+          [paste + image|physical|wcs|wcsa...wcsz]
+          [undo]
+  
+ Example:
+ $ds9 -regions foo.reg
+ $ds9 -regions -format ciao bar.reg # load as ciao format
+ $ds9 -regions foo.fits # FITS regions files do not need a format + specification
+ $ds9 -regions load foo.reg # load foo.reg into current frame
+ $ds9 -regions load all foo.reg # load foo.reg into all frames
+ $ds9 -regions load '*.reg'# expand *.reg and load into current + frame
+ $ds9 -regions load all '*.reg' # expand *.reg and load into all + frames
+ $ds9 -regions save foo.reg
+ $ds9 -regions list
+ $ds9 -regions list close
+ $ds9 -regions epsilon 5
+ $ds9 -regions show yes
+ $ds9 -regions showtext no
+ $ds9 -regions centroid
+ $ds9 -regions centroid auto yes
+ $ds9 -regions centroid radius 10
+ $ds9 -regions centroid iteration 20
+ $ds9 -regions getinfo
+ $ds9 -regions move back
+ $ds9 -regions move front
+ $ds9 -regions select all
+ $ds9 -regions select none
+ $ds9 -regions select invert
+ $ds9 -regions delete all
+ $ds9 -regions delete select
+ $ds9 -regions format ds9
+ $ds9 -regions system wcs
+ $ds9 -regions sky fk5
+ $ds9 -regions skyformat degrees
+ $ds9 -regions delim nl
+ $ds9 -regions strip yes
+ $ds9 -regions shape ellipse
+ $ds9 -regions color red
+ $ds9 -regions width 3
+ $ds9 -regions edit yes
+ $ds9 -regions include
+ $ds9 -regions command "circle 100 100 20 # color=red"
+ $ds9 -regions composite
+ $ds9 -regions dissolve
+ $ds9 -regions template foo.tpl
+ $ds9 -regions template foo.tpl at 13:29:55.92 +47:12:48.02 fk5
+ $ds9 -regions savetemplate foo.tpl
+ $ds9 -regions group new
+ $ds9 -regions group foo new
+ $ds9 -regions group foo update
+ $ds9 -regions group foo select
+ $ds9 -regions group foo color red
+ $ds9 -regions group foo copy
+ $ds9 -regions group foo delete
+ $ds9 -regions group foo cut
+ $ds9 -regions group foo font {times 14 bold}
+ $ds9 -regions group foo move 100 100
+ $ds9 -regions group foo movefront
+ $ds9 -regions group foo moveback
+ $ds9 -regions group foo property delete no
+ $ds9 -regions copy
+ $ds9 -regions cut
+ $ds9 -regions paste wcs
+ $ds9 -regions undo
+ +

red

+

For RGB frames, sets the current color channel to red.

+ Syntax:
+ -red
+  
+ Example:
+ $ds9 -red foo.fits
+ +

restore

+

Restore DS9 to a previous state from a backup save set.

+ Syntax:
+ -restore <filename>
+  
+ Example:
+ $ds9 -restore ds9.bck
+

rgb

+

Create RGB frame and control RGB frame parameters.

+ Syntax:
+ -rgb []
+      [red|green|blue]
+      [channel [red|green|blue]]
+      [view [red|green|blue] [yes|no]]
+      [system <coordsys>]
+      [lock + wcs|crop|slice|bin|scale|scalelimits|colorbar|block|smooth + [yes|no]]
+      [open|close]
+  
+ Example:
+ $ds9 -rgb # create new rgb frame
+ $ds9 -rgb red # set current channel to red
+ $ds9 -rgb channel red # set current channel to red
+ $ds9 -rgb view blue no # turn off blue channel
+ $ds9 -rgb system wcs # set rgb coordinate system
+ $ds9 -rgb lock wcs yes
+ $ds9 -rgb lock crop yes
+ $ds9 -rgb lock slice yes
+ $ds9 -rgb lock bin yes
+ $ds9 -rgb lock scale yes
+ $ds9 -rgb lock scalelimits yes
+ $ds9 -rgb lock colorbar yes
+ $ds9 -rgb lock block yes
+ $ds9 -rgb lock smooth yes
+ $ds9 -rgb open
+ $ds9 -rgb close
+
+

rgbarray

+

Load raw data array cube into rgb frame.
+

+ Syntax:
+ -rgbarray +<filename>[[xdim=<x>,ydim=<y>|dim=<dim>],[zdim=3],bitpix=<b>,skip=<s>,endian=[little|big]]
+  
+ Example:
+ $ds9 -rgbarray foo.arr[dim=512,zdim=3,bitpix=-32,endian=little]
+ $cat foo.arr | ds9 -rgbarray + -[dim=512,zdim=3,bitpix=-32,endian=little]
+

rgbcube

+

Load FITS rgbcube into rgb frame.
+

+ Syntax:
+ -rgbcube <filename>
+  
+ Example:
+ $ds9 -rgbcube foo.fits
+ $cat foo.fits | ds9 -rgbcube -
+

rgbimage

+

Load FITS rgbimage into rgb frame.
+

+ Syntax:
+ -rgbimage <filename>
+  
+ Example:
+ $ds9 -rgbimage foo.fits
+ $cat foo.fits | ds9 -rgbimage -
+

rotate

+

Controls the rotation angle (in degrees) of the current frame. +

+ Syntax:
+ -rotate [<value>]
+         [to <value>]
+         [open|close]
+  
+ Example:
+ $ds9 -rotate 45
+ $ds9 -rotate to 30
+ $ds9 -rotate open
+ $ds9 -rotate close
+ +

samp

+

Configure SAMP protocol.

+ Syntax:
+ -samp [yes|no|connect|disconnect]
+       [broadcast [image|table]]
+       [send [image|table] + <application>]
+  
+ Example:
+ $ds9 -samp yes
+ $ds9 -samp connect
+ $ds9 -samp broadcast image
+ $ds9 -samp send image aladin
+

save
+

+

Save loaded image data of current frame as FITS.

+ Syntax:
+ -save [fits|rgbimage|rgbcube|mecube|mosaic|mosaicimage] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <filename> [image|table|slice]
+  
+ Example:
+ $ds9 -save foo.fits
+ $ds9 -save fits foo.fits image
+ $ds9 -save fits foo.fits table
+ $ds9 -save fits foo.fits slice
+ $ds9 -save rgbimage foo.fits
+ $ds9 -save rgbcube foo.fits
+ $ds9 -save mecube foo.fits
+ $ds9 -save mosaic foo.fits
+ $ds9 -save mosaicimage foo.fits
+

saveimage

+

Create a snap shot of the current DS9 window and save in + specified image format. If no format specified, the file name + extension is used to determine the output format. Optional + parameters: jpeg quality (1-100) and tiff + compression method.

+ Syntax:
+ -saveimage [fits|eps|gif|tiff|jpeg|png] <filename>
+ -saveimage <filename>.jpeg [1-100]
+ -saveimage <filename>.tiff [none|jpeg|packbits|deflate]
+  
+ Example:
+ $ds9 -saveimage ds9.tiff
+ $ds9 -saveimage jpeg ds9.jpeg 75
+ +

scale

+

Controls the limits and color scale distribution.

+ Syntax:
+ -scale [linear|log|pow|sqrt|squared|asinh|sinh|histequ]
+        [log exp <value>]
+        [datasec yes|no]
+        [limits <minvalue> + <maxvalue>]
+        [mode + minmax|<value>|zscale|zmax]
+        [scope local|global]
+        [match]
+        [match limits]
+        [lock [yes|no]]
+        [lock limits [yes|no]]
+        [open|close]
+  
+ Example:
+ $ds9 -scale linear
+ $ds9 -scale log exp 100
+ $ds9 -scale datasec yes
+ $ds9 -scale histequ
+ $ds9 -scale limits 1 100
+ $ds9 -scale mode zscale
+ $ds9 -scale mode 99.5
+ $ds9 -scale scope local
+ $ds9 -scale match
+ $ds9 -scale match limits
+ $ds9 -scale lock yes
+ $ds9 -scale lock limits yes
+ $ds9 -scale open
+ $ds9 -scale close
+ +

shm

+

Load a shared memory segment into the current frame.

+ Syntax:
+ -shm [<key> [<filename>]]
+      [key <id> [<filename>]]
+      [shmid <id> [<filename>]]
+      [fits [key|shmid] <id> + [<filename>]]
+      [mosaicimage + [iraf|wcs|wcsa...wcsz|wfpc2] [key|shmid] <id> + [<filename>]]
+      [mosaicimagenext [wcs|wcsa...wcsz] + [key|shmid] <id> [<filename>]]
+      [mosaic [iraf|wcs|wcsa...wcsz] + [key|shmid] <id> [<filename>]]
+      [rgbcube [key|shmid] <id> + [<filename>]]
+      [rgbimage [key|shmid] <id> + [<filename>]]
+      [rgbarray [key|shmid] <id> +[xdim=<x>,ydim=<y>|dim=<dim>,zdim=3],bitpix=<b>,[skip=<s>]]
+      [array [key|shmid] <id> +[xdim=<x>,ydim=<y>|dim=<dim>],bitpix=<b>,[skip=<s>]]
+  
+ Example:
+ $ds9 -shm 102
+ $ds9 -shm key 102
+ $ds9 -shm shmid 102 foo
+ $ds9 -shm fits 100 foo
+ $ds9 -shm mosaicimage iraf key 100 foo
+ $ds9 -shm mosaicimage wcs key 100 foo
+ $ds9 -shm mosaicimage wcsa key 100 foo
+ $ds9 -shm mosaicimage wfpc2 key 100 foo
+ $ds9 -shm mosaicimagenext wcs key 100 foo
+ $ds9 -shm mosaic iraf key 100 foo
+ $ds9 -shm mosaic wcs key 100 foo
+ $ds9 -shm rgbcube key 100 foo
+ $ds9 -shm rgbimage key 100 foo
+ $ds9 -shm rgbarray shmid 102 [dim=32,zdim=3,bitpix=-32]
+ $ds9 -shm array shmid 102 [dim=32,bitpix=-32]
+ +

sia
+

+

Support for VO Simple Image Access protocol. The first command + will create a new search. All other commands operated on the + last search created, unless indicated otherwise.

+ Syntax:
+ -sia [2mass|akari|astrowise|cadc|cxc|mast|sdss|skyview|tgssadr]
+
+      + [<ref>] [cancel]
+      [<ref>] [clear]
+      [<ref>] [close]
+      [<ref>] [coordinate <ra> + <dec> <coordsys>]
+      [<ref>] + [crosshair]
+      [<ref>] [export sb|tsv + <filename>]
+      [<ref>] [name <object>]
+      [<ref>] [print]
+      [<ref>] [retrieve]
+      [<ref>] [save + <filename>]
+      [<ref>] [size <width> + <height> degrees|arcmin|arcsec]
+      [<ref>] [sky + <skyframe>]
+      [<ref>] [skyformat + <skyformat>]
+      [<ref>] [system + <coordsys>]
+      [<ref>] [update]
+
+ Example:
+ $ds9 -sia 2mass
+ $ds9 -sia cancel
+ $ds9 -sia clear
+ $ds9 -sia close
+ $ds9 -sia coordinate 202.48 47.21 fk5
+ $ds9 -sia crosshair
+ $ds9 -sia export tsv bar.tsv
+ $ds9 -sia name m51
+ $ds9 -sia print
+ $ds9 -sia retrieve
+ $ds9 -sia save foo.xml
+ $ds9 -sia size 1 1 degrees
+ $ds9 -sia sky fk5
+ $ds9 -sia skyformat degrees
+ $ds9 -sia system wcs
+ $ds9 -sia update
+
+ single +

Set display mode to single.

+ Syntax:
+ -single
+  
+ Example:
+ $ds9 -single
+ +

skyview

+

Support for SkyView image server at HEASARC.

+ Syntax:
+ -skyview []
+          [<object>]
+          [name + <object>]
+          [coord + <ra> <dec> degrees|sexagesimal] # in wcs fk5
+          [size + <width> <height> degrees|arcmin|arcsec]
+          [pixels + <width> <height>]
+          [save yes|no]
+          [frame + new|current]
+          [update + frame|crosshair]
+          [survey <survey>]
+          [open|close]
+  
+ Example:
+ $ds9 -skyview
+ $ds9 -skyview m31
+ $ds9 -skyview name m31
+ $ds9 -skyview coord 00:42:44.404 +41:16:08.78 sexagesimal
+ $ds9 -skyview size 60 60 arcmin
+ $ds9 -skyview pixels 600 600
+ $ds9 -skyview save yes
+ $ds9 -skyview frame current
+ $ds9 -skyview update frame
+ $ds9 -skyview survey sdssi
+ $ds9 -skyview open
+ $ds9 -skyview close
+ +

sleep

+

Delays execution for specified number of seconds. Default is 1 + second.

+ Syntax:
+ -sleep [#]
+  
+ Example:
+ $ds9 -sleep
+ $ds9 -sleep 2
+ +

slice
+ noslice
+

+

Indicates next files loaded are to treated as slices of a cube. + Can be disabled with noslice command.
+

+ Syntax:
+ -slice <filename>
+ -noslice
+  
+ Example:
+ $ds9 -slice *.fits
+ $ds9 -noslice
+ +

smooth

+

Smooth current image or set smooth parameters.

+ Syntax:
+ -smooth []
+         [yes|no]
+         [function + boxcar|tophat|gaussian]
+         [radius <int>]
+         [open|close]
+         [match]
+         [lock [yes|no]]
+  
+ Example:
+ $ds9 -smooth
+ $ds9 -smooth yes
+ $ds9 -smooth function tophat
+ $ds9 -smooth radius 4
+ $ds9 -smooth open
+ $ds9 -smooth close
+ $ds9 -smooth match
+ $ds9 -smooth lock yes
+ +

squared

+

Select squared scale function for the current frame.

+ Syntax:
+ -squared
+  
+ Example:
+ $ds9 -squared +

sqrt

+

Select square soot scale function for the current frame.

+ Syntax:
+ -sqrt
+  
+ Example:
+ $ds9 -sqrt +

source

+

Source TCL code from a file.

+ Syntax:
+ -source <filename>
+  
+ Example:
+ $ds9 -source extensions.tcl
+ +

tcl

+

Execute one TCL command. Note: this a different behavior from + previous versions of DS9.
+

+ Syntax:
+ -tcl <tcl command>
+  
+ Example:
+ $ds9 -tcl 'puts "Hello, World"'
+

threads

+

Set number of process threads for functions which are + multi-threaded.

+ Syntax:
+ -threads #
+  
+ Example:
+ $ds9 -threads 8
+
+ tiff
+

Load TIFF image into current frame.
+

+ Syntax:
+ -tiff <filename>
+  
+ Example:
+ $ds9 -tiff foo.tiff
+ $cat foo.fits | ds9 -tiff -
+ +

tile

+

Controls the tile display mode.

+ Syntax:
+ -tile []
+       [yes|no]
+       [mode grid|column|row]
+       [grid]
+       [grid mode automatic|manual]
+       [grid direction x|y]
+       [grid layout <col> + <row>]
+       [grid gap <pixels>]
+       [row]
+       [column]
+  
+ Example:
+ $ds9 -tile
+ $ds9 -tile yes
+ $ds9 -tile mode row
+ $ds9 -tile grid
+ $ds9 -tile grid mode manual
+ $ds9 -tile grid direction x
+ $ds9 -tile grid layout 5 5
+ $ds9 -tile grid gap 10
+ $ds9 -tile row
+ $ds9 -tile column +

title

+

Changes the display window title to the specified name.

+ Syntax:
+ -title name
+  
+ Example:
+ $ds9 -title Voyager +

unix

+

Set the IRAF unix socket name, used by IRAF to communicate with + DS9. The default is /tmp/.IMT%d, so that the standard IRAF unix + socket is defined.

+ Syntax:
+ -unix name
+  
+ Example:
+ $ds9 -unix "/tmp/.IMT%d" +

unix_only

+

Only use the IRAF unix socket name. This is the same as -fifo + none -port 0.

+ Syntax:
+ -unix_only
+  
+ Example:
+ $ds9 -unix_only
+ +

update

+

Updates the current frame or region of frame. In the second + form, the first argument is the number of the fits HDU (starting + with 1) and the remaining args are a bounding box in IMAGE + coordinates. By default, the screen is updated the next + available idle cycle. However, you may force an immediate update + by specifying the NOW option.

+ Syntax:
+ -update []
+         [# x1 y1 x2 y2]
+         [now]
+         [now # x1 y1 x2 y2]
+  
+ Example:
+ $ds9 -update
+ $ds9 -update 1 100 100 300 400
+ $ds9 -update now
+ $ds9 -update now 1 100 100 300 400
+

url

+

Load FITS from URL into the current frame

+ Syntax:
+ -url <url>
+  
+ Example:
+ $ds9 -url http://foo.bar.edu/foo.fits +

version

+

Returns the current version of DS9 and exits.

+ Syntax:
+ -version
+  
+ Example:
+ $ds9 -version +

view

+

Controls the GUI and visible RGB frame color channels.

+ Syntax:
+ -view [layout horizontal|vertical]
+       [keyvalue <string>]
+       [info yes|no]
+       [panner yes|no]
+       [magnifier yes|no]
+       [buttons yes|no]
+       [colorbar yes|no]
+       [graph horizontal|vertical + yes|no]
+       [filename yes|no]
+       [object yes|no]
+       [keyword yes|no]
+       [minmax yes|no]
+       [lowhigh yes|no]
+       [units yes|no]
+       [image|physical|wcs|wcsa...wcsz + yes|no]
+       [frame yes|no]
+       [red yes|no]
+       [green yes|no]
+       [blue yes|no]
+  
+ Example:
+ $ds9 -view layout vertical
+ $ds9 -view keyvalue BITPIX
+ $ds9 -view info yes
+ $ds9 -view panner yes
+ $ds9 -view magnifier yes
+ $ds9 -view buttons yes
+ $ds9 -view colorbar yes
+ $ds9 -view graph horizontal yes
+ $ds9 -view filename yes
+ $ds9 -view object yes
+ $ds9 -view keyword yes
+ $ds9 -view minmax yes
+ $ds9 -view lowhigh yes
+ $ds9 -view wcsa yes
+ $ds9 -view frame yes
+ $ds9 -view red yes
+ $ds9 -view green yes
+ $ds9 -view blue yes
+ +

visual

+

Force DS9 to use the specified color visual. This argument MUST + be the first argument listed. Requires the visual be available. +

+ Syntax:
+ -visual + [pseudocolor|pseudocolor8|truecolor|truecolor8|truecolor16|truecolor24] +  
+ Example:
+ $ds9 -visual truecolor24
+ +

vla

+

Support for VLA Sky Survey.

+ Syntax:
+ -vla []
+        [<object>]
+        [name <object>]
+        [coord <ra> + <dec> degrees|sexagesimal] # in wcs fk5
+        [size <width> + <height> degrees|arcmin|arcsec]
+        [save yes|no]
+        [frame new|current]
+        [update frame|crosshair]
+        [survey first|stripe82]
+        [open|close]
+  
+ Example:
+ $ds9 -vla
+ $ds9 -vla m31
+ $ds9 -vla name m31
+ $ds9 -vla coord 00:42:44.404 +41:16:08.78 sexagesimal
+ $ds9 -vla size 60 60 arcmin
+ $ds9 -vla save yes
+ $ds9 -vla frame current
+ $ds9 -vla update frame
+ $ds9 -vla survey stripe82
+ $ds9 -vla open
+ $ds9 -vla close
+

vlss

+

Support for NRAO VLSS Sky Survey.

+ Syntax:
+ -vlss []
+       [<object>]
+       [name <object>]
+       [coord <ra> <dec> + degrees|sexagesimal] # in wcs fk5
+       [size <width> + <height> degrees|arcmin|arcsec]
+       [save yes|no]
+       [frame new|current]
+       [update frame|crosshair]
+       [open|close]
+  
+ Example:
+ $ds9 -vlss
+ $ds9 -vlss m31
+ $ds9 -vlss name m31
+ $ds9 -vlss coord 00:42:44.404 +41:16:08.78 sexagesimal
+ $ds9 -vlss size 60 60 arcmin
+ $ds9 -vlss save yes
+ $ds9 -vlss frame current
+ $ds9 -vlss update frame
+ $ds9 -vlss open
+ $ds9 -nvess close +

vo

+

Invoke an connection to a Virtual Observatory site.

+ Syntax:
+ -vo [method xpa|mime]
+     [server <url>]
+     [internal yes|no]
+     [delay #]
+     [<url>]
+     [connect <url>]
+     [disconnect <url>]
+     [open|close]
+  
+ Example:
+ $ds9 -vo method xpa
+ $ds9 -vo server "http://foo.bar.edu/list.txt"
+ $ds9 -vo internal yes
+ $ds9 -vo delay 15 # keep-alive delay
+ $ds9 -vo chandra-ed
+ $ds9 -vo connect chandra-ed
+ $ds9 -vo disconnect chandra-ed
+ $ds9 -vo open
+ $ds9 -vo close
+ +

wcs

+

Controls the World Coordinate System for the current frame. If + the wcs system, skyframe, or skyformat is modified, the info + panel, compass, grid, and alignment will be modified + accordingly. Also, a new WCS specification can be loaded and + used by the current image regardless of the WCS that was + contained in the image file. Please see WCS + for more information.

+ Syntax:
+ -wcs [[system] wcs|wcsa...wcsz]
+      [[sky] fk4|fk5|icrs|galactic|ecliptic] +
+      [[skyformat] degrees|sexagesimal]
+      [align yes|no]
+      [reset [#]]
+      [replace [#] <filename>]
+      [append [#] <filename>]
+      [open|close]
+  
+ Example:
+ $ds9 -wcs wcs
+ $ds9 -wcs system wcs
+ $ds9 -wcs fk5
+ $ds9 -wcs sky fk5
+ $ds9 -wcs sexagesimal
+ $ds9 -wcs skyformat sexagesimal
+ $ds9 -wcs align yes
+ $ds9 -wcs reset
+ $ds9 -wcs reset 3
+ $ds9 -wcs replace foo.wcs
+ $ds9 -wcs replace 3 foo.wcs
+ $ds9 -wcs append foo.wcs
+ $ds9 -wcs append 3 foo.wcs
+ $ds9 -wcs open
+ $ds9 -wcs close
+ +

web

+

Display specified URL in the web display.

+ Syntax:
+ -web [new|<webname>] [<url>]
+      [<webname>] [click + back|forward|stop|reload|#]
+      [<webname>] [clear]
+      [<webname>] [close]
+  
+ Example:
+ $ds9 -web www.cnn.com
+ $ds9 -web new www.cnn.com
+ $ds9 -web hvweb www.apple.com
+ $ds9 -web click back
+ $ds9 -web click 2
+ $ds9 -web clear
+ $ds9 -web close
+ +

width

+

Set the width of the image display window. Use the geometry command to set the + overall width and height of the ds9 window.

+ Syntax:
+ -width [<value>]
+  
+ Example:
+ $ds9 -width 512
+ +

xpa

+

Configure XPA.

+ Syntax:
+ -xpa [yes|no]
+      [inet|local|unix|localhost]
+      [noxpans]
+      [connect]
+      [disconnect]
+      [info]
+  
+ Example:
+ $ds9 -xpa no
+ $ds9 -xpa local
+ $ds9 -xpa noxpans
+ $ds9 -xpa connect
+ $ds9 -xpa disconnect
+ $ds9 -xpa info
+ +

zmax

+

Set Scale Limits based  on the IRAF algorithm and + maximum data value.

+ Syntax:
+ -zmax
+  
+ Example:
+ $ds9 -zmax +

zscale

+

Set Scale Limits based  on the IRAF algorithm.

+ Syntax:
+ -zscale []
+         [contrast]
+         [sample]
+         [line]
+  
+ Example:
+ $ds9 -zscale
+ $ds9 -zscale contrast .25
+ $ds9 -zscale sample 600
+ $ds9 -zscale line 120
+ +

zoom

+

Controls the current zoom value for the current frame.

+ Syntax:
+ -zoom [<value>]
+       [<value> <value>]
+       [to <value>]
+       [to <value> <value>] +
+       [in]
+       [out]
+       [to fit]
+       [open|close]
+  
+ Example:
+ $ds9 -zoom 2
+ $ds9 -zoom 2 4
+ $ds9 -zoom to 4
+ $ds9 -zoom to 2 4
+ $ds9 -zoom in
+ $ds9 -zoom out
+ $ds9 -zoom to fit
+ $ds9 -zoom open
+ $ds9 -zoom close
+
+

Contours

+

DS9 can create and display contours as an overlay on an image. + The Analysis Contours menu is used to display contours. To + create, copy, paste,  and configure contours, use the + Analysis Contour Parameters menu.

+

Contour Parameters

+

When creating a new contour, a dialog box appears, in which the + user selects the number of contour levels, smoothness, and the + distribution of the contours.

+

Contour Levels

+

Specifies the number of contour levels to be generated. A + typical number is between 1 and 10. Note: large numbers of + contours can take a long time to generate.

+

Contour Smoothness

+

Specifies how smooth the contours are. A smoothness level of 1 + will evaluate the contour at each image pixel. A level of 2 will + evaluate the contour at every other pixel. The larger the + number, the quicker the contour will be generated, and the less + detail will be available.

+

Contour Scale

+

Specifies the distribution of the contour levels.
+

+

Contour Method

+

There are two methods that are available to calculate the + contour lines. The first, BLOCK, blocks down the image, by the + smoothness factor, before contours are calculated. As a result, + the larger the smoothness, the faster the result. The second + method, SMOOTH, smooths the image before calculating contours. + As a result, the larger the smoothness, the slower the result.
+

+

Contour Files

+

A contour file is an ASCII file containing a header, global + properties, coordinate system, contour levels, and contour + points.
+

+

+

Header

+

A DS9 contour file may start with the following optional + header:

+

# Contour file format: DS9 version 7.5
+

+

Global Properties

+

Global properties affect all contour levels unless a line + level attribute is specified. The global keyword is + first, followed by a list of keyword = value pairs. Multiple + global property lines may be used within a region file.

+

global color=green width=1 dash=1 dashlist=8 3
+

+

Coordinate Systems

+

For each contour file, it is important to specify the + coordinate system used to interpret the contour points, i.e., + to set the context in which the positions are interpreted. For + this purpose, the following keywords are recognized:

+

PHYSICAL                + +# + + + + + + + + + pixel coords of original file using LTM/LTV
+ IMAGE                   + +# + + + + + + + + + pixel coords of current file
+ FK4,B1950             +   + # sky coordinate systems
+ FK5,J2000               +# + + + + + + + + + sky coordinate systems
+ ICRS                    + +# + sky coordinate systems
+ GALACTIC                + +# + + + + + + + + + sky coordinate systems
+ ECLIPTIC                + +# + + + + + + + + + sky coordinate systems
+ WCS        +         +      # primary WCS
+ WCSA        +             # + secondary WCS
+ LINEAR                  + +# + + + + + + + + + linear primary WCS
+

+

+

+

Contour Level

+

Each contour level is composed of a line value, line + attributes and one or more contours. Line attributes are + specified at the start of a new level and only affect contours + within that level .

+

level=15.78775 color=pink width=2 dash=yes dashlist=2 + 2
+

+

Contour

+

Each contour is composed of one or more X,Y coordinates, with + a deliminator of space or comma,  starting with "(" and + ending with ")". Contours are not closed.
+

+

+

+

(202.4836468 47.22380226
+  202.4833538 47.2239185
+  202.4831634 47.22409874
+  202.4829883 47.22428858)
+

+

+

+

+

+

+

+

+

+

+

+

+

+

+

File Formats

FITS
+ FITS Image
+ FITS Binary Events Table
+ FITS HEALPIX Table
+ FITS Data Cube
+ FITS Multiple Extension + Data Cube
+ FITS Multiple + Extension Multiple Frames
+ FITS Mosaic
+ FITS Mosaic Data Cube
+ FITS RGB
+ Split FITS
+ Array
+ NRRD
+ ENVI
+ GIF
+ TIFF
+ JPEG
+ PNG
+ External Format Support
+ External Analysis Support
+ Region Files
+ Contour Files
+ Color Lookup Table
+ WCS
+ Preference File
+ Startup File
+ TCL
+

FITS

+ DS9 supports FITS images and FITS binary tables. The following + algorithm is used to locate and to load the FITS image or table if + no additional information is provide: +

+

+
• Examine primary HDU, if IMAGE, load.
  +
+
• Examine each extension HDU
+
+
• If IMAGE, load.
  +
+
• If BINARY TABLE, create IMAGE if the following is + true:
+
+
• FITS COMPRESSED: keyword ZIMAGE is T.
+
• FITS EVENTS: keyword EXTNAME is EVENTS,STDEVT, or + RAYEVENT, column names X and Y are present.
+
• FITS HEALPIX: keyword PIXTYPE is HEALPIX.
  +
+
+
+
• If DS9 traverses the entire FITS file without + satisfying one of the above, an error is generated.
+

+

+ FITS keyword inheritance is supported. All valid FITS BITPIX + values are supported, along with -16, for UNSIGNED + SHORT. The following FITS keywords are supported: +

OBJECT
+ UNITS
+ BSCALE / BZERO
+ BLANK
+ DATASEC
+ LTV / LTM  for physical coords
+ DTV / DTM  for detector coords
+ ATV / ATM  for amplifier coords
+ WCS keywords
+ WCS# keywords

+

FITS Image

+ At load time, the user may provide just a file name or a file name + along with FITS extension name/number and image section + specification. FITS extension names are case insensitive. When + specifying an extension, be sure to quote strings correctly to + pass both the shell and DS9 parser. A image section specification + is used to specify the x,y limits of an image subsection. By + default, x and y coordinates are in IMAGE, use a 'p' + as the last character to indicate PHYSICAL coordinates. + A '*' indicates use the default for that axis only. + Block is optional and defaults to 1.
+

Syntax:
+ filename
+ filename[ext]
+ filename[ext][sect]
+ filename[sect]
+ filename[ext,sect]
+
+ where
+
+ ext:
+ [extension name | extension #]
+
+ sect:
+ [x0:x1,y0:y1[p]]
+ [x0:x1,y0:y1,block[p]]
+ [x0:x1,y0:y1,z0:z1[p]]
+ [x0:x1,y0:y1,block,z0:z1[p]]
+ [*,y0:y1[p]]
+ [*,y0:y1,block[p]]
+ [*,y0:y1,z0:z1[p]]
+ [*,y0:y1,block,z0:z1[p]]
+ [x0:x1,*[p]]
+ [x0:x1,*,block[p]]
+ [x0:x1,*,z0:z1[p]]
+ [x0:x1,*,block,z0:z1[p]]
+ [*,*,block]
+ [*,*,z0:z1]
+ [*,*,block,z0:z1]
+
+ [dim1@xcen,dim2@ycen[p]]
+ [dim1@xcen,dim2@ycen,block[p]]
+ [dim1@xcen,dim2@ycen,dim3@zcen[p]]
+ [dim1@xcen,dim2@ycen,block,dim3@zcen[p]]
+ [*,dim2@ycen[p]]
+ [*,dim2@ycen,block[p]]
+ [*,dim2@ycen,dim3@zcen[p]]
+ [*,dim2@ycen,block,dim3@zcen[p]]
+ [dim1@xcen,*[p]]
+ [dim1@xcen,*,block[p]]
+ [dim1@xcen,*,dim3@zcen[p]]
+ [dim1@xcen,*,block,dim3@zcen[p]]
+ [*,*,block]
+ [*,*,dim3@zcen]
+ [*,*,block,dim3@zcen]
+
+ [dim@xcen@ycen]
+ [dim@xcen@ycen,block]
+ [dim@xcen@ycen,zdim@zcen]
+ [dim@xcen@ycen,block,zdim@zcen]
+
+ Example:
+ $ds9 foo.fits # default load
+ $ds9 foo.fits[1] # load first extension
+ $ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD'
+ $ds9 foo.fits[10:200,40:100] # image section
+ $ds9 foo.fits[10:200,40:100,2] # image section, + blocked by 2
+ $ds9 foo.fits[*,40:100] # only section y axis
+ $ds9 foo.fits[256@512@512] # section box at 512,512
+ $ds9 foo.fits[2][100:200,100:200] # second extension, image + section
+ $ds9 foo.fits[2][100:200,100:200,2] # second + extension, image section, blocked by 2
+ $ds9 foo.fits[10:200,40:100,5:20] # cube section
+ $ds9 foo.fits[*,40:100,5:20] # only section y and z axes
+ $ds9 foo.fits[256@512@512] # section cube at 512,512
+ $ds9 foo.fits[2][100:200,100:200,5:20] # second extension, + cube section
+ $ds9 foo.fits[2][100:200,100:200,2,5:20] # second extension, + cube section, blocked by 2

+ FITS Binary Events Table
+
+ At load time, the user may provide just a file name or a file + name along with FITS extension name/number, image section + specification, and binnng parameters. DS9 will automatically + convert an FITS binary events table into a 2D image for display. + FITS extension names and parameters are case insensitive. The + users may specify a number of parameters on how to construct the + image and how to filter data. When specifying a filter, be sure to + quote strings correctly to pass both the shell and DS9 parser.

+

Syntax:
+ filename
+ filename[ext]
+ filename[ext][sect]
+ filename[sect]
+ filename[ext,sect]
+
+ filename[ext][bin]
+ filename[ext][bin][sect]
+ filename[ext][sect][bin]
+ filename[bin]
+ filename[bin][sect]
+ filename[sect][bin]
+ filename[ext,bin]
+
+ where:
+ ext: see FITS Image
+ sect: see FITS Image
+
+ bin:
+ [bin=colx,coly] # bin counts
+ [bin=colx,coly,filter] # bin counts with filter
+ [bin=colx,coly,colz] # bin on colz
+ [bin=colx,coly,colz,filter] # bin on colz with + filter
+ [bin=colz] # bin cols 'x', 'y', and colz
+ [bin=colz,filter] # bin cols 'x', 'y', and + colz with filter
+ [key=colx,coly]
+ [binkey=colx,coly]
+
+ (see Introduction + + + + + + + + + + + + + + + + to Filtering)
+
+ Example:
+ $ds9 foo.fits # default load
+ $ds9 foo.fits[1] # load first extension
+ $ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD'
+ $ds9 foo.fits[bin=detx,dety] # bin on detx,dety
+ $ds9 foo.fits[2][bin=rawx,rawy] # load ext 2, cols + rawx,rawy
+ $ds9 foo.fits[bg_events,bin=rawx,rawy] # load ext + bg_events, cols rawx,rawy
+ $ds9 foo.fits[bin=x,y,pha] # bin on x,y,pi
+ $ds9 foo.fits[bin=pi] # bin on x,y,pi
+ $ds9 'foo.fits[ccd_id==3&&energy>4000]' # quoted + filter
+ $ds9 '"foo.fits[ccd_id==3 && energy>4000]"' # + double quoted filter
+ $ds9 'foo.fits[events][pha>5,pi<2]' # load extension + 'events' and filter

+

+

+

The shell environment variable DS9_BINKEY may be + used to specify default bin cols for FITS bin tables. Example:

+

$ export DS9_BINKEY='[bin=rawx,rawy]'
+ $ ds9 foo.fits # load FITS bin table, bin on rawx, rawy
+

+

FITS HEALPIX Table
+

+ At load time, the user may provide just a file name or a file name + along with FITS extension name/number, image section + specification, and Healpix parameters. DS9 will automatically + convert a FITS HEALPIX binary or ascii table into a 2D image for + display. FITS extension names and parameters are case insensitive. + The users may specify a number of parameters on how to construct + the image. Any table with keyword PIXTYPE=HEALPIX or NSIDE=x will + be processed as an HEALPIX image. The following FITS keywords will + be used if present and not overwritten by a command line option: + NSIDE, COORDSYS, ORDER.
+

+

+ Syntax:
+ filename
+ filename[ext]
+ filename[ext][sect]
+ filename[sect]
+ filename[ext,sect]
+
+ filename[ext][hpx]
+ filename[ext][hpx][sect]
+ filename[ext][sect][hpx]
+ filename[hpx]
+ filename[hpx][sect]
+ filename[sect][hpx]
+ filename[ext,hpx]
+
+ where:
+ ext: see FITS + + + + + + Image
+ sect: see FITS + + + + + + Image
+
+ hpx:
+ [order=ring|nested] # default ring
+ [layout=equatorial|north|south] # default equatorial
+ [col=<column number>] # defaut 1
+ [quad=<quadurant number>] # (1-4) default 1
+ [system=equatorial|galactic|ecliptic|unknown] # default + unknown
+
+ Example:
+ $ds9 foo.fits # default load
+ $ds9 foo.fits[1] # load first extension
+ $ds9 + foo.fits[order=ring,layout=equatorial,col=1,quad=1,system=unknown]
+ $ds9 foo.fits[1,order=nested] # first extension, nested + order
+

+

+

FITS Cube

+ A FITS Cube is a FITS image which contains more than 2 axes + (NAXES>2). DS9 will automatically detect if a cube is present + and will load all additional images. In addition, individual + images can be loaded one at a time into a cube. DS9 will display + the Cube dialog box which allows the user to select which 2 image + to be displayed. +

FITS Multiple + Extension Cube

+ A FITS Multiple Extension Data Cube file is a FITS file with one + or more extensions, that is to be displayed as a data cube. Each + image does not have to be the same size, however, only the + coordinate systems from the first extension will be used for + contours and grids.
+

Example:
+ $ds9 -mecube foo.fits # load multiple extension fits file + as data cube

+

FITS + Multiple Extension Multiple Frames

+ Load a multiple extension FITS file into multiple frames. Please + note that files loaded via standard-in or the xpa fits command can + not be displayed using this method.
+

Example:
+ $ds9 -multiframe foo.fits # load multiple extension fits + file as multiple frames

+

FITS Mosaic

+ A FITS mosaic image may exist as a series of FITS files, or as one + FITS file with many extensions. A FITS mosaic may be loaded all a + one time, or by the segment. Once loaded, the multiple FITS images + are treated as one FITS image.
+
+ DS9 supports three forms of mosaics:  + + + + + + + + + + + + + + + + +

IRAF +	contains the DETSEC and DETSIZE + keywords. + See NOAO + +IRAF +Mosaic +Data + + + + + + + + + + + + + + + + Structures +
WCS +	each FITS image contains + a valid WCS. +
HST WFPC2 +	valid HST WFPC2 data + cube, consisting of 4 planes, along with a fits ascii + table containing wcs information.

+ + +

Example:
+ $ds9 -mosaicimage iraf foo.fits # load mosaic iraf from one + fits file with multiple exts
+ $ds9 -mosaic iraf foo.fits bar.fits wow.fits # load mosaic + iraf from 3 files
+ $ds9 -mosaicimage wcs foo.fits # load mosaic wcs from one + fits file with multiple exts
+ $ds9 -mosaic wcs foo.fits bar.fits wow.fits # load mosaic + wcs from 3 files
+ $ds9 -mosaicimage wfpc2 bar.fits # load wfpc2 mosaic
+ $ds9 -mosaic foo.fits bar.fits wow.fits # load mosaic (wcs) + from 3 files
+

+

FITS Mosaic Data Cube

+ A FITS Mosaic Data Cube is a FITS mosaic image which contains more + than 2 axes (NAXES>2). DS9 will automatically detect if a + mosaic data cube is present and will load all additional images. + At the same time, DS9 will display the data cube dialog box which + allows the user to select which 2 image to be displayed. +

FITS RGB

+ A FITS RGB image may exist as three of FITS images, one FITS file + with three extensions, or as a FITS 3D Data cube, with three + slices, each representing the red, green, and blue channel. A FITS + RGB image may be loaded all a one time, or by the channel. Once + loaded, the multiple FITS images are treated as one FITS image.
+

Example:
+ $ds9 -rgbimage rgb.fits # load rgb image consisting of one + fits file with 3 image exts
+ $ds9 -rgbcube cube.fits # load rgb image consisting of one + fits data cube
+ $ds9 -rgb -red foo.fits -green bar.fits -blue wow.fits # + rgb image from 3 fits images
+

+

Split FITS

+ A split fits is a valid fits file in which two files contain the + header and data segments. +

Array

+ Raw data arrays are supported. To load an array, the user must + provide the dimensions, pixel depth, and optional header size and + architecture type. +

Syntax:
+ filename[arr]
+ filename[arr][sect]
+ filename[sect][arr]
+  
+ where
+ sect: see FITS + + + + + + Image
+ arr:
+ +

xdim=value
+ ydim=value
+ zdim=value # default is a depth of 1
+ dim=value
+ dims=value
+ bitpix=[8|16|-16|32|64|-32|-64]
+ skip=value # must be even, most must be factor of 4
+ arch|endian=[big|bigendian|little|littleendian]
+

+ Example:
+ $ds9 -array bar.arr[xdim=512,ydim=512,zdim=1,bitpix=16] # load + 512x512 short
+ $ds9 -array bar.arr[dim=256,bitpix=-32,skip=4] # load 256x256 + float with 4 byte head
+ $ds9 -array bar.arr[dim=512,bitpix=32,arch=little] # load + 512x512 long, intel
+ +

or alternate format:

+ filename[array(<type><dim><:skip><endian>)]
+
+ where:
+ type: +

'b' 8 -bit unsigned char
+ 's' 16-bit short int
+ 'u' 16-bit unsigned short int
+ 'i' 32-bit int
+ 'l' 64-bit int
+ 'r' 32-bit float
+ 'f' 32-bit float
+ 'd' 64-bit float

+ dim: +

int     # x,y dim
+ int.int # x,y dim
+ int.int.int # x,y,z dim
+

+ skip: +

int     # number of bytes to + skip

+ endian: +

'l' little endian
+ 'b' big endian
+

+ Example:
+ $ds9 -array bar.arr[array(s512)]   # load 512x512 + short
+ $ds9 -array bar.arr[array(r256:4)] # load 256x256 float with 4 + byte head
+ $ds9 -array bar.arr[array(i512l)]  # load 512x512 long, + intel +

The shell environment variable DS9_ARRAY may be + used to specify default array parameters.

+ Example:
+ $export DS9_ARRAY='[dim=256,bitpix=-32]'
+ $ds9 -array foo.arr # load 256x256 float
+

+

NRRD (Nearly Raw Raster Data)
+

+ Images in NRRD are supported directly. Encodings supported: raw, + + + + + + + + + gzip
+
+ Syntax:
+ filename
+ filename[sect]
+
+ where:
+ sect: see FITS + + + + + + Image
+
+ Example:
+ $ds9 -nrrd foo.nrrd
+ $ds9 -nrrd foo.nrrd[100:200,100:200] # cropped
+

ENVI
+

+ Images in ENVI are supported directly. Encodings supported: BIL, + + + + + + + BIP, BSQ.
+
+ Syntax:
+ filename
+ filename[sect]
+
+ where:
+ sect: see FITS + + + + + + Image
+
+ Example:
+ $ds9 -envi foo.hdr foo.bsq
+ $ds9 -envi foo.hdr foo.bsq[100:200,100:200] # cropped
+ +

GIF
+

+ Images in GIF are supported directly. For a Frame, the + average of the luminosity is used. For Frame RGB, each + channel is loaded directly.
+
+ Syntax:
+ filename
+
+ Example:
+ $ ds9 -gif foo.gif
+

TIFF
+

+ Images in TIFF are supported directly. For a Frame, the + average of the luminosity is used. For Frame RGB, each + channel is loaded directly.
+
+ Syntax:
+ filename
+
+ Example:
+ $ ds9 -tiff foo.tiff
+

JPEG
+

+ Images in JPEG are supported directly. For a Frame, the + average of the luminosity is used. For Frame RGB, each + channel is loaded directly.
+
+ Syntax:
+ filename
+
+ Example:
+ $ ds9 -jpeg foo.jpeg
+

PNG
+

+ Images in PNG are supported directly. For a Frame, the + average of the luminosity is used. For Frame RGB, each + channel is loaded directly.
+
+ Syntax:
+ filename
+
+ Example:
+ $ ds9 -png foo.png
+

External File Support

+ DS9 supports external file formats via an ASCII description file. + When loading a file into DS9, these descriptions are referenced + for instructions for loading the file, based on the file + extension. If found, the command is executed and the result, a + FITS image or FITS Binary Table, is read into DS9 via stdin.
+ At start-up, DS9 first searches for the ASCII file, named .ds9.filin + + +the +local +directory, + + + + + + + + + + + + + + + + then in the users home directory.
+ The file command first is macro-expanded to fill in user-defined + arguments and then is executed externally.
+ The ASCII file that defines the known image files consists of one + or more file descriptors, each of which has the following format: +

Help description
+ A space-separated list of templates
+ A space-separated list of file types (not currently used)
+ The command line for the loading this file type
+

+ Note that blank lines separate the file descriptions and should + not be used as part of a description. Also, the '#' character is a + comment character.
+
+ The following macros are supported: $filename
+

For Example:
+ # File access descriptions:
+ #       help explanation
+ #       file template
+ #       file type
+ #       access command
+ IRAF IMH files
+ *.imh
+ IMH
+ i2f -s $filename

+

External Analysis + Support

+ For more information about external analysis support files, see Analysis. +

Region Files

+ DS9 can read and write a number of region file formats. See Regions documentation for more + information. +

DS9
+ FUNTools
+ Ciao
+ SAOimage
+ IRAF PROS
+ FITS REGION Binary + Table
+ X Y
+

+

Contour Files

+ See Contours + documentation for more information.
+ +

+

Color Lookup Table

+ DS9 has a number of default colormaps available to the user. DS9 + also supports reading and writing color lookup table formats from + the following programs: +

SAOimage
+ SAOtng
+ XImtool
+

+ DS9 uses the file extension to determine the color table format: + + + + + + + + + + + + + + + + + + + + +

+ Ext +	+ Format +
.lut	XImtool, SAOtng
.sao	DS9, SAOimage
any other	DS9

+ +

WCS

+ A new WCS specification can be loaded and used by the current + image regardless of the WCS that was contained in the image file. + WCS specification can be sent to DS9 as an ASCII file via XPA. The + format of the specification is a set of valid FITS keywords that + describe a WCS. +

Example:
+     CRPIX1  + =               + + + + + + + + + + + + + + + + 257.75
+     CRPIX2  + =               + + + + + + + + + + + + + + + + 258.93
+     CRVAL1  + =      -201.94541667302
+     CRVAL2  + =             + + + + + + + + + + + + + + + + -47.45444
+     CDELT1  + =        -2.1277777E-4
+     CDELT2  + =         2.1277777E-4 +
+     CTYPE1  = 'RA---TAN'
+     CTYPE2  = 'DEC--TAN'
+

+ Note that the WCS definitions can contain standard FITS 80 + character WCS card images, as shown above, or free-form name/value + pairs without the intervening "=" sign: +

    CRPIX1    + 257.75
+     CRPIX2    258.93
+     CRVAL1    -201.94541667302
+     CRVAL2    -47.45444
+     CDELT1    -2.1277777E-4
+     CDELT2    2.1277777E-4
+     CTYPE1   'RA---TAN'
+     CTYPE2   'DEC--TAN'

+

Preference File

+ A preference file is a valid tcl script generated by DS9 to save + the current preference items. See Preferences + for more information. +

Startup File

+ If a startup file $HOME/ds9.ini is available, it is + sourced as the last step in initialization. The file permissions + must be group/world readonly.
+ Users may have several different startup files. DS9 looks for a + startup file with its own name. By default, if the application is + named ds9, it will look for .ds9.ini. However, + if the DS9 application is named foo, then DS9 will look + for .foo.ini. In this manner, the user can have several + predefined startup files that are activated by invoking DS9 with a + different application names.
+

TCL

+ TCL/TK script file. Users may customize the appearance and enhance + the capabilities of DS9 by sourcing their own TCL scripts.