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

0001 <?xml version="1.0" encoding="UTF-8"?>
0002 <sect1 id="ekos-focus">
0003   <title>Focus</title>
0004 
0005   <indexterm>
0006     <primary>Tools</primary>
0007 
0008     <secondary>Ekos</secondary>
0009 
0010     <tertiary>Focus</tertiary>
0011   </indexterm>
0012 
0013   <sect2 id="focus-theory">
0014     <title>Theory Of Operation</title>
0015 
0016     <screenshot>
0017       <screeninfo> Ekos Focus </screeninfo>
0018 
0019       <mediaobject>
0020         <imageobject>
0021           <imagedata fileref="ekos_focus.png" format="PNG" width="75%"/>
0022         </imageobject>
0023 
0024         <textobject>
0025           <phrase>Ekos Focus</phrase>
0026         </textobject>
0027       </mediaobject>
0028     </screenshot>
0029 
0030     <para> In order to focus an image, Ekos needs to establish a numerical
0031     method for gauging how <emphasis>good</emphasis> your focus is. It's easy
0032     when you look at an image and can see it as
0033     <emphasis>unfocused</emphasis>, as the human eye is very good at detecting
0034     that, but <emphasis>how</emphasis> can Ekos possibly know that? </para>
0035 
0036     <para> The most tried and tested method is Half-Flux-Radius (HFR), which is a
0037     measure of the width in pixels counting from the center of the star until
0038     the accumulated intensity is half of the total flux of the star. As you move
0039     closer to the point of optimum focus, so the HFR gets smaller, reaching a
0040     minimum at the point of focus before increasing as you start to move away
0041     from focus. HFR has been used on lots of different types of equipment and has
0042     proved to be stable in a wide range of circumstances. </para>
0043 
0044     <para> In addition to HFR, Ekos supports other focus measures, including
0045     an adjusted HFR measure, FWHM, Number of Stars and Fourier Power. It is
0046     recommended to start with HFR and when the user has become proficient in
0047     focusing their equipment, to try the other measures. </para>
0048 
0049     <para> After Ekos processes an image, it selects either a single star and
0050     starts measuring its HFR, or it selects a set of stars matching the
0051     criteria that have been set and calculates an average HFR. It can
0052     automatically select stars, or you can select a single star manually. It
0053     is recommended to allow Ekos to select a set of stars. </para>
0054 
0055     <para> Ekos supports 4 different focus algorithms: Linear 1 Pass, Linear,
0056     Iterative, Polynomial. Linear 1 Pass is the recommended algorithm. </para>
0057 
0058     <itemizedlist>
0059       <listitem>
0060         <para> <emphasis role="bold">Linear 1 Pass</emphasis>: In the Linear 1
0061         Pass algorithm, Ekos establishes a V-Curve and fits a curve to the data
0062         to find the focus solution. It then moves to the calculated minimum.
0063         Key features include: </para>
0064 
0065         <itemizedlist>
0066           <listitem>
0067             <para> The algorithm compensates for focuser backlash. </para>
0068           </listitem>
0069 
0070           <listitem>
0071             <para> The algorithm is fast, taking 1 pass to identify optimum
0072             focus. </para>
0073           </listitem>
0074 
0075           <listitem>
0076             <para> The algorithm uses more sophisticated curve fitting to
0077             pinpoint the optimum focus position. </para>
0078           </listitem>
0079 
0080           <listitem>
0081             <para> The algorithm is highly configurable with user control over
0082             many parameters like step size, number of steps and how to deal with
0083             outliers in the datapoints. </para>
0084           </listitem>
0085         </itemizedlist>
0086       <para> Providing the focuser behaves in a repeatable way, i.e. when commanded
0087       to go to position X, it always goes to the same position, then this algorithm
0088       will be the best to use.</para>
0089       </listitem>
0090 
0091       <listitem>
0092         <para> <emphasis role="bold">Linear</emphasis>: In the Linear
0093         algorithm, Ekos steps outward from its starting point then moves
0094         inward taking regular datapoints through the point of optimum focus
0095         and then further inward, to draw a V-Curve. It then fits a quadratic
0096         curve to the datapoints and calculates the point of optimum focus. It
0097         then moves out again past the point of optimum focus, halves the
0098         stepsize and moves in again for a second pass. It looks to follow the
0099         curve from the first pass and find the minimum HFR. Due to randomness
0100         in the HFR measurements it uses the % tolerance to help decide when it
0101         has found a solution. Key features include: </para>
0102 
0103         <itemizedlist>
0104           <listitem>
0105             <para> The algorithm compensates for focuser backlash. </para>
0106           </listitem>
0107 
0108           <listitem>
0109             <para> The algorithm is slow, taking 2 passes to identify optimum
0110             focus. </para>
0111           </listitem>
0112 
0113           <listitem>
0114             <para> The algorithm uses curve fitting to pinpoint the optimum
0115             focus position in pass 1, but then uses % Tolerance to try to stop
0116             as close as possible to this HFR on pass 2. </para>
0117           </listitem>
0118 
0119           <listitem>
0120             <para> The algorithm is highly configurable with user control over
0121             many parameters like step size and number of steps. </para>
0122           </listitem>
0123         </itemizedlist>
0124         <para> If the focuser behaves in an inconsistent way, i.e. when commanded
0125         to go to position X, there is variability in the position it goes to, then
0126         this algorithm will be the best to use as it has some built in tolerance
0127         for this variability.</para>
0128       </listitem>
0129 
0130       <listitem>
0131         <para> <emphasis role="bold">Iterative</emphasis>: In the Iterative
0132         algorithm, Ekos operates iteratively by moving in discrete steps,
0133         decided initially by the user-configurable step size and later by the
0134         slope of the V-Curve, to get closer to the optimal focus position
0135         where it then changes gears and performs smaller, finer moves to reach
0136         the optimal focus. The focus process stops when the measured HFR is
0137         within the configurable tolerance of the minimum recorded HFR in the
0138         process. In other words, whenever the process starts searching for a
0139         solution within a narrowly limited range, it checks if the current HFR
0140         is within % difference compared to the minimum HFR recorded, and if
0141         this condition is met then the Autofocus process is considered
0142         successful. The default value is set to 1% and is sufficient for most
0143         situations. The Step options specify the number of initial ticks the
0144         focuser has to move. If the image is severely out of focus, we set the
0145         step size high (i.e. greater than 250). On the other hand, if the
0146         focus is close to optimal focus, we set the step size to a more
0147         reasonable range (less than 50). It takes trial and error to find the
0148         best starting tick, but Ekos only uses that for the first focus
0149         motion, as all subsequent motions depend on the V-Curve slope
0150         calculations. Key features include:</para>
0151 
0152         <itemizedlist>
0153           <listitem>
0154             <para> The algorithm relies on the focuser having well controlled
0155             backlash. </para>
0156           </listitem>
0157 
0158           <listitem>
0159             <para> The algorithm can be fast using a minimum number of steps.
0160             </para>
0161           </listitem>
0162 
0163           <listitem>
0164             <para> The algorithm works on a "good enough" paradigm whereby it
0165             stops when the HFR is within % Tolerance of the perceived minimum.
0166             </para>
0167           </listitem>
0168         </itemizedlist>
0169       </listitem>
0170 
0171       <listitem>
0172         <para> <emphasis role="bold">Polynomial</emphasis>: In the Polynomial
0173         algorithm, the process starts off in Iterative mode, but once we cross
0174         to the other side of the V-Curve (once HFR values start increasing
0175         again after decreasing for a while), then Ekos performs quadratic
0176         curve fitting to find a solution that predicts the minimum possible
0177         HFR position. Key features include:</para>
0178 
0179         <itemizedlist>
0180           <listitem>
0181             <para> The algorithm relies on the focuser having well controlled
0182             backlash. </para>
0183           </listitem>
0184 
0185           <listitem>
0186             <para> The algorithm can be fast using a minimum number of steps.
0187             </para>
0188           </listitem>
0189 
0190           <listitem>
0191             <para> The algorithm uses curve fitting to pinpoint the optimum
0192             focus position. </para>
0193           </listitem>
0194         </itemizedlist>
0195       </listitem>
0196     </itemizedlist>
0197   </sect2>
0198 
0199   <sect2 id="optical-train-group">
0200     <title>Optical Train Group</title>
0201 
0202     <screenshot>
0203       <screeninfo> Optical Train </screeninfo>
0204 
0205       <mediaobject>
0206         <imageobject>
0207           <imagedata fileref="optical_train_group.png" format="PNG"
0208                      width="50%"/>
0209         </imageobject>
0210 
0211         <textobject>
0212           <phrase>Optical Train Settings</phrase>
0213         </textobject>
0214       </mediaobject>
0215     </screenshot>
0216 
0217     <para> The Optical Train group displays the currently selected Optical
0218     Train. By default this will be the primary imaging train, but other trains
0219     can be selected. The group consists of:</para>
0220 
0221     <itemizedlist>
0222       <listitem>
0223         <para> <guibutton>Train</guibutton>: The Optical Train currently in
0224         use by the Focus tab. Hover the mouse over this field for a more
0225         detailed description of the selected train.</para>
0226       </listitem>
0227 
0228       <listitem>
0229         <para> <guibutton>Edit Button</guibutton>: Brings up the Optical Train
0230         dialog to view and potentially change the optical trains.</para>
0231       </listitem>
0232     </itemizedlist>
0233 
0234     <para> Focus parameters are saved per Optical Train automatically.</para>
0235   </sect2>
0236 
0237   <sect2 id="focus-focuser-group">
0238     <title>Focuser Group</title>
0239 
0240     <screenshot>
0241       <screeninfo> Focuser Settings </screeninfo>
0242 
0243       <mediaobject>
0244         <imageobject>
0245           <imagedata fileref="focuser_group.png" format="PNG" width="50%"/>
0246         </imageobject>
0247 
0248         <textobject>
0249           <phrase>Focuser Settings</phrase>
0250         </textobject>
0251       </mediaobject>
0252     </screenshot>
0253 
0254     <para> All INDI-compatible focusers are supported. It is recommended to
0255     use <emphasis role="bold">absolute</emphasis> focusers for the best
0256     results since their absolute position is known on power up. In INDI, the
0257     focuser <emphasis>zero</emphasis> position is when the drawtube is
0258     <emphasis role="bold">fully retracted</emphasis>. When focusing
0259     <emphasis>outwards</emphasis>, the focuser position increases, while it
0260     decreases when focusing <emphasis>inwards</emphasis>. The following
0261     focuser types are supported: </para>
0262 
0263     <itemizedlist>
0264       <listitem>
0265         <para> <emphasis role="bold">Absolute</emphasis>: Absolute Position
0266         Focusers such as RoboFocus, MoonLite, ASI ZWO </para>
0267       </listitem>
0268 
0269       <listitem>
0270         <para> <emphasis role="bold">Relative</emphasis>: Relative Position
0271         Focusers. </para>
0272       </listitem>
0273 
0274       <listitem>
0275         <para> <emphasis role="bold">Time Based</emphasis>: Time based
0276         focusers with no position feedback that adjust focus position by
0277         moving for a certain amount of time. </para>
0278       </listitem>
0279     </itemizedlist>
0280 
0281     <para> The <guibutton>Focuser</guibutton> field contains the focuser in the
0282     attached Optical Train. </para>
0283 
0284     <para> For absolute and relative focusers, the step size is in units of
0285     <emphasis>ticks</emphasis> and for simple, or time based, focusers, the
0286     step size is in <emphasis>milliseconds</emphasis>. The
0287     <guibutton>In</guibutton> and <guibutton>Out</guibutton> buttons can then
0288     be used to move the focuser by the number of ticks defined in the
0289     <guibutton>Initial Step Size</guibutton> field in the
0290     <link linkend="focus-mechanics">Mechanics</link> tab.</para>
0291 
0292     <para> The Steps fields has 2 parts:</para>
0293     <itemizedlist>
0294       <listitem>
0295         <para> <emphasis role="bold">Left Hand Steps</emphasis>: Current focuser position. This is
0296         output only and is updated as the focuser moves to reflect the current position.</para>
0297       </listitem>
0298 
0299       <listitem>
0300         <para> <emphasis role="bold">Right Hand Steps</emphasis>: This is input and allows the user
0301         to enter a desired position. When the <guibutton>Goto</guibutton> button is pressed, the
0302         focuser is moved from its current position to the position indicated in this field. </para>
0303       </listitem>
0304     </itemizedlist>
0305 
0306     <para> On startup, the Left Hand Steps will show the current focuser position. The Right Hand Steps
0307     field is defaulted from the Optical Train saved settings. This is useful, for example, if
0308     you have several Optical Trains that use the same focuser but solve at different positions. In
0309     this case, the Right Hand Steps will contain the last persisted value for this field for
0310     the selected Optical Train. So, after swapping equipment and selecting the Optical Train, if the
0311     user presses the <guibutton>Goto</guibutton> button then the focuser will be moved to a
0312     good place to start focusing from.</para>
0313 
0314     <para> The <guibutton>Goto Focus Position</guibutton> button moves the
0315     focuser to the position in the righthand Steps field. </para>
0316 
0317     <para> The <guibutton>Stop Focuser Motion</guibutton> button stops the
0318     in-progress focuser motion. </para>
0319 
0320     <para> The <guibutton>Auto Focus</guibutton> button starts an Autofocus
0321     run. The <guibutton>Stop</guibutton> button is used to stop the run.
0322     </para>
0323 
0324     <para> The <guibutton>Capture Image</guibutton> button will take a frame
0325     based on the current settings in the <link linkend="focus-ccd-filter-wheel">
0326     Camera &amp; Filter Wheel Group</link>. The <guibutton>Start Framing</guibutton>
0327     button will start repeatedly capturing frames until the
0328     <guibutton>Stop</guibutton> button is pressed. </para>
0329 
0330     <para> Some of the focus algorithms will attempt to cope with being
0331     started away from the point of optimum focus, but for predictable results,
0332     it is best to start from a position of being approximately in focus. For
0333     first time setup, <guibutton>Start Framing</guibutton> can be used along
0334     with the <guibutton>In</guibutton> and <guibutton>Out</guibutton> buttons
0335     to adjust the focus position to roughly minimize the HFR of the stars in
0336     the captured images. When Framing is used in this way, the <link
0337     linkend="focus-v-curve">V-Curve</link> graph changes to show a time series
0338     of frames and their associated HFRs. This makes the framing process much
0339     easier to perform.</para>
0340 
0341     <para> If you are completely new to astronomy, it is always a good idea to
0342     get familiar with your equipment in daylight. This includes getting the
0343     approximate focus position on a distant object. This will provide a good
0344     starting position for focusing on stars when nighttime comes.</para>
0345   </sect2>
0346 
0347   <sect2 id="focus-ccd-filter-wheel">
0348     <title>Camera &amp; Filter Wheel Group</title>
0349 
0350     <screenshot>
0351       <screeninfo> Focus Camera &amp; Filter Wheel Group </screeninfo>
0352 
0353       <mediaobject>
0354         <imageobject>
0355           <imagedata fileref="focus_ccdfw_group.png" format="PNG" width="50%"/>
0356         </imageobject>
0357 
0358         <textobject>
0359           <phrase>Focus Camera &amp; Filter Wheel Group</phrase>
0360         </textobject>
0361       </mediaobject>
0362     </screenshot>
0363 
0364     <para> This section of parameters deals with the Camera and Filter
0365     settings to use when focusing.</para>
0366 
0367     <para> The top row of controls allows CCD parameters to be set.</para>
0368 
0369     <itemizedlist>
0370       <listitem>
0371         <para> <guilabel>Exp</guilabel>: The exposure time in seconds.</para>
0372       </listitem>
0373 
0374       <listitem>
0375         <para> The <guibutton>Toggle Full Screen</guibutton> button pops the
0376         window displaying the focus frame out to a separate window. Pressing
0377         it again returns it within the focus window.</para>
0378       </listitem>
0379 
0380       <listitem>
0381         <para> The <guibutton>Show in FITS Viewer</guibutton> button pops-up a
0382         separate FITS Viewer window to display the focus frame, in addition to
0383         the focus frame displayed within the focus window.</para>
0384       </listitem>
0385 
0386       <listitem>
0387         <para> The <guibutton>Live Video</guibutton> button brings up the
0388         associated popup.</para>
0389       </listitem>
0390     </itemizedlist>
0391 
0392     <para> The next row of controls allows Camera parameters to be set. Choose
0393     a value from the binning dropdown and then set either the camera gain or
0394     ISO.</para>
0395 
0396     <itemizedlist>
0397       <listitem>
0398         <para> <guilabel>Binning</guilabel>: Increasing the binning will
0399         change the image scale as well as resulting in brighter pixels. It is
0400         generally only worth binning above 1x1 if your image scale is oversampled
0401         where the increase in image scale does not lead to a loss of resolution.
0402         If you wish to increase star brightness try increasing the exposure
0403         and / or gain. If you are unsure bin 1x1.</para>
0404       </listitem>
0405 
0406       <listitem>
0407         <para> <guilabel>Gain</guilabel>: Set the Gain for the Camera being
0408         used to focus. The value needs to be high enough to give a clear star
0409         pattern but not so high as to create too much noise to interfere with
0410         the focus operation. Some experimentation will be required to find an
0411         optimum value. If you are unsure where to start try unity gain for
0412         your camera and adjust from there.</para>
0413       </listitem>
0414 
0415       <listitem>
0416         <para> <guilabel>ISO</guilabel>: Set the ISO for the Camera being used
0417         to focus. Some experimentation will be required to find an optimum
0418         value.</para>
0419       </listitem>
0420     </itemizedlist>
0421 
0422     <para> The third row of controls deals with the Temperature Source and
0423     Filter, if there is one:</para>
0424 
0425     <itemizedlist>
0426       <listitem>
0427         <para> <guilabel>TS</guilabel>: Select the temperature source from the
0428         dropdown. Underneath are displayed the current temperature from the
0429         selected temperature source and the change in temperature between when
0430         the last successful Autofocus run completed and the current
0431         temperature. It is common practice to redo focus after significant
0432         temperature changes that alter the telescope's focus point.</para>
0433       </listitem>
0434 
0435       <listitem>
0436         <para> <guilabel>Filter</guilabel>: Select the filter to use.</para>
0437 
0438         <para>To start focusing it will probably be easier to select the
0439         filter that allows the most light through, for example the Lum filter.
0440         Click the filter icon <inlinemediaobject><imageobject><imagedata
0441         fileref="view-filter.png" format="PNG"/></imageobject></inlinemediaobject>
0442         to launch the <link linkend="focus-filter-settings">Filter Settings</link>
0443         popup. This allows a number of parameters to be set per filter to be used during
0444         an Autofocus run.</para>
0445       </listitem>
0446 
0447       <listitem>
0448         <para> <guibutton>Reset</guibutton> button will reset the focusing
0449         subframe to full frame.</para>
0450       </listitem>
0451     </itemizedlist>
0452   </sect2>
0453 
0454   <sect2 id="focus-tools">
0455     <title>Tools Group</title>
0456 
0457     <screenshot>
0458       <screeninfo> Focus Tools Group </screeninfo>
0459 
0460       <mediaobject>
0461         <imageobject>
0462           <imagedata fileref="focus_tools_group.png" format="PNG" width="50%"/>
0463         </imageobject>
0464 
0465         <textobject>
0466           <phrase>Focus Tools Group</phrase>
0467         </textobject>
0468       </mediaobject>
0469     </screenshot>
0470 
0471     <para> This section describes the focus tools that are currently available.</para>
0472 
0473     <itemizedlist>
0474       <listitem>
0475         <para> The <guibutton>Aberration Inspector</guibutton> button starts an
0476         <link linkend="focus-aberration-inspector">Aberration Inspector</link> run.
0477         The <guibutton>Stop</guibutton> button can be used to stop the run.
0478         </para>
0479       </listitem>
0480       <listitem>
0481         <para> The <guibutton>CFZ</guibutton> button launches the
0482         <link linkend="focus-cfz">Critical Focus Zone</link> tool.
0483         </para>
0484       </listitem>
0485       <listitem>
0486         <para> The <guibutton>Advisor</guibutton> button launches the
0487         <link linkend="focus-advisor">Focus Advisor</link> tool.
0488         </para>
0489       </listitem>
0490     </itemizedlist>
0491   </sect2>
0492 
0493   <sect2 id="focus-options">
0494   <title>Focus Options</title>
0495 
0496   <screenshot>
0497     <screeninfo> Focus Options </screeninfo>
0498 
0499     <mediaobject>
0500       <imageobject>
0501         <imagedata fileref="focus_options.png" format="PNG" width="50%"/>
0502       </imageobject>
0503 
0504       <textobject>
0505         <phrase>Focus Options</phrase>
0506       </textobject>
0507     </mediaobject>
0508   </screenshot>
0509 
0510   <para>Parameters to configure Focus are accessed by pressing the <guibutton>Options...</guibutton>
0511   button. This launches the Options dialog with three panes:</para>
0512 
0513   <itemizedlist>
0514     <listitem>
0515       <para><link linkend="focus-settings">Settings</link>: These are general Focus settings.</para>
0516     </listitem>
0517     <listitem>
0518       <para><link linkend="focus-process">Process</link>: Parameters associated with the Autofocus process.</para>
0519     </listitem>
0520     <listitem>
0521       <para><link linkend="focus-mechanics">Mechanics</link>: Parameters associated with the focuser mechanics.</para>
0522     </listitem>
0523   </itemizedlist>
0524 
0525   <para>The parameters are stored for each Optical Train. This allows different configurations to be stored for
0526   different equipment. Parameters are stored when they are changed, so on startup the last used configuration for
0527   the selected Optical Train is loaded.</para>
0528 
0529   <sect3 id="focus-settings">
0530     <title>Focus Settings</title>
0531 
0532     <screenshot>
0533       <screeninfo> Focus Settings </screeninfo>
0534 
0535       <mediaobject>
0536         <imageobject>
0537           <imagedata fileref="focus_settings.png" format="PNG" width="50%"/>
0538         </imageobject>
0539 
0540         <textobject>
0541           <phrase>Focus Settings</phrase>
0542         </textobject>
0543       </mediaobject>
0544     </screenshot>
0545 
0546     <para>General section parameters:</para>
0547     <itemizedlist>
0548       <listitem>
0549         <para> <guilabel>Auto Select Star</guilabel>: This setting is only relevant if
0550         <guilabel>Sub Frame</guilabel> is selected. In this case if <guilabel>Auto Select Star</guilabel>
0551         is selected then Ekos will select the star to use for focus; otherwise
0552         the user will have to manually select the star using FitsViewer.</para>
0553       </listitem>
0554 
0555       <listitem>
0556         <para> <guilabel>Suspend Guiding</guilabel>: Set this option to
0557         suspend guiding during an Autofocus run. The purpose of this
0558         is to prevent guiding from having problems with defocused stars during
0559         the focus process where, for example, the guide scope is attached to the
0560         main telescope using an OAG.</para>
0561       </listitem>
0562 
0563       <listitem>
0564         <para> <guilabel>Dark Frame</guilabel>: Check this option to perform
0565         dark-frame subtraction. This option can be useful in noisy images,
0566         where a pretaken dark is subtracted from the focus image before
0567         further processing.</para>
0568 
0569         <para> If hot pixels are causing problems with focus, select Dark Frames and
0570         either setup a regular Master Dark frame or a Defect Map.</para>
0571 
0572         <para> Dark frames are used by Focus, Alignment and Guiding. See the
0573         Dark Library feature within the <link linkend="ekos-capture">Capture
0574         Module</link> for more details on how to setup Dark Frames.</para>
0575       </listitem>
0576 
0577       <listitem>
0578         <para> <guilabel>Full Field</guilabel>: Select to use the full field of
0579         the camera. In this mode, focus will automatically select multiple stars for
0580         use in an Autofocus run. The alternative to this is <guilabel>Sub Frame</guilabel>.</para>
0581       </listitem>
0582 
0583       <listitem>
0584         <para> <guilabel>Sub Frame</guilabel>: Select to use a single star for the
0585         Autofocus process. The alternative to this is <guilabel>Full Field</guilabel> where
0586         multiple stars will be used by Autofocus. Depending on the setting of
0587         <guilabel>Auto Select Star</guilabel> either the user or Ekos will select the star.</para>
0588       </listitem>
0589 
0590       <listitem>
0591         <para> <guilabel>Box</guilabel>: Sets the box size used to enclose the
0592         focus star when using <emphasis role="bold">Sub Frame</emphasis>.
0593         Increase if you have very large stars. For Bahtinov focus the box size
0594         can be increased even more to better enclose the Bahtinov diffraction
0595         pattern.</para>
0596       </listitem>
0597 
0598       <listitem>
0599         <para> <guilabel>Display Units</guilabel>: Select the units for display on the Autofocus V-Curve
0600         when HFR or FWHM is selected. <emphasis role="bold">Pixels</emphasis>
0601         and <emphasis role="bold">Arc Seconds</emphasis> are supported.</para>
0602       </listitem>
0603 
0604       <listitem>
0605         <para> <guilabel>Guide Settle</guilabel>: This option is used in conjunction
0606         with <guilabel>Suspend Guiding</guilabel>. It allows any vibrations in
0607         the optical train to settle by waiting this many seconds after the
0608         Autofocus process has completed, before restarting guiding.</para>
0609       </listitem>
0610     </itemizedlist>
0611 
0612     <para>Mask Section Parameters:</para>
0613 
0614     <para>These controls relate to <emphasis role="bold">Masking Options</emphasis>
0615     to be used when in <guilabel>Full Field</guilabel> mode. The effect of Masking Options can be seen in the
0616     <link linkend="focus-display">FITS Viewer</link>.</para>
0617     <itemizedlist>
0618       <listitem>
0619         <para> <guilabel>Use all stars for focusing</guilabel>: Select this option
0620         if all stars of the field should be considered for focusing.</para>
0621       </listitem>
0622             
0623       <listitem>
0624         <para> <guilabel>Ring Mask</guilabel>: This option provides two input fields
0625         that together define a doughnut over the FOV of the camera. Stars falling
0626         outside of the doughnut are discounted from processing. Setting an inner
0627         value above 0% causes stars in the centre of the FOV to be discarded. This
0628         could be useful to avoid using stars in the target of the image (for example
0629         a galaxy) for focusing purposes. Setting an outer value below 100%
0630         causes stars in the edges of the FOV to be discarded during focusing.
0631         This could be useful if you do not have a flat field out to the edges
0632         of your FOV.</para>
0633       </listitem>
0634 
0635       <listitem>
0636         <para> <guilabel>Mosaic Mask</guilabel>: A 3x3 mosaic is composed with tiles
0637         from the image center, its corners and from the edges. This option is useful
0638         if you want to inspect the optics performance - you might know this from the
0639         PixInsight Aberration Inspector script. The tile size can be configured in
0640         percent of the frame width, with the spacer value specifying the space between
0641         the tiles.</para>
0642         <para> There are four use-cases for the Mosaic Mask:
0643           <itemizedlist>
0644             <listitem>
0645                 <para> Checking focus in all parts of the sensor: The mask allows an easy
0646                 visual inspection and comparisons of stars in the center, corners and edges
0647                 of the sensor. This is especially useful for optics that show aberration if
0648                 the focus is not 100% met.</para>
0649             </listitem>
0650             <listitem>
0651                 <para>Correcting image tilt: especially large sensors are very sensitive to
0652                 incorrect distance and tilting of the sensor. In such cases, the image
0653                 shows aberration, especially in the image corners. If all corners show the same
0654                 effect, the distance needs to be corrected. If the aberrations in the corners
0655                 differ, this is typically the result of a tilted sensor.</para>
0656             </listitem>
0657             <listitem>
0658                 <para>Collimating Newtonians: inspecting frames in a defocused state is typically
0659                 used for collimating Newtonians. See, for example, Tommy Nawratil's
0660                 <ulink url="https://teleskop-austria.at/information/pdf/JUS_Photonewton_Collimation_Primer_EN.pdf">
0661                 The Photonewton Collimation Primer</ulink> for more details.</para>
0662             </listitem>
0663             <listitem>
0664                 <para>Running the <link linkend="focus-aberration-inspector">Aberration Inspector</link> tool.</para>
0665             </listitem>
0666           </itemizedlist></para>
0667       </listitem>
0668     </itemizedlist>
0669 
0670     <para>Adaptive Focus Parameters:</para>
0671 
0672     <para> The next set of controls relate to <emphasis role="bold">Adaptive Focus</emphasis>.
0673     The idea here is to keep the telescope focused by adapting the focuser position based on changes
0674     in environmental conditions without having to perform a full Autofocus run. See the
0675     <link linkend="focus-adaptive">Adaptive Focus</link> section for more details.</para>
0676 
0677     <para> For example, as temperature changes during an imaging session so the focus
0678     point will change. By sampling the temperature between subframes it is possible to
0679     firstly calculate the change in temperature and then to convert this to a number of
0680     ticks of focuser movement to apply between subframes.</para>
0681 
0682     <para> In order to use <emphasis role="bold">Adaptive Focus</emphasis> it is necessary
0683     to setup some data for your system. In particular you need to tell Ekos how many ticks (and
0684     in which direction) to move the focuser when the environmental conditions change. This is
0685     covered in the <link linkend="focus-filter-settings">Filter Settings</link> popup. The
0686     popup is launched by clicking the filter icon <inlinemediaobject><imageobject><imagedata
0687     fileref="view-filter.png" format="PNG"/></imageobject></inlinemediaobject>.</para>
0688 
0689     <para> The following controls are available:
0690         <itemizedlist>
0691             <listitem>
0692               <para> <guilabel>Adaptive Focus</guilabel>: Select this option to activate
0693               <emphasis role="bold">Adaptive Focus</emphasis>.</para>
0694             </listitem>
0695 
0696             <listitem>
0697               <para> <guilabel>Min Move</guilabel>: The minimum Adaptive Focus movement allowed.</para>
0698             </listitem>
0699 
0700             <listitem>
0701               <para> <guilabel>Adapt Start Pos</guilabel>: Check to allow Adaptive Focus to calculate the
0702               start position for an Autofocus run. The starting position is the last good solve position for
0703               the selected filter, adapted for environmental changes.</para>
0704 
0705               <para> For example, if the current focuser position is 1000, temperature = 4C, and if the Red
0706               filter is selected (last good focus position for Red is 990 @ 5C and Ekos is configured to move
0707               +3 <guilabel>Ticks / °C</guilabel>). Then, if Adapt Start Pos is off,
0708               Autofocus will start at 1000. If Adapt Start Pos is on, Autofocus will start at 990 + (5 - 4) * 3
0709               = 993.</para>
0710 
0711               <para> This feature is useful to ensure that Autofocus starts from close to the focus point
0712               which will mean a more symmetric V-curve. It is particularly useful when changing between filters
0713               which have large differences in focus points.</para>
0714 
0715               <para> It is possible to use this feature on its own without Adaptive Focus. Just set the checkbox
0716               and leave the ticks per degree C set to zero. This way the Autofocus start position will be
0717               filter dependent and will start each Autofocus run at the focus point of the last successful
0718               Autofocus run for that filter.</para>
0719             </listitem>
0720 
0721             <listitem>
0722               <para> <guilabel>Max Total Move</guilabel>: The maximum total focuser movement that
0723               Adaptive Focus is allowed in the observing session. The purpose of this is as a "dead man's
0724               handle" on Adaptive Focus in case it runs away. For example, if the temperature source fails
0725               and returns bad temperature readings whilst the equipment is unattended, this could result in
0726               Adaptive Focus attempting to make large focuser movements.</para>
0727 
0728               <para> If the Max Total Move is reached then <guilabel>Adaptive Focus</guilabel> is unchecked
0729               until manually re-checked by the user.</para>
0730             </listitem>
0731         </itemizedlist>
0732     </para>
0733   </sect3>
0734 
0735   <sect3 id="focus-process">
0736     <title>Focus Process</title>
0737 
0738     <screenshot>
0739       <screeninfo> Focus Process </screeninfo>
0740 
0741       <mediaobject>
0742         <imageobject>
0743           <imagedata fileref="focus_process.png" format="PNG" width="50%"/>
0744         </imageobject>
0745 
0746         <textobject>
0747           <phrase>Focus Process</phrase>
0748         </textobject>
0749       </mediaobject>
0750     </screenshot>
0751 
0752     <para>Focus Process Parameters:</para>
0753 
0754     <itemizedlist>
0755       <listitem>
0756         <para> <guilabel>Detection</guilabel>: Select star detection
0757         algorithm. Each algorithm has its strengths and weaknesses. It is
0758         recommended to use SEP, unless you have a specialized
0759         use. The following are available:</para>
0760 
0761         <itemizedlist>
0762           <listitem>
0763             <para> <emphasis role="bold">SEP</emphasis>: Source Extraction and
0764             Photometry built in library. This is the default value.</para>
0765           </listitem>
0766 
0767           <listitem>
0768             <para> <emphasis role="bold">Centroid</emphasis>: An extraction
0769             method based on estimating star mass around signal peaks.</para>
0770           </listitem>
0771 
0772           <listitem>
0773             <para> <emphasis role="bold">Gradient</emphasis>: A single source
0774             extraction model based on the Sobel filter. </para>
0775           </listitem>
0776 
0777           <listitem>
0778             <para> <emphasis role="bold">Threshold</emphasis>: A single source
0779             detection algorithm based on pixel values. </para>
0780           </listitem>
0781 
0782           <listitem>
0783             <para> <emphasis role="bold">Bahtinov</emphasis>: This detection
0784             method can be used when using a Bahtinov mask for focusing. First
0785             take an image, then select the star to focus on. A new image will
0786             be taken and the diffraction pattern will be analysed. Three lines
0787             will be displayed on the diffraction pattern showing how well the
0788             pattern is recognized and how good the image is in focus. When the
0789             pattern is not well recognized, the <emphasis>Num. of
0790             rows</emphasis> parameter can be adjusted to improve recognition.
0791             The line with the circles at each end is a magnified indicator for
0792             the focus. The shorter the line, the better the image is in
0793             focus.</para>
0794           </listitem>
0795         </itemizedlist>
0796       </listitem>
0797 
0798       <listitem>
0799         <para> <guilabel>SEP Profile</guilabel>: If the star detection
0800         algorithm is set to <emphasis>SEP</emphasis>, then choose a parameter
0801         profile to use with the algorithm. It is recommended to use the
0802         default 1-Focus-Default profile as a starting point.</para>
0803       </listitem>
0804 
0805       <listitem>
0806         <para> <guilabel>Algorithm</guilabel>: Select the Autofocus process
0807         algorithm: </para>
0808 
0809       <itemizedlist>
0810         <listitem>
0811           <para> <emphasis role="bold">Linear 1 Pass</emphasis>: This is the
0812           recommended algorithm. In this algorithm, Ekos establishes a V-Curve
0813           and fits a curve to the data to find the focus solution. It then moves
0814           to the calculated solution.</para>
0815 
0816           <para> This algorithm supports the older style Quadratic curve
0817           type as well as the newer <link
0818           linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link>
0819           for Hyperbolic and Parabolic curves. It will also weight the
0820           datapoints in the curve fitting process if <guilabel>Use Weights</guilabel>
0821           is checked and run a refinement process if <guilabel>Refine Curve Fit
0822           </guilabel> is selected.</para>
0823         </listitem>
0824 
0825         <listitem>
0826           <para> <emphasis role="bold">Linear</emphasis>: This algorithm
0827           builds a V-Curve with approximately <emphasis role="bold">Out step
0828           Multiple</emphasis> steps on each side of the minimum. Having
0829           built the V-Curve it then fits a quadratic equation to the curve
0830           (parabolic shape) and uses this to calculate the focuser position
0831           giving the minimum HFR. Having identified the minimum it then
0832           performs a 2nd pass halving the step size, recreating the curve
0833           from the 1st pass. It attempts to stop within <emphasis
0834           role="bold">Tolerance</emphasis> of the minimum HFR calculated
0835           during the 1st pass.</para>
0836         </listitem>
0837 
0838         <listitem>
0839           <para> <emphasis role="bold">Iterative</emphasis>: Moves focuser
0840           by discreet steps initially decided by the step size. Once a curve
0841           slope is calculated, further step sizes are calculated to reach an
0842           optimal solution. The algorithm stops when the measured HFR is
0843           within <emphasis role="bold">Tolerance</emphasis> of the minimum
0844           HFR recorded in the procedure.</para>
0845         </listitem>
0846 
0847         <listitem>
0848           <para> <emphasis role="bold">Polynomial</emphasis>: Starts with
0849           the iterative method. Upon crossing to the other side of the
0850           V-Curve, polynomial fitting coefficients along with possible
0851           minimum solution are calculated. This algorithm can be faster than
0852           a purely iterative approach given a good data set.</para>
0853         </listitem>
0854       </itemizedlist>
0855       </listitem>
0856 
0857       <listitem>
0858         <para> <guilabel>Curve Fit</guilabel>: The type of curve to fit to the datapoints. </para>
0859         <itemizedlist>
0860           <listitem>
0861             <para> <emphasis role="bold">Hyperbola</emphasis>: Fits a Hyperbola using a non-linear least squares
0862             algorithm supplied by GSL (GNU Science Library). See <link
0863             linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link> for more details.</para>
0864 
0865             <para> This is the recommended option.</para>
0866           </listitem>
0867 
0868           <listitem>
0869             <para> <emphasis role="bold">Parabola</emphasis>: Fits a Parabola using a non-linear least squares
0870             algorithm supplied by GSL (GNU Science Library). See <link
0871             linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link> for more details.</para>
0872           </listitem>
0873 
0874           <listitem>
0875             <para> <emphasis role="bold">Quadratic</emphasis>: Uses a quadratic equation using a linear style least
0876             squares algorithm supplied by GSL (GNU Science Library). This is, in effect, a parabolic curve.</para>
0877 
0878             <para> It is no longer recommended to use this curve.</para>
0879           </listitem>
0880         </itemizedlist>
0881       </listitem>
0882 
0883       <listitem>
0884         <para> <guilabel>Measure</guilabel>: Select Measure to use in the focus process.
0885         The following are available:</para>
0886 
0887         <itemizedlist>
0888           <listitem>
0889             <para> <emphasis role="bold">HFR</emphasis>: Half Flux Radius (HFR) is the
0890             recommended measure. When a star is detected, Ekos will calculate the HFR for
0891             the star. This is the radius of an imaginary circle, centered on the star
0892             center, that encloses half the star's total flux.</para>
0893 
0894             <para>The point of best focus corresponds to the minimum HFR.</para>
0895           </listitem>
0896 
0897           <listitem>
0898             <para> <emphasis role="bold">HFR Adj</emphasis>: This feature
0899             uses a brightness adjusted HFR calculation to take account of the fact that the HFR for
0900             brighter stars is larger than for smaller stars.</para>
0901 
0902             <para> The algorithm adjusts the value of the measured HFR, usually upwards, so the HFRs obtained
0903             by the HFR Adj method will be higher than the measured HFR values. This does not mean that you are
0904             getting worse results by using HFR Adj, simply that the measure is different.</para>
0905 
0906             <para> When using this Measure it is usual to get smaller error bars on the datapoints when
0907             <guilabel>Use Weights</guilabel> is selected.</para>
0908 
0909             <para>The point of best focus corresponds to the minimum adjusted HFR.</para>
0910           </listitem>
0911 
0912           <listitem>
0913             <para> <emphasis role="bold">FWHM</emphasis>: This feature fits
0914             a Gaussian surface to each star and uses that to calculate the Full Width Half Maximum
0915             (FWHM) of the star. The FWHM is the width of an circle (or ellipse) centered on the star center
0916             reaching the edge of the star at half its maximum intensity.</para>
0917 
0918             <para>The point of best focus corresponds to the minimum FWHM.</para>
0919 
0920             <para>Expect the FWHM to be approximately twice the HFR of a star.</para>
0921           </listitem>
0922 
0923           <listitem>
0924             <para> <emphasis role="bold"># Stars</emphasis>: This feature
0925             calculates the number of stars in the image and uses this number as the focus measure.
0926             The idea is that as you move nearer focus so more stars become detectable.</para>
0927 
0928             <para> The advantage of this Measure is that it is very simple and does not require
0929             algorithms to calculate HFRs or FWHMs.</para>
0930 
0931             <para>The point of best focus corresponds to a maximum number of stars.</para>
0932           </listitem>
0933 
0934           <listitem>
0935             <para> <emphasis role="bold">Fourier</emphasis>: Fourier takes a Fourier transform of the
0936             image and calculates the image power in frequency space. The assumption is that for an astronomical
0937             image of stars and background, the stars will be gaussians. Under a Fourier
0938             transform, a gaussian transforms to another gaussian; but wider stars transform to narrower
0939             gaussians in frequency space, and vice-versa. So, at focus, summing up the contents in
0940             frequency space, which is in effect a measure of power, will be a maximum.</para>
0941 
0942             <para>This follows the main idea suggested by Tan and Schulz in their paper:
0943             <ulink url="https://arxiv.org/pdf/2201.12466.pdf">A Fourier method for the determination of focus
0944             for telescopes with stars</ulink>. Please note that this paper makes other processing suggestions
0945             beyond the idea of using Fourier Transforms that are not included within Ekos</para>
0946 
0947             <para> This is a relatively new method in the Astro Community, and does not require star detection.
0948             Tan and Schulz report good results with both amateur and professional telescopes.</para>
0949           </listitem>
0950         </itemizedlist>
0951       </listitem>
0952 
0953       <listitem>
0954         <para> <guilabel>PSF</guilabel>: If <guilabel>Measure</guilabel> is set to FWHM, then the PSF
0955         widget can be selected for use in fitting a surface to the star. At present just Gaussian is
0956         supported.</para>
0957       </listitem>
0958 
0959       <listitem>
0960         <para> <guilabel>Use Weights</guilabel>: This is only available with the Linear 1 Pass focus algorithm
0961         and Curve Fits of Hyperbola and Parabola. It requires Full Field to be selected. The option calculates
0962         the standard deviation of star Measure and uses the square of this (mathematically the variance) as a
0963         weighting in the curve fitting process. The advantage of this is that datapoints with less reliable data
0964         and therefore larger HFR standard deviations will be given less weight than more reliable datapoints. If
0965         this option is unchecked, and for all other curve fitting where the option is not allowed, all datapoints
0966         are given equal weight in the curve fitting process.</para>
0967 
0968         <para> The standard deviation is drawn on the V-Curve for each datapoint as an error bar.</para>
0969 
0970         <para> It is recommended to check this option.</para>
0971 
0972         <para> See the <link linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link> for more details.</para>
0973       </listitem>
0974 
0975       <listitem>
0976         <para> <guilabel>R² Limit</guilabel>: This is only available with the Linear 1 Pass focus algorithm
0977         and Curve Fits of Hyperbola and Parabola. As part of the Linear 1 Pass algorithm, the degree to which the
0978         curve fits the datapoints, or <link linkend="Coefficient_of_Determination">Coefficient of Determination,
0979         R²</link>, is calculated. This option allows a minimum acceptable value of R² to be defined that is compared
0980         to the value obtained from the curve fitting process. If the minimum value has not been achieved then
0981         Autofocus will rerun. Only one rerun will be performed and even if the minimum R² has not been met the
0982         second time, the Autofocus run will still be deemed successful.</para>
0983 
0984         <para> Experiment to find an appropriate value but a good starting point would be 0.8 or 0.9</para>
0985       </listitem>
0986 
0987       <listitem>
0988         <para> <guilabel>Refine Curve Fit</guilabel>: This option is only available with the Linear
0989         1 Pass focus algorithm and Curve Fits of Hyperbola and Parabola. If this option is checked then at the end
0990         of the sweep of datapoints, Ekos fits a curve and measures the R². It then applies Peirce's Criterion
0991         based on Gould's methodology for outlier identification. See <ulink
0992         url="https://en.wikipedia.org/wiki/Peirce%27s_criterion">Peirce's Criterion</ulink> for details incl
0993         Peirce's original paper and Gould's paper which are both referenced in the notes. If Peirce's Criterion
0994         detects 1 or more outliers then another curve fit is attempted with the outliers removed. Again the R²
0995         is calculated and compared with the original curve fit R². If the R² is better, then the latest run is used,
0996         if not, the original curve fit (with the outliers included) is used.</para>
0997 
0998         <para> Outliers are clearly marked on the V-Curve with an X through the datapoint.</para>
0999 
1000         <para> It is recommended to check this option.</para>
1001       </listitem>
1002 
1003       <listitem>
1004         <para> <guilabel>Average over</guilabel>: Number of frames to capture at each datapoint. It is usually
1005         sensible to start with 1 but increasing this will result in an averaging process for the star Measure
1006         selected.</para>
1007       </listitem>
1008 
1009       <listitem>
1010         <warning>
1011         <para><guilabel>Donut Buster</guilabel>: This is an experimental feature and should be used with caution. The
1012         intention of Donut Buster is to improve focusing for telescopes with central
1013         obstructions that create donut shaped stars when defocused. In future it is likely that more functionality
1014         will be developed for Donut Buster. In this release the functionality is aimed at data collection in order
1015         to research methods of improving focus.</para>
1016         </warning>
1017       </listitem>
1018       <listitem>
1019         <warning>
1020         <para> <guilabel>Time Dilation Factor</guilabel>: This is an experimental feature of Donut Buster and should be
1021         used with caution. This feature scales the exposure time during Autofocus from the Exposure value entered in the
1022         Exposure field for the furthest datapoints from focus. Datapoints near focus are taken with an unscaled exposure.
1023         For example, if Focus is setup with an Exposure of 2s and Time Dilation Factor is set to 4, then when Autofocus
1024         moves out to take its first datapoint, an exposure of 2s * 4 = 8s is used. On each successive datapoint the
1025         exposure is reduced down to 2s around the point of optimum focus. As the focuser moves through focus, so the
1026         exposure is scaled upwards to 8s for the last datapoint.</para>
1027         <para> The purpose of this feature is to increase the brightness of out of focus datapoints which will be dimmer than
1028         in-focus datapoints and therefore harder for star detection to resolve from the background noise.</para>
1029         <para> This feature assumes Autofocus is run from near to optimum focus.</para>
1030         </warning>
1031       </listitem>
1032 
1033       <listitem>
1034         <para> If <guilabel>Detection</guilabel> is set to Threshold then the following additional field is
1035         available:</para>
1036         <itemizedlist>
1037           <listitem>
1038             <para> <guilabel>Threshold</guilabel>: This contains a percentage value used for star detection using the
1039             <emphasis>Threshold</emphasis> detection algorithm. Increase to restrict the centroid to bright
1040             cores. Decrease to enclose fuzzy stars.</para>
1041           </listitem>
1042         </itemizedlist>
1043       </listitem>
1044 
1045       <listitem>
1046         <para>  If <guilabel>Detection</guilabel> is set to Bahtinov then the following additional widgets are
1047         available:</para>
1048         <itemizedlist>
1049           <listitem>
1050             <para> <guilabel>Num. of rows</guilabel>: The number of lines displayed on screen when using a
1051             Bahtinov mask.</para>
1052           </listitem>
1053 
1054           <listitem>
1055             <para> <guilabel>Sigma</guilabel>: The sigma of the gaussian blur applied to the image before applying
1056             Bahtinov edge detection.</para>
1057           </listitem>
1058 
1059           <listitem>
1060             <para> <guilabel>Kernel Size</guilabel>: The kernel size of the gaussian blur applied to the image
1061             before applying Bahtinov edge detection.</para>
1062           </listitem>
1063         </itemizedlist>
1064       </listitem>
1065 
1066       <listitem>
1067         <para> If <guilabel>Algorithm</guilabel> is set to Linear or Iterative then the following additional widget is
1068         available:</para>
1069         <itemizedlist>
1070           <listitem>
1071           <para> <guilabel>Tolerance</guilabel>: The tolerance percentage value is used to help decide when the
1072           Autofocus process stops. During the Autofocus process, HFR values are recorded, and once the focuser is close to an
1073           optimal position, it starts measuring HFRs against the minimum recorded HFR in the session and stops
1074           whenever a measured HFR value is within % difference of the minimum recorded HFR. Decrease the value to
1075           narrow the optimal focus point solution radius. Increase to expand solution radius. </para>
1076 
1077           <warning>
1078           <para> Setting the Tolerance value too low might result in a repetitive loop and would most likely result in a
1079           failed Autofocus process. </para>
1080           </warning>
1081           </listitem>
1082         </itemizedlist>
1083       </listitem>
1084     </itemizedlist>
1085   </sect3>
1086 
1087   <sect3 id="focus-mechanics">
1088     <title>Focus Mechanics</title>
1089 
1090     <screenshot>
1091       <screeninfo> Focus Mechanics </screeninfo>
1092 
1093       <mediaobject>
1094         <imageobject>
1095           <imagedata fileref="focus_mechanics.png" format="PNG" width="50%"/>
1096         </imageobject>
1097 
1098         <textobject>
1099           <phrase>Focus Mechanics</phrase>
1100         </textobject>
1101       </mediaobject>
1102     </screenshot>
1103 
1104     <para> Focus Mechanics Parameters:</para>
1105 
1106   <itemizedlist>
1107   <listitem>
1108     <para> <guilabel>Walk</guilabel>: This specifies the way Autofocus will "walk" inwards through its
1109     sweep to produce the V-Curve from which the focus solution will be calculated.</para>
1110 
1111     <para> The following are available:
1112     <itemizedlist>
1113       <listitem>
1114         <para> <emphasis role="bold">Classic</emphasis>: This is the recommended setting. The inward sweep
1115         follows a series of steps of equal size (<guilabel>Initial Step Size</guilabel>). The algorithm includes
1116         logic to determine when to stop that makes the exact number of steps unpredictable but it will be about
1117         2 * (<guilabel>Out Step Multiple</guilabel>) + 1.</para>
1118         <para> This Walk is tolerant of curve fitting failures in the last step where it will take a further
1119         step and try again to solve. It is also somewhat tolerant of not being started near to focus so is a good
1120         choice for the initial Autofocus run.</para>
1121         <para> Because of the "tolerance" of this Walk to less than perfect setup it is a conservative option
1122         to chose, but comes at the expense of extra steps and therefore extra time in the Autofocus process.</para>
1123       </listitem>
1124 
1125       <listitem>
1126         <para> <emphasis role="bold">Fixed Steps</emphasis>: This feature is available in the Linear 1 Pass
1127         <guilabel>Algorithm</guilabel>. It is quite similar to Classic but <guilabel>Fixed Steps</guilabel>
1128         is used to control the total number of steps taken.</para>
1129         <para> This algorithm is more predicable than Classic in that it takes a definite number of steps (so
1130         will be faster), but is less tolerant of issues curve fitting the last data point and needs to be
1131         started near to focus.</para>
1132         <para> When selected, the <guilabel>Out Steps Multiple</guilabel> is replaced by
1133         <guilabel>Fixed Steps:</guilabel>
1134         <screenshot>
1135           <screeninfo> Focus Mechanics </screeninfo>
1136           <mediaobject> <imageobject> <imagedata fileref="focus_mechanics1.png" format="PNG" width="50%"/>
1137             </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
1138         </screenshot>
1139         </para>
1140       </listitem>
1141       <listitem>
1142         <para> <emphasis role="bold">CFZ Shuffle</emphasis>: This feature is available in the Linear 1 Pass
1143         <guilabel>Algorithm</guilabel>. It is a variation on Fixed Steps so the comments on that Walk are
1144         applicable here as well.</para>
1145 
1146         <para> The difference between CFZ Shuffle and Fixed Steps is that near the center of the sweep (which
1147         should be around the Critical Focus Zone (CFZ)) the algorithm takes steps of half the specified size.</para>
1148       </listitem>
1149     </itemizedlist>
1150     </para>
1151   </listitem>
1152 
1153   <listitem>
1154     <para> <guilabel>Focuser Settle</guilabel>: The number of seconds to wait, after moving the focuser, before
1155     starting the next capture. The purpose is to stop any vibrations in the optical train from affecting
1156     the next frame.</para>
1157   </listitem>
1158 
1159   <listitem>
1160     <para> <guilabel>Initial Step size</guilabel>: This sets the step size to be used by various focus algorithms.
1161     For absolute and relative focusers this is the number of ticks; for timer based focusers this is the number of
1162     milliseconds.</para>
1163   </listitem>
1164 
1165   <listitem>
1166     <para> <guilabel>Out Step Multiple</guilabel>: Used by the Linear and Linear 1 Pass focus algorithms in the
1167     Classic walk, this parameter specifies the initial number of outward steps the focuser takes at the start of
1168     an Autofocus run.</para>
1169   </listitem>
1170 
1171   <listitem>
1172     <para> <guilabel>Number Steps</guilabel>: Used by the Linear 1 Pass algorithm in the Fixed Steps and CFZ
1173     Shuffle walks, this parameter specifies the total number of steps the focuser takes to create the V-Curve in
1174     an Autofocus run.</para>
1175   </listitem>
1176 
1177   <listitem>
1178     <para> <guilabel>Max Travel</guilabel>: Puts bounds on the amount of travel from the current focuser position
1179     that is permitted by the Autofocus algorithms. The purpose is to protect the focuser from travelling too far
1180     and potentially damaging itself. On the other hand, the value needs to be big enough to allow sufficient focuser
1181     motion to permit the auto focus runs to complete.</para>
1182   </listitem>
1183 
1184   <listitem>
1185     <para> <guilabel>Max Step Size</guilabel>: Used by the Iterative algorithm to limit the maximum step size that
1186     can be used.</para>
1187   </listitem>
1188 
1189   <listitem>
1190     <para> <guilabel>Driver Backlash</guilabel>: See the section on <link linkend="focus-backlash">Backlash</link>.</para>
1191 
1192     <para>There are 2 schemes that can be used:</para>
1193 
1194     <itemizedlist>
1195       <listitem>
1196         <para>Set <guilabel>Driver Backlash</guilabel> to 0 to switch it off and deal with Backlash elsewhere.</para>
1197       </listitem>
1198 
1199       <listitem>
1200         <para>Set <guilabel>Driver Backlash</guilabel> &gt; 0 to use Driver Backlash to manage Backlash in the device driver. Note
1201         that this field is only editable if the device driver supports Backlash.</para>
1202         <para>This is the same data field that is displayed in the Indi Control Panel for the focuser device. It can be set
1203         in either place.</para>
1204       </listitem>
1205     </itemizedlist>
1206   </listitem>
1207 
1208   <listitem>
1209     <para> <guilabel>AF Overscan</guilabel>: See the section on <link linkend="focus-backlash">Backlash</link>.</para>
1210 
1211     <para> There are 2 schemes that can be used:</para>
1212     <itemizedlist>
1213       <listitem>
1214         <para> Set <guilabel>AF Overscan</guilabel> to 0 to switch it off and deal with Backlash elsewhere.</para>
1215       </listitem>
1216 
1217       <listitem>
1218         <para> Set <guilabel>AF Overscan</guilabel> &gt; 0 to have the Focus module manage Backlash.</para>
1219       </listitem>
1220     </itemizedlist>
1221   </listitem>
1222 
1223   <listitem>
1224     <para> <guilabel>Capture Timeout</guilabel>: The amount of time in seconds to wait for a captured image to be received before
1225     declaring a timeout. This should only be triggered if there are problems with the camera during the Focus process so set this
1226     to a high enough value that it will not occur during normal operation.</para>
1227   </listitem>
1228 
1229   <listitem>
1230     <para> <guilabel>Motion Timeout</guilabel>: The amount of time in seconds to wait for the focuser to move to the requested position
1231     before declaring a timeout. This should only be triggered if there are problems with the focuser during the Focus process so set this
1232     to a high enough value that it will not occur during normal operation.</para>
1233   </listitem>
1234   </itemizedlist>
1235   </sect3>
1236   </sect2>
1237 
1238   <sect2 id="focus-cfz">
1239     <title>Focus Critical Focus Zone (CFZ)</title>
1240 
1241     <screenshot>
1242       <screeninfo> Focus CFZ </screeninfo>
1243 
1244       <mediaobject>
1245         <imageobject>
1246           <imagedata fileref="focus_cfz_classic.png" format="PNG" width="50%"/>
1247         </imageobject>
1248 
1249         <textobject>
1250           <phrase>Focus CFZ</phrase>
1251         </textobject>
1252       </mediaobject>
1253     </screenshot>
1254 
1255     <para>Focus CFZ Parameters:</para>
1256 
1257   <itemizedlist>
1258   <listitem>
1259     <para> <guilabel>Algorithm</guilabel>: This specifies the Critical Focus Zone (CFZ) algorithm. The purpose of this is
1260     to calculate the CFZ for the equipment attached in the Optical Train. It is not necessary to use this functionality
1261     in order to successfully focus, but it provides useful information if correctly configured.</para>
1262 
1263     <para> It requires some knowledge to configure it correctly. There is plenty of information available on the internet.</para>
1264 
1265     <para> The idea of the CFZ dialog is that it starts with data from the Optical Train used in the Focus tab and uses that to
1266     calculate the CFZ. The user can adjust parameters to do "what-if" scenarios to see how it affects the CFZ. Clicking the
1267     <guilabel>Reset to OT</guilabel> button resets any adjusted parameters to the Optical Train values.</para>
1268 
1269     <para> If the <guilabel>Display</guilabel> box is checked then the CFZ is drawn on the V-Curve after Autofocus
1270     successfully completes.
1271     <screenshot>
1272       <screeninfo> Focus Mechanics </screeninfo>
1273       <mediaobject> <imageobject> <imagedata fileref="focus_cfz_moustache.png" format="PNG" width="50%"/>
1274         </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
1275     </screenshot></para>
1276     <para> It is necessary to specify the <guilabel>Step Size</guilabel> parameter which specifies in microns how far one tick
1277     moves the focal plane. For refractors there is usually a 1-to-1 relationship between moving the focuser which moves the
1278     telescope draw-tube mechanism and the focal plane movement. For other types of telescope the relationship is likely to be
1279     more complex. Refer to details of your telescope / manufacturer for this information.</para>
1280 
1281     <para> The following algorithms are available:
1282     <itemizedlist>
1283       <listitem>
1284         <para> <emphasis role="bold">Classic</emphasis>: This is the recommended setting. The equation used is displayed
1285         in the top right of the dialog and is the equation most commonly seen on the internet. The equation comes from a
1286         linear optics treatment using the Airy Disc and is acknowledged to have limitations. For this reason it includes
1287         a "tolerance" factor that can be adjusted by the user. For example, in the often quoted “In Perfect Focus” article
1288         by Don Goldman and Barry Megdal in Sky &amp; Telescope 2010 they suggest setting t=1/3.</para>
1289       </listitem>
1290 
1291       <listitem>
1292         <para> <emphasis role="bold">Wavefront</emphasis>: The equation used is displayed in the top right of the dialog.
1293         The equation comes from a wavefront approach to the CFZ. Again, it has limitations and again, for this reason it
1294         includes a "tolerance" factor that can be adjusted by the user.
1295         <screenshot>
1296           <screeninfo> Focus Mechanics </screeninfo>
1297           <mediaobject> <imageobject> <imagedata fileref="focus_cfz_wavefront.png" format="PNG" width="50%"/>
1298             </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
1299         </screenshot>
1300         </para>
1301       </listitem>
1302 
1303       <listitem>
1304         <para> <emphasis role="bold">Gold</emphasis>: This method is based on work done by Gold Astro and presented
1305         <ulink url="https://www.goldastro.com/goldfocus/ncfz.php">here</ulink>.</para>
1306         <screenshot>
1307           <screeninfo> Focus Mechanics </screeninfo>
1308           <mediaobject> <imageobject> <imagedata fileref="focus_cfz_gold.png" format="PNG" width="50%"/>
1309             </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
1310         </screenshot>
1311       </listitem>
1312     </itemizedlist>
1313     </para>
1314   </listitem>
1315 
1316   <listitem>
1317     <para> <guilabel>Tolerance</guilabel>: This is used by Classic and Wavefront algorithms and is a scaling factor
1318     between 0 and 1.</para>
1319     <para> For the Classic algorithm, Goldman and Megdal suggest 1/3.</para>
1320     <para> For the Wavefront algorithm, some have suggested 1/3 or even 1/10.</para>
1321   </listitem>
1322 
1323   <listitem>
1324     <para> <guilabel>Tolerance (τ)</guilabel>: This is used by the Gold algorithm and is a focus tolerance as a percentage of
1325     total seeing. The Gold website suggests 3-5% for a good focuser or 1-2% for a top quality focuser. See the
1326     <ulink url="https://www.goldastro.com/goldfocus/ncfz.php">Gold Astro website</ulink> for more details.</para>
1327   </listitem>
1328 
1329   <listitem>
1330     <para> <guilabel>Display</guilabel>: Check this box to display the calculated CFZ on the V-Curve after a
1331     successful Autofocus run. It is displayed as a yellow moustache.</para>
1332   </listitem>
1333 
1334   <listitem>
1335     <para> <guilabel>Reset to OT</guilabel>: Press this button to reset any parameters to values defaulted from the
1336     currently connected Optical Train.</para>
1337   </listitem>
1338 
1339   <listitem>
1340     <para> <guilabel>Wavelength (λ)</guilabel>: This is the light wavelength to use. It is defaulted from the currently used
1341     filter. Remember to set this up in <link linkend="focus-filter-settings">Filter Settings</link> for your filters.</para>
1342   </listitem>
1343 
1344   <listitem>
1345     <para> <guilabel>Aperture (A)</guilabel>: This is the aperture of the telescope in mm. It is defaulted from the
1346     currently connected Optical Train.</para>
1347   </listitem>
1348 
1349   <listitem>
1350     <para> <guilabel>Focal Ratio (f)</guilabel>: This is the focal ratio of the telescope. It is defaulted from the
1351     currently connected Optical Train.</para>
1352   </listitem>
1353 
1354   <listitem>
1355     <para> <guilabel>FWHM (θ)</guilabel>: This is used by the Gold Algorithm and is the total seeing. This is the combined
1356     contribution of the diffraction limit of your telescope and the astronomical seeing. The
1357     <ulink url="https://www.goldastro.com/goldfocus/ncfz.php">Gold Astro website</ulink> describes how you might approximate
1358     the total once you have values for the individual contributions.</para>
1359   </listitem>
1360 
1361   <listitem>
1362     <para> <guilabel>CFZ</guilabel>: This is calculated CFZ in microns and in ticks.</para>
1363   </listitem>
1364 
1365   <listitem>
1366     <para> <guilabel>Step Size</guilabel>: This must be input by the user (as it cannot be calculated by Ekos). It relates how far
1367     1 tick moves the focal plane in microns. </para>
1368     <para> For a refractor this is how far the drawtube moves when the focuser is moved by 1 tick. You might be able to get this
1369     value from the specification of your focuser (how many ticks for a complete revolution of your focuser) and the thread pitch of
1370     your telescope drawtube along with any gearing involved.</para>
1371     <para> Alternatively, you can measure how far the drawtube moves from end to end (be careful not to force the drawtube) with
1372     a set of calipers or a ruler. By subtracting the furthest "in" position (in ticks) from the furthest "out" position (in ticks) you
1373     have how many ticks moved the drawtube the distance you measured. From this you can calculate the distance in microns a single
1374     tick moves the drawtube.</para>
1375     <para> Other types of telescope will have other ways to adjust the focal plane, for example, by moving the primary or
1376     secondary mirrors. You will need to either get the Step Size from the documentation for your equipment or work out how to
1377     measure it in a way that are consistent with that described above.</para>
1378   </listitem>
1379 
1380   <listitem>
1381     <para> <guilabel>CFZ Camera</guilabel>: The pixel size of the camera attached via the Optical Train may have a limiting
1382     effect on the CFZ. So an equivalent CFZ for the attached camera is calculated assuming a Nyquist 2* limit.</para>
1383   </listitem>
1384 
1385   <listitem>
1386     <para> <guilabel>Final CFZ</guilabel>: This is the larger of the CFZ calculated using the selected algorithm for the specified
1387     parameter and the <guilabel>CFZ Camera</guilabel>. It is the display value and is, in effect, the CFZ of your equipment.</para>
1388   </listitem>
1389 
1390   </itemizedlist>
1391   </sect2>
1392 
1393 
1394   <sect2 id="focus-advisor">
1395     <title>Focus Advisor</title>
1396 
1397     <screenshot>
1398       <screeninfo> Focus Advisor </screeninfo>
1399 
1400       <mediaobject>
1401         <imageobject>
1402           <imagedata fileref="focus_advisor.png" format="PNG" width="33%"/>
1403         </imageobject>
1404 
1405         <textobject>
1406           <phrase>Focus Advisor</phrase>
1407         </textobject>
1408       </mediaobject>
1409     </screenshot>
1410 
1411     <para> This is the Focus Advisor dialog. It is a feature to assist with management of focus parameters.</para>
1412 
1413     <para> The purpose of Focus Advisor is to help people struggling to use the Focus module within Ekos. The Focus module is
1414     functionally rich and contains a lot of parameters that need to be set self-consistently to achieve good results. Focus
1415     Advisor is designed to help with basic parameter setup that should achieve focus. It is not designed to achieve the best possible
1416     focus for your equipment; you will have to experiment with your setup to achieve that. But Focus Advisor provides a place to
1417     start that experimentation.</para>
1418 
1419     <para> So Focus Advisor is aimed towards the less experienced users.</para>
1420     <para> If Focus Advisor does not appear to give good results on your setup why not start a discussion on the forum so it can
1421     be enhanced to give better results in the future. This way it will build over time to be more useful.</para>
1422     <para> When you click on Focus Advisor it works out a series of parameter recommendations based on the Optical
1423     Train you are using in Focus.</para>
1424     <para> At the top of the dialog it displays information about the connected Optical Train. Then it displays 6 lines relating
1425     to various sets of parameters used within Focus. Against each line is a checkbox to update the associated Focus fields
1426     with Focus Advisor's recommendations.</para>
1427     <para> Focus parameters are broken into the following groupings:</para>
1428 
1429     <itemizedlist>
1430     <listitem>
1431     <para> <guilabel>Step Size</guilabel>: This is the suggested focus step size to use. This is a critical parameter. It is
1432     defaulted from the Critical Focus Zone (CFZ) dialog. So the first thing to do is set this dialog up and get a reasonable value
1433     for the CFZ. Alternatively, if you know a reasonable value for your equipment from other sources you can just enter that.</para>
1434     </listitem>
1435 
1436     <listitem>
1437     <para> <guilabel>Out Step Multiple</guilabel>: This is the suggested outward step multiple to use.</para>
1438     </listitem>
1439 
1440     <listitem>
1441     <para> <guilabel>Camera &amp; Filter Wheel Parameters</guilabel>: This sets the parameters in the
1442     <link linkend="focus-ccd-filter-wheel">CCD &amp; Filter Wheel</link> section of the Focus screen. By hovering the mouse over this
1443     label you can see in the tooltip what values Focus Advisor is recommending.</para>
1444     </listitem>
1445 
1446     <listitem>
1447     <para> <guilabel>Settings Parameters</guilabel>: This sets the parameters in
1448     <link linkend="focus-settings">Focus Settings</link>. By hovering the mouse over this
1449     label you can see in the tooltip what values Focus Advisor is recommending.</para>
1450     </listitem>
1451 
1452     <listitem>
1453     <para> <guilabel>Process Parameters</guilabel>: This sets the parameters in
1454     <link linkend="focus-process">Focus Process</link>. By hovering the mouse over this
1455     label you can see in the tooltip what values Focus Advisor is recommending.</para>
1456     </listitem>
1457 
1458     <listitem>
1459     <para> <guilabel>Mechanics Parameters</guilabel>: This sets the parameters in
1460     <link linkend="focus-mechanics">Focus Mechanics</link>. By hovering the mouse over this
1461     label you can see in the tooltip what values Focus Advisor is recommending.</para>
1462     </listitem>
1463 
1464     <listitem>
1465     <para> <guilabel>Help</guilabel>: Press this button to get help on using Focus Advisor.</para>
1466     </listitem>
1467 
1468     <listitem>
1469     <para> <guilabel>Update Params</guilabel>: Press this button to accept the Focus Advisor recommendations and update
1470     the Focus parameters where the associated <guilabel>Update</guilabel> checkbox is checked..</para>
1471     </listitem>
1472 
1473   </itemizedlist>
1474   </sect2>
1475 
1476   <sect2 id="focus-filter-settings">
1477       <title>Filter Settings</title>
1478 
1479       <screenshot>
1480           <screeninfo>
1481               Filter Queue
1482           </screeninfo>
1483           <mediaobject>
1484               <imageobject>
1485                   <imagedata fileref="filter_settings.png" format="PNG" width="50%"/>
1486               </imageobject>
1487               <textobject>
1488                   <phrase>Filter Queue</phrase>
1489               </textobject>
1490           </mediaobject>
1491       </screenshot>
1492 
1493       <para> Click the filter icon <inlinemediaobject><imageobject><imagedata fileref="view-filter.png" format="PNG"/></imageobject>
1494           </inlinemediaobject> from either Capture or Focus to open the filter settings dialog. This popup allows the user to
1495           configure data associated with each filter, and used for various functions within the system.</para>
1496 
1497       <para> Focusing with different filters can be done in one of three ways within Ekos.</para>
1498 
1499       <itemizedlist>
1500         <listitem>
1501           <para> <emphasis role="bold">Direct Autofocus</emphasis>: When Capture changes to this filter it is possible to automatically
1502           refocus this filter. The exposure to use for the selected filter is taken from the <guilabel>Exposure</guilabel> field. This
1503           allows, for example, narrowband filters to use a longer exposure than broadband filters during Autofocus.</para>
1504 
1505           <para> Check <guilabel>Auto Focus</guilabel> to use the filter in this way.</para>
1506         </listitem>
1507 
1508         <listitem>
1509           <para> <emphasis role="bold">Autofocus on Lock Filter</emphasis>: It is possible to specify a Lock filter to use when it is
1510           required to focus this filter. For example, if the Ha filter is used and an Autofocus run required, it is possible to run
1511           Autofocus using the Lum filter and then, when complete, adjust the focus position by an Offset value corresponding to the
1512           predetermined focus difference between the Lum and Ha filters (100 ticks in this example). This is useful when, for example,
1513           it is difficult to focus some filters directly without excessively long exposure times. Note that this locked filter approach
1514           may also be used in the <link linkend="ekos-align">Alignment Module</link> whenever it performs a capture for astrometry.</para>
1515 
1516           <para> To use a filter in this way, check <guilabel>Auto Focus</guilabel>, specify the <guilabel>Lock Filter</guilabel> to use
1517           and make sure that the Offsets for this filter and the <guilabel>Lock Filter</guilabel> are set.</para>
1518         </listitem>
1519 
1520         <listitem>
1521           <para> <emphasis role="bold">Use Offsets</emphasis>: It is possible to use filter offsets to adjust focus when swapping
1522           between filters, without running Autofocus. This requires some setup work ahead of time but has the advantage of
1523           reducing the number of Autofocus runs and therefore reducing the time spent autofocusing.</para>
1524 
1525           <para> In order to use this feature it is necessary to work out the relative focus position between all filters that you
1526           wish to use this functionality for. For example, if Lum and Red have the same focus position (they are parfocal) but Green
1527           focuses 300 ticks further out than Lum (or Red) then setup Offsets for Lum, Red and Green as 0, 0, 300 as shown above. If a
1528           sequence is created to take 10 subframes of Lum, then 10 Red, then 10 Green, then at the start, since Lum has
1529           <guilabel>Auto Focus</guilabel> checked, an Autofocus will be run on Lum and the 10 subs taken. Capture will then switch
1530           filters to Red. Since Red has <guilabel>Auto Focus</guilabel> unchecked no Autofocus will happen and Ekos will look to the
1531           Offsets between Red and Lum. In this case 0 - 0 = 0. So the focuser will not be moved and Capture will take 10 subs of Red.
1532           Then Capture will swap from Red to Green. Again, Green has <guilabel>Auto Focus</guilabel> unchecked no Autofocus will happen
1533           and Ekos will look to the Offsets between Green and Red. In this case 300 - 0 = 300. So Focus will adjust the focus position
1534           by +300 (move the focuser out by 300 ticks). Capture will then take the 10 Green subs.</para>
1535 
1536           <para> To use a filter in this way, uncheck <guilabel>Auto Focus</guilabel> and make sure that the Offsets for this filter
1537           and all other filters that can precede this filter in a sequence are set.</para>
1538 
1539           <para> The Offsets can either be worked out by running Autofocus with different filters and manually calculating the relative
1540           offsets and entering them into the table or by using the <link linkend="build-filter-offsets">Build Offsets</link> tool.</para>
1541         </listitem>
1542       </itemizedlist>
1543 
1544       <para>
1545           Configure settings for each filter in the table:
1546       </para>
1547       <orderedlist>
1548           <listitem>
1549               <para><guilabel>Filter</guilabel>: Filter Name.</para>
1550           </listitem>
1551           <listitem>
1552               <para><guilabel>Exposure</guilabel>: Set exposure time (in seconds) to be used when performing Autofocus on this filter.
1553               By default, it is set to 1 second.</para>
1554           </listitem>
1555           <listitem>
1556               <para><guilabel>Offset</guilabel>: Set relative offsets. Ekos will command a focus offset change if there is a
1557               difference between the current and target filter offsets. For example, given the values in the example image, if the
1558               current filter is set to <emphasis>Red</emphasis> and next filter is <emphasis>Green</emphasis>, then Ekos shall
1559               command the focuser to Focus In by +300 ticks. Relative positive focus offsets denote Focus Out while negative
1560               values denote Focus In.</para>
1561           </listitem>
1562           <listitem>
1563               <para><guilabel>Auto Focus</guilabel>: Check this option to perform AutoFocus whenever the filter is changed
1564               to this filter.</para>
1565           </listitem>
1566           <listitem>
1567               <para><guilabel>Lock Filter</guilabel>: Set which filter should be set and <emphasis>locked</emphasis> when
1568               performing autofocus for this filter. "--" indicates no Lock Filter. It is not allowed to next filters more than
1569               1 deep, i.e. Red cannot be locked to Blue which is itself locked to Green. A filter cannot be locked to itself.</para>
1570           </listitem>
1571           <listitem>
1572               <para><guilabel>Last AF Solution</guilabel>: The last successful Autofocus position. Under normal operation Ekos will
1573               automatically update this field.</para>
1574           </listitem>
1575           <listitem>
1576               <para><guilabel>Last AF Temp (°C)</guilabel>: The temperature of the <guilabel>Last AF Solution</guilabel>. Under
1577               normal operation Ekos will automatically update this field.</para>
1578           </listitem>
1579           <listitem>
1580               <para><guilabel>Last AF Alt (°Alt)</guilabel>: The altitude of the <guilabel>Last AF Solution</guilabel>. Under
1581               normal operation Ekos will automatically update this field.</para>
1582           </listitem>
1583           <listitem>
1584               <para><guilabel>Ticks / °C</guilabel>: The number of ticks to move the focuser when the temperature changes by 1°C.
1585               For example, if focus moves out by 5 ticks when temperature increases by 1°C, set this field to 5. If focus moves
1586               in by 5 ticks when temperature increases by 1°C, set this field to -5.</para>
1587           </listitem>
1588           <listitem>
1589               <para><guilabel>Ticks / °Alt</guilabel>: The number of ticks to move the focuser when the altitude changes by 1°Alt.
1590               For example, if focus moves out by 0.5 tick when altitude increases by 1°Alt, set this field to 0.5. If focus moves in
1591               by 0.5 tick when altitude increases by 1°Alt, set this field to -0.5.</para>
1592           </listitem>
1593           <listitem>
1594               <para><guilabel>Wavelength</guilabel>: The center of the passband of the filter in nanometers. This is used in
1595               some Critical Focus Zone (CFZ) calculations in Focus.</para>
1596           </listitem>
1597       </orderedlist>
1598 
1599       <para>In addition to the data table, the following controls are available at the bottom of the popup:</para>
1600       <itemizedlist>
1601           <listitem>
1602           <para><guilabel>Build Offsets</guilabel>: Press the <guibutton>Build Offsets</guibutton> button to launch the
1603           <link linkend="build-filter-offsets">Build Offsets</link> popup.</para>
1604           </listitem>
1605           <listitem>
1606           <para><guilabel>Capture flats at the same focus as lights</guilabel>: When checked, flats will be taken at the
1607           <guilabel>Last AF Solution</guilabel> focuser position.</para>
1608           </listitem>
1609       </itemizedlist>
1610 
1611       <para>Let's take an example. If we have a capture sequence starting with Lum -> Red -> Green -> Blue -> Sii -> Ha -> Oiii
1612       using the setup in the Filter Settings popup:</para>
1613       <itemizedlist>
1614           <listitem>
1615               <para>Lum: The Lum filter is configured to Autofocus initially so an Autofocus run is performed, then the Lum sequence
1616               runs.</para>
1617           </listitem>
1618           <listitem>
1619               <para>Red: The Red filter is not configured for Autofocus and has an Offset of 0. So when the Red sequence starts,
1620               there is no Autofocus run and the relative Offset between Lum and Red is 0, so the focuser is not moved.</para>
1621           </listitem>
1622           <listitem>
1623               <para>Green: The Green filter is not configured for Autofocus and has an Offset of 300. So when the Green sequence
1624               starts, there is no Autofocus run and the relative Offset between Red and Green is 300 - 0 = +300, so the focuser moves
1625               out by 300.</para>
1626           </listitem>
1627           <listitem>
1628               <para>Blue: The Blue filter is not configured for Autofocus and has an Offset of 0. So when the Blue sequence starts,
1629               there is no Autofocus run and the relative Offset between Green and Blue is 0 - 300 = -300, so the focuser moves in
1630               by 300.</para>
1631           </listitem>
1632           <listitem>
1633               <para>Sii: The Sii filter is configured for Autofocus, is locked to Lum and has an Offset of 0. So when the Sii sequence
1634               starts, there is an Autofocus run on Lum and the relative Offset between Lum and Sii is 0 - 0 = 0, so the focuser moves
1635               to the Lum Autofocus run solution.</para>
1636           </listitem>
1637           <listitem>
1638               <para>Ha: The Ha filter is configured for Autofocus, is locked to Lum and has an Offset of 100. So when the Ha sequence
1639               starts, there is an Autofocus run on Lum and the relative Offset between Lum and Ha is 100 - 0 = +100, so the focuser
1640               moves to the Lum Autofocus run solution then out by 100.</para>
1641           </listitem>
1642           <listitem>
1643               <para>Oiii: The Oiii filter is configured for Autofocus, is locked to Lum and has an Offset of -100. So when the Oiii
1644               sequence starts, there is an Autofocus run on Lum and the relative Offset between Lum and Oiii is -100 - 0 = -100, so
1645               the focuser moves to the Lum Autofocus run solution then in by 100.</para>
1646           </listitem>
1647       </itemizedlist>
1648   </sect2>
1649 
1650 
1651   <sect2 id="build-filter-offsets">
1652       <title>Build Offsets</title>
1653 
1654       <screenshot>
1655           <screeninfo>
1656               Build Filter Offsets
1657           </screeninfo>
1658           <mediaobject>
1659               <imageobject>
1660                   <imagedata fileref="build_filter_offsets.png" format="PNG" width="33%"/>
1661               </imageobject>
1662               <textobject>
1663                   <phrase>Build Filter Offsets</phrase>
1664               </textobject>
1665           </mediaobject>
1666       </screenshot>
1667 
1668       <para>
1669           Click the <guilabel>Build Offsets</guilabel> button on the <link linkend="focus-filter-settings">Filter Settings</link>
1670           popup to launch the Build Offsets tool. Filter Offsets can either be entered manually into the table
1671           in the Filter Settings popup or this tool can be used to assist in creating them.
1672       </para>
1673       <para>
1674           <emphasis>Note: This utility should not be run during an imaging session as it takes exclusive control of the
1675           Focus process whilst it is running.</emphasis>
1676       </para>
1677       <para>
1678           To start with, configure settings for each filter in the table in the Filter Settings popup and then launch
1679           Build Filter Offsets. The popup is launched with a table of data with the following columns.
1680       </para>
1681       <itemizedlist>
1682           <listitem>
1683               <para>
1684                   <guilabel>Filter</guilabel>: Filter Name. The first filter has an "*" after the filter name, "Lum *" in the above example.
1685                   This means that Lum is the reference filter against which offsets for other filters will be measured. Double click another
1686                   Filter Name to make that filter the reference filter.
1687               </para>
1688           </listitem>
1689           <listitem>
1690               <para>
1691                   <guilabel>Offset</guilabel>: The current offset.
1692               </para>
1693           </listitem>
1694           <listitem>
1695               <para>
1696                   <guilabel>Lock Filter</guilabel>: The current Lock filter.
1697               </para>
1698           </listitem>
1699           <listitem>
1700               <para>
1701                   <guilabel># Focus Runs</guilabel>: The number of focus runs for this filter. The default is 5.
1702                   To exclude a filter from the process set this field to zero. Note, the reference filter must have at least 1 run.
1703               </para>
1704           </listitem>
1705       </itemizedlist>
1706       <para>
1707           When the <guilabel># Focus Runs</guilabel> have been configured press the <guilabel>Run</guilabel>
1708           button to start the automated process.
1709       </para>
1710       <para>
1711           Press the <guilabel>Stop</guilabel> button to stop the process at any time.
1712       </para>
1713       <para>
1714           Toggle the <guilabel>Adapt Focus</guilabel> checkbox at any point in the processing to switch between measured Autofocus results
1715           and results after Adaptive Focus adjustments have been applied. See the <link linkend="focus-adaptive">Adaptive Focus</link> section
1716           for more details on what Adaptive Focus is.
1717       </para>
1718       <para>
1719           Let's take an example where we have 7 filters: Lum, Red, Green, Blue, Sii, Ha and Oiii. The 8th slot in the filter wheel is marked
1720           as Blank. The process has completed 5 runs for all filters, 0 for Blank (effectively excluding Blank from the process). In this
1721           case 8 extra columns have been created in the table.
1722       </para>
1723       <screenshot>
1724           <screeninfo>
1725               Build Filter Offsets
1726           </screeninfo>
1727           <mediaobject>
1728               <imageobject>
1729                   <imagedata fileref="build_filter_offsets2.png" format="PNG" width="50%"/>
1730               </imageobject>
1731               <textobject>
1732                   <phrase>Build Filter Offsets</phrase>
1733               </textobject>
1734           </mediaobject>
1735       </screenshot>
1736       <itemizedlist>
1737           <listitem>
1738               <para>
1739                   AF Run 1-5: The maximum <guilabel># Focus Runs</guilabel> selected by the user is 5, so 5 columns
1740                   have been created, 1 for each AF run solution.
1741               </para>
1742           </listitem>
1743           <listitem>
1744               <para>
1745                   Average: The average (mean) of the AF solutions.
1746               </para>
1747           </listitem>
1748           <listitem>
1749               <para>
1750                    New Offset: The offset calculated from the Lum filter. E.g. for Sii 36731 - 36743 = -12
1751               </para>
1752           </listitem>
1753           <listitem>
1754               <para>
1755                   Save: Check to save the offset for this filter when the <guilabel>Save</guilabel> button is pressed.
1756                   The default is to check these boxes but unchecking allows a value to be ignored whilst saving
1757                   other filters.
1758               </para>
1759           </listitem>
1760       </itemizedlist>
1761       <para>
1762           At this stage, it is recommended to review the AF runs to make sure they are all good. For example, lets
1763           assume we are unhappy with the 2nd AF run on Oiii. In this case we could either:</para>
1764           <itemizedlist>
1765             <listitem>
1766               <para> Edit AF Run 2 and set the value to whatever value we want.</para>
1767             </listitem>
1768             <listitem>
1769               <para> Edit the New Offset column and set the value directly (bypassing the logic to calculate it).</para>
1770             </listitem>
1771             <listitem>
1772               <para> Discard the AF Run 2 by setting the value to 0 (see below). In this case, the Average and New Offset
1773               for Oiii is recalculated based on AF Runs 1, 3, 4, 5. In the example below the new Average and New Offsets are
1774               calculated and displayed.</para>
1775             </listitem>
1776           </itemizedlist>
1777       <screenshot>
1778           <screeninfo>
1779               Build Filter Offsets
1780           </screeninfo>
1781           <mediaobject>
1782               <imageobject>
1783                   <imagedata fileref="build_filter_offsets3.png" format="PNG" width="50%"/>
1784               </imageobject>
1785               <textobject>
1786                   <phrase>Build Filter Offsets</phrase>
1787               </textobject>
1788           </mediaobject>
1789       </screenshot>
1790       <para>
1791           After reviewing the results, the user can press:
1792       </para>
1793       <itemizedlist>
1794           <listitem>
1795               <para>
1796                   Save: All filters where the <guilabel>Save</guilabel> checkbox is checked will have the New Offset
1797                   value saved in Filter Offsets for use during the next imaging session.
1798               </para>
1799           </listitem>
1800           <listitem>
1801               <para>
1802                   Close: The Build Filter Offsets tool is closed without saving any data.
1803               </para>
1804           </listitem>
1805       </itemizedlist>
1806       <para>
1807           If the <guilabel>Adapt Focus</guilabel> box is checked, the AF Runs are updated for Adaptive Focus. See the
1808           <link linkend="focus-adaptive">Adaptive Focus</link> section for more details on the theory of Adaptive Focus. The first AF run
1809           (in this example AF Run 1 on Lum) is the basis for the Adaptations. So the temperature and altitude of AF Run 1 on Lum is used as
1810           the basis for all the other AF Runs and the data is adapted back to what the AF solution would have been, had it been run at the
1811           temperature and altitude of AF Run 1 on Lum.
1812       </para>
1813       <para>
1814           In this example, Adaptive Focus is setup for Altitude adjustments on the Red filter only in Filter Settings. So the
1815           Adapted AF Run values are the same as the unadapted values for all the other filters.
1816       </para>
1817 
1818       <screenshot>
1819         <screeninfo>
1820             Build Filter Offsets
1821         </screeninfo>
1822         <mediaobject>
1823             <imageobject>
1824                 <imagedata fileref="build_filter_offsets4.png" format="PNG" width="50%"/>
1825             </imageobject>
1826             <textobject>
1827                 <phrase>Build Filter Offsets</phrase>
1828             </textobject>
1829         </mediaobject>
1830       </screenshot>
1831       <para>
1832           If you hover the mouse over an AF Run it will show a tooltip Adaptive Focus Explainer. In the example, the mouse is hovering over
1833           AF Run 1 on Red. The 1st row of the Explainer shows the measured Autofocus result for that run (36683), adaptations for Temperature (0.0C) and Altitude (0.2 degrees Alt).
1834           The 2nd row of the Explainer shows the Adaptations: 206 total, 0 temperature, 205.9 altitude. The 3rd row shows the Adapted Position
1835           of 36889.
1836       </para>
1837       <para>
1838           The user can toggle between Adapt Focus or raw values. Whichever values are displayed in the grid will be the values that are saved.
1839       </para>
1840       <para>
1841           Here are some tips for using this utility:
1842           <itemizedlist>
1843             <listitem><para> Start by making sure the area of the sky you are running Build Filter Offsets on works well for Autofocus. Aiming
1844             high in the sky will result in shooting through less atmosphere with smaller, tighter stars. Make sure there are enough stars in the
1845             frame. Avoid Meridian Flips during the process. Track the same area during the process so each run is using more or less the
1846             same set of stars. Although the facility to use Adapt Focus is available to adjust for environmental changes such as temperature
1847             and altitude try to minimise these changes over the course of running the utility by selecting an appropriate area
1848             of the sky.</para></listitem>
1849 
1850             <listitem><para> Make sure your equipment is in thermal equilibrium before starting. Calculate roughly how long the utility will
1851             take which is the total number of AF runs * time for a single AF run. Try to make sure that the conditions will remain as
1852             consistent as possible during this time, e.g. there is enough time before dawn, the moon won't affect focusing of some images
1853             more than others, the target won't drop below your horizon during the process, etc.</para></listitem>
1854 
1855             <listitem><para> Configure the utility for # Focus Runs (5 is a good start), reference filter (e.g. Lum) and Adapt Focus
1856             setting. Run the utility to completion.</para></listitem>
1857 
1858             <listitem><para> Review the results. For each filter review each AF run looking for outliers. For each outlier decide what to
1859             do, e.g. remove from processing by setting to 0. If there are filters for which you are unhappy with the results, uncheck the
1860             Save checkbox for those filters.</para></listitem>
1861 
1862             <listitem><para> When happy, press Save to save the filter offsets to Filter Settings for future use.</para></listitem>
1863             </itemizedlist>
1864       </para>
1865 </sect2>
1866 
1867   <sect2 id="focus-display">
1868     <title>Focus Display</title>
1869 
1870     <screenshot>
1871       <screeninfo> Focus Display </screeninfo>
1872 
1873       <mediaobject>
1874         <imageobject>
1875           <imagedata fileref="focus_display.png" format="PNG" width="50%"/>
1876         </imageobject>
1877 
1878         <textobject>
1879           <phrase>Focus Display</phrase>
1880         </textobject>
1881       </mediaobject>
1882     </screenshot>
1883 
1884     <para> The focus display, displays a FITS viewer window onto the frame
1885     taken during the focus process. If <guilabel>Ring Mask</guilabel> is selected, then the mask
1886     is drawn on the image. All the stars detected by Ekos based on the selected parameters, have their
1887     HFR value displayed next to the associated star (unless Measure is set to FWHM). </para>
1888 
1889     <para> If <guilabel>Mosaic Mask</guilabel> has been selected then the FITS viewer displays the
1890     mosaic 3x3 grid showing the center, edges and sides as configured in the Mosaic Mask options.
1891     <screenshot><screeninfo> Focus Display Mosaic</screeninfo><mediaobject>
1892     <imageobject><imagedata fileref="focus_display_mosaic.png" format="PNG" width="50%"/></imageobject>
1893     <textobject><phrase>Focus Display Mosaic</phrase></textobject></mediaobject></screenshot></para>
1894 
1895     <para> The window supports the following FITS viewer options (at the top
1896     of the window):</para>
1897 
1898     <itemizedlist>
1899       <listitem>
1900         <para> <guibutton>Zoom In</guibutton> and <guibutton>Zoom
1901         Out</guibutton>.</para>
1902       </listitem>
1903 
1904       <listitem>
1905         <para> <guibutton>Default Zoom</guibutton> and <guibutton>Zoom to
1906         Fit</guibutton>.</para>
1907       </listitem>
1908 
1909       <listitem>
1910         <para> <guibutton>Toggle Stretch</guibutton>: Toggle screen stretch on
1911         or off.</para>
1912       </listitem>
1913 
1914       <listitem>
1915         <para> <guibutton>Toggle Crosshairs</guibutton>: Toggle crosshairs on
1916         or off.</para>
1917       </listitem>
1918 
1919       <listitem>
1920         <para> <guibutton>Toggle Gridlines</guibutton>: Toggle pixel gridlines
1921         on or off.</para>
1922       </listitem>
1923 
1924       <listitem>
1925         <para> <guibutton>Toggle Stars</guibutton>: Toggle star detection on
1926         or off.</para>
1927       </listitem>
1928 
1929       <listitem>
1930         <para> <guibutton>View Star Profile</guibutton>: Launches the View Star Profile dialog.</para>
1931       </listitem>
1932     </itemizedlist>
1933   </sect2>
1934 
1935   <sect2 id="focus-v-curve">
1936     <title>V-Curve</title>
1937 
1938     <screenshot>
1939       <screeninfo> Focus V-Curve </screeninfo>
1940 
1941       <mediaobject>
1942         <imageobject>
1943           <imagedata fileref="focus_vcurve.png" format="PNG" width="50%"/>
1944         </imageobject>
1945 
1946         <textobject>
1947           <phrase>Focus V-Curve</phrase>
1948         </textobject>
1949       </mediaobject>
1950     </screenshot>
1951 
1952     <para> The V-Curve displays focuser position (x-axis) versus focus Measure, e.g. Half-Flux-Radius (HFR) (y-axis).
1953     Each datapoint is drawn on the graph and represented by a circle with a number representing the datapoint. How many
1954     datapoints are taken and how the focuser moves is determined by the parameters chosen. </para>
1955 
1956     <para> For certain algorithms, Ekos will also draw a curve of best fit through the datapoints. If <guilabel>Use Weights</guilabel>
1957     is selected then error bars are indicated on each datapoint that correspond to the standard deviation in measured value.</para>
1958 
1959     <para> The units of the y-axis depend on the selected focus Measure. For example, for HFR, the y-axis will either be in Pixels
1960     or Arc seconds depending on how <guilabel>Display Units</guilabel> is set.</para>
1961 
1962     <para> If <guilabel>Refine Curve Fit</guilabel> is selected, Focus will check for and potentially exclude outlying datapoints.
1963     In this case datapoints 1, 5 and 7 were excluded.</para>
1964 
1965     <para> Under the V-Curve a number of parameters are displayed:</para>
1966 
1967     <itemizedlist>
1968       <listitem>
1969         <para> <guilabel>HFR</guilabel>: Displays the star HFR for the most recent datapoint if relevant.</para>
1970       </listitem>
1971 
1972       <listitem>
1973         <para> <guilabel>FWHM</guilabel>: Displays the star FWHM for the most recent datapoint if relevant.</para>
1974       </listitem>
1975 
1976       <listitem>
1977         <para> <guilabel>Stars</guilabel>: The number of stars used for the most recent datapoint.</para>
1978       </listitem>
1979 
1980       <listitem>
1981         <para> <guilabel>Iteration</guilabel>: The number of datapoints taken so far.</para>
1982       </listitem>
1983 
1984       <listitem>
1985         <para> <guibutton>Relative Profile...</guibutton>: Invokes the <link linkend="focus-relative-profile">Relative Profile</link>
1986         popup.</para>
1987       </listitem>
1988 
1989       <listitem>
1990         <para> <guibutton>Clear Data</guibutton>: Resets the V-Curve graph by clearing the displayed data.</para>
1991       </listitem>
1992     </itemizedlist>
1993 
1994     <para> Here is a V-Curve when Measure is set to HFR Adj:
1995     <screenshot><screeninfo> V-Curve HFR Adj</screeninfo><mediaobject><imageobject>
1996           <imagedata fileref="focus_vcurve_hfradj.png" format="PNG" width="50%"/></imageobject><textobject>
1997           <phrase>Focus V-Curve HFR Adj</phrase></textobject></mediaobject></screenshot></para>
1998 
1999     <para> Here is a V-Curve when Measure is set to FWHM:
2000     <screenshot><screeninfo> V-Curve FWHM</screeninfo><mediaobject><imageobject>
2001       <imagedata fileref="focus_vcurve_fwhm.png" format="PNG" width="50%"/></imageobject><textobject>
2002       <phrase>Focus V-Curve FWHM</phrase></textobject></mediaobject></screenshot></para>
2003 
2004     <para> Here is a V-Curve when Measure is set to # Stars. In this case the Critical Focus Zone (CFZ)
2005     <guilabel>Display</guilabel> checkbox has been checked so the CFZ is displayed as well:
2006     <screenshot><screeninfo> V-Curve Num Stars</screeninfo><mediaobject><imageobject>
2007       <imagedata fileref="focus_vcurve_numstars.png" format="PNG" width="50%"/></imageobject><textobject>
2008       <phrase>Focus V-Curve Num Stars</phrase></textobject></mediaobject></screenshot></para>
2009 
2010     <para> Here is a V-Curve when Measure is set to Fourier:
2011     <screenshot><screeninfo> V-Curve Fourier</screeninfo><mediaobject><imageobject>
2012       <imagedata fileref="focus_vcurve_fourier.png" format="PNG" width="50%"/></imageobject><textobject>
2013       <phrase>Focus V-Curve Fourier</phrase></textobject></mediaobject></screenshot></para>
2014 
2015     <para> When Framing, the graph format changes to that of a "time series" where horizontal axis denotes the frame number.
2016     This is to aid you in the framing process as you can see how Measure, in this case HFR, changes between frames. </para>
2017 
2018     <para> This is very useful, for example, when trying to get the system into approximate focus before starting an Autofocus run.
2019     In this case Framing is started and the Step In and Step Out buttons used to adjust focus and the effect on the V-Curve
2020     observed.</para>
2021 
2022     <screenshot>
2023       <screeninfo> V-Curve as timeseries</screeninfo>
2024 
2025       <mediaobject>
2026         <imageobject>
2027           <imagedata fileref="focus_vcurve_timeseries.png" format="PNG"
2028                      width="50%"/>
2029         </imageobject>
2030 
2031         <textobject>
2032           <phrase>Focus V-Curve Timeseries</phrase>
2033         </textobject>
2034       </mediaobject>
2035     </screenshot>
2036   </sect2>
2037 
2038   <sect2 id="focus-relative-profile">
2039     <title>Relative Profile</title>
2040 
2041     <screenshot>
2042       <screeninfo> Focus Relative Profile </screeninfo>
2043 
2044       <mediaobject>
2045         <imageobject>
2046           <imagedata fileref="focus_relative_profile.png" format="PNG"
2047                      width="50%"/>
2048         </imageobject>
2049 
2050         <textobject>
2051           <phrase>Focus Relative Profile</phrase>
2052         </textobject>
2053       </mediaobject>
2054     </screenshot>
2055 
2056     <para> The relative profile is a graph that displays the relative HFR
2057     values plotted against each other. Lower HFR values correspond to narrower
2058     shapes and vice-versa. The solid red curve is the profile of the current
2059     HFR value, while the dotted green curve is for the previous HFR value.
2060     Finally, the magenta curve denotes the first measured HFR. This enables
2061     you to judge how well the Autofocus process improved the relative focus
2062     quality. </para>
2063   </sect2>
2064 
2065   <sect2 id="How_to_Setup_for_an_Auto_Focus_Run">
2066     <title>How to Setup for an Autofocus Run</title>
2067 
2068     <para> The exact settings that work best for a given astronomical setup need to be worked out by the user using trial and error.
2069     A good place to start is the <link linkend="focus-advisor">Focus Advisor</link> section. Run Focus Advisor and accept its
2070     recommendations. It uses the Linear 1 Pass algorithm:</para>
2071 
2072     <itemizedlist>
2073       <listitem>
2074         <para> Setup Backlash. See the <link linkend="focus-backlash">Backlash</link> section for more details.</para>
2075       </listitem>
2076 
2077       <listitem>
2078         <para> Initial Step Size. This is a critical parameter. You may have an idea from other people with a similar setup.
2079         If not you can try setting it from the Critical Focus Zone (CFZ) for your equipment. See the
2080         <link linkend="focus-cfz">CFZ section</link> for more details.</para>
2081         </listitem>
2082 
2083       <listitem>
2084         <para> Start near to focus by manually finding focus. Use the <guibutton>Start Framing</guibutton> option and manually adjust
2085         the focus to get to approximate focus.</para>
2086       </listitem>
2087 
2088       <listitem>
2089         <para> Make sure you are finding enough stars. Increasing the exposure usually finds more stars (but makes the focus process
2090         longer).</para>
2091       </listitem>
2092     </itemizedlist>
2093 
2094     <para> Run Autofocus. This is the sort of V-Curve you are after:</para>
2095     <screenshot><screeninfo> Good Focus Curve </screeninfo><mediaobject>
2096     <imageobject><imagedata fileref="focus_good_focus.png" format="PNG" width="50%"/></imageobject>
2097     <textobject><phrase>Good Focus Curve</phrase></textobject></mediaobject></screenshot>
2098 
2099     <para> In contrast, the next picture shows an Initial Step Size that has been set too low. The HFR varies from about 0.78 to 0.72.
2100       Which gives a max / min just over 1. The other clue that this is a poor setup is that the Error Bar range is very large compared
2101       to HFR movement which means that the curve solver is drawing a curve through a lot of noise, which means the results will not be
2102       very accurate.</para>
2103     <screenshot><screeninfo> Bad Focus Curve </screeninfo><mediaobject><imageobject>
2104     <imagedata fileref="focus_bad_focus.png" format="PNG" width="50%"/></imageobject>
2105     <textobject><phrase>Bad Focus Curve</phrase></textobject></mediaobject></screenshot>
2106   </sect2>
2107 
2108   <sect2 id="focus-backlash">
2109     <title>Focuser Backlash</title>
2110 
2111     <para>Backlash in the focuser setup is due to a combination of backlash in the electronic focuser itself (e.g. in the gearing
2112     mechanism), in the binding of the electronic focuser to the telescope drawtube, and in the telescope drawtube's mechanism. Thus,
2113     each setup will have its own backlash characteristic even if the same focuser is used.</para>
2114 
2115     <para> It is important to have a clear strategy for dealing with Backlash and to setup Focus appropriately for the chosen
2116     strategy. It is best to have backlash managed in one place to avoid conflicts. Whilst it is possible to have backlash
2117     managed in multiple places (this has been done successfully) it is not recommended in general because it can lead to conflicts
2118     between software components and the focuser.</para>
2119 
2120     <para> There are several ways to measure backlash in ticks. Consult the documentation on your focuser or use the internet
2121     including the Indi Forum.</para>
2122 
2123     <para> There are several things to consider when working out how to deal with backlash:
2124     <itemizedlist>
2125       <listitem>
2126         <para> <emphasis role="bold">No Backlash</emphasis>: If you are fortunate enough to have a setup with no backlash then it would
2127         make sense to set <guilabel>Driver Backlash</guilabel> and <guilabel>AF Overscan</guilabel> off (set to zero).</para>
2128       </listitem>
2129 
2130       <listitem>
2131         <para> <emphasis role="bold">Backlash Managed by Focuser</emphasis>: If your focuser had the ability to manage backlash itself
2132         then you can use this facility and turn <guilabel>Driver Backlash</guilabel> and <guilabel>AF Overscan</guilabel> off
2133         (set to zero). Alternatively, if it's possible, you could turn off the focuser's backlash facility and use either the
2134         Device Driver or AF Overscan to manage backlash.</para>
2135       </listitem>
2136 
2137       <listitem>
2138         <para> <emphasis role="bold">Backlash Managed by Device Driver</emphasis>: If your device driver has the ability to
2139         manage backlash then you can use this facility and turn off <guilabel>AF Overscan</guilabel> (set to zero). Alternatively,
2140         you could turn off the device driver's backlash facility and set <guilabel>AF Overscan</guilabel>.</para>
2141 
2142         <para> To know whether the device driver supports backlash, check the <guilabel>Driver Backlash</guilabel> field.
2143         If it is enabled and you can set values then the driver supports Backlash. If the field is disabled then the driver
2144         does not support Backlash.</para>
2145       </listitem>
2146 
2147       <listitem>
2148         <para> <emphasis role="bold">AF Overscan</emphasis>: The Focus module can manage Backlash itself by over scanning
2149         outward motions by the value in the <guilabel>AF Overscan</guilabel> field. For example, if <guilabel>AF Overscan</guilabel>
2150         is set to 40 then whenever Focus moves the focuser outwards, it does this as a 2-step process. Firstly it moves the
2151         focuser 40 ticks past where it wants to end up; secondly it moves back in by 40 ticks.</para>
2152 
2153         <para> The advantage of <guilabel>AF Overscan</guilabel> is that you do not need to know Backlash exactly, you just need
2154         to set the <guilabel>AF Overscan</guilabel> &gt;= backlash. So, for example, if you measure backlash as around 60 ticks
2155         then you could set <guilabel>AF Overscan</guilabel> to 80.</para>
2156 
2157         <para> <guilabel>AF Overscan</guilabel> is also useful where Backlash is not exactly predictable. For example, if Backlash
2158         measurements yield slightly different values, e.g. 61, 60, 59 ticks then by using <guilabel>AF Overscan</guilabel> this
2159         inconsistency can be effectively neutralised. Were you to use <guilabel>Focuser Backlash</guilabel> you would probably
2160         average the readings and set the value to 60. Sometimes this will correctly take up all the backlash; sometimes it will
2161         be a little short; and sometimes it will over correct.</para>
2162 
2163         <para> All focuser movements managed by Focus will have <guilabel>AF Overscan</guilabel> applied, including Step Out, Goto,
2164         Autofocus runs, Adaptive Focus movements, Adapt Start Pos movements and Take flats at the same position as lights.</para>
2165       </listitem>
2166     </itemizedlist>
2167     </para>
2168   </sect2>
2169 
2170   <sect2 id="focus-adaptive">
2171     <title>Adaptive Focus</title>
2172 
2173     <screenshot>
2174       <screeninfo> Adaptive Focus  </screeninfo>
2175 
2176       <mediaobject>
2177         <imageobject>
2178           <imagedata fileref="focus_adaptive_focus.png" format="PNG" width="50%"/>
2179         </imageobject>
2180 
2181         <textobject>
2182           <phrase>Adaptive Focus</phrase>
2183         </textobject>
2184       </mediaobject>
2185     </screenshot>
2186 
2187     <para> Ekos supports the concept of Adaptive Focus (AF). Without AF, a typical imaging plan would start
2188     with an Autofocus run then a sequence of subframes, then an Autofocus run, etc. The Autofocus runs would be triggered by
2189     a number of factors such as time, filter change, temperature change, etc. So basically as a sequence
2190     runs subframes are being taken slightly away from optimum focus until a threshold (e.g. temperature
2191     change) triggers an Autofocus run.</para>
2192 
2193     <para> The idea of AF is to adjust focus as environmental factors change to try to take each subframe
2194     as close as possible to optimum focus. Ideally, the effect of Adaptive Focus is like performing an Autofocus run before
2195     each subframe but without the overhead of actually doing the run.</para>
2196 
2197     <para> AF works as a complement to the various triggers for Autofocus that are available in Ekos now. So
2198     it is not necessary to change the Autofocus triggers when starting to use AF. Indeed, at the start, it is not recommended
2199     to relax Autofocus conditions when using AF. However, over time, as confidence grows in AF it would be possible to do less
2200     Autofocusing (and therefore more imaging). But either way, each subframe should be more in focus when using AF, providing
2201     it is setup correctly. </para>
2202 
2203     <para> So how do you know if AF would be useful for your setup or not? Perhaps the simplest way would be to
2204     examine subframes just after an Autofocus and compare them with subframes just before the next Autofocus. Can you
2205     see a difference in focus? If you have a setup where the focus point is tolerant of environmental changes between
2206     Autofocus runs then AF may not add anything to your images; if however you have a setup that is sensitive to
2207     environmental changes and the frequency of Autofocus runs is a compromise between quality and imaging time then
2208     AF ought to improve the quality of your subframes.</para>
2209 
2210     <para>AF currently supports two environmental dimensions: Temperature and Altitude (of the imaged target):</para>
2211     <itemizedlist>
2212       <listitem>
2213         <para> Temperature. All the components of the imaging system will be affected by changes in ambient temperature.
2214         The most obvious will be the telescope tube. Typically this will expand as temperature increases and contract as
2215         it decreases. This will affect the focus point. But also the optical path the light from the imaged target takes
2216         through the atmosphere and through the imaging components of the telescope will be affected by temperature and
2217         therefore will affect the focus point.</para>
2218 
2219         <para> It is necessary to have a reliable source of temperature information available to the focus module in order
2220         to use the temperature feature of AF.</para>
2221 
2222         <para> Where the temperature source is located is, of course, up to the user. Given the changes in temperature effect
2223         many components it is not obvious where the best location would be. Some experimentation may be required to get
2224         the best results but as a guide, the source should be near the imaging train but not near any heating effect of
2225         electrical equipment that would say, heat the temperature source but not the optical train. Consistency of location
2226         is likely to be important.</para>
2227       </listitem>
2228 
2229       <listitem>
2230         <para> Altitude. Some users have reported that the focus point changes with the altitude of the target. This effect
2231         is likely to be smaller than the temperature effect and may be negligible for some setups.</para>
2232       </listitem>
2233     </itemizedlist>
2234 
2235     <para> To use AF you need to work out firstly whether you want to adapt for Temperature, Altitude or both. If you are
2236     new to AF it is recommended to start with Temperature and once you have that working, determine whether your setup would
2237     benefit from adding Altitude.</para>
2238 
2239     <para> The first step is to workout the <guilabel>Ticks / °C</guilabel> and/or <guilabel>Ticks / °Alt</guilabel> for your
2240     equipment. To do this there is an existing utility in Ekos whereby when Focus logging is enabled, in addition to adding focus
2241     messages to the debug log, every time an Autofocus run completes, information is written to a text file in a directory called
2242     focuslogs located in the same place as the debug logs directory. The files are called “autofocus-(datetime).txt”. The data
2243     written are: date, time, position, temperature, filter, HFR, altitude. This data will need to be analysed outside of Ekos to
2244     determine the <guilabel>Ticks / °C</guilabel> and if required the <guilabel>Ticks / °Alt</guilabel>.</para>
2245 
2246     <para> Here is an example of a “autofocus-(datetime).txt” file:
2247     <screenshot>
2248       <screeninfo> Focus Autofocus Log </screeninfo>
2249       <mediaobject> <imageobject> <imagedata fileref="focus_autofocus_log.png" format="PNG" width="50%"/>
2250         </imageobject><textobject><phrase>Focus Autofocus Log</phrase></textobject></mediaobject>
2251     </screenshot></para>
2252 
2253     <para> Currently Ekos supports a simple linear relationship between temperature, or altitude, and ticks. In the future,
2254     if there is demand, more sophisticated relationships could be supported. A linear relationship will deliver the majority
2255     of the benefit of AF and is fairly straight-forward to administer. More complex relationships could be more accurate but
2256     come with more complex administration. Note also that more complex focus point vs temperature relationships will likely
2257     be more or less linear for small changes in temperature.</para>
2258 
2259     <para> A way to get a value for <guilabel>Ticks / °C</guilabel> would be to take the data from the
2260     autofocus-(datetime).txt files from a few nights of observing into a spreadsheet and graph focus position against temperature
2261     for each filter. Review the data and remove any outliers and plot a line of best fit. Use the line to get
2262     <guilabel>Ticks / °C</guilabel>. If you intend to adapt for altitude as well as temperature, then it would be better to use a
2263     set of data at similar altitude when calibrating temperature. Then it's possible to calculate the effect of Temperature and
2264     remove this from the data when calculating the effect of Altitude.</para>
2265 
2266     <para> You will need to ensure that your focus position is repeatable at the same temperature and altitude and that there
2267     is no slipping of the focuser or uncompensated backlash. In addition, when calibrating it is better to avoid changing the
2268     optical train in a way that could change the focus position. If this is unavoidable and if the change affected the focus
2269     position then you will need to appropriately adjust the historical focus data so they can be compared.</para>
2270 
2271     <para> A simple approach is to start with a small amount of data, say 1 night and use this to calculate, say the Ticks /
2272     degree C. Run with this and adjust it over time as you collect more data. A way to check how well AF is performing would be
2273     to use Analyze to review how AF had moved the focus over 1 hour. If things are spot on, then where ever AF had positioned
2274     the focuser after 1 hour would match the Autofocus result. Where there is a discrepancy, it will be because of randomness
2275     in the Autofocus result and miscalibration in the AF <guilabel>Ticks / °C</guilabel>. By doing this regularly you will build
2276     knowledge of your equipment and be able to fine tune AF. Below is a screenshot of Analyze configured for Focus where you can
2277     see how Focus position changes throughout the imaging session:
2278     <screenshot>
2279       <screeninfo> Focus Analyze </screeninfo>
2280       <mediaobject> <imageobject> <imagedata fileref="focus_analyze.png" format="PNG" width="50%"/>
2281         </imageobject><textobject><phrase>Focus Analyze</phrase></textobject></mediaobject>
2282     </screenshot></para>
2283 
2284     <para> Once you have your data you can configure it in the <link linkend="focus-filter-settings">Filter Settings</link>
2285     popup. Then in Focus, switch on Adaptive Focus in <link linkend="focus-settings">Focus Settings</link>. At this
2286     point, when you run a sequence, Ekos will check after each subframe whether it needs to adapt the focuser position. If so,
2287     Focus will do that and then Capture will continue with the next Subframe.</para>
2288 
2289     <para> The screenshot at the top of this section shows an example. <guilabel>Ticks / °C</guilabel> is set to 9.
2290     Autofocus ran and it solved at 36580 at 10C. Then a simple sequence of 5 subframes was run. The temperature was firstly set to 9C
2291     then to 8C. After each subframe completed, Ekos performed an adaptive focus run and where there was a temperature change it calculates
2292     the number of ticks to move the focuser. In this example, the focuser was moved inward by 9 ticks on 2 separate occasions,
2293     starting at 36580, before moving to 36571 and then to 36562 as shown on the Focus Tab in the Current Position widget and in
2294     the message box.</para>
2295 
2296     <para> The Adaptive Focus concept has been built into the <link linkend="build-filter-offsets">Build Offsets</link> tool.</para>
2297   </sect2>
2298 
2299 
2300   <sect2 id="Coefficient_of_Determination">
2301     <title>Coefficient of Determination, R²</title>
2302 
2303     <para> The Coefficient of Determination, or R², is calculated in order to
2304     give a measure of how well the fitted curve matches the datapoints. More
2305     information is available <ulink
2306     url="https://en.wikipedia.org/wiki/Coefficient_of_determination">here</ulink>.
2307     This feature that is available for the Linear 1 Pass
2308     focus algorithm. In essence, R² gives a value between 0 and 1, with 1
2309     meaning a perfect fit where all datapoints sit on the curve, and 0 meaning
2310     that there is no correlation between the datapoints and the curve. The
2311     user should experiment with their equipment to see what values they can
2312     obtain, but as a guide, a value above, say 0.9 would be a good fit.</para>
2313 
2314     <para> There is an option to set an “R² Limit” in
2315     <link linkend="focus-settings">Focus Settings</link> that is compared
2316     to the calculated R² after the auto focus run has completed. If the limit value
2317     has not been achieved, then the auto focus is rerun.</para>
2318 
2319     <para> Setting an R² Limit could be useful for unattended observation if
2320     the focus run produces a bad result for a 1-off reason. Obviously if the
2321     reason is not transitory then rerunning will not improve anything.</para>
2322 
2323     <para> If the R² Limit is not achieved and the focus process is rerun, and
2324     again fails to achieve the R² Limit, then the focus run is marked as
2325     successful to avoid the process getting stuck rerunning auto focus
2326     forever.</para>
2327 
2328     <para> This feature is turned off by setting the R² Limit to 0.</para>
2329   </sect2>
2330 
2331   <sect2 id="Levenberg-Marquardt">
2332     <title>Levenberg–Marquardt Solver</title>
2333 
2334     <para> The Levenberg-Marquardt (LM) algorithm is used to solve non-linear
2335     least squares problems. The GNU Science Library provides an implementation
2336     of the solver. These resources provide more details: </para>
2337 
2338     <itemizedlist>
2339       <listitem>
2340         <para>
2341           <ulink url="https://en.wikipedia.org/wiki/Levenberg–Marquardt_algorithm"/>
2342         </para>
2343       </listitem>
2344 
2345       <listitem>
2346         <para>
2347           <ulink url="https://www.gnu.org/software/gsl/doc/html/nls.html"/>
2348         </para>
2349       </listitem>
2350     </itemizedlist>
2351 
2352     <para> The Levenberg-Marquardt algorithm is a non-linear least-squares solver and
2353     thus suitable for many different equations. The basic idea is to adjust
2354     the equation y = f(x,P) so that the computed y values are as close as
2355     possible to the y values of the datapoints provided, so that the resultant
2356     curve fits the data as best as it can. P is a set of parameters that are
2357     varied by the solver in order to find the best fit. The solver measures
2358     how far away the curve is at each data point, squares the result and adds
2359     them all up. This is the number to be minimized, let's call it S. The
2360     solver is supplied with an initial guess for the parameters, P. It
2361     calculates S, makes an adjustment to P and calculates a new S1. Provided
2362     S1 &lt; S then we are moving in the right direction. It iterates through
2363     the procedure until:</para>
2364 
2365     <itemizedlist>
2366       <listitem>
2367         <para> the delta in S is less than a supplied limit (convergence has
2368         been reached), or</para>
2369       </listitem>
2370 
2371       <listitem>
2372         <para> the maximum number of iterations has been reached, or</para>
2373       </listitem>
2374 
2375       <listitem>
2376         <para> the solver encountered an error.</para>
2377       </listitem>
2378     </itemizedlist>
2379 
2380     <para> The solver is capable of solving either an unweighted or weighted
2381     set of datapoints. In essence, an unweighted set of data gives equal
2382     weight to each datapoint when trying to fit a curve. An alternative is to
2383     weight each datapoint with a measure that corresponds to how accurate the
2384     measurement of the datapoint actually is. In our case this is the variance
2385     of star HFRs associated with the datapoint. The variance is the standard
2386     deviation squared.</para>
2387 
2388     <para> Currently the solver is used to fit either a parabolic or a
2389     hyperbolic curve.</para>
2390   </sect2>
2391 
2392   <sect2 id="focus-aberration-inspector">
2393     <title>Aberration Inspector</title>
2394 
2395     <screenshot>
2396       <screeninfo> Aberration Inspector </screeninfo>
2397 
2398       <mediaobject>
2399         <imageobject>
2400           <imagedata fileref="aberration_inspector.png" format="PNG" width="75%"/>
2401         </imageobject>
2402 
2403         <textobject>
2404           <phrase>Aberration Inspector</phrase>
2405         </textobject>
2406       </mediaobject>
2407     </screenshot>
2408 
2409     <para>The Aberration Inspector is a tool that makes use of Autofocus to analyze backfocus and sensor tilt in the
2410     connected optical train.</para>
2411     <para>To run Aberration Inspector press the <guibutton>Aberration Inspector</guibutton> button.
2412     See <link linkend="focus-tools">Focus Tools</link> for more details. The following criteria must be met in
2413     order for the button to be active and the tool to work:</para>
2414 
2415     <itemizedlist>
2416       <listitem>
2417         <para>The focuser must be an absolute focuser.</para>
2418       </listitem>
2419 
2420       <listitem>
2421         <para>The focus algorithm must be Linear 1 Pass.</para>
2422       </listitem>
2423 
2424       <listitem>
2425         <para>A mosaic mask must be applied.</para>
2426       </listitem>
2427 
2428       <listitem>
2429         <para>Focuser step size needs to be setup. It is the number of microns the focal plane moves for 1 focuser tick.
2430         This is setup in the CFZ dialog. See the
2431         <link linkend="focus-cfz">CFZ section</link> for more details.</para>
2432       </listitem>
2433 
2434     </itemizedlist>
2435 
2436     <para>When the Inspector button is pressed, AutoFocus will run, but in addition, for each datapoint, extra information
2437     is captured for later use by Aberration Inspector. Once Autofocus completes, the Aberration Inspector dialog is
2438     displayed.</para>
2439 
2440     <para>To initially setup to use the tool it is recommended to do the following:</para>
2441 
2442     <itemizedlist>
2443       <listitem>
2444         <para>Point to a part of the sky where Autofocus solves well. Typically this would be high in the sky away from
2445         any obstacles. Choose somewhere with lots of stars such as the Milky Way. The reason this is more important
2446         for Aberration Inspector than Autofocus is that focus analysis needs to be performed for each tile in the mosaic.
2447         Therefore, it is important that each tile has enough stars to perform accurate Autofocus.</para>
2448       </listitem>
2449 
2450       <listitem>
2451         <para>Run Autofocus a couple of times to ensure it is solving correctly and that you have a good set of
2452         stars in each mosaic tile. Whilst most focus parameters can be used it is recommended to use the
2453         parameters that work best for Autofocus with your equipment. The reason for this is that Aberration
2454         Inspector needs be focus solve each mosaic tile and not just the sensor as a whole.</para>
2455       </listitem>
2456 
2457       <listitem>
2458         <para>A mosaic mask must be applied. Some experimentation will be required to set this up optimally for
2459         your equipment. The configuration parameter to adjust is the tile size which is the size of tile as a
2460         percentage of sensor width. The higher the percentage, the bigger each tile, e.g. for a 4:3 sensor using a
2461         tile size of 25% means each tile is 8% of the sensor's area. Using a tile size of 10% means each tile is
2462         1% of the sensor's area. The bigger the area the more stars will be present and the better the focus
2463         algorithm will solve. However, the purpose of the Aberration Inspector is to provide information
2464         on aberrations (backfocus and tilt) across the sensor, so ideally the information for each tile would be
2465         specific to as small an area as possible.</para>
2466         <para>The sweet spot for tile size is as small a value as possible that still contains enough stars to
2467         solve well in each tile.</para>
2468       </listitem>
2469     </itemizedlist>
2470 
2471     <para>The Aberration Inspector can be used in conjunction with a device to adjust tilt and / or backfocus. The
2472     method to do this is an iterative approach, like for example, collimating a telescope. The steps are:</para>
2473 
2474     <itemizedlist>
2475       <listitem>
2476         <para>Run the Aberration Inspector and obtain results.</para>
2477       </listitem>
2478 
2479       <listitem>
2480         <para>Inspect the results and make sure they are good, e.g. number of stars in each tile is sufficient and
2481         the R² is acceptable for all relevant tiles.</para>
2482       </listitem>
2483 
2484       <listitem>
2485         <para>Adjust tilt and / or backfocus using your device, based on Aberration Inspector results.</para>
2486       </listitem>
2487 
2488       <listitem>
2489         <para>Re-run Aberration Inspector. It will launch another dialog. Check results as before.
2490         If the tilt and / or backfocus is getting better then the adjustment was made in the correct sense;
2491         if not reverse the sense and retry. Use the feedback from the previous adjustment for the next adjustment.</para>
2492       </listitem>
2493     </itemizedlist>
2494 
2495     <para>Repeat the above process until the limit of sensitivity of the equipment is reached.</para>
2496 
2497     <para>Note the amount of adjustment, e.g. how far to turn bolts, and the sense, clockwise or counter-clockwise,
2498     will vary by equipment and must be discovered by the user by trial and error. Always follow the recommendations of
2499     the tilt / backfocus device manufacturer.</para>
2500 
2501     <para>Each time Aberration Inspector is run it launches a new dialog with the run number appended to the title.
2502     This way several runs can be performed and the results compared. Note, however, that the dialog holds a lot of
2503     data (roughly 10x the amount of a standard Autofocus run). The system resources associated with this are released
2504     when the dialog is closed. For this reason on lower powered machines, once the tool has been used, it is recommended
2505     to close all Aberration Inspector dialogs before imaging.</para>
2506 
2507     <para>The following sections describe the sections of the Aberration Inspector dialog.</para>
2508 
2509     <sect3 id="aberration-inspector-vcurve">
2510       <title>Aberration Inspector V-Curve</title>
2511 
2512       <screenshot>
2513         <screeninfo> Aberration Inspector V-Curve </screeninfo>
2514 
2515         <mediaobject>
2516           <imageobject>
2517           <imagedata fileref="aberration_inspector_vcurve.png" format="PNG" width="50%"/>
2518         </imageobject>
2519 
2520         <textobject>
2521           <phrase>Aberration Inspector V-Curve</phrase>
2522         </textobject>
2523         </mediaobject>
2524       </screenshot>
2525 
2526     <para> At the top of the dialog are some controls, followed by the V-Curve. The controls are:</para>
2527 
2528     <itemizedlist>
2529       <listitem>
2530         <para> <guilabel>Tiles</guilabel>: Three options are available:</para>
2531         <itemizedlist>
2532           <listitem>
2533             <para>All: All 9 tiles are displayed.</para>
2534           </listitem>
2535           <listitem>
2536             <para>Centre and outer corners: The centre and 4 corner tiles are displayed.</para>
2537           </listitem>
2538           <listitem>
2539             <para>Centre and inner diamond: The centre and 4 inner diamond tiles are displayed.</para>
2540           </listitem>
2541         </itemizedlist>
2542       </listitem>
2543       <listitem>
2544         <para> <guilabel>Labels</guilabel>: Checkbox toggles focus point labels on the V-Curve.</para>
2545       </listitem>
2546       <listitem>
2547         <para> <guilabel>CFZ</guilabel>: Checkbox toggles whether the CFZ moustache is displayed on the V-Curve.</para>
2548       </listitem>
2549       <listitem>
2550         <para> <guilabel>Optimise Tile Centres</guilabel>: If unchecked, the geometrical centre of the tile is used;
2551         if checked, the centre of the tile is calculated as an average of the star positions within the tile.
2552         Whilst theoretically more accurate to check this option, it is likely to have a significant impact only if the
2553         number of stars is small.</para>
2554       </listitem>
2555       <listitem>
2556         <para> <guilabel>Close</guilabel>: Close the Aberration Inspector dialog.</para>
2557       </listitem>
2558     </itemizedlist>
2559 
2560     <para>The V-Curve is similar to the V-Curve on the main Focus tab, except each tile is represented by its own curve.
2561     The number of curves is determined by the setting of the <guilabel>Tiles</guilabel> combobox. The x-axis displays
2562     the focuser position and the y-axis the measure (e.g. HFR) used by Autofocus. Each curve has its own colour
2563     and 2 character identifier as displayed in the legend.</para>
2564 
2565     <para>Hover the mouse over a curve minimum to see more information about that curve.</para>
2566     </sect3>
2567 
2568     <sect3 id="aberration-inspector-table">
2569     <title>Aberration Inspector Table</title>
2570 
2571     <screenshot>
2572       <screeninfo> Aberration Inspector Table </screeninfo>
2573 
2574       <mediaobject>
2575         <imageobject>
2576         <imagedata fileref="aberration_inspector_table.png" format="PNG" width="50%"/>
2577       </imageobject>
2578 
2579       <textobject>
2580         <phrase>Aberration Inspector Table</phrase>
2581       </textobject>
2582       </mediaobject>
2583     </screenshot>
2584 
2585     <para>The table displays information pertinent to each tile as selected by the
2586     <guilabel>Tiles</guilabel> setting.</para>
2587 
2588     <para>A tooltip like graphic is displayed when the mouse is hovered over either of the leftmost 2 columns.
2589     The graphic displays a picture of the sensor scaled to the dimensions of the sensor. Overlayed on the
2590     sensor are the tiles as selected by the <guilabel>Tiles</guilabel> setting. The tiles are scaled
2591     appropriately for the tile settings. Each tile is labelled with the Tile Name and the tile corresponding
2592     to the row that the mouse is hovering over, is highlighted in the colour of that tile.</para>
2593 
2594     <para>The following columns are displayed:</para>
2595 
2596     <itemizedlist>
2597       <listitem>
2598         <para> <guilabel>Tile</guilabel>: The 1 or 2 character name of the tile, e.g. TL = Top Left,
2599         C = Centre, etc.</para>
2600       </listitem>
2601       <listitem>
2602         <para> <guilabel>Description</guilabel>: Tile Description, e.g. Top Left, Centre, etc.</para>
2603       </listitem>
2604       <listitem>
2605         <para> <guilabel>Solution</guilabel>: The focus solution. This matches the solution on the V_Curve.</para>
2606       </listitem>
2607       <listitem>
2608         <para> <guilabel>Delta (ticks)</guilabel>: This is the delta of the solution for the current table row
2609         from the solution of the Centre tile. The Delta of the Centre row will, of course, be zero.</para>
2610       </listitem>
2611       <listitem>
2612         <para> <guilabel>Delta (μm)</guilabel>: This is Delta (ticks) converted to microns using the step size
2613         in microns as specified in the CFZ Focus tab.</para>
2614       </listitem>
2615       <listitem>
2616         <para> <guilabel>Num Stars</guilabel>: This shows the min / max number of stars detected during the
2617         Autofocus run. Usually, the minimum number would be a far out of focus datapoint and the max number
2618         would be the in focus datapoint.</para>
2619       </listitem>
2620       <listitem>
2621         <para> <guilabel>R²</guilabel>: R-squared of the curve fit for this tile. See
2622         <link linkend="Coefficient_of_Determination">Coefficient of Determination</link> for more details.</para>
2623       </listitem>
2624       <listitem>
2625         <para> <guilabel>Exclude</guilabel>: Checkbox to include / exclude this tile in calculations. By
2626         default, if a tile has been curve fitted it will be included; if a tile was not curve fitted then
2627         it will be excluded. In addition, the user may decide that a particular tile may contain poor
2628         quality data, for example the R² is low; or the number of stars is low. In this case the Exclude
2629         can be checked and this row will be excluded from calculations. Note that by excluding some rows,
2630         some calculations may not be performed. If the Centre tile is excluded, no calculations can be
2631         performed.</para>
2632 
2633         <para>Note that whilst it's possible to exclude tiles and still get calculated values, if the data
2634         is poor quality then it is recommended to rerun Aberration Inspector rather than persist with poor
2635         quality data.</para>
2636       </listitem>
2637     </itemizedlist>
2638 
2639     <para>The recommended approach is to check the table for quality data and once achieved, move onto
2640     analysing the <link linkend="aberration-inspector-results">Aberration Inspector Results</link>.</para>
2641     </sect3>
2642 
2643     <sect3 id="aberration-inspector-results">
2644     <title>Aberration Inspector Results</title>
2645 
2646     <screenshot>
2647       <screeninfo> Aberration Inspector Results </screeninfo>
2648 
2649       <mediaobject>
2650         <imageobject>
2651         <imagedata fileref="aberration_inspector_results.png" format="PNG" width="50%"/>
2652       </imageobject>
2653 
2654       <textobject>
2655         <phrase>Aberration Inspector Results</phrase>
2656       </textobject>
2657       </mediaobject>
2658     </screenshot>
2659 
2660     <para>The calculation results are displayed in this section, based on the data displayed in the table:</para>
2661 
2662     <itemizedlist>
2663       <listitem>
2664         <para> <guilabel>Backfocus Δ</guilabel>: This is the value of the Backfocus delta. The nearer to
2665         perfect backfocus, the lower the backfocus delta. Note that the Backfocus delta gives a clue as to
2666         how far out the Backfocus is, in terms of scale and direction, but is not the amount by which the
2667         sensor needs to be moved. The relationship between backfocus Delta and how far to move the sensor
2668         will vary with the equipment used, and needs to be worked out by the user.</para>
2669 
2670         <para>The field gives the sense of the backfocus movement required to improve backfocus: either move
2671         the sensor nearer to the field flattener (telescope) or move it further away.</para>
2672       </listitem>
2673       <listitem>
2674         <para> <guilabel>Left-Right Tilt</guilabel>: Gives the Left to Right tilt in microns and as a
2675         percentage.</para>
2676       </listitem>
2677       <listitem>
2678         <para> <guilabel>Top-Bottom Tilt</guilabel>: Gives the Top to Bottom tilt in microns and as a
2679         percentage</para>
2680       </listitem>
2681       <listitem>
2682         <para> <guilabel>Total Tilt</guilabel>: The diagonal tilt in microns and as a percentage.</para>
2683       </listitem>
2684     </itemizedlist>
2685 
2686     <para>The smaller the backfocus delta the nearer the sensor is to perfect backfocus. If the field flattner
2687     does not flatten the field all the way to the edges of the sensor then this will be visible by switching the
2688     Tiles option between "Centre and outer corners" and "Centre and inner diamond". If the backfocus delta results
2689     are consistent when the Tiles option is changed then this indicates that the field flattener is working to the
2690     corners of the sensor.</para>
2691 
2692     <para>There will always be some backfocus delta at least because of noise in the observation data. The important
2693     thing is that when in focus, stars are circular in all parts of the sensor.</para>
2694 
2695     <para>The smaller the tilt percentages, the nearer the sensor is to being flat to the plane of light from the
2696     flattener / telescope. As with backfocus delta, there is always going to be some noise in the data, which will
2697     present as tilt. The important thing is that when in focus the star sizes are consistent across all parts of the
2698     sensor.</para>
2699 
2700     <para>Because of the nature of the backfocus delta and tilt calculations, one will affect the other so it will
2701     probably be better to try and adjust both together, in small increments, rather than trying to perfect one in
2702     isolation, before adjusting the other.</para>
2703     </sect3>
2704 
2705     <sect3 id="aberration-inspector-3dgraphic">
2706     <title>Aberration Inspector 3D Graphic</title>
2707 
2708     <screenshot>
2709       <screeninfo> Aberration Inspector 3D Graphic </screeninfo>
2710 
2711       <mediaobject>
2712         <imageobject>
2713         <imagedata fileref="aberration_inspector_3dgraphic.png" format="PNG" width="50%"/>
2714       </imageobject>
2715 
2716       <textobject>
2717         <phrase>Aberration Inspector 3D Graphic</phrase>
2718       </textobject>
2719       </mediaobject>
2720     </screenshot>
2721 
2722     <para>The 3D graphic displays the sensor tilted as per the
2723     <link linkend="aberration-inspector-results">Aberration Inspector Results</link>. To help
2724     visualise the Petzval surface (see <ulink
2725     url="https://en.wikipedia.org/wiki/Petzval_field_curvature">Petzval Field Curvature</ulink> for more details)
2726     of light coming out of the telescope and incident on the sensor the surface is also modelled. The higher the
2727     backfocus error, the more curved the Petzval surface.</para>
2728 
2729     <para>The graphic can be zoomed and rotated using gestures. To zoom use pinch. To rotate use
2730     touch-and-move.</para>
2731 
2732     <para>The graphic has a Simulation Mode that allows backfocus and tilt to be adjusted by the
2733     sliders. The effect on the sensor's tilt and Petzval surface is displayed in the graphic.</para>
2734 
2735     <para>The following options are available for the graphic:</para>
2736 
2737     <itemizedlist>
2738       <listitem>
2739         <para> <guilabel>Selection</guilabel>: The following options are available:</para>
2740 
2741         <itemizedlist>
2742           <listitem>
2743           <para>None: No selection is possible.</para>
2744           </listitem>
2745 
2746           <listitem>
2747           <para>Item: A datapoint may be selected and data values are displayed.</para>
2748           </listitem>
2749 
2750           <listitem>
2751           <para>Slice: A 2D slice through the 3D graphic is displayed.</para>
2752           </listitem>
2753         </itemizedlist>
2754 
2755       </listitem>
2756       <listitem>
2757         <para> <guilabel>Theme</guilabel>: A number of colour themes are available.</para>
2758       </listitem>
2759 
2760       <listitem>
2761         <para> <guilabel>Labels</guilabel>: Checkbox to show / hide tile labels on the graphic.</para>
2762       </listitem>
2763 
2764       <listitem>
2765         <para> <guilabel>Sensor</guilabel>: Checkbox to show / hide the sensor.</para>
2766       </listitem>
2767 
2768       <listitem>
2769         <para> <guilabel>Petzval Wire</guilabel>: Checkbox to show / hide the Petzval surface as a graphic wire.</para>
2770       </listitem>
2771 
2772       <listitem>
2773         <para> <guilabel>Petzval Surface</guilabel>: Checkbox to show / hide the Petzval surface.</para>
2774       </listitem>
2775 
2776       <listitem>
2777         <para> <guilabel>Sim Mode</guilabel>: Checkbox to toggle Simulation Mode on / off. When off, the
2778         graphic displays the sensor and Petzval surface based on the calculated results of the Aberration Inspector
2779         run. When on, the sliders for Backfocus, Left-to-Right tilt and Top-to-Bottom tilt are activated, and these can be
2780         dragged by the user to adjust the graphic. Hover the mouse over each slider to see the tooltips describing what
2781         each slider does.</para>
2782       </listitem>
2783     </itemizedlist>
2784 
2785     <para>The 3D graphic is not essential to using Aberration Inspector. All relevant information is displayed in the
2786     <link linkend="aberration-inspector-table">Table</link> and <link linkend="aberration-inspector-results">Results</link>
2787     sections of the dialog. Its purpose is to aid the user in understanding Aberration Inspector and to orient themselves
2788     with the information the tool provides.</para>
2789     </sect3>
2790   </sect2>
2791 </sect1>