Copyright (C) 2015-2021, 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 gnuastroGnuastro'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.
Header (astheader): Print and manipulate the header data of a FITS file.
Match (astmatch): Given two input catalogs, find the rows that match with each other within a given aperture (may be an ellipse).
MakeCatalog (astmkcatalog): Make catalog of labeled image (output of NoiseChisel). The catalogs are highly customizable and adding new calculations/columns is very streightforward.
MakeNoise (astmknoise): Make (add) noise to an image, with a large set of random number generators and any seed.
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.
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. Any projective transformation or Homography can be applied to the input images.
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-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-radial-profile: Calculate the radial profile 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).
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.
The mandatory dependencies which are required to install Gnuastro from the tarball are listed below.
The optional dependencies are:
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.gzUnpacking, 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 installSee 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.
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 infoTo 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 'help-gnuastro@gnu.org' 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.
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-gnuastroIn short, you can send a mail to 'bug-gnuastro@gnu.org', or submit a report in the link below (the latter is recommended):
https://savannah.gnu.org/support/?func=additem&group=gnuastroIn 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=gnuastroHave 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 (C) 2015-2021, 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.