1With this document, we try to collect all the useful code snipplets to help you
2using `Astrometry.net <http://astrometry.net/>`_, which will now be referred to
3by *AN*. While there is already some limited documentation around for quite
4specific aspects of all the components used, an overview helping a beginner to
5solve astronomical images was missing---until now.
6
7.. contents::
8
9***********************************************
10Building Your Local Astrometry.net Installation
11***********************************************
12
13There are several ways to use the *AN* functionality:
14
15#. Build your own local installation;
16#. use one of the projects using it, eg.
17
18	- The Flickr Astro group, where all uploaded images are automatically
19	  fetched and fed through the solver;
20	- `AstroTortilla <http://sourceforge.net/projects/astrotortilla/>`_, which
21	  uses *AN* internally;
22
23#. or finally, you can use *AN*'s web service to process your images.
24
25This section will describe how to prepare a local installation by getting and
26building the source code. You'll need additional *index* files to actually
27solve images, but that will be described later. (They can be downloaded or
28prepared locally.)
29
30Getting the Source Code
31=======================
32The following examples always work on the *complete* SVN repository, though you
33only need the ``./src/astrometry/`` subdirectory. Thus, you'd always add that to
34save quite some bandwidth.
35
36Downloading Release Tarballs or Daily Snapshots
37-----------------------------------------------
38
39For details, please refer to the `AN Usage page
40<http://astrometry.net/use.html>`_.  Snapshots as well as release tarballs can
41be found at `http://astrometry.net/downloads/
42<http://astrometry.net/downloads/>`_.  Please look at the file names carefully:
43Some contain version numbers, some SVN revision numbers. As usual, newer is
44better. Your choice!
45
46As the project currently (20140623) switches over to GitHub, you'll find
47all upcoming releases there, too, listed at
48`https://github.com/dstndstn/astrometry.net/releases <https://github.com/dstndstn/astrometry.net/releases>`_.
49
50Current Sources
51---------------
52
53The current source tree is managed in GIT on GitHub. Anonymous users will clone
54from there::
55
56	git clone https://github.com/dstndstn/astrometry.net.git
57
58while authenticated users (you need your SSH keys in place!) can clone with::
59
60	git clone git@github.com:dstndstn/astrometry.net.git
61
62Historic SVN Tree
63-----------------
64
65With SVN
66^^^^^^^^
67You can anonymously download the *AN* sources like this::
68
69	svn co http://astrometry.net/svn/trunk astrometry
70
71If you have an account (with a few useful patches posted to the mailing
72list, you'll usually get one if you ask for it), you can of course fetch
73as an authenticated user and will be able to commit your changes::
74
75	svn co svn+ssh://<username>@astrometry.net/svn/trunk astrometry
76
77With GIT-SVN
78^^^^^^^^^^^^
79Anonymously, this is done by::
80
81	git svn clone http://astrometry.net/svn/trunk astrometry
82
83As an authenticated user, you'd use::
84
85	git svn clone svn+ssh://<username>@astrometry.net/svn/trunk astrometry
86
87Both variants will place a GIT-SVN converted copy of the whole repository into
88the local ``./astrometry/`` directory, which you can update with ``git svn
89rebase``.
90
91With commit rights (using authenticated access), you can also easily commit
92to SVN: Just commit them locally (ie. using ``git update-index``, ``git
93add``, ``git rm`` etc., finally followed by ``git commit`` to commit your
94changes) and then push them into the upstream SVN repository using ``git svn
95dcommit``.
96
97
98********************
99Using Astrometry.net
100********************
101
102With or without a local *AN* installation, you can use it to solve your
103astronomical images. It will accept `FITS <http://fits.gsfc.nasa.gov/>`_
104files as well as other commonly used digital image formats. You can even feed
105it with preprocessed (X,\ Y) coordinates you got other astronomical software
106stacks, like `SExtractor <http://sextractor.sourceforge.net/>`_.
107
108Astrometry.net Flickr Group
109===========================
110
111We've a bot installed watching the `Astrometry Flickr Group
112<https://www.flickr.com/groups/astrometry>`_. Every image uploaded to this group
113will be solved automatically. Some comments will be added describing the image's location,
114rotation, and important objects found.
115
116Astrometry.net Web Service
117==========================
118
119You can upload your images to the `Nova Web Service
120<http://nova.astrometry.net/upload>`_ found at
121``http://nova.astrometry.net/upload``. Keep in mind that this is a public web
122service; others may see your captures. We're doing lots of work there, the
123service may be unstable from time to time. For every image, you'll find a page
124linking to all important files with the WCS solution etc.
125
126Local *AN* Installation
127=======================
128
129Other Projects Using Astrometry.net
130===================================
131
132AstroTortilla
133-------------
134
135AstroTortilla (`SourceForge project page
136<http://sourceforge.net/projects/astrotortilla/>`_, `home page
137<http://sourceforge.net/p/astrotortilla/home/Home/>`_) is Windows software
138shipping a `Cygwin <https://www.cygwin.com/>`_ build of *AN*, which it uses
139internally.
140