No description
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 '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. 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 'bug-gnuastro@gnu.org', 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.