GNU Astronomy Utilities
=======================

Copyright (C) 2015-2024 Free Software Foundation, Inc.
See the end of the file for license conditions.

GNU Astronomy Utilities (Gnuastro) is an official GNU package of programs
and a library functions for astronomical data manipulation and
analysis. The programs are run directory on the operating system's
command-line enabling easy and efficient operation combined with other
installed programs in shell scripts or Makefiles. The libraries are also
usable in C and C++ programs. The full package comes with a comprehensive
book or documentation in various formats (plain text, info, PDF and HTML):

    http://www.gnu.org/software/gnuastro/manual/

The Gnuastro book explains all the mathematical, physical and even
historical concepts (when necessary) for effective usage of all the
programs and libraries along with short examples for each program and full
descriptions of all their options (in the "Invoking ProgramName'
sections). There is also a separate chapter devoted to tutorials for
effectively use Gnuastro combined with other software already available on
your Unix-like operating system (see Chapter 2).

To install Gnuastro, follow the instructions in the "Install Gnuastro"
section below. If you have already installed gnuastro, you can read the
full book by running the following command. You can go through the whole
book by pressing the 'SPACE' key, and leave the Info environment at any
time by pressing 'q' key. See the "Getting help" section below (in this
file) or in the book for more.

    info gnuastro

Gnuastro's programs are listed below followed by their executable name in
parenthesis and a short description. This list is ordered
alphabetically. In the book, they are grouped and ordered by context under
categories/chapters.

  - Arithmetic (astarithmetic): For arithmetic operations on multiple
    (theoretically unlimited) number of datasets (images). It has a large
    and growing set of arithmetic, mathematical, and even statistical
    operators (for example +, -, *, /, sqrt, log, min, average, median).

  - BuildProgram (astbuildprog): Compile, link and run programs that depend
    on the Gnuastro library. BuildProgram will automatically link with the
    libraries that Gnuastro depends on, so there is no need to explicily
    mention them every time you are compiling a Gnuastro library dependent
    program.

  - ConvertType (astconvertt): Convert astronomical data files (FITS or
    IMH) to and from several other standard image and data formats, for
    example TXT, JPEG, EPS or PDF.

  - Convolve (astconvolve): Convolve (blur or smooth) data with a given
    kernel in spatial and frequency domain on multiple threads. Convolve
    can also do de-convolution to find the appropriate kernel to PSF-match
    two images.

  - CosmicCalculator (astconvolve): Do cosmological calculations, for
    example the luminosity distance, distance modulus, comoving volume and
    many more.

  - Crop (astcrop): Crop region(s) from an image and stitch several images
    if necessary.  Inputs can be in pixel coordinates or world coordinates.

  - Fits (astfits): View and manipulate FITS file HDUs/extensions and
    header keywords.

  - MakeCatalog (astmkcatalog): Make catalog of labeled image (output of
    NoiseChisel). The catalogs are highly customizable and adding new
    calculations/columns is very streightforward.

  - MakeProfiles (astmkprof): Make mock 2D profiles in an image. The
    central regions of radial profiles are made with a configurable 2D
    Monte Carlo integration. It can also build the profiles on an
    over-sampled image.

  - Match (astmatch): Given two input catalogs, find the rows that match
    with each other within a given aperture (may be an ellipse).

  - NoiseChisel (astnoisechisel): Detect and signal in noise. It uses a
    technique to detect very faint and diffuse, irregularly shaped signal
    in noise (galaxies in the sky), using thresholds that are below the Sky
    value (see arXiv:1505.01664).

  - Query (astquery): High-level interface to query pre-defined remote, or
    external, databases and directly download the required sub-tables on the
    command-line.

  - Segment (astsegment): Segment a detection based on the structure of
    signal within it.

  - Statistics (aststatistics): Get pixel statistics and save histogram and
    cumulative frequency plots.

  - Table (asttable): convert FITS binary and ASCII tables into other such
    tables, or print them on the command-line, or save them in a plain text
    file.  Output columns can also be determined by number or regular
    expression matching of column names.

  - Warp (astwarp): Warp image to new pixel grid. By default it will align
    the pixel and WCS coordinates, removing any non-linear WCS distortions.
    Any linear warp (projective transformation or Homography) can also be
    applied to the input images by explicitly calling the respective
    operation.

The programs listed above are designed to be highly modular and
generic. For higher-level operations (combining multiple programs, or
running a program in a special way), Gnuastro also installs Bash scripts
(all prefixed with 'astscript-'). They can be run like a program and behave
very similarly (with minor differences, as explained in the book).

  - astscript-color-faint-gray: Given three images for the Red-Green-Blue
    (RGB) channels, this script will use the bright pixels for color and
    will show the faint/diffuse regions in grayscale. This greatly helps
    in visualizing the full dynamic range of astronical data.

  - astscript-ds9-region: Given a table (either as a file or from
    standard input), create an SAO DS9 region file from the requested
    positional columns (WCS or image coordinates).

  - astscript-fits-view Given any number of FITS files, this script will
    either open SAO DS9 (for images or cubes) or TOPCAT (for tables) to
    view them in a graphic user interface (GUI).

  - astscript-pointing-simulate: Given a table of pointings on the sky,
    create and a reference image that contain's your camera's distortions
    and properties, generate a stacked exposure map. This is very useful in
    testing the coverage of dither patterns when planning your observing
    strategy and it is highly customizable.

  - astscript-radial-profile: Calculate the 1D radial profile or 2D polar
    plot of an object within an image. The object can be at any location in
    the image, using various measures (median, sigma-clipped mean and etc),
    and the radial distance can also be measured on any general ellipse.

  - astscript-sort-by-night: Given a list of FITS files, and a HDU and
    keyword name for a date, this script separates the files in the same
    night (possibly over two calendar days).

  - astscript-psf-select-stars: Find all the stars within an image that are
    suitable for constructing an extended PSF. If the image has WCS, this
    script can automatically query Gaia to find the good stars.

  - astscript-psf-stamp: build a crop (stamp) of a certain width around a
    star at a certain coordinate in a larger image. This script will do
    sub-pixel re-positioning to make sure the star is centered and can
    optionally mask all other background sources).

  - astscript-psf-scale-factor: Given a PSF model, and the central
    coordinates of a star in an image, find the scale factor that has to be
    multiplied by the PSF to scale it to that star.

  - astscript-psf-unite: Unite the various components of a PSF into
    one. Because of saturation and non-linearity, to get a good estimate of
    the extended PSF, its necessary to construct various parts from
    different magnitude ranges.

  - astscript-psf-subtract: Given the model of a PSF and the central
    coordinates of a star in the image, do sub-pixel re-positioning of the
    PSF, scale it to the star and subtract it from the image.

  - astscript-zeropoint: Estimate the zero point (to calibrate pixel
    values) of an input image using a reference image or a reference
    catalog.

All the programs share the same basic command-line user interface and a set
of common options for the comfort of both the users and
developers. Gnuastro is written to comply fully with the GNU coding
standards so it integrates finely with the GNU/Linux operating system and
Unix-like operating systems in general. This also enables astronomers to
expect a fully familiar experience in the source code, building, installing
and command line user interaction that they have seen in all the other GNU
software that they use.

Behind the scenes, Gnuastro comes with a very robust infra-structure
enabling easy addition of new programs and new features to existing
programs and a full chapter devoted to explaining how to develop most
effectively (see the "Developing" chapter). Please join us in developing
this comprehensive and low level set of tools for astronomical data
manipulation and analysis. The copyright owner of Gnuastro is the Free
Software Foundation to guarantee its freedom in the future, and not any
particular astronomer or astronomical project, or astronomical institution,
so please join us and feel free to use it in your research.

Gnuastro's library can also be directly accessed within Makefiles (when run
with GNU Make) to offer workflow organization features that are useful in
data analysis with FITS files. See the "Makefile extensions" section of the
Gnuastro manual for more.


Installing Gnuastro
-------------------

The mandatory dependencies which are required to install Gnuastro from the
tarball are listed below.

  - GNU Scientific Library (GSL): https://www.gnu.org/software/gsl/
  - CFITSIO: http://heasarc.gsfc.nasa.gov/fitsio/
  - WCSLIB: http://www.atnf.csiro.au/people/mcalabre/WCS/

The optional dependencies are:

  - GNU Libtool: https://www.gnu.org/software/libtool/
  - Git library (libgit2): https://libgit2.github.com/
  - JPEG library (libjpeg): http://ijg.org/
  - TIFF library (libtiff): http://simplesystems.org/libtiff/
  - Ghostscript: https://www.ghostscript.com/

See the "Dependencies" section of the book for their detailed installation
guides and optional dependencies to enable extra features. Prior to
installation, you can find it in the 'doc/gnuastro.texi' file (source of
the book), or on the web:

  https://www.gnu.org/software/gnuastro/manual/html_node/Dependencies.html

If you have just cloned Gnuastro and want to install from the version
controlled source, please read the 'README-hacking' file (not available in
the tarball) or the "Bootstrapping dependencies" subsection of the manual
before continuing.

The most recent stable Gnuastro release can be downloaded from the
following link. Please see the "Downloading the source" section of the
Gnuastro book for a more complete discussion of your download options.

    http://ftp.gnu.org/gnu/gnuastro/gnuastro-latest.tar.gz

Unpacking, configuring, building, checking and installing Gnuastro follows
the standard GNU Build system as shown below. After the './configure'
command, Gnuastro will print messages upon the successful completion of
each step, giving further information and suggestions for the next steps.

    tar xf gnuastro-latest.tar.lz        # Also works for 'tar.gz' files
    cd gnuastro-X.X
    ./configure
    make
    make check
    sudo make install

See the "Build and install" section of the book for more information. Also,
see the 'INSTALL' file which is distributed with this file for a standard
(very comprehensive and general) review of the GNU build and install
methods. The 'INSTALL' file is shared in many software packages, so reading
it once in any package is enough to help you greatly customize your build
of a very large collection of Free and Open Source (FOSS) software.



Getting help
------------

To access the appropriate section of the Gnuastro book/documentation from
your command-line (in the middle of your work, without distracting your
self by having to move your hand off the keyboard), please run any of the
following two commands. Note that you can leave the Info environment by
pressing the key 'q'.

    info ProgramName               # For example 'info NoiseChisel'
    info astprogname               # For example 'info astnoisechisel'

The Info environment is great for easily reading of the complete
documentation of many software packages, not just Gnuastro. It can greatly
enhance your life/work in the Unix-like operating systems. If you are not
familiar with it, please run the following command and read through it (it
is short and only takes about an hour, so we strongly recommend it):

    info info

To immediately get a short list of each programs's options and a short
explanation of each, please run:

    astprogname --help             # For example 'astnoisechisel --help'

Ultimately you can send a mail to '[email protected]' to get help in
installing or using Gnuastro. Some Gnuastro developers and active users are
subscribed to this list and are ready to help you in using these programs.



Reporting bugs
--------------

The most effective way to report bugs is explained in the "Report a bug"
section of the documentation, after installation, you can read it by
running (leave the Info environment by pressing the 'q' key afterwards):

    info bug-gnuastro

In short, you can send a mail to '[email protected]', or submit a report
in the link below (the latter is recommended):

    https://savannah.gnu.org/support/?func=additem&group=gnuastro

In any case, please be very descriptive and give the exact command that
produced the bug, we will be able to solve it faster and more effectively
if we can reproduce it after your first report. The list of previous bugs
along with their status can be seen here

    https://savannah.gnu.org/bugs/?group=gnuastro

Have a look in the link above to see if your problem has already been
addressed. Click on "Display Criteria" and choose the "Category" of your
bug for a shorter and more relevant list to look into.





Copyright information
---------------------
Copyright (C) 2015-2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.3 or any later
version published by the Free Software Foundation; with no Invariant
Sections, with no Front-Cover Texts, and with no Back-Cover Texts.