summaryrefslogtreecommitdiffstats
path: root/funtools/man/man7/funds9.7
blob: 963084a2d9e20a0c2f0ab51d5b72c02d09f106af (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "funds9 7"
.TH funds9 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
.SH "NAME"
FunDS9 \- Funtools and DS9 Image Display
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Describes how funtools can be integrated into the ds9 Analysis menu.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
SAOImage/DS9 is an astronomical imaging and data visualization
application used by astronomers around the world.  \s-1DS9\s0 can display
standard astronomical \s-1FITS\s0 images and binary tables, but also has
support for displaying raw array files, shared memory files, and data
files automatically retrieved via \s-1FTP\s0 and \s-1HTTP\s0.  Standard functional
capabilities include multiple frame buffers, colormap and region
manipulation, and many data scaling algorithms. \s-1DS9\s0's advanced
features include TrueColor visuals, deep frame buffers, true
PostScript printing, and display of image mosaics. The program's
support of image tiling, \*(L"blinking\*(R", arbitrary zoom, rotation, and pan
is unparalleled in astronomy. It also has innovative support for
automatic retrieval and display of standard image data such as the
Digital Sky Survey (using servers at \s-1SAO\s0, StScI, or \s-1ESO\s0).
.PP
\&\s-1DS9\s0 can communicate with external programs such as Funtools using the
\&\s-1XPA\s0
messaging system.  In addition, programs can be integrated directly
into the \s-1DS9\s0 \s-1GUI\s0 by means of a configurable Analysis menu.  By
default, the \s-1DS9\s0 Analysis menu contains algorithms deemed essential to
the core functions of \s-1DS9\s0, e.g., display cross-cuts of data,
iso-intensity contours, and \s-1WCS\s0 grids. However, new programs can be
added to \s-1DS9\s0 by creating a set-up file which can be loaded into \s-1DS9\s0 
to reconfigure the Analysis menu.
.PP
The basic format of the analysis set-up file is:
.PP
.Vb 6
\&  #
\&  # Analysis command descriptions:
\&  #   menu label/description
\&  #   file templates for this command
\&  #   "menu" (add to menu) |"bind" (bind to key)
\&  #   analysis command line
.Ve
.PP
For example, the funcnts program can be specified in this way:
.PP
.Vb 4
\&  Funcnts (counts in source/bkgd regions; options: none)
\&  *
\&  menu
\&  funcnts $filename $regions(source,,) $regions(background,,) | $text
.Ve
.PP
As shown above, \s-1DS9\s0 supports a macro facility to provide information
as well as task support to command lines. For example, the \f(CW$regions\fR
macro is expanded by \s-1DS9\s0 to provide the current source and/or
background region to the analysis command. The \f(CW$text\fR macro is expanded
to generate a text window display. It also is possible to query for
parameters using a \f(CW$param\fR macro, plot data using a \f(CW$plot\fR macro,
etc. See the \s-1DS9\s0 documentation for further details.
.PP
A set-up file called funtools.ds9 will
load some useful Funtools applications (counts in regions, radial
profile, X\-ray light curve and energy spectrum, 1D histogram) into the \s-1DS9\s0
Analysis menu (version 2.1 and above).  The file resides in the bin
directory where Funtools programs are installed. It can be manually
loaded into \s-1DS9\s0 from the \fBLoad Analysis Commands ...\fR option of
the \fBAnalysis\fR menu.  Alternatively, you can tell \s-1DS9\s0 to load
this file automatically at start-up time by adding the pathname to the
\&\fBEdit\fR\->\fBPreferences\fR\->\fBAnalysis Menu\fR\->Analysis
File menu option.  (\s-1NB:\s0 make sure you select
\&\fBEdit\fR\->\fBPreferences\fR\->\fBSave Preferences\fR after setting
the pathname.)
.PP
The tasks in this setup file generally process the original disk-based
\&\s-1FITS\s0 file.  Funcnts-based results (radial profile, counts in regions)
are presented in \s-1WCS\s0 units, if present in the \s-1FITS\s0 header. For
situations where a disk file is not available (e.g., image data
generated and sent to \s-1DS9\s0's 'fits' \s-1XPA\s0 access point), versions of the
radial profile and counts in regions tasks also are also offered
utilizing \s-1DS9\s0's internal image data. Results are presented in pixels.
Aside from the units, the results should be identical to the file-based
results.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See funtools(7) for a list of Funtools help pages