1.. image:: https://readthedocs.org/projects/astlib/badge/?version=latest 2 3astLib provides some tools for research astronomers who use Python. It is divided into several modules: 4 5* astCalc (general calculations, e.g. luminosity distance etc.) 6* astCoords (coordinate conversions etc.) 7* astImages (clip sections from .fits etc.) 8* astPlots (provides a flexible image plot class, e.g. plot image with catalogue objects overlaid) 9* astSED (calculate colours, magnitudes from stellar population models or spectral templates, fit photometric observations using stellar population models etc.) 10* astStats (statistics, e.g. biweight location/scale estimators etc.) 11* astWCS (routines for using FITS World Coordinate System information) 12 13The astWCS module is a higher level interface to PyWCSTools, a simple SWIG (http://www.swig.org) wrapping 14of some of the routines from WCSTools by Jessica Mink (http://tdc-www.harvard.edu/software/wcstools/). It is 15used by some routines in astCoords, astImages and astPlots. 16 17The goal of astLib was to provide features useful to astronomers that are not included in the scipy 18(http://scipy.org), numpy (http://numpy.scipy.org) or matplotlib (http://matplotlib.sourceforge.net) modules 19on which astLib depends. For a far more extensive set of Python astronomy modules, see astropy 20(http://www.astropy.org/). 21 22Some scripts using astLib can be found in the examples/ folder provided with the source code distribution. 23 24 25Software needed 26=============== 27 28astLib requires: 29 30* Python (tested on versions 3.6+) 31* Astropy - http://www.astropy.org (tested on version 3.2.1) 32* Numpy - http://numpy.scipy.org (tested on version 1.18.1) 33* SciPy - http://scipy.org (tested on version 1.3.1) 34* Matplotlib - http://matplotlib.sourceforge.net (tested on version 3.1.1) 35 36From astLib 0.10.0, pyfits is no longer supported, as STScI have depreciated it. If you still require pyfits 37instead of Astropy, please continue to use astLib 0.9.3. 38 39Optional: 40 41* Python Imaging Library - http://www.pythonware.com/products/pil (tested on version 1.1.7) 42 43Other versions of the software listed above are likely to work. 44 45 46Installation 47============ 48 49You can install astLib via pip: 50 51.. code-block:: 52 53 pip install pip 54 55 56You may also install using the standard ``setup.py`` script, e.g., as root: 57 58.. code-block:: 59 60 sudo python setup.py install 61 62 63Alternatively, 64 65.. code-block:: 66 67 python setup.py install --user 68 69 70will install ``astLib`` under ``$HOME/.local`` (on Ubuntu), and in some other default location on Mac. 71 72You can also use the ``--prefix`` option, e.g., 73 74.. code-block:: 75 76 python setup.py install --prefix=$HOME/local 77 78 79and then add, e.g., ``$HOME/local/lib/python3.6/site-packages`` to 80$PYTHONPATH (adjust the path according to your Python version number). 81 82.. code-block:: 83 84 export PYTHONPATH=$HOME/local/lib/python3.6/site-packages:$PYTHONPATH 85 86 87Installation on recent versions of macOS 88======================================== 89 90Some users have reported that the standard method for installing ``astLib`` does not work on recent versions 91of macOS (e.g., Big Sur), due to the default compiler flags. The current workaround for this is to install 92using: 93 94.. code-block:: 95 96 CFLAGS="-Wno-error=implicit-function-declaration" python setup.py install 97 98 99Thanks to Michael Cowley and Stefano Covino for helping to resolve this issue. 100 101 102Usage 103===== 104 105To access the routines in the astLib modules, simply: 106 107.. code-block:: 108 109 from astLib import astCalc 110 from astLib import astCoords 111 from astLib import astWCS 112 113 114etc. 115 116The astWCS module currently provides access to what are (I think) the most commonly needed WCS information 117and functions (such as converting between pixel and WCS coordinates etc.). However, should you wish to 118access the wrapped WCSTools routines themselves directly: 119 120.. code-block:: 121 122 from PyWCSTools import wcs 123 from PyWCSTools import wcscon 124 125etc. 126 127Note that PyWCSTools only includes some functions from wcs.c and wcscon.c at present. For examples of usage, 128look at the Python code for the astLib.astWCS module. Documentation for the WCSTools routines can be found 129here: http://tdc-www.harvard.edu/software/wcstools/subroutines/libwcs.wcs.html. 130 131As of version 0.11.x+, by default the ``astWCS.WCS`` class is using the ``astropy.wcs`` module instead of 132PyWCSTools (this allows one to benefit from some features of ``astropy.wcs`` without having to re-write 133code based on ``astWCS.WCS``). To use PyWCSTools instead, set ``useAstropyWCS = False`` when creating a 134``WCS`` object. 135 136 137Known issues 138============ 139 140This may no longer apply, but just in case... 141 142Recent versions of matplotlib (on which astLib depends) now use locale information. On systems where the 143decimal point separator is not '.' (e.g. Germany), the astWCS coordinate conversions routines will give 144strange results if this is not accounted for. As of version 0.3.0, the astWCS module will detect if this is 145the case and print a warning message to the console. 146 147The workaround for this issue is to add the following after importing any python modules that expicitly set 148the locale (such as matplotlib): 149 150.. code-block:: 151 152 import locale 153 locale.setlocale(locale.LC_NUMERIC, 'C')" 154 155Thanks to Markus Demleitner for pointing this out. 156 157 158Documentation 159============= 160 161Documentation is available on the web at http://astlib.readthedocs.io. 162 163 164Bugs 165==== 166 167Please email bug reports to matt.hilton@mykolab.com, and/or use the `GitHub issues page <https://github.com/mattyowl/astLib/issues>`_. 168 169Please include details of your operating system, python version, and versions of the python packages 170required by astLib that you have installed on your machine. For any WCS-related bugs, it would be helpful 171if you could also include the image header as a text file so that I can reproduce them easily. 172