1{ 2 "body": "<div class=\"section\" id=\"introduction-and-installation\">\n<span id=\"usagepage\"></span><h1>Introduction and Installation<a class=\"headerlink\" href=\"#introduction-and-installation\" title=\"Permalink to this headline\">\u00b6</a></h1>\n<img alt=\"https://readthedocs.org/projects/astlib/badge/?version=latest\" src=\"https://readthedocs.org/projects/astlib/badge/?version=latest\" />\n<p>astLib provides some tools for research astronomers who use Python. It is divided into several modules:</p>\n<ul class=\"simple\">\n<li><p>astCalc (general calculations, e.g. luminosity distance etc.)</p></li>\n<li><p>astCoords (coordinate conversions etc.)</p></li>\n<li><p>astImages (clip sections from .fits etc.)</p></li>\n<li><p>astPlots (provides a flexible image plot class, e.g. plot image with catalogue objects overlaid)</p></li>\n<li><p>astSED (calculate colours, magnitudes from stellar population models or spectral templates, fit photometric observations using stellar population models etc.)</p></li>\n<li><p>astStats (statistics, e.g. biweight location/scale estimators etc.)</p></li>\n<li><p>astWCS (routines for using FITS World Coordinate System information)</p></li>\n</ul>\n<p>The astWCS module is a higher level interface to PyWCSTools, a simple SWIG (<a class=\"reference external\" href=\"http://www.swig.org\">http://www.swig.org</a>) wrapping\nof some of the routines from WCSTools by Jessica Mink (<a class=\"reference external\" href=\"http://tdc-www.harvard.edu/software/wcstools/\">http://tdc-www.harvard.edu/software/wcstools/</a>). It is\nused by some routines in astCoords, astImages and astPlots.</p>\n<p>The goal of astLib was to provide features useful to astronomers that are not included in the scipy\n(<a class=\"reference external\" href=\"http://scipy.org\">http://scipy.org</a>), numpy (<a class=\"reference external\" href=\"http://numpy.scipy.org\">http://numpy.scipy.org</a>) or matplotlib (<a class=\"reference external\" href=\"http://matplotlib.sourceforge.net\">http://matplotlib.sourceforge.net</a>) modules\non which astLib depends. For a far more extensive set of Python astronomy modules, see astropy\n(<a class=\"reference external\" href=\"http://www.astropy.org/\">http://www.astropy.org/</a>).</p>\n<p>Some scripts using astLib can be found in the examples/ folder provided with the source code distribution.</p>\n<div class=\"section\" id=\"software-needed\">\n<h2>Software needed<a class=\"headerlink\" href=\"#software-needed\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>astLib requires:</p>\n<ul class=\"simple\">\n<li><p>Python (tested on versions 3.6+)</p></li>\n<li><p>Astropy - <a class=\"reference external\" href=\"http://www.astropy.org\">http://www.astropy.org</a> (tested on version 3.2.1)</p></li>\n<li><p>Numpy - <a class=\"reference external\" href=\"http://numpy.scipy.org\">http://numpy.scipy.org</a> (tested on version 1.18.1)</p></li>\n<li><p>SciPy - <a class=\"reference external\" href=\"http://scipy.org\">http://scipy.org</a> (tested on version 1.3.1)</p></li>\n<li><p>Matplotlib - <a class=\"reference external\" href=\"http://matplotlib.sourceforge.net\">http://matplotlib.sourceforge.net</a> (tested on version 3.1.1)</p></li>\n</ul>\n<p>From astLib 0.10.0, pyfits is no longer supported, as STScI have depreciated it. If you still require pyfits\ninstead of Astropy, please continue to use astLib 0.9.3.</p>\n<p>Optional:</p>\n<ul class=\"simple\">\n<li><p>Python Imaging Library - <a class=\"reference external\" href=\"http://www.pythonware.com/products/pil\">http://www.pythonware.com/products/pil</a> (tested on version 1.1.7)</p></li>\n</ul>\n<p>Other versions of the software listed above are likely to work.</p>\n</div>\n<div class=\"section\" id=\"installation\">\n<h2>Installation<a class=\"headerlink\" href=\"#installation\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>You can install astLib via pip:</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span><span class=\"n\">pip</span> <span class=\"n\">install</span> <span class=\"n\">pip</span>\n</pre></div>\n</div>\n<p>You may also install using the standard <code class=\"docutils literal notranslate\"><span class=\"pre\">setup.py</span></code> script, e.g., as root:</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span><span class=\"n\">sudo</span> <span class=\"n\">python</span> <span class=\"n\">setup</span><span class=\"o\">.</span><span class=\"n\">py</span> <span class=\"n\">install</span>\n</pre></div>\n</div>\n<p>Alternatively,</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span><span class=\"n\">python</span> <span class=\"n\">setup</span><span class=\"o\">.</span><span class=\"n\">py</span> <span class=\"n\">install</span> <span class=\"o\">--</span><span class=\"n\">user</span>\n</pre></div>\n</div>\n<p>will install <code class=\"docutils literal notranslate\"><span class=\"pre\">astLib</span></code> under <code class=\"docutils literal notranslate\"><span class=\"pre\">$HOME/.local</span></code> (on Ubuntu), and in some other default location on Mac.</p>\n<p>You can also use the <code class=\"docutils literal notranslate\"><span class=\"pre\">--prefix</span></code> option, e.g.,</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span>python setup.py install --prefix=$HOME/local\n</pre></div>\n</div>\n<p>and then add, e.g., <code class=\"docutils literal notranslate\"><span class=\"pre\">$HOME/local/lib/python3.6/site-packages</span></code> to\n$PYTHONPATH (adjust the path according to your Python version number).</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span>export PYTHONPATH=$HOME/local/lib/python3.6/site-packages:$PYTHONPATH\n</pre></div>\n</div>\n</div>\n<div class=\"section\" id=\"installation-on-recent-versions-of-macos\">\n<h2>Installation on recent versions of macOS<a class=\"headerlink\" href=\"#installation-on-recent-versions-of-macos\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>Some users have reported that the standard method for installing <code class=\"docutils literal notranslate\"><span class=\"pre\">astLib</span></code> does not work on recent versions\nof macOS (e.g., Big Sur), due to the default compiler flags. The current workaround for this is to install\nusing:</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span><span class=\"n\">CFLAGS</span><span class=\"o\">=</span><span class=\"s2\">"-Wno-error=implicit-function-declaration"</span> <span class=\"n\">python</span> <span class=\"n\">setup</span><span class=\"o\">.</span><span class=\"n\">py</span> <span class=\"n\">install</span>\n</pre></div>\n</div>\n<p>Thanks to Michael Cowley and Stefano Covino for helping to resolve this issue.</p>\n</div>\n<div class=\"section\" id=\"usage\">\n<h2>Usage<a class=\"headerlink\" href=\"#usage\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>To access the routines in the astLib modules, simply:</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span><span class=\"kn\">from</span> <span class=\"nn\">astLib</span> <span class=\"kn\">import</span> <span class=\"n\">astCalc</span>\n<span class=\"kn\">from</span> <span class=\"nn\">astLib</span> <span class=\"kn\">import</span> <span class=\"n\">astCoords</span>\n<span class=\"kn\">from</span> <span class=\"nn\">astLib</span> <span class=\"kn\">import</span> <span class=\"n\">astWCS</span>\n</pre></div>\n</div>\n<p>etc.</p>\n<p>The astWCS module currently provides access to what are (I think) the most commonly needed WCS information\nand functions (such as converting between pixel and WCS coordinates etc.). However, should you wish to\naccess the wrapped WCSTools routines themselves directly:</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span><span class=\"kn\">from</span> <span class=\"nn\">PyWCSTools</span> <span class=\"kn\">import</span> <span class=\"n\">wcs</span>\n<span class=\"kn\">from</span> <span class=\"nn\">PyWCSTools</span> <span class=\"kn\">import</span> <span class=\"n\">wcscon</span>\n</pre></div>\n</div>\n<p>etc.</p>\n<p>Note that PyWCSTools only includes some functions from wcs.c and wcscon.c at present. For examples of usage,\nlook at the Python code for the astLib.astWCS module. Documentation for the WCSTools routines can be found\nhere: <a class=\"reference external\" href=\"http://tdc-www.harvard.edu/software/wcstools/subroutines/libwcs.wcs.html\">http://tdc-www.harvard.edu/software/wcstools/subroutines/libwcs.wcs.html</a>.</p>\n<p>As of version 0.11.x+, by default the <code class=\"docutils literal notranslate\"><span class=\"pre\">astWCS.WCS</span></code> class is using the <code class=\"docutils literal notranslate\"><span class=\"pre\">astropy.wcs</span></code> module instead of\nPyWCSTools (this allows one to benefit from some features of <code class=\"docutils literal notranslate\"><span class=\"pre\">astropy.wcs</span></code> without having to re-write\ncode based on <code class=\"docutils literal notranslate\"><span class=\"pre\">astWCS.WCS</span></code>). To use PyWCSTools instead, set <code class=\"docutils literal notranslate\"><span class=\"pre\">useAstropyWCS</span> <span class=\"pre\">=</span> <span class=\"pre\">False</span></code> when creating a\n<code class=\"docutils literal notranslate\"><span class=\"pre\">WCS</span></code> object.</p>\n</div>\n<div class=\"section\" id=\"known-issues\">\n<h2>Known issues<a class=\"headerlink\" href=\"#known-issues\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>This may no longer apply, but just in case\u2026</p>\n<p>Recent versions of matplotlib (on which astLib depends) now use locale information. On systems where the\ndecimal point separator is not \u2018.\u2019 (e.g. Germany), the astWCS coordinate conversions routines will give\nstrange results if this is not accounted for. As of version 0.3.0, the astWCS module will detect if this is\nthe case and print a warning message to the console.</p>\n<p>The workaround for this issue is to add the following after importing any python modules that expicitly set\nthe locale (such as matplotlib):</p>\n<div class=\"highlight-default notranslate\"><div class=\"highlight\"><pre><span></span><span class=\"kn\">import</span> <span class=\"nn\">locale</span>\n<span class=\"n\">locale</span><span class=\"o\">.</span><span class=\"n\">setlocale</span><span class=\"p\">(</span><span class=\"n\">locale</span><span class=\"o\">.</span><span class=\"n\">LC_NUMERIC</span><span class=\"p\">,</span> <span class=\"s1\">'C'</span><span class=\"p\">)</span><span class=\"s2\">"</span>\n</pre></div>\n</div>\n<p>Thanks to Markus Demleitner for pointing this out.</p>\n</div>\n<div class=\"section\" id=\"documentation\">\n<h2>Documentation<a class=\"headerlink\" href=\"#documentation\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>Documentation is available on the web at <a class=\"reference external\" href=\"http://astlib.readthedocs.io\">http://astlib.readthedocs.io</a>.</p>\n</div>\n<div class=\"section\" id=\"bugs\">\n<h2>Bugs<a class=\"headerlink\" href=\"#bugs\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>Please email bug reports to <a class=\"reference external\" href=\"mailto:matt.hilton%40mykolab.com\">matt<span>.</span>hilton<span>@</span>mykolab<span>.</span>com</a>, and/or use the <a class=\"reference external\" href=\"https://github.com/mattyowl/astLib/issues\">GitHub issues page</a>.</p>\n<p>Please include details of your operating system, python version, and versions of the python packages\nrequired by astLib that you have installed on your machine. For any WCS-related bugs, it would be helpful\nif you could also include the image header as a text file so that I can reproduce them easily.</p>\n</div>\n</div>\n", 3 "title": "Introduction and Installation", 4 "sourcename": "usage.rst.txt", 5 "current_page_name": "usage", 6 "toc": "<ul>\n<li><a class=\"reference internal\" href=\"#\">Introduction and Installation</a><ul>\n<li><a class=\"reference internal\" href=\"#software-needed\">Software needed</a></li>\n<li><a class=\"reference internal\" href=\"#installation\">Installation</a></li>\n<li><a class=\"reference internal\" href=\"#installation-on-recent-versions-of-macos\">Installation on recent versions of macOS</a></li>\n<li><a class=\"reference internal\" href=\"#usage\">Usage</a></li>\n<li><a class=\"reference internal\" href=\"#known-issues\">Known issues</a></li>\n<li><a class=\"reference internal\" href=\"#documentation\">Documentation</a></li>\n<li><a class=\"reference internal\" href=\"#bugs\">Bugs</a></li>\n</ul>\n</li>\n</ul>\n", 7 "page_source_suffix": ".rst" 8}