[gnuastro-commits] master 8371d675: Installation: SAO DS9 and TOPCAT defined as optional dependencies

[Mohammad Akhlaghi]

branch: master
commit 8371d67504fa3a6a59295ef28635fbd0aeff85e0
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Installation: SAO DS9 and TOPCAT defined as optional dependencies
    
    Until now, the 'astscript-fits-view' and 'astscript-ds9-region' would
    assume that SAO DS9 already exists on the host operating
    system. 'astscript-fits-view' would also assume that TOPCAT exists for
    viewing tables. However, at configure time and in the description of
    optional dependencies, there was no mention of DS9 or TOPCAT.
    
    Also, in the extended PSF tutorial, the first time 'astscript-fits-view'
    was run on a table, there was no mention that the user has to have TOPCAT
    on their system.
    
    With this commit, checks have been added in the configuration script so if
    the user doesn't have them, they are warned/told about this. Also, an item
    has been added for each in the optional dependencies and the commands to
    install the dependencies from package managers now also include these
    two.
    
    Also, in the extended PSF tutorial, TOPCAT has been mentioned upon the
    first usage of 'astscript-fits-view' on a table.
    
    This issue was raised by Aaron Watkins.
    
    In the process, I also noticed that some of the menus of the extended PSF
    tutorial don't have any short description. So one was added for them.
---
 configure.ac                 |  30 ++++++++++++
 doc/announce-acknowledge.txt |   1 +
 doc/gnuastro.texi            | 114 +++++++++++++++++++++++++++++++++----------
 3 files changed, 119 insertions(+), 26 deletions(-)

diff --git a/configure.ac b/configure.ac
index 4e1e7bb5..a1e0a55f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -705,6 +705,16 @@ AM_CONDITIONAL([COND_HASGHOSTSCRIPT], [test 
"x$has_ghostscript" = "xyes"])
 
 
 
+# Check DS9 and TOPCAT
+AC_CHECK_PROG(has_ds9, ds9, [yes], [no])
+AS_IF([test "x$has_ds9" = "xno"], [anywarnings=yes])
+AC_CHECK_PROG(has_topcat, topcat, [yes], [no])
+AS_IF([test "x$has_topcat" = "xno"], [anywarnings=yes])
+
+
+
+
+
 # If any necessary dependency is missing inform the user and abort.
 AS_IF([test "x$missing_mandatory" = "xyes"],
       [
@@ -741,6 +751,10 @@ AS_IF([test "x$missing_mandatory" = "xyes"],
                       [ AS_ECHO([" - Missing Libgit2: https://libgit2.org";])   
                   ])
                 AS_IF([test "x$has_curl" = "x0"],
                       [ AS_ECHO([" - Missing cURL: https://curl.haxx.se";])     
                   ])
+                AS_IF([test "x$has_ds9" = "xno"],
+                      [ AS_ECHO([" - Missing SAO DS9: 
https://sites.google.com/cfa.harvard.edu/saoimageds9";]) ])
+                AS_IF([test "x$has_topcat" = "xno"],
+                      [ AS_ECHO([" - Missing TOPCAT: 
http://www.star.bris.ac.uk/~mbt/topcat/";]) ])
                 AS_IF([test "x$usable_libtool" = "xno"],
                       [ AS_ECHO([" - Unusable GNU Libtool: 
https://www.gnu.org/s/libtool";])
                         AS_IF([test "x$has_gnulibtool" = "xyes"],
@@ -1241,6 +1255,22 @@ AS_IF([test x$enable_guide_message = xyes],
                AS_ECHO(["    first time)."])
                AS_ECHO([]) ])
 
+        AS_IF([test "x$has_ds9" = "xno"],
+              [dependency_notice=yes
+               AS_ECHO(["  - (GUI only) SAO ds9 
(https://sites.google.com/cfa.harvard.edu/saoimageds9)"])
+               AS_ECHO(["    couldn't be found. DS9 is called by 
'astscript-fits-view' to visually"])
+               AS_ECHO(["    inspect FITS images. This doesn't affect the 
building of Gnuastro. So you"])
+               AS_ECHO(["    can safely install it later (after building and 
installing Gnuasro)."])
+               AS_ECHO([]) ])
+
+        AS_IF([test "x$has_topcat" = "xno"],
+              [dependency_notice=yes
+               AS_ECHO(["  - (GUI only) TOPCAT 
(http://www.star.bris.ac.uk/~mbt/topcat) couldn't be"])
+               AS_ECHO(["    found. TOPCAT is called by 'astscript-fits-view' 
to visually inspect"])
+               AS_ECHO(["    astronomical tables. This doesn't affect the 
building of Gnuastro. So "])
+               AS_ECHO(["    you can safely install it later (after building 
and installing Gnuasro)."])
+               AS_ECHO([]) ])
+
         # Notice for obtaining the optional dependencies using a package
         # manager.
         AS_IF([test "x$dependency_notice" = "xyes"],
diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index 8826d4db..2bc50872 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -19,6 +19,7 @@ Ignacio Ruiz Cejudo
 Manuel Sánchez-Benavente
 Peter Teuben
 Jesús Varela
+Aaron Watkins
 
 
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 7bb853a9..1707e53b 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -250,7 +250,7 @@ Tutorials
 * Sufi simulates a detection::  Simulating a detection.
 * General program usage tutorial::  Tutorial on many programs in generic 
scenario.
 * Detecting large extended targets::  NoiseChisel for huge extended targets.
-* Building the extended PSF::
+* Building the extended PSF::   How to extract an extended PSF from science 
data.
 
 Sufi simulates a detection
 
@@ -292,7 +292,7 @@ Building the extended PSF
 
 * Preparing input for extended PSF::  Which stars should be used?
 * Saturated pixels and Segment's clumps::  Saturation is a major hurdle!
-* One object for the whole detection::
+* One object for the whole detection::  Avoiding over-segmentation in objects.
 * Building outer part of PSF::  Building the outermost PSF wings.
 * Inner part of the PSF::       Going towards the PSF center.
 * Uniting the different PSF components::  Merging all the components into one 
PSF.
@@ -1675,6 +1675,11 @@ Besides the interesting scientific questions in these 
low-surface brightness fea
 This is an important issue, especially in wide surveys.
 Because bright/large galaxies and stars@footnote{Stars also have similarly 
large and extended wings due to the point spread function, see @ref{PSF}.}, 
cover a significant fraction of the survey area.
 
+@ref{Building the extended PSF} tackles an important problem in astronomy: how 
the extract the PSF of an image, to the largest possible extent, without 
assuming any functional form.
+In Gnuastro we have multiple installed scripts for this job.
+Their usage and logic behind best tuning them for the particular step, is 
fully described in this tutorial, on a real dataset.
+The tutorial concluds with subtracting that extended PSF from the science 
image; thus giving you a cleaner image (with no scattered light of the brighter 
stars) for your higher-level analysis.
+
 In these tutorials, we have intentionally avoided too many cross references to 
make it more easy to read.
 For more information about a particular program, you can visit the section 
with the same name as the program in this book.
 Each program section in the subsequent chapters starts by explaining the 
general concepts behind what it does, for example see @ref{Convolve}.
@@ -1685,7 +1690,7 @@ For an explanation of the conventions we use in the 
example codes through the bo
 * Sufi simulates a detection::  Simulating a detection.
 * General program usage tutorial::  Tutorial on many programs in generic 
scenario.
 * Detecting large extended targets::  NoiseChisel for huge extended targets.
-* Building the extended PSF::
+* Building the extended PSF::   How to extract an extended PSF from science 
data.
 @end menu
 
 
@@ -5403,7 +5408,7 @@ An overview of the process is given in @ref{Overview of 
the PSF scripts}.
 @menu
 * Preparing input for extended PSF::  Which stars should be used?
 * Saturated pixels and Segment's clumps::  Saturation is a major hurdle!
-* One object for the whole detection::
+* One object for the whole detection::  Avoiding over-segmentation in objects.
 * Building outer part of PSF::  Building the outermost PSF wings.
 * Inner part of the PSF::       Going towards the PSF center.
 * Uniting the different PSF components::  Merging all the components into one 
PSF.
@@ -5444,6 +5449,15 @@ $ astscript-fits-view flat/67510.fits
 @noindent
 Please zoom into the edges again, you will see that they now have the same 
noise-level as the rest of the image (the problematic parts are now gone).
 
+
+
+
+
+
+
+
+
+
 @node Saturated pixels and Segment's clumps, One object for the whole 
detection, Preparing input for extended PSF, Building the extended PSF
 @subsection Saturated pixels and Segment's clumps
 A constant-depth (flat) image was created in the previous section 
(@ref{Preparing input for extended PSF}).
@@ -5666,6 +5680,15 @@ If the issue was only clumps (like in a normal deep 
image processing), this was
 However, in the scenario here, with the very extended wings of the bright 
stars, it usually happens that background objects become ``clumps'' in the 
outskirts and will rip the bright star outskirts into separate ``objects''.
 In the next section (@ref{One object for the whole detection}), we'll describe 
how you can modify Segment to avoid this issue.
 
+
+
+
+
+
+
+
+
+
 @node One object for the whole detection, Building outer part of PSF, 
Saturated pixels and Segment's clumps, Building the extended PSF
 @subsection One object for the whole detection
 
@@ -5806,6 +5829,15 @@ $ rm cat.fits
 @noindent
 We are now ready to start building the outer parts of the PSF in @ref{Building 
outer part of PSF}.
 
+
+
+
+
+
+
+
+
+
 @node Building outer part of PSF, Inner part of the PSF, One object for the 
whole detection, Building the extended PSF
 @subsection Building outer part of PSF
 In @ref{Preparing input for extended PSF}, we described how to create a 
Segment clump and object map, while accounting for saturated stars and won't 
cause over-fragmentation of objects in the outskirts of stars.
@@ -5903,7 +5935,9 @@ $ astscript-fits-view 
finding-normradii/cropped-masked*.fits
 @end example
 
 @noindent
-If everything looks good in the image, let's open all the radial profiles and 
visually check those:
+If everything looks good in the image, let's open all the radial profiles and 
visually check those with the command below.
+Note that @command{astscript-fits-view} calls the @command{topcat} graphic 
user interface (GUI) program to visually inspect (plot) tables.
+If you don't already have it, see @ref{TOPCAT}.
 
 @example
 $ astscript-fits-view finding-normradii/rprofile*.fits
@@ -5963,20 +5997,13 @@ In a large survey like J-PLUS (that we are using here), 
you can simply look into
 Infact, the J-PLUS DR2 tile ID of the field above was intentially preserved 
during the steps above to show how easy it is to use images from other fields 
and blend them all into the output PSF.
 
 
-@c -------------------------------------------
-@c If its worth adding this part?
-@c -------------------------------------------
-@c To fill those regions, we can use the radial profile of the stacked PSF.
-@c Obtaining the radial profile for a simple (square, with a single, circular 
object), image is very easy:
-@c
-@c @example
-@c $ astscript-radial-profile outer/stack.fits -oouter/stack-radial.fits
-@c $ echo "1 251 251 8 300 0 0 1 1 1" \
-@c        | astmkprof --background=outer/stack.fits --clearcanvas \
-@c                    --customtable=outer/stack-radial.fits
-@c
-@c @end example
-@c -------------------------------------------
+
+
+
+
+
+
+
 
 @node Inner part of the PSF, Uniting the different PSF components, Building 
outer part of PSF, Building the extended PSF
 @subsection Inner part of the PSF
@@ -6031,6 +6058,15 @@ $ astscript-fits-view inner/stack.fits 
inner/stamps/*.fits
 @noindent
 We are now ready to unite the two stacks we have constructed: the outer and 
the inner parts.
 
+
+
+
+
+
+
+
+
+
 @node Uniting the different PSF components, Subtracting the PSF, Inner part of 
the PSF, Building the extended PSF
 @subsection Uniting the different PSF components
 
@@ -6215,6 +6251,15 @@ Now that the complete PSF has been obtained, let's 
remove that bad-looking PSF,
 $ rm -rf psf-bad.fits
 @end example
 
+
+
+
+
+
+
+
+
+
 @node Subtracting the PSF,  , Uniting the different PSF components, Building 
the extended PSF
 @subsection Subtracting the PSF
 Previously (in @ref{Uniting the different PSF components}) we constructed a 
full PSF, from the central pixel to a radius of 500 pixels.
@@ -6732,6 +6777,18 @@ Just be sure to have it when you run @command{astquery}, 
otherwise you'll get an
 GPL Ghostscript's executable (@command{gs}) is called by ConvertType to 
compile a PDF file from a source PostScript file, see @ref{ConvertType}.
 Therefore its headers (and libraries) are not needed.
 
+@item SAO DS9
+SAO DS9 (@command{ds9}) is a visualization tool for FITS images.
+Gnuastro's @command{astscript-fits-view} program to visualize FITS images.
+We have a full appendix on it and how to install it in @ref{SAO DS9}.
+Since it is a run-time dependency, it can be installed at any later time 
(after building and installing Gnuastro).
+
+@item TOPCAT
+SAO DS9 (@command{ds9}) is a visualization tool for astronomical tables.
+Gnuastro's @command{astscript-fits-view} program uses it to visualize tables.
+We have a full appendix on it and how to install it in @ref{TOPCAT}.
+Since it is a run-time dependency, it can be installed at any later time 
(after building and installing Gnuastro).
+
 @end table
 
 
@@ -6974,8 +7031,9 @@ All of them use Debian's Advanced Packaging Tool (APT, 
for example @command{apt-
 @example
 $ sudo apt-get install ghostscript libtool-bin libjpeg-dev  \
                        libtiff-dev libgit2-dev curl lzip    \
+                       saods9 topcat                        \
                                                             \
-                       libgsl0-dev libcfitsio-dev wcslib-dev
+                       libgsl-dev libcfitsio-dev wcslib-dev
 @end example
 
 @noindent
@@ -6999,6 +7057,7 @@ If the latter isn't available on your system, you can use 
@command{yum} instead
 @example
 $ sudo dnf install ghostscript libtool libjpeg-devel     \
                    libtiff-devel libgit2-devel lzip curl \
+                   ds9 topcat                            \
                                                          \
                    gsl-devel cfitsio-devel wcslib-devel
 @end example
@@ -7017,20 +7076,20 @@ If not already installed, first obtain Homebrew by 
following the instructions at
 Homebrew manages packages in different `taps'.
 To install WCSLIB (discussed in @ref{Mandatory dependencies}) via Homebrew you 
will need to @command{tap} into @command{brewsci/science} first (the tap may 
change in the future, but can be found by calling @command{brew search wcslib}).
 @example
-$ brew install ghostscript libtool libjpeg libtiff \
-               libgit2 curl lzip                   \
-                                                   \
+$ brew install ghostscript libtool libjpeg libtiff  \
+               libgit2 curl lzip saoimageds9 topcat \
+                                                    \
                gsl cfitsio
 $ brew tap brewsci/science
 $ brew install wcslib
 @end example
 
 @item @command{pacman} (Arch Linux)
-@cindex Arch Linux
+@cindex Arch GNU/Linux
 @cindex @command{pacman}
 @url{https://en.wikipedia.org/wiki/Arch_Linux,Arch Linux} is a smaller 
GNU/Linux distribution, which follows the KISS principle (``keep it simple, 
stupid'') as a general guideline.
 It ``focuses on elegance, code correctness, minimalism and simplicity, and 
expects the user to be willing to make some effort to understand the system's 
operation''.
-Arch Linux uses ``Package manager'' (Pacman) to manage its packages/components.
+Arch GNU/Linux uses ``Package manager'' (Pacman) to manage its 
packages/components.
 @example
 $ sudo pacman -S ghostscript libtool libjpeg libtiff \
                  libgit2 curl lzip                   \
@@ -7038,6 +7097,9 @@ $ sudo pacman -S ghostscript libtool libjpeg libtiff \
                  gsl cfitsio wcslib
 @end example
 
+SAO DS9 and TOPCAT aren't available in the standard Arch GNU/Linux 
repositories.
+However, installing and using both is very easy from their own webpages, as 
described in @ref{SAO DS9} and @ref{TOPCAT}.
+
 @item @command{zypper} (openSUSE and SUSE Linux Enterprise Server)
 @cindex openSUSE
 @cindex SUSE Linux Enterprise Server
@@ -7050,7 +7112,7 @@ packages.
 @example
 $ sudo zypper install ghostscript_any libtool pkgconfig   \
               libcurl-devel libgit2-devel libjpeg62-devel \
-              libtiff-devel curl                          \
+              libtiff-devel curl ds9 topcat               \
                                                           \
               gsl-devel cfitsio-devel wcslib-devel
 @end example