Warning, /education/kstars/doc/ekos-align.docbook is written in an unsupported language. File is not indexed.

 <sect1 id="ekos-align">
     <title>Align</title>
     <indexterm>
         <primary>Tools</primary>
         <secondary>Ekos</secondary>
         <tertiary>Align</tertiary>
     </indexterm>
     <sect2 id="ekos-align-introduction">
         <title>Introduction</title>
         <screenshot>
             <screeninfo>
                 Ekos Align Module
             </screeninfo>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="ekos_astrometry.png" format="PNG"/>
                 </imageobject>
                 <textobject>
                     <phrase>Ekos Align Module</phrase>
                 </textobject>
             </mediaobject>
         </screenshot>
         <para>
             The Ekos Alignment Module enables highly accurate GOTOs and can measure and correct polar alignment errors. This is possible thanks to third-party plate-solving technology. The main plate-solving software used is the StellarSolver package, which itself makes use of the offline (and online) astrometry.net, ASTAP and Watney solvers.  Ekos begins by capturing an image of a star field, feeding that image to the chosen solver (e.g. see <ulink url="https://astrometry.net">astrometry.net</ulink>, <ulink url="https://github.com/rlancaste/stellarsolver">StellarSolver</ulink> or <ulink url="https://www.hnsky.org/astap">ASTAP</ulink>), and gets in return the central coordinates (RA, DEC), scale, and orientation of the image. The solver essentially performs pattern recognition against a catalog of millions of stars. Once the coordinates are determined, the true pointing of the telescope is known.
         </para>
         <para>
             Often, there is a discrepancy between where the telescope thinks it is looking at and where it is truly pointing. The magnitude of this discrepancy can range from a few arcminutes to a couple of degrees. Ekos can correct the discrepancy by syncing to the new coordinates, and then slewing the mount to the desired target originally requested.
         </para>
         <para>
             Ekos also provides a Polar Alignment Assistant Tool to correct polar alignment errors. It takes three images, slewing between the images, and calculates the offset between the mount axis and polar axis. It feeds back to the user the altitude and azimuth adjustments needed to align these axes. These images are typically taken near the celestial pole (close to Polaris for Northern Hemisphere) but can work well taken from anywhere, usually starting near the meridian and slewing either East or West.
         </para>
         <para>
             At a minimum, you need a CCD/Webcam and a telescope that supports Slew &amp; Sync commands. Most popular commercial telescope nowadays support such commands.
         </para>
     </sect2>
 
         <sect2 id="ekos-align-typical">
             <title>Typical use</title>
             <para>
                 Using Ekos Alignment Module, aligning your mount using the controller's 1, 2, or 3 star alignment is <emphasis>not</emphasis> strictly necessary, though for some mounts it is recommended to perform a rough 1 or 2 star alignment before using Ekos alignment module. If you are using EQMod, you can start using Ekos alignment module right away. A typical workflow for GOTO alignment involves the following steps:
             </para>
             <orderedlist>
                 <listitem>
                     <para>
                         Start KStars and Ekos and connect to INDI. 
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         Unpark your mount from its home position (usually the NCP for equatorial mounts).
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         Slew to a nearby bright star using the slew telescope command in the SkyMap using the <guilabel>Slew the telescope to the mouse-pointer position</guilabel> command.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         Select <guilabel>Slew to Target</guilabel> in the <guilabel>Solver Action</guilabel> on the Align page.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         After slew is complete, click <guibutton>Capture &amp; Solve</guibutton> on the Align page.
                     </para>
                 </listitem>
             </orderedlist>
             <para>
                 Align will capture an image and try to solve it. If the solver is successful, Ekos will send a sync command to the mount and then slew to the star. The results are displayed in the <guilabel>Solution Results</guilabel> tab along with a bullseye diagram that shows the offset the reported telescope coordinates (&ie; where the telescope <emphasis>thinks</emphasis> it is looking vs. its actual pointing position in the sky as determined by the solver). Align will stop if it is within the desired error tolerance, otherwise it will repeat the Slew/Capture/Solve/Sync process until it is within tolerance.
             </para>
             <para>
                 Each time the solver is executed and returns successful results, Ekos can run on the following actions:
             </para>
             <itemizedlist>
                 <listitem>
                     <para>
                         <guilabel>Sync</guilabel>: Syncs the telescope coordinates to the solution coordinates.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Slew to Target</guilabel>: Syncs the telescope coordinates to the solution coordinates and then slew to the target.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Nothing</guilabel>: Just solve the image and display the solution coordinates.
                     </para>
                 </listitem>
             </itemizedlist>
         </sect2>
     
     <sect2 id="ekos-solver-options">
       <title>Configure StellarSolver Options </title>
         <screenshot>
             <screeninfo>
                 StellarSolver Options
             </screeninfo>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="ekos_stellarsolver_options.png" format="PNG"/>
                 </imageobject>
                 <textobject>
                     <phrase>StellarSolver Options</phrase>
                 </textobject>
             </mediaobject>
         </screenshot>
       <para>
         To use the solvers, you must first configure the StellarSolver options. The above page is displayed when clicking on the <guilabel>Options</guilabel> button on the lower right of the Align page, then selecting the <guilabel>StellarSolver Options</guilabel> tab. Start with the <guilabel>Builtin method for solver</guilabel> <guilabel>Source Extraction method</guilabel> so that each solver uses its preferred star-extraction code. For <guilabel>Solving Method</guilabel> we recommend choosing <guilabel>Internal Solver</guilabel> to use StellarSolver's copy of the Astrometry.net code, or choose <guilabel>Local ASTAP</guilabel> if you prefer that. The online astrometry solver is accurate, but can take a long time to solve because of all the data transfer required. For <guilabel>Options Profile</guilabel>, start with the <guilabel>1-Default</guilabel> profile.
       </para>
       <para>
         There are two other minor options. <guilabel>WCS</guilabel> or  World-Coordinate-System is a system for embedding equatorial coordinate information within the image. When you view a solved image, you can hover it and view the coordinate for each pixel. You can also click anywhere in the image and command to the telescope to slew there. It is highly recommended to keep this option on. <guilabel>Overlay</guilabel> overlays captured images unto the sky map of &kstars;.
         </para>
     </sect2>
     
     <sect2 id="ekos-solver-external">
       <title>Configure StellarSolver External Programs </title>
         <screenshot>
             <screeninfo>
                 StellarSolver External Programs
             </screeninfo>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="ekos_stellarsolver_external.png" format="PNG"/>
                 </imageobject>
                 <textobject>
                     <phrase>StellarSolver External Programs</phrase>
                 </textobject>
             </mediaobject>
         </screenshot>
       <para>
         This is only required if you choose one of the external programs for your <guilabel>Solving Method</guilabel>. If you choose <guilabel>Internal Solver</guilabel>, then it is not necessary.
         </para>
       <para>
         You will need to make sure the paths are correct for the solver you choose. The top menu item <guilabel>select to load one of the default sets</guilabel> usually configures the boxes correctly.
         </para>
     </sect2>
 
     <sect2 id="ekos-solver-scale">
       <title>Configure StellarSolver Scale and Position </title>
         <screenshot>
             <screeninfo>
                 StellarSolver Scale and Position
             </screeninfo>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="ekos_stellarsolver_scale.png" format="PNG"/>
                 </imageobject>
                 <textobject>
                     <phrase>StellarSolver Scale and Position</phrase>
                 </textobject>
             </mediaobject>
         </screenshot>
       <para>
         This page tells Ekos whether you want to constrain your plate-solving search by scale or position.
         </para><para>Scale can be the image width in degrees (<guilabel>dw</guilabel>), the image width in arc-minutes (<guilabel>aw</guilabel>), or the pixel width in arc-seconds (<guilabel>app</guilabel>). All should work, but arc-seconds per pixel is recommended. Typically you want to use this constraint for faster solving, so we recommend you check this box. The system doesn't require that the scale be exactly right--it allows deviations of 10-20%. However, frequently issues related to solving are due to an inaccurate scale being used. Therefore, if you have plate-solving problems, you may want to uncheck <guilabel>Use Scale</guilabel> until those issues are resolved. This will likely result in longer solving times. <guilabel>Auto-update</guilabel> will automatically fill the scale box with the scale found in the most-recent successful solve.
         </para><para>The RA and DEC positions are usually filled in from the position the telescope thinks it is pointing. Naturally, the system doesn't require an exactly correct positional constraint--afterall the purpose of plate-solving is to find that position. The maximum distance in degrees from the specified position to the actual position is given by the <guilabel>Radius</guilabel> field. Plate-solving will fail if the specified position is further away.  Typically you want to enable <guilabel>Use Position</guilabel> for faster solving, so we recommend you check this box. However, frequently issues related to solving are due to using a poor positional estimate (e.g. the telescope is significantly misaligned). Therefore, if you have plate-solving problems, you may want to uncheck <guilabel>Use Position</guilabel> until those issues are resolved. As mentioned, this will result in longer solving times. <guilabel>Auto-update</guilabel> will fill the position box with the position found in the most-recent successful solve. However, a slew will update the position to the position where the telescope thinks it is pointing after the slew.
         </para>
     </sect2>
 
     <sect2 id="ekos-align-profiles">
       <title>Configure StellarSolver Profiles </title>
         <screenshot>
             <screeninfo>
                 StellarSolver Profiles
             </screeninfo>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="ekos_stellarsolver_profiles.png" format="PNG"/>
                 </imageobject>
                 <textobject>
                     <phrase>StellarSolver Profiles</phrase>
                 </textobject>
             </mediaobject>
         </screenshot>
         <para>
           This applies if you are using the (recommended) <guilabel>Internal Solver</guilabel> <guilabel>Solving Method</guilabel>.
       </para><para>
           You can choose an <guilabel>Options Profile</guilabel> on the <guilabel>StellarSolver Options</guilabel> tab. Profiles are simply collections of parameters to configure the performance of the star-extraction and plate-solving system inside of StellarSolver.  The <guilabel>1-Default</guilabel> profile is the recommended one to start with. There are a few other possible profiles such as <guilabel>Large Scale Solving</guilabel>, <guilabel>Small Scale Solving</guilabel>, and <guilabel>Single Thread Solving</guilabel>.
         </para><para>In the <guilabel>Align Options Profile Editor</guilabel> tab you can view and edit profiles. There are many parameters, most of which you need not change to solve issues. There are 3 types of parameters.
          </para>
         <itemizedlist>
          <listitem><para>The top section labelled <guilabel>Sextractor Parameters</guilabel> (with column headings <guilabel>Extraction Parameters</guilabel>, <guilabel>Deblending Params</guilabel>, and <guilabel>Photometry Params</guilabel>) are star extraction parameters--that is those that help find stars in your image.</para></listitem>
          <listitem><para>The second section labelled <guilabel>Star Filtering Parameters</guilabel> filters/reduces the number of stars extracted before sending the list to either the plate-solver (when aligning or polar-aligning), or to autofocus or the internal guider (when just a list of stars is needed).</para></listitem>
          <listitem><para>The third section labelled Astrometry Parameters adjusts the performance of plate solving.</para></listitem>
         </itemizedlist>
         <para>
           All the input fields have tooltips that are displayed if you hover your mouse over the input box.
           </para><para>You can make changes to the values and save the profile if you like, or restore the profile's original values.
           </para>
         <sect3 id="profile-star-extraction">
           <title>Star-Extraction Parameters</title>
           <para>
             The column headings are links to the Sextractor manual which is the main source for these parameters. View those links to find details on all the parameters. We will touch upon some of the parameters you might consider adjusting. However, it's probably best not to get into the weeds of modifying most of these values.
             </para>
         <itemizedlist>
          <listitem><para><guilabel>Thresh Multiple</guilabel> and <guilabel>Thresh Offset</guilabel> relate to how sensitive the system will be to pixel values. The level of the background is multiplied by <guilabel>Thresh Multiple</guilabel> and then <guilabel>Thresh Offset</guilabel> is added to that. If a pixel's value exceeds the result, then it may be used to detect a star. Therefore, lower values (especially for multiple) may cause even dim pixels to be detected as stars. Higher values will reduce the number of stars detected.</para></listitem>
          <listitem><para><guilabel>Min Area</guilabel> is the minimum area for a star detection--area is in square pixels where all pixels have higher-than-threshold pixel values. If you are detecting small noise spikes as stars, you might want to increase this. If you are not detecting desired smaller real stars, perhaps your <guilabel>Min Area</guilabel> is too high.</para></listitem>
          <listitem><para><guilabel>Conv FWHM</guilabel> should be adjusted to roughly the seeing in your area in pixels. The image is smoothed by this amount before star detection is initiated.</para></listitem>
         </itemizedlist>
         </sect3>    
 
         <sect3 id="profile-star-filtering">
         <title>Star-Filtering Parameters</title>
           <para>
             This filtering is done for the sake of speed mostly, as well as for removing clipped stars, or very elliptical objects which might be galaxies. We will touch upon some of the parameters you might consider adjusting. Zero values for these parameters disable the filter. However, once again it's probably best not to get into the weeds of modifying most of these values.
             </para>
              <itemizedlist>
          <listitem><para><guilabel>Initial Keep</guilabel> and <guilabel>Stars Keep #</guilabel> relates to the number of stars returned by the system. The system will initially run its detection algorithm and find some number of possible detections. It will filter that list, keeping only the <guilabel>Initial Keep</guilabel> brightest stars. It will then run the rest of the filtering, including computing the HFR of all those stars and  finally only return a list of <guilabel>Stars Keep #</guilabel> stars. None of the uses (alignment, autofocus, guiding) of StellarSolver require thousands of stars to be able to do their job, and the more stars processed the slower the operation. An initial list of 1000 stars and a few hundred returned stars should be sufficient for most applications.</para></listitem>
          <listitem><para><guilabel>Max Size</guilabel> and <guilabel>Min Size</guilabel> filter stars by their sizes (pixel diameters), and are similar in usage to <guilabel>Min Area</guilabel> above.</para></listitem>
          <listitem><para><guilabel>Max Ellipse</guilabel> specifies how elliptical a star can be before being removed. 2 would mean the larger axis could be twice as large as the smaller axis.</para></listitem>
          <listitem><para><guilabel>Cut Brightest</guilabel> and <guilabel>Cut Dimmest</guilabel> remove the X% brightest or dimmest stars from consideration. <guilabel>Sat Limit</guilabel> removes stars whose pixel values exceed that percentage of the maximum pixel value--to remove saturated stars.</para></listitem>
              </itemizedlist>
         </sect3>
 
         <sect3 id="profile-plate-solving">
           <title>Plate-Solving Parameters</title>
           <para>
             These plate-solving parameters mostly relate to computation resources.
             </para>
              <itemizedlist>
          <listitem><para><guilabel>Search Radius</guilabel> is the distance from the position estimate in degrees that may be searched if <guilabel>Use Position</guilabel> is checked. </para></listitem>
          <listitem><para><guilabel>Maximum Time</guilabel> is the maximum number of seconds that the plate-solving will run before it times out.</para></listitem>
              </itemizedlist>
         </sect3>    
     </sect2>    
     
     <sect2 id="ekos-align-download-index-files">
       <title>Download Index Files</title>
       <para>
         Index files are required if you choose the <guilabel>Internal Solver</guilabel> or <guilabel>Local Astrometry</guilabel> <guilabel>Solving Method</guilabel>.
         </para>
         <para>
             For offline (and remote) solvers, index files are necessary for the solver to work. The complete collection of index files is huge (over 30 GB), but you only need to download what is necessary for your equipment setup. Index files are sorted by the Field-Of-View (FOV) range they cover. There are two methods to fetch the necessary index files: The new download support in Align module, and the old manual way.
         </para>
         <sect3 id="ekos-align-automatic-download">
             <title>Automatic Download</title>
             <screenshot>
                 <screeninfo>
                     Astrometry.net Indexes Download
                 </screeninfo>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="astrometry_indexes_settings.png" format="PNG"/>
                     </imageobject>
                     <textobject>
                         <phrase>Astrometry.net Indexes Download</phrase>
                     </textobject>
                 </mediaobject>
             </screenshot>
             <para>
                 Automatic download is only available for Ekos users on &Linux; &amp; &MacOS;. For &Windows; users, please download ANSVR solver.
             </para>
             <para>
                 To access the download page, click the <guibutton>Options</guibutton> button in the <link linkend="ekos-align">Align module</link> and then select <guilabel>Astrometry Index Files</guilabel> tab. The page displays the current FOV of your current setup and below it a list of available and installed index files. Three icons are used to designate the importance of index files given your current setup as follows:
             </para>
             <itemizedlist>
                 <listitem>
                     <para>
                         <inlinemediaobject><imageobject><imagedata fileref="security-high.png" format="PNG"/></imageobject></inlinemediaobject> <guilabel>Required</guilabel>
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <inlinemediaobject><imageobject><imagedata fileref="security-medium.png" format="PNG"/></imageobject></inlinemediaobject> <guilabel>Recommended</guilabel>
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <inlinemediaobject><imageobject><imagedata fileref="security-low.png" format="PNG"/></imageobject></inlinemediaobject> <guilabel>Optional</guilabel>
                     </para>
                 </listitem>
             </itemizedlist>
             <para>
                 You must download all the required files, and if you have plenty of hard drive space left, you can also download the recommended indexes. If an index file is installed, the checkmark shall be checked, otherwise check it to download the relevant index file. Please only download one file at a time, especially for larger files. You might be prompted to enter the administrator password (default in StellarMate is <userinput>smate</userinput>) to install the files. Once you installed all the required files, you can begin using the offline astrometry.net solver immediately.
             </para>
         </sect3>
         <sect3 id="ekos-align-manual-download">
                 <title>Manual Download</title>
                 <para>
                     You need to <ulink url="http://data.astrometry.net">download</ulink> and install the necessary index files suitable for your telescope+CCD field of view (FOV). You need to install index files covering 100% to 10% of your FOV. For example, if your FOV is 60 arcminutes, you need to install index files covering skymarks from 6 arcminutes (10%) to 60 arcminutes (100%). There are many online tools to calculate FOVs, such as <ulink url="http://starizona.com/acb/ccd/calc_pixel.aspx">Starizona Field of View Calculator</ulink>.
                 </para>
                 <table frame="all">
                     <title>Index Files</title>
                     <tgroup cols='3' align='left' colsep='1' rowsep='1'>
                         <thead>
                             <row>
                                 <entry>Index Filename</entry>
                                 <entry>FOV (arcminutes)</entry>
                                 <entry>Debian Package</entry>
                             </row>
                         </thead>
                         <tbody>
                             <row>
                                 <entry>index-4219.fits</entry>
                                 <entry>1400 - 2000</entry>
                                 <entry morerows="11" valign="middle"><ulink url="http://data.astrometry.net/debian/astrometry-data-4208-4219_0.45_all.deb">astrometry-data-4208-4219</ulink></entry>
                             </row>
                             <row>
                                 <entry>index-4218.fits</entry>
                                 <entry>1000 - 1400</entry>
                             </row>
                             <row>
                                 <entry>index-4217.fits</entry>
                                 <entry>680 - 1000</entry>
                             </row>
                             <row>
                                 <entry>index-4216.fits</entry>
                                 <entry>480 - 680</entry>
                             </row>
                             <row>
                                 <entry>index-4215.fits</entry>
                                 <entry>340 - 480</entry>
                             </row>
                             <row>
                                 <entry>index-4214.fits</entry>
                                 <entry>240 - 340</entry>
                             </row>
                             <row>
                                 <entry>index-4213.fits</entry>
                                 <entry>170 - 240</entry>
                             </row>
                             <row>
                                 <entry>index-4212.fits</entry>
                                 <entry>120 - 170</entry>
                             </row>
                             <row>
                                 <entry>index-4211.fits</entry>
                                 <entry>85 - 120</entry>
                             </row>
                             <row>
                                 <entry>index-4210.fits</entry>
                                 <entry>60 - 85</entry>
                             </row>
                             <row>
                                 <entry>index-4209.fits</entry>
                                 <entry>42 - 60</entry>
                             </row>
                             <row>
                                 <entry>index-4208.fits</entry>
                                 <entry>30 - 42</entry>
                             </row>
                             <row>
                                 <entry>index-4207-*.fits</entry>
                                 <entry>22 - 30</entry>
                                 <entry><ulink url="http://data.astrometry.net/debian/astrometry-data-4207_0.45_all.deb">astrometry-data-4207</ulink></entry>
                             </row>
                             <row>
                                 <entry>index-4206-*.fits</entry>
                                 <entry>16 - 22</entry>
                                 <entry><ulink url="http://data.astrometry.net/debian/astrometry-data-4206_0.45_all.deb">astrometry-data-4206</ulink></entry>
                             </row>
                             <row>
                                 <entry>index-4205-*.fits</entry>
                                 <entry>11 - 16</entry>
                                 <entry><ulink url="http://data.astrometry.net/debian/astrometry-data-4205_0.45_all.deb">astrometry-data-4205</ulink></entry>
                             </row>
                             <row>
                                 <entry>index-4204-*.fits</entry>
                                 <entry>8 - 11</entry>
                                 <entry><ulink url="http://data.astrometry.net/debian/astrometry-data-4204_0.45_all.deb">astrometry-data-4204</ulink></entry>
                             </row>
                             <row>
                                 <entry>index-4203-*.fits</entry>
                                 <entry>5.6 - 8.0</entry>
                                 <entry><ulink url="http://data.astrometry.net/debian/astrometry-data-4203_0.45_all.deb">astrometry-data-4203</ulink></entry>
                             </row>
                             <row>
                                 <entry>index-4202-*.fits</entry>
                                 <entry>4.0 - 5.6</entry>
                                 <entry><ulink url="http://data.astrometry.net/debian/astrometry-data-4202_0.45_all.deb">astrometry-data-4202</ulink></entry>
                             </row>
                             <row>
                                 <entry>index-4201-*.fits</entry>
                                 <entry>2.8 - 4.0</entry>
                                 <entry><ulink url="http://data.astrometry.net/debian/astrometry-data-4201-1_0.45_all.deb">astrometry-data-4201-1</ulink> <ulink url="http://data.astrometry.net/debian/astrometry-data-4201-2_0.45_all.deb">astrometry-data-4201-2</ulink> <ulink url="http://data.astrometry.net/debian/astrometry-data-4201-3_0.45_all.deb">astrometry-data-4201-3</ulink> <ulink url="http://data.astrometry.net/debian/astrometry-data-4201-4_0.45_all.deb">astrometry-data-4201-4</ulink></entry>
                             </row>
                             <row>
                                 <entry>index-4200-*.fits</entry>
                                 <entry>2.0 - 2.8</entry>
                                 <entry><ulink url="http://data.astrometry.net/debian/astrometry-data-4200-1_0.45_all.deb">astrometry-data-4200-1</ulink> <ulink url="http://data.astrometry.net/debian/astrometry-data-4200-2_0.45_all.deb">astrometry-data-4200-2</ulink> <ulink url="http://data.astrometry.net/debian/astrometry-data-4200-3_0.45_all.deb">astrometry-data-4200-3</ulink> <ulink url="http://data.astrometry.net/debian/astrometry-data-4200-4_0.45_all.deb">astrometry-data-4200-4</ulink></entry>
                             </row>
                         </tbody>
                     </tgroup>
                 </table>
                 <para>
                     The Debian packages are suitable for any Debian-based distribution (Ubuntu, Mint, &etc;). If you downloaded the Debian Packages above for your FOV range, you can install them from your favorite package manager, or via the following command:
                 </para>
                 <para>
                     <command>sudo dpkg -i astrometry-data-*.deb</command>
                 </para>
                 <para>
                     On the other hand, if you downloaded the FITS index files directly, copy them to <filename role="directory">/usr/share/astrometry</filename> directory.
                 </para>
                 <note>
                     <para>
                         It is recommended to use a download manager as such <ulink url="https://addons.mozilla.org/en-US/firefox/addon/downthemall/">DownThemAll!</ulink> for &firefox; to download the Debian packages as browsers' built-in download manager may have problems with download large packages.
                     </para>
                 </note>
             </sect3>
         </sect2>
 
     <sect2 id="ekos-align-get-astrometry">
         <title>Optionally get astrometry.net</title>
 
         <para>
           This is only required if you choose the <guilabel>Local Astrometry</guilabel> option for <guilabel>Source Extraction Method</guilabel> which is no longer recommended.
           </para>
         <note>
             <para>
                 Astrometry.net is already shipped with StellarMate so there is no need to install it. Index files from 16 arcminutes and above (4206 to 4019) are included with StellarMate. For any additional index files, you need to install them as necessary. To use Astrometry in StellarMate from a remote Ekos on &Linux;/&Windows;/&MacOS;, make sure to select <guimenuitem>Remote</guimenuitem> option in Ekos Alignment Module. Furthermore, make sure that the <guimenuitem>Astrometry</guimenuitem> driver is selected in your equipment profile.
             </para>
         </note>
         <screenshot>
             <screeninfo>
                 Ekos Remote Astrometry
             </screeninfo>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="ekos_remote_astrometry.png" format="PNG"/>
                 </imageobject>
                 <textobject>
                     <phrase>Ekos Remote Astrometry</phrase>
                 </textobject>
             </mediaobject>
         </screenshot>
         <variablelist>
             <varlistentry>
                 <term>&Windows;</term>
                 <listitem>
                     <para>
                         To use astrometry.net under &Windows;, you need to download and install the <ulink url="https://adgsoftware.com/ansvr/">ANSVR Local Astrometry.net solver</ulink>. The ANSVR mimics the astrometry.net online server on your local computer; thus the internet not required for any astrometry queries.
                     </para>
                     <para>
                         After installing the ANSVR server and downloading the appropriate index files for your setup, make sure ANSVR server is up and running and then go to Ekos Alignment options where you can simply change the <guilabel>API URL</guilabel> to use the ANSVR server as illustrated below:
                     </para>
                     <screenshot>
                         <screeninfo>
                             ANSVR Parameters
                         </screeninfo>
                         <mediaobject>
                             <imageobject>
                                 <imagedata fileref="astrometry_windows_ansvr.png" format="PNG"/>
                             </imageobject>
                             <textobject>
                                 <phrase>ANSVR Parameters</phrase>
                             </textobject>
                         </mediaobject>
                     </screenshot>
                     <para>
                         In Ekos Align module, you must set the solver type to <guimenuitem>Online</guimenuitem> so that it uses the local ANSVR server for all astrometry queries. Then you can use the align module as you would normally do.
                     </para>
                     <para>
                         Remember as indicated above that StellarMate <emphasis>already</emphasis> includes astrometry.net. Therefore, if you would like to use StellarMate remotely to solve your images, simply change solver type to <guimenuitem>Remote</guimenuitem> and ensure that your equipment profile includes <emphasis role="bold">Astrometry</emphasis> driver which can be selected under the <guilabel>Auxiliary</guilabel> dropdown. This is applicable to all operating systems and not just &Windows;.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>&MacOS;</term>
                 <listitem>
                     <para>
                         Astrometry.net is already included with &kstars; for &MacOS;, so no need to install it.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>&Linux;</term>
                 <listitem>
                     <para>
                         Astrometry.net is already included with &kstars; bleeding version. But if astrometry is not installed, then you can install it by running the following command under &ubuntu;:
                     </para>
                     <para>
                         <command>sudo apt-get install astrometry.net</command>
                     </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </sect2>
     
         <sect2 id="ekos-align-how-to-use">
             <title>How to Use?</title>
             <para>
                 Ekos Align Module offers multiple functions to aid you in achieving accurate GOTOs. For some mounts it is useful to start your session with your mount in home position with the telescope tube looking directly at the celestial pole. For users in Northern Hemisphere, point the telescope as close as possible to Polaris. It is not necessary to perform 2 or 3 star alignments, but it can be useful for some mount types. Make sure your camera is focused.
             </para>
             <para>
               At the top left of the Align page you can find two solver commands, and two actions to take given the solver solution.
             </para>
             <itemizedlist>
                 <listitem>
                     <para>
                         <guilabel>Capture &amp; Solve</guilabel>: Capture an image and determine exactly where in the sky the telescope is pointing. The astrometry results include the equatorial coordinates (RA &amp; DEC) of the center of the captured image and the pixel scale and field rotation. Depending on the Solver Action settings, the results can be used to Sync the mount or Sync and then Slew to the target location. For example, suppose you slewed the mount to Vega then used <emphasis>Capture &amp; Solve</emphasis>. If the actual telescope location is different from Vega, it will be first synced to the solved coordinate and then Ekos shall command the mount to slew to Vega. After slew is complete, the Alignment module will repeat Capture &amp; Solve process again until the error between reported and actual position falls below the accuracy thresholds (30 arcseconds by default).
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Load &amp; Slew</guilabel>: Load a FITS or JPEG file, solve it, and then slew to it.
                     </para>
                 </listitem>
             </itemizedlist>
             <warning>
                 <para>
                     <emphasis role="bold">Never</emphasis> solve an image at or near the celestial pole (unless Ekos Polar Alignment Assistant Tool is used). Slew at least 20 degrees away from the celestial pole before solving the first image. Solving very close to the poles will make your mount pointing worse, so avoid it.
                 </para>
             </warning>
         </sect2>
         
         <sect2 id="ekos-align-alignment-settings">
             <title>Alignment Settings</title>
             <para>
                 Before you begin the alignment process, select the desired optical train. You can explore astrometry.net options that are passed to the astrometry.net solver each time an image is captured:
             </para>
             <itemizedlist>
                 <listitem>
                     <para>
                         <guilabel>Accuracy</guilabel>: Acceptable difference between the desired target position and the solved coordinates from the captured image. If the difference exceeds this many arc-seconds, then the system will continue to capture, solve and slew until the solved position is close enough to the target position.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Train</guilabel>: Select the Optical Train which will be used to capture the image to be aligned. It is also used to compute the image scale.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Exposure</guilabel>: Exposure duration in seconds.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Bin</guilabel>: The binning of the image before solving.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Gain/ISO</guilabel>: The camera gain or ISO.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Filter/Use Current</guilabel>: The filter to use when capturing the image. <guilabel>Use Current</guilabel> uses whatever filter is currently active.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
                         <guilabel>Dark</guilabel>: Whether to use the dark-image subtraction scheme before analyzing the captured image.
                     </para>
                 </listitem>
             </itemizedlist>
         </sect2>
 
         <sect2 id="ekos-align-polaralignment">
             <title>Polar Alignment</title>
                 <para>
                     When setting up a German Equatorial Mount (GEM) for imaging, a critical aspect of capturing long-exposure images is to ensure proper polar alignment. A GEM mount has two axis: Right Ascension (RA) axis and Declination (DE) axis. Ideally, the RA axis should be aligned with the celestial sphere polar axis. A mount's job is to track the star's motion around the sky, from the moment they rise at the eastern horizon, all the way up across the median, and westward until they set.
                 </para>
 
                 <mediaobject>
                     <videoobject>
                         <videodata contentdepth="595" contentwidth="800" fileref="https://www.stellarmate.com/images/videos/polar_align.webm"/>
                     </videoobject>
                     <caption>
                         <para>
                             <phrase>Polar Alignment Assistant</phrase>
                         </para>
                     </caption>
                 </mediaobject>
 
                 <para>
                     In long exposure imaging, a camera is attached to the telescope where the image sensor captures incoming photons from a particular area in the sky. The incident photons have to strike the same photo-site over and over again if we are to gather a clear and crisp image. Of course, actual photons do not behave in this way: optics, atmosphere, seeing quality all scatter and refract photons in one way or another. Furthermore, photons do not arrive uniformly but follow a Poisson distribution. For point-like sources like stars, a point spread function describes how photons are spatially distributed across the pixels. Nevertheless, the <emphasis>overall</emphasis> idea we want to keep the source photons hitting the same pixels. Otherwise, we might end up with an image plagued with various trail artifacts.
                 </para>
                 <screenshot>
                     <screeninfo>
                         Polar Alignment
                     </screeninfo>
                     <mediaobject>
                         <imageobject>
                             <imagedata fileref="alignment_polaris.png" format="PNG"/>
                         </imageobject>
                         <textobject>
                             <phrase>Polar Alignment</phrase>
                         </textobject>
                     </mediaobject>
                 </screenshot>
                 <para>
                     Since mounts are not perfect, they cannot perfectly keep track of object as it transits across the sky. This can stem from many factors, one of which is the misalignment of the mount's Right Ascension axis with respect to the celestial pole axis. Polar alignment removes one of the biggest sources of tracking errors in the mount, but other sources of error still play a factor. If properly aligned, some mounts can track an object for a few minutes with the only deviation of 1-2 arcsec RMS.
                 </para>
                 <para>
                     However, unless you have a top of the line mount, then you'd probably want to use an autoguider to keep the same star locked in the same position over time. Despite all of this, if the axis of the mount is not properly aligned with the celestial pole, then even a mechanically-perfect mount would lose tracking with time. Tracking errors are proportional to the magnitude of the misalignment. It is therefore very important for long exposure imaging to get the mount polar aligned to reduce any residual errors as it spans across the sky.
                 </para>
                 <para>
                     Before starting the process, point the mount as close as possible to the celestial pole with the counterweights down. If you are living in the Northern Hemisphere, point it as close as possible to Polaris. If Polaris is not visible (&eg; blocked by trees or  buildings) you may point elsewhere, preferably near the Meridian. Make sure there is at least 30-60 degrees of sky viewable in an arc East or West of the Meridian from the position you choose. Select the direction of free sky, the number of degrees for each of two slews, the mount slew speed, and whether the mount will be slewing automatically (recommended) or manually.
                 </para>
                 <para>
                     The tool works by capturing and solving three images. After capturing each, the mount rotates by the fixed amount you entered and another image is captured and solved. If you choose manual, you will need to slew the mount by roughly the angle chosen.
                 </para>
                 <screenshot>
                     <screeninfo>
                         Polar Alignment Assistant
                     </screeninfo>
                     <mediaobject>
                         <imageobject>
                             <imagedata fileref="polar_assistant_main2.png" format="PNG"/>
                         </imageobject>
                         <textobject>
                             <phrase>Polar Alignment Assistant</phrase>
                         </textobject>
                     </mediaobject>
                 </screenshot>
 
             <sect3 id="ekos-align-platesolvecorrection">
                 <title>Plate Solve Correction Scheme</title>
                 
                 <para>
                   The images below show the workflow when the <emphasis>Plate Solve</emphasis> correction technique is used. The image below shows a display after the 3 measurement images are captured and solved. It shows an error of almost 18' in altitude and that the mount's axis needs to be moved up. Similarly it shows an azimuth error of almost 15' and that the axis needs to be moved to the right (as viewed from behind the telescope). 
                 </para>
                 <screenshot>
                     <screeninfo>
                         Polar Alignment Assistant
                     </screeninfo>
                     <mediaobject>
                         <imageobject>
                             <imagedata fileref="polar_assistant_ps1.png" format="PNG"/>
                         </imageobject>
                         <textobject>
                             <phrase>Polar Alignment Assistant, Plate Solve Workflow 1</phrase>
                         </textobject>
                     </mediaobject>
                 </screenshot>
                 <para>
                   If your error is low enough (&eg; less than an arc-minute) then you don't need to make any adjustments. Simply press stop and you're done.
                 </para>
                 <para>
                   If you will be making corrections to your mount's axis, you should select the adjustment approach (we're using Plate Solve in this example), and how often the system should recapture images to re-measure the polar alignment error. The refresh interval should be frequent, but it doesn't make sense to make it faster that your CPU can capture and plate-solve the images. We're using 2s in this example. Then press the <guibutton>Refresh</guibutton> button to begin the correction process.
                 </para>
                 <para>
                   The system will capture images, and re-estimate the polar alignment error after each image. You can try to reduce the error by adjusting the Altitude and Azimuth correction knobs on your mount. The image below shows the screen after the altitude error has been almost zeroed. See the difference between the  <emphasis>Measured Error</emphasis> row, which shows the originally measured error after the original 3 captures, and the  <emphasis>Updated Error</emphasis> row which shows the current error estimate.
                 </para>
                 <screenshot>
                     <screeninfo>
                         Polar Alignment Assistant
                     </screeninfo>
                     <mediaobject>
                         <imageobject>
                             <imagedata fileref="polar_assistant_ps2.png" format="PNG"/>
                         </imageobject>
                         <textobject>
                             <phrase>Polar Alignment Assistant, Plate Solve Workflow 2</phrase>
                         </textobject>
                     </mediaobject>
                 </screenshot>
                 <para>
                   Below the user has also adjust Azimuth to reduce the error further. Now the error is very low and the process is done. The user should press the stop button.
                 </para>
                 <screenshot>
                     <screeninfo>
                         Polar Alignment Assistant
                     </screeninfo>
                     <mediaobject>
                         <imageobject>
                             <imagedata fileref="polar_assistant_ps3.png" format="PNG"/>
                         </imageobject>
                         <textobject>
                             <phrase>Polar Alignment Assistant, Plate Solve Workflow 3</phrase>
                         </textobject>
                     </mediaobject>
                 </screenshot>
                 </sect3>
                 <sect3 id="ekos-align-move-star-correction">
                 <title>Move Star Correction Scheme</title>
 
                 <para>
                   We also have an alternative schemes for correcting polar alignment. Two variations are <emphasis>Move Star &amp; Calc Error</emphasis> and <emphasis>Move Star</emphasis>. When you select this scheme, the system place a yellow/green/violet triangle on the screen. The triangle can be moved by clicking near a star, and the yellow/violet corner is moved to that star. In this scheme the user corrects polar alignment by first adjusting the mount's azimuth knob so that the selected star moves along the yellow side of the triangle. Once the star is near the next vertex, the azimuth knob should be adjusted so that the star moves along the green side of the triangle. Once the star is moved to the green/violet vertex, the mount is polar aligned, and the user can click <emphasis>stop</emphasis>.
                 </para>
                   <para>
                     The difference between <emphasis>Move Star &amp; Calc Error</emphasis> and  <emphasis>Move Star</emphasis> is that in the former, the system attempts to track the star the user has selected, and places a circle around that star. In that scheme it also attempts to update the <emphasis>Updated Err</emphasis> row. If the star tracking isn't reliable, simply ignore it or use the <emphasis> Move Star </emphasis>scheme and move the star by-eye until it's close to the final target. An example of using this technique is shown in this video: 
                     <ulink url="https://www.youtube.com/watch?v=iOp7hrxw0oU">https://www.youtube.com/watch?v=iOp7hrxw0oU</ulink>
                 </para>
             </sect3>
         </sect2>
 </sect1>