Example:imexam.sh

From FITSH
(Difference between revisions)
Jump to: navigation, search
(Created page with "Although one of the primary design concepts of the '''FITSH''' package was to provide a robust set of command-line driven utilities and to provide a shell-hosted environment f...")
 
m
Line 1: Line 1:
 
Although one of the primary design concepts of the '''FITSH''' package was to provide a robust set of command-line driven utilities and to provide a shell-hosted environment for massive batched image processing; the individual '''FITSH''' tasks can be exploited easily to create interactive applications as well. In this example we show how the tasks [[firandom]], [[fiphot]] and [[lfit]] can be used to implement the well-known [[IRAF]] task, [http://stsdas.stsci.edu/cgi-bin/gethelp.cgi?imexamine imexamine] (that is usually referred as simply as '''imexam''', see also [http://www.astro.washington.edu/courses/astro480/IRAF/iraf1_tutorial.html this] or [http://noao.edu/kpno/manuals/ice/node31.html this] references).
 
Although one of the primary design concepts of the '''FITSH''' package was to provide a robust set of command-line driven utilities and to provide a shell-hosted environment for massive batched image processing; the individual '''FITSH''' tasks can be exploited easily to create interactive applications as well. In this example we show how the tasks [[firandom]], [[fiphot]] and [[lfit]] can be used to implement the well-known [[IRAF]] task, [http://stsdas.stsci.edu/cgi-bin/gethelp.cgi?imexamine imexamine] (that is usually referred as simply as '''imexam''', see also [http://www.astro.washington.edu/courses/astro480/IRAF/iraf1_tutorial.html this] or [http://noao.edu/kpno/manuals/ice/node31.html this] references).
  
Indeed, '''FITSH''' does not provide any tool for plotting, so displaying the respective graphs and plots expected from this '''imexam''' scriptlet; we have to use some third-party tool for this purpose. In our example here, we employ one of the most popular free graphing utility, [http://www.gnuplot.info/ gnuplot]. Similarly to the original [[IRAF]]-hosted implementation, this '''imexam''' scriptlet exploits the built-in features of the astronomical visualization application [[DS9]] and uses the [[XPA|XPA messaging interface]] in order to establish communication between the scriptlet and [[DS9]]. Therefore, this program expects all of the above utilities installed and properly configured on your system. In addition, this example needs also some [[awk]] implementation as well.
+
Indeed, '''FITSH''' does not provide any tool for plotting, so displaying the respective graphs and plots expected from this '''imexam''' scriptlet; we have to use some third-party tool for this purpose. In our example here, we employ one of the most popular free graphing utility, [[gnuplot]]. Similarly to the original [[IRAF]]-hosted implementation, this '''imexam''' scriptlet exploits the built-in features of the astronomical visualization application [[DS9]] and uses the [[XPA|XPA messaging interface]] in order to establish communication between the scriptlet and [[DS9]]. Therefore, this program expects all of the above utilities installed and properly configured on your system. In addition, this example needs also some [[awk]] implementation as well.
 +
 
 +
=== Configuration parameters ===
 +
 
 +
In the beginning of this '''imexam''' script, one must setup the current locations of the required programs ([[xpaget]] for communicating with [[DS9]] via the [[XPA|XPA messaging system]], [[awk]], [[gnuplot]], and the '''FITSH''' tasks). Basically, we can safely suppose that all of these programs are found in the shell's path (see <code>$PATH</code> variable), so these declarations are the following:
 +
 
 +
<nowiki>
 +
#!/bin/bash
 +
 
 +
# Required external binaries:
 +
AWK=awk
 +
XPAGET=xpaget
 +
GNUPLOT=gnuplot
 +
FIRANDOM=firandom
 +
FIPHOT=fiphot
 +
LFIT=lfit</nowiki>
 +
 
 +
Then, we must setup some initial parameters of the image sampling and aperture photometry:
 +
 
 +
<nowiki>
 +
# default plotting parameters:
 +
radialradius=10
 +
sx=16
 +
sy=16
 +
aperture=5:7:5</nowiki>
 +
 
 +
Here, <code>$sx</code> and <code>$sy</code> are the dimensions of the image sample that is read from [[DS9]] via [[XPA]] and only this stamp is used for further analysis. The variable <code>$radialradius</code> is used as the maximum radius of the radial plot while the parameter <code>$aperture</code> is passed directly to [[fiphot]] when it is neccessary. It is safe to override this default values but one has to be sure that all of these altered in accordance (do not specify a value for <code>$radialradius</code> that is larger than the half of the diameter of the sampling box, etc.).
 +
 
 +
Of course, the script can be extended easily to parse command line arguments and override these default values. In addition, the [[XPA]] tool [[xpaset]] can also be exploited to upload images to [[DS9]] before any real image examination starts (similarly to the display task in [[IRAF]]).
 +
 
 +
=== The complete script ===
 +
 
 +
The complete working script is not so long compared to the programming standards (merely ~210 lines of bash/shell script code), but it is not copied here. You can download the fully working script: [http://fitsh.net/static/scripts/imexam/imexam.sh imexam.sh]. Just copy it some directory what is in your shell's <code>$PATH</code> and type <code>imexam.sh</code> to start it. Note that this is still just a demonstration script, so if you intend to alter the analysis parameters (see above), you also have to alter the respective parts of the shell script.
 +
 
 +
Here are also some screenshots showing this script in action: a surface plot (key "S" is pressed), a radial plot (key "R" is pressed) and a contour plot (key "E" is pressed). Of course, the script itself is just started from a terminal. Hence, [[DS9]] should be opened (with the image of interest) before the script is started and the [[gnuplot]] window is displayed by the script itself.

Revision as of 21:23, 8 September 2016

Although one of the primary design concepts of the FITSH package was to provide a robust set of command-line driven utilities and to provide a shell-hosted environment for massive batched image processing; the individual FITSH tasks can be exploited easily to create interactive applications as well. In this example we show how the tasks firandom, fiphot and lfit can be used to implement the well-known IRAF task, imexamine (that is usually referred as simply as imexam, see also this or this references).

Indeed, FITSH does not provide any tool for plotting, so displaying the respective graphs and plots expected from this imexam scriptlet; we have to use some third-party tool for this purpose. In our example here, we employ one of the most popular free graphing utility, gnuplot. Similarly to the original IRAF-hosted implementation, this imexam scriptlet exploits the built-in features of the astronomical visualization application DS9 and uses the XPA messaging interface in order to establish communication between the scriptlet and DS9. Therefore, this program expects all of the above utilities installed and properly configured on your system. In addition, this example needs also some awk implementation as well.

Configuration parameters

In the beginning of this imexam script, one must setup the current locations of the required programs (xpaget for communicating with DS9 via the XPA messaging system, awk, gnuplot, and the FITSH tasks). Basically, we can safely suppose that all of these programs are found in the shell's path (see $PATH variable), so these declarations are the following:

#!/bin/bash

# Required external binaries:
AWK=awk
XPAGET=xpaget
GNUPLOT=gnuplot
FIRANDOM=firandom
FIPHOT=fiphot
LFIT=lfit

Then, we must setup some initial parameters of the image sampling and aperture photometry:

# default plotting parameters:
radialradius=10
sx=16
sy=16
aperture=5:7:5

Here, $sx and $sy are the dimensions of the image sample that is read from DS9 via XPA and only this stamp is used for further analysis. The variable $radialradius is used as the maximum radius of the radial plot while the parameter $aperture is passed directly to fiphot when it is neccessary. It is safe to override this default values but one has to be sure that all of these altered in accordance (do not specify a value for $radialradius that is larger than the half of the diameter of the sampling box, etc.).

Of course, the script can be extended easily to parse command line arguments and override these default values. In addition, the XPA tool xpaset can also be exploited to upload images to DS9 before any real image examination starts (similarly to the display task in IRAF).

The complete script

The complete working script is not so long compared to the programming standards (merely ~210 lines of bash/shell script code), but it is not copied here. You can download the fully working script: imexam.sh. Just copy it some directory what is in your shell's $PATH and type imexam.sh to start it. Note that this is still just a demonstration script, so if you intend to alter the analysis parameters (see above), you also have to alter the respective parts of the shell script.

Here are also some screenshots showing this script in action: a surface plot (key "S" is pressed), a radial plot (key "R" is pressed) and a contour plot (key "E" is pressed). Of course, the script itself is just started from a terminal. Hence, DS9 should be opened (with the image of interest) before the script is started and the gnuplot window is displayed by the script itself.

Personal tools