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
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
|
#!/bin/sh
# Convert the given two columns into a ds9 region file.
#
# Original author:
# Mohammad Akhlaghi <mohammad@akhlaghi.org>
# Contributing author(s):
# Samane Raji <samaneraji@protonmail.com>
# Raul Infante-Sainz <infantesainz@gmail.com>
# Copyright (C) 2021-2025 Free Software Foundation, Inc.
#
# Gnuastro is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option)
# any later version.
#
# Gnuastro is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
# more details.
#
# You should have received a copy of the GNU General Public License along
# with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
# Exit the script in the case of failure
set -e
# 'LC_NUMERIC' is responsible for formatting numbers printed by the OS. It
# prevents floating points like '23,45' instead of '23.45'.
export LC_NUMERIC=C
# Default option values (can be changed with options on the
# command-line).
hdu=1
col=""
width=1
mode=wcs
radius=""
command=""
namecol=""
fontsize=12
out=ds9.reg
color=green
dontdelete=0
version=@VERSION@
scriptname=@SCRIPT_NAME@
# Output of '--usage' and '--help':
print_usage() {
cat <<EOF
$scriptname: run with '--help' for list of options
EOF
}
print_help() {
cat <<EOF
Usage: $scriptname [OPTION] FITS-files
This script is part of GNU Astronomy Utilities $version.
This script will take two column names (or numbers) and return a "region
file" (with one region over each entry) for easy inspection of catalog
entries in this SAO DS9.
For more information, please run any of the following commands. In
particular the first contains a very comprehensive explanation of this
script's invocation: expected input(s), output(s), and a full description
of all the options.
Inputs/Outputs and options: $ info $scriptname
Full Gnuastro manual/book: $ info gnuastro
If you couldn't find your answer in the manual, you can get direct help from
experienced Gnuastro users and developers. For more information, please run:
$ info help-gnuastro
$scriptname options:
Input:
-h, --hdu=STR HDU/extension of all input FITS files.
-c, --column=STR,STR Columns to use as coordinates (name or number).
-m, --mode=wcs|img Coordinates in WCS or image (default: $mode)
-n, --namecol=STR ID of each region (name or number of a column)
Output:
-C, --color=STR Color for the regions (read by DS9).
-w, --width=INT Line thickness of the regions (in DS9).
-r, --radius=FLT Radius of each region (arcseconds if in WCS mode).
-s, --fontsize=INT Font size for name.
-D, --dontdelete Don't delete output if it exists.
-o, --output=STR Name of output file.
--command="STR" DS9 command to run after making region.
Operating mode:
-?, --help Print this help list.
--cite BibTeX citation for this program.
-V, --version Print program version.
Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.
GNU Astronomy Utilities home page: http://www.gnu.org/software/gnuastro/
Report bugs to bug-gnuastro@gnu.org.
EOF
}
# Output of '--version':
print_version() {
cat <<EOF
$scriptname (GNU Astronomy Utilities) $version
Copyright (C) 2015-2025 Free Software Foundation, Inc.
License GPLv3+: GNU General public license version 3 or later.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Written/developed by Mohammad Akhlaghi
EOF
}
# Functions to check option values and complain if necessary.
on_off_option_error() {
if [ x"$2" = x ]; then
echo "$scriptname: '$1' doesn't take any values"
else
echo "$scriptname: '$1' (or '$2') doesn't take any values"
fi
exit 1
}
check_v() {
if [ x"$2" = x ]; then
cat <<EOF
$scriptname: option '$1' requires an argument. Try '$scriptname --help' for more information
EOF
exit 1;
fi
}
# Separate command-line arguments from options. Then put the option
# value into the respective variable.
#
# OPTIONS WITH A VALUE:
#
# Each option has three lines because we want to all common formats: for
# long option names: '--longname value' and '--longname=value'. For short
# option names we want '-l value', '-l=value' and '-lvalue' (where '-l'
# is the short version of the hypothetical '--longname' option).
#
# The first case (with a space between the name and value) is two
# command-line arguments. So, we'll need to shift it two times. The
# latter two cases are a single command-line argument, so we just need to
# "shift" the counter by one. IMPORTANT NOTE: the ORDER OF THE LATTER TWO
# cases matters: '-h*' should be checked only when we are sure that its
# not '-h=*').
#
# OPTIONS WITH NO VALUE (ON-OFF OPTIONS)
#
# For these, we just want the two forms of '--longname' or '-l'. Nothing
# else. So if an equal sign is given we should definitely crash and also,
# if a value is appended to the short format it should crash. So in the
# second test for these ('-l*') will account for both the case where we
# have an equal sign and where we don't.
input=""
while [ $# -gt 0 ]
do
# Initialize 'tcol':
tcol=""
# Put the values in the proper variable.
case "$1" in
# Input parameters.
-h|--hdu) hdu="$2"; check_v "$1" "$hdu"; shift;shift;;
-h=*|--hdu=*) hdu="${1#*=}"; check_v "$1" "$hdu"; shift;;
-h*) hdu=$(echo "$1" | sed -e's/-h//'); check_v "$1" "$hdu"; shift;;
-c|--column) tcol="$2"; check_v "$1" "$tcol"; shift;shift;;
-c=*|--column=*) tcol="${1#*=}"; check_v "$1" "$tcol"; shift;;
-c*) tcol=$(echo "$1" | sed -e's/-c//'); check_v "$1" "$tcol"; shift;;
-m|--mode) mode="$2"; check_v "$1" "$mode"; shift;shift;;
-m=*|--mode=*) mode="${1#*=}"; check_v "$1" "$mode"; shift;;
-m*) mode=$(echo "$1" | sed -e's/-m//'); check_v "$1" "$mode"; shift;;
-n|--namecol) namecol="$2"; check_v "$1" "$namecol"; shift;shift;;
-n=*|--namecol=*) namecol="${1#*=}"; check_v "$1" "$namecol"; shift;;
-n*) namecol=$(echo "$1" | sed -e's/-n//'); check_v "$1" "$namecol"; shift;;
# Output parameters
-C|--color) color="$2"; check_v "$1" "$color"; shift;shift;;
-C=*|--color=*) color="${1#*=}"; check_v "$1" "$color"; shift;;
-C*) color=$(echo "$1" | sed -e's/-C//'); check_v "$1" "$color"; shift;;
-w|--width) width="$2"; check_v "$1" "$width"; shift;shift;;
-w=*|--width=*) width="${1#*=}"; check_v "$1" "$width"; shift;;
-w*) width=$(echo "$1" | sed -e's/-w//'); check_v "$1" "$width"; shift;;
-r|--radius) radius="$2"; check_v "$1" "$radius"; shift;shift;;
-r=*|--radius=*) radius="${1#*=}"; check_v "$1" "$radius"; shift;;
-r*) radius=$(echo "$1" | sed -e's/-r//'); check_v "$1" "$radius"; shift;;
-s|--fontsize) fontsize="$2"; check_v "$1" "$fontsize"; shift;shift;;
-s=*|--fontsize=*) fontsize="${1#*=}"; check_v "$1" "$fontsize"; shift;;
-s*) fontsize=$(echo "$1" | sed -e's/-s//'); check_v "$1" "$fontsize"; shift;;
-D|--dontdelete) dontdelete=1; shift;;
-D*|--dontdelete=*) on_off_option_error --dontdelete -D;;
-o|--output) out="$2"; check_v "$1" "$out"; shift;shift;;
-o=*|--output=*) out="${1#*=}"; check_v "$1" "$out"; shift;;
-o*) out=$(echo "$1" | sed -e's/-o//'); check_v "$1" "$out"; shift;;
--command) command="$2"; check_v "$1" "$command"; shift;shift;;
--command=*) command="${1#*=}"; check_v "$1" "$command"; shift;;
# Non-operating options.
-?|--help) print_help; exit 0;;
-'?'*|--help=*) on_off_option_error --help -?;;
-V|--version) print_version; exit 0;;
-V*|--version=*) on_off_option_error --version -V;;
--cite) astfits --cite; exit 0;;
--cite=*) on_off_option_error --cite;;
# Unrecognized option:
-*) echo "$scriptname: unknown option '$1'"; exit 1;;
# Not an option (not starting with a '-'): assumed to be input FITS
# file name.
*) if [ x"$input" = x ]; then
if [ -f "$1" ]; then
input="$1";
else echo "$scriptname: $1: no such file"; exit 1;
fi;
else echo "$scriptname: only one input should be given"; exit 1
fi; shift;;
esac
# If a column was given, add it to possibly existing previous columns
# into a comma-separate list.
if [ x"$tcol" != x ]; then
if [ x"$col" != x ]; then col="$col,$tcol"; else col=$tcol; fi
fi
done
# Basic sanity checks
# ===================
# Make sure only two columns are given, then set the columns.
if [ x"$col" = x ]; then
echo "$scriptname: no columns specified, you can use '--column' (or '-c')"
exit 1
else
ncols=$(echo $col | awk 'BEGIN{FS=","} \
{for(i=1;i<=NF;++i) c+=$i!=""} \
END{print c}')
if [ x$ncols != x2 ]; then
echo "$scriptname: only two columns should be given with '--column' (or '-c'), but $ncols were given"
exit 1
fi
fi
# Make sure the value to '--mode' is either 'wcs' or 'img'. Note: '-o'
# means "or" and is preferred to '[ ] || [ ]' because only a single
# invocation of 'test' is done. Run 'man test' for more.
if [ "$mode" = wcs -o $mode = "img" ]; then
junk=1
else
echo "$scriptname: value to '--mode' ('-m') should be 'wcs' or 'img'"
exit 1
fi
# If the output already exists and the user doesn't want to overwrite, then
# abort with an error.
if [ -f $out ]; then
if [ $dontdelete = 1 ]; then
echo "$scriptname: '$out' already exists! Aborting due to '--dontdelete'"
exit 1
fi
fi
# Make sure a single column is given to '--namecol':
if [ x"$namecol" != x ]; then
ncols=$(echo $namecol | awk 'BEGIN{FS=","}END{print NF}')
if [ x$ncols != x1 ]; then
echo "$scriptname: only one column should be given to '--namecol'"
exit 1
fi
fi
# Initalize the radius value if not given. If we are in WCS mode, select a
# 3 arcsecond radius and if we are in image mode, select a 5 pixel radius.
if [ x"$radius" = x ]; then
if [ "$mode" = wcs ]; then radius=1
else radius=3
fi
fi
# Set the units of the radius.
if [ x"$mode" = xwcs ]; then unit="\""; else unit=""; fi
# Set the font size.
font="font=\"helvetica $fontsize normal roman\""
# Write the metadata in the output.
printf "# Region file format: DS9 version 4.1\n" > $out
printf "# Created by $scriptname (GNU Astronomy Utilities) $version\n" >> $out
if [ x"$input" = x ]; then printf "# Input from stdin\n" >> $out
else printf "# Input file: $input (hdu $hdu)\n" >> $out
fi
printf "# Columns: $col\n" >> $out
if [ x"$namecol" != x ]; then
printf "# Region name (or label) column: $namecol\n" >> $out
fi
printf "global color=%s width=%d\n" $color $width >> $out
if [ "$mode" = wcs ]; then printf "icrs\n" >> $out
else printf "image\n" >> $out; fi
# Write each region's results (when no input file is given, read from the
# standard input). Note that the 'unit' string will be empty in image-mode
# coordinates. As a result, it we don't enclose it in double-quotations,
# 'printf' will not see anything and use the next variable where the unit
# should be printed! See https://savannah.gnu.org/bugs/index.php?64153
if [ x"$namecol" = x ]; then
if [ x"$input" = x ]; then
cat /dev/stdin \
| asttable --column=$col \
| while read a b; do \
printf "circle(%f,%f,%f%s)\n" \
$a $b $radius "$unit" >> $out; \
done
else
asttable $input --hdu=$hdu --column=$col \
| while read a b; do \
printf "circle(%f,%f,%f%s)\n" \
$a $b $radius "$unit" >> $out; \
done
fi
else
if [ x"$input" = x ]; then
cat /dev/stdin \
| asttable --column=$col --column=$namecol \
| while read a b c; do \
printf "circle(%f,%f,%f%s) # $font text={%g}\n" \
$a $b $radius "$unit" $c >> $out; \
done
else
asttable $input --hdu=$hdu --column=$col --column=$namecol \
| while read a b c; do \
printf "circle(%f,%f,%f%s) # $font text={%g}\n" \
$a $b $radius "$unit" $c >> $out; \
done
fi
fi
# Run the user's command (while appending the region).
if [ x"$command" != x ]; then
$command -regions $out
if [ $dontdelete = 0 ]; then rm $out; fi
fi
|
