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 <sect2 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   <sect3 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> There are multiple methods. One is to calculate the Full Width at
0037     Half Maximum (FHWM) of a star profile within an image, and then adjust the
0038     focus until an optimal (narrower) FWHM is reached. The problem with FWHM
0039     is that it assumes the initial focus position to be close to the critical
0040     focus. Additionally, FWHM does not perform very well under low-intensity
0041     fluxes. An Alternative method is Half-Flux-Radius (HFR), which is a
0042     measure of the width in pixels counting from the center of the star until
0043     the accumulated intensity is half of the total flux of the star. HFR
0044     proved to be much more stable in conditions where you might have
0045     unfavorable sky conditions, when the brightness profile of the stars is
0046     low, and when the starting position of the focus is far from the optimal
0047     focus. </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: Iterative, Polynominal,
0056     Linear and Linear 1 Pass. </para>
0057 
0058     <itemizedlist>
0059       <listitem>
0060         <para> <emphasis role="bold">Iterative</emphasis>: In the Iterative
0061         algorithm, Ekos operates iteratively by moving in discrete steps,
0062         decided initially by the user-configurable step size and later by the
0063         slope of the V-Curve, to get closer to the optimal focus position
0064         where it then changes gears and performs smaller, finer moves to reach
0065         the optimal focus. The focus process stops when the measured HFR is
0066         within the configurable tolerance of the minimum recorded HFR in the
0067         process. In other words, whenever the process starts searching for a
0068         solution within a narrowly limited range, it checks if the current HFR
0069         is within % difference compared to the minimum HFR recorded, and if
0070         this condition is met then the Autofocus process is considered
0071         successful. The default value is set to 1% and is sufficient for most
0072         situations. The Step options specify the number of initial ticks the
0073         focuser has to move. If the image is severely out of focus, we set the
0074         step size high (i.e. greater than 250). On the other hand, if the
0075         focus is close to optimal focus, we set the step size to a more
0076         reasonable range (less than 50). It takes trial and error to find the
0077         best starting tick, but Ekos only uses that for the first focus
0078         motion, as all subsequent motions depend on the V-Curve slope
0079         calculations. Key features include:</para>
0080 
0081         <itemizedlist>
0082           <listitem>
0083             <para> The algorithm relies on the focuser having well controlled
0084             backlash. </para>
0085           </listitem>
0086 
0087           <listitem>
0088             <para> The algorithm can be fast using a minimum number of steps.
0089             </para>
0090           </listitem>
0091 
0092           <listitem>
0093             <para> The algorithm works on a "good enough" paradigm whereby it
0094             stops when the HFR is within % Tolerance of the perceived minimum.
0095             </para>
0096           </listitem>
0097         </itemizedlist>
0098       </listitem>
0099 
0100       <listitem>
0101         <para> <emphasis role="bold">Polynomial</emphasis>: In the Polynomial
0102         algorithm, the process starts off in Iterative mode, but once we cross
0103         to the other side of the V-Curve (once HFR values start increasing
0104         again after decreasing for a while), then Ekos performs quadratic
0105         curve fitting to find a solution that predicts the minimum possible
0106         HFR position. Key features include:</para>
0107 
0108         <itemizedlist>
0109           <listitem>
0110             <para> The algorithm relies on the focuser having well controlled
0111             backlash. </para>
0112           </listitem>
0113 
0114           <listitem>
0115             <para> The algorithm can be fast using a minimum number of steps.
0116             </para>
0117           </listitem>
0118 
0119           <listitem>
0120             <para> The algorithm uses curve fitting to pinpoint the optimum
0121             focus position. </para>
0122           </listitem>
0123         </itemizedlist>
0124       </listitem>
0125 
0126       <listitem>
0127         <para> <emphasis role="bold">Linear</emphasis>: In the Linear
0128         algorithm, Ekos steps outward from its starting point then moves
0129         inward taking regular datapoints through the point of optimum focus
0130         and then further inward, to draw a V-Curve. It then fits a quadratic
0131         curve to the datapoints and calculates the point of optimum focus. It
0132         then moves out again past the point of optimum focus, halves the
0133         stepsize and moves in again for a second pass. It looks to follow the
0134         curve from the first pass and find the minimum HFR. Due to randomness
0135         in the HFR measurements it uses the % tolerance to help decide when it
0136         has found a solution. Key features include: </para>
0137 
0138         <itemizedlist>
0139           <listitem>
0140             <para> The algorithm compensates for focuser backlash and can deal
0141             with both consistent and inconsistent backlash. </para>
0142           </listitem>
0143 
0144           <listitem>
0145             <para> The algorithm is slow, taking 2 passes to identify optimum
0146             focus. </para>
0147           </listitem>
0148 
0149           <listitem>
0150             <para> The algorithm uses curve fitting to pinpoint the optimum
0151             focus position in pass 1, but then uses % Tolerance to try to stop
0152             as close as possible to this HFR on pass 2. </para>
0153           </listitem>
0154 
0155           <listitem>
0156             <para> The algorithm is highly configurable with user control over
0157             many parameters like step size and number of steps. </para>
0158           </listitem>
0159         </itemizedlist>
0160       </listitem>
0161 
0162       <listitem>
0163         <para> <emphasis role="bold">Linear 1 Pass</emphasis>: In the Linear 1
0164         Pass algorithm, Ekos initially performs like the Linear algorithm in
0165         establishing the first pass V-Curve and fitting a curve to it to find
0166         the solution. Then, however, it moves directly to the calculated
0167         minimum. Key features include: </para>
0168 
0169         <itemizedlist>
0170           <listitem>
0171             <para> The algorithm compensates for focuser backlash, providing
0172             that backlash is consistent. </para>
0173           </listitem>
0174 
0175           <listitem>
0176             <para> The algorithm is fast, taking 1 pass to identify optimum
0177             focus. </para>
0178           </listitem>
0179 
0180           <listitem>
0181             <para> The algorithm uses more sophisticated curve fitting to
0182             pinpoint the optimum focus position. </para>
0183           </listitem>
0184 
0185           <listitem>
0186             <para> The algorithm is highly configurable with user control over
0187             many parameters like step size and number of steps. </para>
0188           </listitem>
0189         </itemizedlist>
0190       </listitem>
0191     </itemizedlist>
0192   </sect3>
0193 
0194   <sect3 id="optical-train-group">
0195     <title>Optical Train Group</title>
0196 
0197     <screenshot>
0198       <screeninfo> Optical Train </screeninfo>
0199 
0200       <mediaobject>
0201         <imageobject>
0202           <imagedata fileref="optical_train_group.png" format="PNG"
0203                      width="50%"/>
0204         </imageobject>
0205 
0206         <textobject>
0207           <phrase>Optical Train Settings</phrase>
0208         </textobject>
0209       </mediaobject>
0210     </screenshot>
0211 
0212     <para> The Optical Train group displays the currently selected Optical
0213     Train. By default this will be the primary imaging train, but other trains
0214     can be selected. The group consists of:</para>
0215 
0216     <itemizedlist>
0217       <listitem>
0218         <para> <guibutton>Train</guibutton>: The Optical Train currently in
0219         use by the Focus tab. Hover the mouse over this field for a more
0220         detailed description of the selected train.</para>
0221       </listitem>
0222 
0223       <listitem>
0224         <para> <guibutton>Edit Button</guibutton>: Brings up the Optical Train
0225         dialog to view and potentially change the optical trains.</para>
0226       </listitem>
0227     </itemizedlist>
0228   </sect3>
0229 
0230   <sect3 id="focus-focuser-group">
0231     <title>Focuser Group</title>
0232 
0233     <screenshot>
0234       <screeninfo> Focuser Settings </screeninfo>
0235 
0236       <mediaobject>
0237         <imageobject>
0238           <imagedata fileref="focuser_group.png" format="PNG" width="50%"/>
0239         </imageobject>
0240 
0241         <textobject>
0242           <phrase>Focuser Settings</phrase>
0243         </textobject>
0244       </mediaobject>
0245     </screenshot>
0246 
0247     <para> All INDI-compatible focusers are supported. It is recommended to
0248     use <emphasis role="bold">absolute</emphasis> focusers for the best
0249     results since their absolute position is known on power up. In INDI, the
0250     focuser <emphasis>zero</emphasis> position is when the drawtube is
0251     <emphasis role="bold">fully retracted</emphasis>. When focusing
0252     <emphasis>outwards</emphasis>, the focuser position increases, while it
0253     decreases when focusing <emphasis>inwards</emphasis>. The following
0254     focuser types are supported: </para>
0255 
0256     <itemizedlist>
0257       <listitem>
0258         <para> <emphasis role="bold">Absolute</emphasis>: Absolute Position
0259         Focusers such as RoboFocus, MoonLite, ASI ZWO </para>
0260       </listitem>
0261 
0262       <listitem>
0263         <para> <emphasis role="bold">Relative</emphasis>: Relative Position
0264         Focusers. </para>
0265       </listitem>
0266 
0267       <listitem>
0268         <para> <emphasis role="bold">Time Based</emphasis>: Time based
0269         focusers with no position feedback that adjust focus position by
0270         moving for a certain amount of time. </para>
0271       </listitem>
0272     </itemizedlist>
0273 
0274     <para> Start off by selecting the Focuser from the dropdown. </para>
0275 
0276     <para> For absolute focusers, you can set the ticks count in the Initial
0277     Steps Size field in the <link linkend="focus-mechanics">Mechanics</link>
0278     tab. For absolute and relative focusers, the step size is in units of
0279     <emphasis>ticks</emphasis> and for simple, or time based, focusers, the
0280     step size is in <emphasis>milliseconds</emphasis>. The
0281     <guibutton>In</guibutton> and <guibutton>Out</guibutton> buttons can then
0282     be used to move the focuser by this number of ticks.</para>
0283 
0284     <para> The Steps fields will initially contain the starting point in ticks
0285     for the focuser. As the focuser moves, the left field will update to
0286     reflect the focuser's current position. The right field will initially
0287     contain the starting position of the focuser but will update each time a
0288     successful Autofocus run completes, to keep a last good focus position. In
0289     addition you can set the right field to whatever value you like, and use
0290     the <guibutton>Goto</guibutton> button to move the focuser to this
0291     position.</para>
0292 
0293     <para> The <guibutton>Goto Focus Position</guibutton> button moves the
0294     focuser to the position in the righthand Steps field. </para>
0295 
0296     <para> The <guibutton>Stop Focuser Motion</guibutton> button stops the
0297     in-progress focuser motion. </para>
0298 
0299     <para> The <guibutton>Auto Focus</guibutton> button starts an Autofocus
0300     run. The <guibutton>Stop</guibutton> button is used to stop the run.
0301     </para>
0302 
0303     <para> The <guibutton>Capture Image</guibutton> button will take a frame
0304     based on the current settings in the <guilabel>CCD and Filter
0305     Wheel</guilabel> group. The <guibutton>Start Framing</guibutton> button
0306     will start repeatedly capturing frames until the
0307     <guibutton>Stop</guibutton> button is pressed. </para>
0308 
0309     <para> Some of the focus algorithms will attempt to cope with being
0310     started away from the point of optimum focus, but for predictable results,
0311     it is best to start from a position of being approximately in focus. For
0312     first time setup, <guibutton>Start Framing</guibutton> can be used along
0313     with the <guibutton>In</guibutton> and <guibutton>Out</guibutton> buttons
0314     to adjust the focus position to roughly minimize the HFR of the stars in
0315     the captured images. When Framing is used in this way, the <link
0316     linkend="focus-v-curve">V-Curve</link> graph changes to show a time series
0317     of frames and their associated HFRs. This makes the framing process much
0318     easier to perform.</para>
0319 
0320     <para> If you are completely new to astronomy, it is always a good idea to
0321     get familiar with your equipment in daylight. This includes getting the
0322     approximate focus position on a distant object. This will provide a good
0323     starting position for focusing on stars when nighttime comes.</para>
0324   </sect3>
0325 
0326   <sect3 id="focus-ccd-filter-wheel">
0327     <title>Camera &amp; Filter Wheel Group</title>
0328 
0329     <screenshot>
0330       <screeninfo> Focus Camera &amp; Filter Wheel Group </screeninfo>
0331 
0332       <mediaobject>
0333         <imageobject>
0334           <imagedata fileref="focus_ccdfw_group.png" format="PNG" width="50%"/>
0335         </imageobject>
0336 
0337         <textobject>
0338           <phrase>Focus Camera &amp; Filter Wheel Group</phrase>
0339         </textobject>
0340       </mediaobject>
0341     </screenshot>
0342 
0343     <para> This section of parameters deals with the Camera and Filter
0344     settings to use when focusing.</para>
0345 
0346     <para> The top row of controls allows CCD parameters to be set.</para>
0347 
0348     <itemizedlist>
0349       <listitem>
0350         <para> <guilabel>Exp</guilabel>: The exposure time in seconds.</para>
0351       </listitem>
0352 
0353       <listitem>
0354         <para> The <guibutton>Toggle Full Screen</guibutton> button pops the
0355         window displaying the focus frame out to a separate window. Pressing
0356         it again returns it within the focus window.</para>
0357       </listitem>
0358 
0359       <listitem>
0360         <para> The <guibutton>Show in FITS Viewer</guibutton> button pops-up a
0361         separate FITS Viewer window to display the focus frame, in addition to
0362         the focus frame displayed within the focus window.</para>
0363       </listitem>
0364 
0365       <listitem>
0366         <para> The <guibutton>Live Video</guibutton> button brings up the
0367         associated popup.</para>
0368       </listitem>
0369     </itemizedlist>
0370 
0371     <para> The next row of controls allows Camera parameters to be set. Choose
0372     a value from the binning dropdown and then set either the camera gain or
0373     ISO.</para>
0374 
0375     <itemizedlist>
0376       <listitem>
0377         <para> <guilabel>Binning</guilabel>: Increasing the binning will
0378         change the image scale as well as resulting in brighter pixels. A good
0379         place to start would be 1x1 and then see whether better results can be
0380         obtained by binning at higher levels such as 2x2 or 4x4.</para>
0381       </listitem>
0382 
0383       <listitem>
0384         <para> <guilabel>Gain</guilabel>: Set the Gain for the Camera being
0385         used to focus. The value needs to be high enough to give a clear star
0386         pattern but not so high as to create too much noise to interfere with
0387         the focus operation. Some experimentation will be required to find an
0388         optimum value. If you are unsure where to start try unity gain for
0389         your camera and adjust from there.</para>
0390       </listitem>
0391 
0392       <listitem>
0393         <para> <guilabel>ISO</guilabel>: Set the ISO for the Camera being used
0394         to focus. Some experimentation will be required to find an optimum
0395         value.</para>
0396       </listitem>
0397     </itemizedlist>
0398 
0399     <para> The third row of controls deals with the Temperature Source and
0400     Filter, if there is one:</para>
0401 
0402     <itemizedlist>
0403       <listitem>
0404         <para> <guilabel>TS</guilabel>: Select the temperature source from the
0405         dropdown. Underneath are displayed the current temperature from the
0406         selected temperature source and the change in temperature between when
0407         the last successful Autofocus run completed and the current
0408         temperature. It is common practice to redo focus after significant
0409         temperature changes that alter the telescope's focus point.</para>
0410       </listitem>
0411 
0412       <listitem>
0413         <para> <guilabel>Filter</guilabel>: Select the filter to use.</para>
0414 
0415         <para>To start focusing it will probably be easier to select the
0416         filter that allows the most light through, for example the Lum filter.
0417         The <guibutton>Filter Settings</guibutton> button brings up the <link
0418         linkend="capture-filter-settings">Filter Settings</link> popup. This
0419         allows a number of parameters to be set per filter to be used during
0420         an Autofocus run which could be unattended so a user would not be
0421         available to set parameters at run time. Broadly these allow two types
0422         of focus runs:</para>
0423 
0424         <itemizedlist>
0425           <listitem>
0426             <para> <emphasis role="bold">Per Filter</emphasis>: When another
0427             module, for example, the Capture module requires a filter change,
0428             it is possible to automatically refocus for the new filter. The
0429             exposure to use for each filter is taken from the <link
0430             linkend="capture-filter-settings">Filter Settings</link> popup.
0431             This is very useful where, for example, narrowband filter require
0432             longer exposure times than broadband filters.</para>
0433           </listitem>
0434 
0435           <listitem>
0436             <para> <emphasis role="bold">Lock Filter</emphasis>: It is
0437             possible to specify a Lock filter to use when it is required to
0438             focus another filter. For example, if a Red filter is used and an
0439             Autofocus run required, it is possible to run the Autofocus using
0440             the Lum filter and then, when complete, adjust the focus position
0441             by an Offset value corresponding to the predetermined focus
0442             difference between the Lum and Red filters. This is useful when,
0443             for example, it is difficult to focus some filters directly
0444             without excessively long exposure times. Note that this locked
0445             filter approach may also be used in the <link
0446             linkend="ekos-align">Alignment Module</link> whenever it performs
0447             a capture for astrometry.</para>
0448           </listitem>
0449         </itemizedlist>
0450       </listitem>
0451 
0452       <listitem>
0453         <para> <guibutton>Reset</guibutton> button will reset the focusing
0454         subframe to full frame.</para>
0455       </listitem>
0456     </itemizedlist>
0457   </sect3>
0458 
0459   <sect3 id="focus-settings">
0460     <title>Focus Settings</title>
0461 
0462     <screenshot>
0463       <screeninfo> Focus Settings </screeninfo>
0464 
0465       <mediaobject>
0466         <imageobject>
0467           <imagedata fileref="focus_settings.png" format="PNG" width="50%"/>
0468         </imageobject>
0469 
0470         <textobject>
0471           <phrase>Focus Settings</phrase>
0472         </textobject>
0473       </mediaobject>
0474     </screenshot>
0475 
0476     <para> Next are 3 tabbed panes of parameters. These parameters are
0477     retained between sessions. First up is the Settings pane.</para>
0478 
0479     <itemizedlist>
0480       <listitem>
0481         <para> <guilabel>Auto Select Star</guilabel>: Allow Ekos to select the
0482         focus star(s) from the image. If not selected then the user will have
0483         to manually select a star.</para>
0484       </listitem>
0485 
0486       <listitem>
0487         <para> <guilabel>Dark Frame</guilabel>: Check this option to perform
0488         dark-frame subtraction. This option can be useful in noisy images,
0489         where a pretaken dark is subtracted from the focus image before
0490         further processing.</para>
0491 
0492         <para> Dark frames are used by Focus, Alignment and Guiding. See the
0493         Dark Library feature within the <link linkend="ekos-capture">Capture
0494         Module</link> for more details on how to setup Dark Frames.</para>
0495       </listitem>
0496 
0497       <listitem>
0498         <para> <guilabel>AF Backlash Comp</guilabel>: Check this option to
0499         have the Autofocus algorithm perform backlash compensation. This
0500         option is available when using the Linear and Linear 1 Pass
0501         algorithms. This field should be set together with the
0502         <guilabel>Backlash</guilabel> field. See the <link
0503         linkend="focus-mechanics">Focus Mechanics</link> section for more
0504         details.</para>
0505 
0506         <para>Backlash in the focuser setup is likely to a combination of
0507         backlash in the electronic focuser itself (e.g. in the gearing
0508         mechanism), in the binding of the electronic focuser to the telescope
0509         drawtube, and in the telescope drawtube's mechanism. Thus, each setup
0510         will have its own backlash characteristic.</para>
0511 
0512         <para> There are several things to consider when working out how to
0513         deal with backlash: <itemizedlist>
0514             <listitem>
0515               <para> <emphasis role="bold">No Backlash</emphasis>: If you are
0516               fortunate enough to have a setup with no backlash then it would
0517               make sense to set AF Backlash Comp off. It should work fine if
0518               AF Backlash Comp is on, but the AutoFocus routine will make
0519               unnecessary movements.</para>
0520             </listitem>
0521 
0522             <listitem>
0523               <para> <emphasis role="bold">Backlash Managed by
0524               Focuser</emphasis>: If your focuser had the ability to manage
0525               backlash itself then you can use this facility and turn off AF
0526               Backlash Comp. Alternatively, if it's possible, you could turn
0527               off the focuser's backlash facility and set AF Backlash Comp
0528               on.</para>
0529             </listitem>
0530 
0531             <listitem>
0532               <para> <emphasis role="bold">Backlash Managed by Device
0533               Driver</emphasis>: If your device driver had the ability to
0534               manage backlash itself then you can use this facility and turn
0535               off AF Backlash Comp. Alternatively, if it's possible, you could
0536               turn off the device driver's backlash facility and set AF
0537               Backlash Comp on.</para>
0538             </listitem>
0539           </itemizedlist> </para>
0540 
0541         <para>It is important to have backlash managed in one place to avoid
0542         conflicts.</para>
0543       </listitem>
0544 
0545       <listitem>
0546         <para> <guilabel>Sub Frame</guilabel>: Either use the Full Field of
0547         the camera or select a Subframe around the focus star during the
0548         Autofocus procedure. This is only relevant if a single star is used
0549         for focusing. Enabling subframing can speed up the focus
0550         process.</para>
0551       </listitem>
0552 
0553       <listitem>
0554         <para> <guilabel>Box</guilabel>: Sets the box size used to enclose the
0555         focus star when using <emphasis role="bold">Sub Frame</emphasis>.
0556         Increase if you have very large stars. For Bahtinov focus the box size
0557         can be increased even more to better enclose the Bahtinov diffraction
0558         pattern.</para>
0559       </listitem>
0560 
0561       <listitem>
0562         <para> <guilabel>Full Field</guilabel>: Either use the full field of
0563         the camera or select a Sub Frame around the focus star during the
0564         Autofocus procedure. If using multiple stars then this option must be
0565         selected.</para>
0566       </listitem>
0567 
0568       <listitem>
0569         <para> <guilabel>Annulus</guilabel>: Used in conjunction with Full
0570         Field, Annulus provides two input fields that together define a
0571         doughnut over the FOV of the camera. Stars falling outside of the
0572         doughnut are discounted from processing. Setting an inner value above
0573         0% causes stars in the centre of the FOV to be discarded. This could
0574         be useful to avoid using stars in the target of the image (for example
0575         a galaxy) for focusing purposes. Setting an outer value below 100%
0576         causes stars in the edges of the FOV to be discarded during focusing.
0577         This could be useful if you do not have a flat field out to the edges
0578         of your FOV.</para>
0579       </listitem>
0580 
0581       <listitem>
0582         <para> <guilabel>Suspend Guiding</guilabel>: Set this option to
0583         suspend guiding during an Autofocus run. An additional check is made
0584         to only suspend guiding if it is being carried out via the primary
0585         scope, for example when using an Off Axis Guider. The purpose of this
0586         is to prevent guiding from having problems with defocused stars during
0587         the focus process.</para>
0588       </listitem>
0589 
0590       <listitem>
0591         <para> <guilabel>Settle</guilabel>: This option is used in conjunction
0592         with <guilabel>Suspend Guiding</guilabel>. It allows any vibrations in
0593         the optical train to settle by waiting this many seconds after the
0594         Autofocus process has completed, before restarting guiding.</para>
0595       </listitem>
0596 
0597       <listitem>
0598         <para> <guilabel>Use Weights</guilabel>: This is an experimental
0599         option only available with the Linear 1 Pass focus algorithm and Curve
0600         Types of Hyperbola and Parabola. It requires Full Field to be
0601         selected. The option calculates the standard deviation of star HFRs
0602         and uses the square of this (mathematically the variance) as a
0603         weighting in the curve fitting process. The advantage of this is that
0604         datapoints with less reliable data and therefore larger HFR standard
0605         deviations will be given less weight than more reliable datapoints. If
0606         this option is unchecked, and for all other curve fitting where the
0607         option is not allowed, all datapoints are given equal weight in the
0608         curve fitting process. </para>
0609 
0610         <para> See the <link linkend="Levenberg-Marquardt">Levenberg-Marquardt
0611         Solver</link> for more details.</para>
0612       </listitem>
0613 
0614       <listitem>
0615         <para> <guilabel>R² Limit</guilabel>: This is an experimental option
0616         only available with the Linear 1 Pass focus algorithm and Curve Types
0617         of Hyperbola and Parabola. As part of the Linear 1 Pass algorithm, the
0618         degree to which the curve fits the datapoints, or <link
0619         linkend="Coefficient_of_Determination">Coefficient of Determination,
0620         R²</link>, is calculated. This option allows a minimum acceptable
0621         value of R² to be defined that is compared to the value obtained from
0622         the curve fitting process. If the minimum value has not been achieved
0623         then Autofocus will rerun. Only one rerun will be performed and even
0624         if the minimum R² has not been met the second time, the Autofocus run
0625         will still be deemed successful.</para>
0626 
0627         <para> Experiment to find an appropriate value but a good starting
0628         point would be 0.8 or 0.9</para>
0629       </listitem>
0630     </itemizedlist>
0631   </sect3>
0632 
0633   <sect3 id="focus-process">
0634     <title>Focus Process</title>
0635 
0636     <screenshot>
0637       <screeninfo> Focus Process </screeninfo>
0638 
0639       <mediaobject>
0640         <imageobject>
0641           <imagedata fileref="focus_process.png" format="PNG" width="50%"/>
0642         </imageobject>
0643 
0644         <textobject>
0645           <phrase>Focus Process</phrase>
0646         </textobject>
0647       </mediaobject>
0648     </screenshot>
0649 
0650     <para> This is the Focus Process parameters pane.</para>
0651 
0652     <itemizedlist>
0653       <listitem>
0654         <para> <guilabel>Detection</guilabel>: Select star detection
0655         algorithm. Each algorithm has its strengths and weaknesses. It is
0656         recommended to keep the default value, SEP, unless it fails to
0657         properly detect stars. The following are available:</para>
0658 
0659         <itemizedlist>
0660           <listitem>
0661             <para> <emphasis role="bold">SEP</emphasis>: Source Extraction and
0662             Photometry built in library. This is the default value.</para>
0663           </listitem>
0664 
0665           <listitem>
0666             <para> <emphasis role="bold">Centroid</emphasis>: An extraction
0667             method based on estimating star mass around signal peaks.</para>
0668           </listitem>
0669 
0670           <listitem>
0671             <para> <emphasis role="bold">Gradient</emphasis>: A single source
0672             extraction model based on the Sobel filter. </para>
0673           </listitem>
0674 
0675           <listitem>
0676             <para> <emphasis role="bold">Threshold</emphasis>: A single source
0677             detection algorithm based on pixel values. </para>
0678           </listitem>
0679 
0680           <listitem>
0681             <para> <emphasis role="bold">Bahtinov</emphasis>: This detection
0682             method can be used when using a Bahtinov mask for focusing. First
0683             take an image, then select the star to focus on. A new image will
0684             be taken and the diffraction pattern will be analysed. Three lines
0685             will be displayed on the diffraction pattern showing how well the
0686             pattern is recognized and how good the image is in focus. When the
0687             pattern is not well recognized, the <emphasis>Num. of
0688             rows</emphasis> parameter can be adjusted to improve recognition.
0689             The line with the circles at each end is a magnified indicator for
0690             the focus. The shorter the line, the better the image is in
0691             focus.</para>
0692           </listitem>
0693         </itemizedlist>
0694       </listitem>
0695 
0696       <listitem>
0697         <para> <guilabel>SEP Profile</guilabel>: If the star detection
0698         algorithm is set to <emphasis>SEP</emphasis>, then choose a parameter
0699         profile to use with the algorithm. It is recommended to use the
0700         default 1-Focus-Default profile as a starting point.</para>
0701       </listitem>
0702 
0703       <listitem>
0704         <para> <guilabel>Threshold</guilabel>: Threshold percentage value is
0705         used for star detection using the <emphasis>Threshold</emphasis>
0706         detection algorithm. Increase to restrict the centroid to bright
0707         cores. Decrease to enclose fuzzy stars.</para>
0708       </listitem>
0709 
0710       <listitem>
0711         <para> <guilabel>Algorithm</guilabel>: Select the Autofocus process
0712         algorithm: </para>
0713 
0714         <itemizedlist>
0715           <listitem>
0716             <para> <emphasis role="bold">Iterative</emphasis>: Moves focuser
0717             by discreet steps initially decided by the step size. Once a curve
0718             slope is calculated, further step sizes are calculated to reach an
0719             optimal solution. The algorithm stops when the measured HFR is
0720             within <emphasis role="bold">Tolerance</emphasis> of the minimum
0721             HFR recorded in the procedure.</para>
0722           </listitem>
0723 
0724           <listitem>
0725             <para> <emphasis role="bold">Polynomial</emphasis>: Starts with
0726             the iterative method. Upon crossing to the other side of the
0727             V-Curve, polynomial fitting coefficients along with possible
0728             minimum solution are calculated. This algorithm can be faster than
0729             a purely iterative approach given a good data set.</para>
0730           </listitem>
0731 
0732           <listitem>
0733             <para> <emphasis role="bold">Linear</emphasis>: This algorithm
0734             builds a V-Curve with approximately <emphasis role="bold">Out step
0735             Multiple</emphasis> steps on each side of the minimum. Having
0736             built the V-Curve it then fits a quadratic equation to the curve
0737             (parabolic shape) and uses this to calculate the focuser position
0738             giving the minimum HFR. Having identified the minimum it then
0739             performs a 2nd pass halving the step size, recreating the curve
0740             from the 1st pass. It attempts to stop within <emphasis
0741             role="bold">Tolerance</emphasis> of the minimum HFR calculated
0742             during the 1st pass.</para>
0743           </listitem>
0744 
0745           <listitem>
0746             <para> <emphasis role="bold">Linear 1 Pass</emphasis>: This
0747             algorithm starts in the same way as <emphasis
0748             role="bold">Linear</emphasis> building a V-Curve. Having built the
0749             V-Curve it then fits the <emphasis role="bold">Curve
0750             Fit</emphasis> type to the datapoints and then calculates the
0751             focuser position giving the minimum HFR. Having identified the
0752             minimum it then moves directly to that point in a way designed to
0753             neutralise backlash.</para>
0754 
0755             <para> This algorithm supports the older style Quadratic curve
0756             type as well as the newer <link
0757             linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link>
0758             for Hyperbolic and Parabolic curves. It will also weight the
0759             datapoints in the curve fitting process if Use Weights is
0760             checked.</para>
0761           </listitem>
0762         </itemizedlist>
0763       </listitem>
0764 
0765       <listitem>
0766         <para> <guilabel>Effect</guilabel>: You may select an
0767         <guilabel>Effect</guilabel> filter to enhance the image for preview
0768         purposes. It is highly advisable to turn off any effects during the
0769         focusing process as it may interfere with HFR calculations. For DSLR
0770         cameras, you can change the ISO settings.</para>
0771       </listitem>
0772 
0773       <listitem>
0774         <para> <guilabel>Tolerance</guilabel>: The tolerance percentage value
0775         is used to help decide when the Autofocus process stops in the
0776         <guilabel>Iterative</guilabel> and <guilabel>Linear</guilabel>
0777         algorithms. During the Autofocus process, HFR values are recorded, and
0778         once the focuser is close to an optimal position, it starts measuring
0779         HFRs against the minimum recorded HFR in the sessions and stops
0780         whenever a measured HFR value is within % difference of the minimum
0781         recorded HFR. Decrease the value to narrow the optimal focus point
0782         solution radius. Increase to expand solution radius. </para>
0783 
0784         <warning>
0785           <para> Setting the value too low might result in a repetitive loop
0786           and would most likely result in a failed Autofocus process. </para>
0787         </warning>
0788       </listitem>
0789 
0790       <listitem>
0791         <para> <guilabel>Kernel Size</guilabel>: The kernel size of the
0792         gaussian blur applied to the image before applying Bahtinov edge
0793         detection. Used when <emphasis role="bold">Detection</emphasis> is
0794         Bahtinov.</para>
0795       </listitem>
0796 
0797       <listitem>
0798         <para> <guilabel>Average over</guilabel>: Number of frames to capture
0799         at each datapoint. It is usually sensible to start with 1 but
0800         increasing this will result in an averaging process over the star
0801         HFRs.</para>
0802       </listitem>
0803 
0804       <listitem>
0805         <para> <guilabel>Sigma</guilabel>: The sigma of the gaussian blur
0806         applied to the image before applying Bahtinov edge detection. Used
0807         when <emphasis role="bold">Detection</emphasis> is Bahtinov.</para>
0808       </listitem>
0809 
0810       <listitem>
0811         <para> <guilabel>Num. of rows</guilabel>: The number of lines
0812         displayed on screen when using a Bahtinov mask. Used when <emphasis
0813         role="bold">Detection</emphasis> is Bahtinov.</para>
0814       </listitem>
0815 
0816       <listitem>
0817         <para> <guilabel>Curve Fit</guilabel>: The type of curve to fit to the
0818         datapoints. </para>
0819 
0820         <itemizedlist>
0821           <listitem>
0822             <para> <emphasis role="bold">Quadratic</emphasis>: Uses a
0823             quadratic equation using a linear style least squares algorithm
0824             supplied by GSL (GNU Science Library). This is, in effect, a
0825             parabolic curve.</para>
0826           </listitem>
0827 
0828           <listitem>
0829             <para> <emphasis role="bold">Hyperbola</emphasis>: Fits a
0830             Hyperbola using a non-linear least squares algorithm supplied by
0831             GSL (GNU Science Library). See <link
0832             linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link>
0833             for more details.</para>
0834           </listitem>
0835 
0836           <listitem>
0837             <para> <emphasis role="bold">Parabola</emphasis>: Fits a Parabola
0838             using a non-linear least squares algorithm supplied by GSL (GNU
0839             Science Library). See <link
0840             linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link>
0841             for more details.</para>
0842           </listitem>
0843         </itemizedlist>
0844       </listitem>
0845     </itemizedlist>
0846   </sect3>
0847 
0848   <sect3 id="focus-mechanics">
0849     <title>Focus Mechanics</title>
0850 
0851     <screenshot>
0852       <screeninfo> Focus Mechanics </screeninfo>
0853 
0854       <mediaobject>
0855         <imageobject>
0856           <imagedata fileref="focus_mechanics.png" format="PNG" width="50%"/>
0857         </imageobject>
0858 
0859         <textobject>
0860           <phrase>Focus Mechanics</phrase>
0861         </textobject>
0862       </mediaobject>
0863     </screenshot>
0864 
0865     <para> This is the Focus Mechanics parameters pane.</para>
0866 
0867     <itemizedlist>
0868       <listitem>
0869         <para> <guilabel>Initial Step size</guilabel>: This sets the step size
0870         to be used by various focus algorithms. For absolute and relative
0871         focusers this is the number of ticks; for timer based focusers this is
0872         the number of milliseconds.</para>
0873       </listitem>
0874 
0875       <listitem>
0876         <para> <guilabel>Max Travel</guilabel>: Puts bounds on the amount of
0877         travel from the current focuser position that is permitted by the
0878         Autofocus algorithms. The purpose is to protect the focuser from
0879         travelling too far and potentially damaging itself. On the other hand,
0880         the value needs to be big enough to allow sufficient focuser motion to
0881         permit the auto focus runs to complete.</para>
0882       </listitem>
0883 
0884       <listitem>
0885         <para> <guilabel>Max Step size</guilabel>: Used by the Iterative focus
0886         algorithm to limit the maximum step size that can be used.</para>
0887       </listitem>
0888 
0889       <listitem>
0890         <para> <guilabel>Backlash</guilabel>: All mechanical devices with
0891         gears suffer from backlash. In a typical focuser there will be a dead
0892         zone where changing direction (e.g. from “in” to “out”) results in
0893         movement of the focuser by a few ticks, but no actual movement of the
0894         optical train.</para>
0895 
0896         <para>The Linear 1 Pass algorithm (like the Linear algorithm) provides
0897         backlash compensation in the 2 places during an auto focus run when
0898         the focuser moves outwards:</para>
0899 
0900         <itemizedlist>
0901           <listitem>
0902             <para> The initial outward movement of Initial Step Size * Out
0903             Step Multiple at the start of the run.</para>
0904           </listitem>
0905 
0906           <listitem>
0907             <para> When the inward pass is complete and Ekos has determined
0908             the best focus position and moves outward to it.</para>
0909           </listitem>
0910         </itemizedlist>
0911 
0912         <para> Linear 1 Pass will extend (by x ticks) the outward movement,
0913         and then, as a separate movement it will move inward by x ticks. So it
0914         always approaches the desired position in an inward direction.</para>
0915 
0916         <para>There are 2 schemes that can be used:</para>
0917 
0918         <itemizedlist>
0919           <listitem>
0920             <para>Set Backlash to 0. Ekos will use a value of 5 * Initial Step
0921             Size.</para>
0922           </listitem>
0923 
0924           <listitem>
0925             <para>Set Backlash &gt; 0. EKOS will use this value in its
0926             backlash calculations. There will probably be instructions with
0927             your focuser for determining the value of Backlash. It is not
0928             necessary to set an exact value for either Linear or Linear 1 Pass
0929             to work correctly; all that is required is that the value set in
0930             Backlash is &gt;= the actual backlash value. For example, if you
0931             measure backlash and get a value around 100, any value &gt;=100
0932             will work equally well. For example, set Backlash = 200.</para>
0933           </listitem>
0934         </itemizedlist>
0935       </listitem>
0936 
0937       <listitem>
0938         <para> <guilabel>Settle</guilabel>: The number of seconds to wait,
0939         after moving the focuser, before starting the next capture. The
0940         purpose is to stop any vibrations in the optical train from affecting
0941         the next frame.</para>
0942       </listitem>
0943 
0944       <listitem>
0945         <para> <guilabel>Out Step Multiple</guilabel>: Used by the Linear and
0946         Linear 1 Pass focus algorithms, this parameter specifies the initial
0947         number of outward steps the focuser takes at the start of a Autofocus
0948         run.</para>
0949       </listitem>
0950 
0951       <listitem>
0952         <para> <guilabel>Capture Timeout</guilabel>: The amount of time in
0953         seconds to wait for a captured image to be received before declaring a
0954         timeout.</para>
0955       </listitem>
0956 
0957       <listitem>
0958         <para> <guilabel>Motion Timeout</guilabel>: The amount of time in
0959         seconds to wait for the focuser to move to the requested position
0960         before declaring a timeout.</para>
0961       </listitem>
0962     </itemizedlist>
0963   </sect3>
0964 
0965   <sect3 id="focus-display">
0966     <title>Focus Display</title>
0967 
0968     <screenshot>
0969       <screeninfo> Focus Display </screeninfo>
0970 
0971       <mediaobject>
0972         <imageobject>
0973           <imagedata fileref="focus_display.png" format="PNG" width="50%"/>
0974         </imageobject>
0975 
0976         <textobject>
0977           <phrase>Focus Display</phrase>
0978         </textobject>
0979       </mediaobject>
0980     </screenshot>
0981 
0982     <para> The focus display, displays a FITS viewer window onto the frame
0983     taken during the focus process. It displays the
0984     <guilabel>Annulus</guilabel> values superimposed on the image. All the
0985     stars detected by Ekos based on the selected parameters, have their HFR
0986     value displayed next to the associated star. </para>
0987 
0988     <para> The window supports the following FITS viewer options (at the top
0989     of the window):</para>
0990 
0991     <itemizedlist>
0992       <listitem>
0993         <para> <guibutton>Zoom In</guibutton> and <guibutton>Zoom
0994         Out</guibutton>.</para>
0995       </listitem>
0996 
0997       <listitem>
0998         <para> <guibutton>Default Zoom</guibutton> and <guibutton>Zoom to
0999         Fit</guibutton>.</para>
1000       </listitem>
1001 
1002       <listitem>
1003         <para> <guibutton>Toggle Stretch</guibutton>: Toggle screen stretch on
1004         or off.</para>
1005       </listitem>
1006 
1007       <listitem>
1008         <para> <guibutton>Toggle Crosshairs</guibutton>: Toggle crosshairs on
1009         or off.</para>
1010       </listitem>
1011 
1012       <listitem>
1013         <para> <guibutton>Toggle Gridlines</guibutton>: Toggle pixel gridlines
1014         on or off.</para>
1015       </listitem>
1016 
1017       <listitem>
1018         <para> <guibutton>Toggle Stars</guibutton>: Toggle star detection on
1019         or off.</para>
1020       </listitem>
1021     </itemizedlist>
1022   </sect3>
1023 
1024   <sect3 id="focus-v-curve">
1025     <title>V-Curve</title>
1026 
1027     <screenshot>
1028       <screeninfo> Focus V-Curve </screeninfo>
1029 
1030       <mediaobject>
1031         <imageobject>
1032           <imagedata fileref="focus_vcurve.png" format="PNG" width="50%"/>
1033         </imageobject>
1034 
1035         <textobject>
1036           <phrase>Focus V-Curve</phrase>
1037         </textobject>
1038       </mediaobject>
1039     </screenshot>
1040 
1041     <para> The V-Curve displays focuser position (x-axis) versus
1042     Half-Flux-Radius (HFR) (y-axis). Each datapoint is drawn on the graph and
1043     represented by a circle with a number representing the datapoint. How many
1044     datapoints are taken and how the focuser moves is determined by the
1045     parameters chosen. </para>
1046 
1047     <para> For certain algorithms, Ekos will also draw a curve of best fit
1048     through the datapoints. If <guilabel>Use Weights</guilabel> is selected
1049     then error bars are indicated on each datapoint that correspond to the
1050     standard deviation in measured HFR value.</para>
1051 
1052     <para> Under the V-Curve a number of parameters are displayed:</para>
1053 
1054     <itemizedlist>
1055       <listitem>
1056         <para> <guilabel>HFR</guilabel>: Displays the star HFR for the most
1057         recent datapoint.</para>
1058       </listitem>
1059 
1060       <listitem>
1061         <para> <guilabel>Stars</guilabel>: The number of stars used for the
1062         most recent datapoint.</para>
1063       </listitem>
1064 
1065       <listitem>
1066         <para> <guilabel>Iteration</guilabel>: The number of datapoints taken
1067         so far.</para>
1068       </listitem>
1069 
1070       <listitem>
1071         <para> <guibutton>HFR</guibutton>: Invokes the <link
1072         linkend="focus-relative-profile">Relative Profile</link> popup.</para>
1073       </listitem>
1074 
1075       <listitem>
1076         <para> <guibutton>Clear Data</guibutton>: Resets the V-Curve graph by
1077         clearing the displayed data.</para>
1078       </listitem>
1079     </itemizedlist>
1080 
1081     <para> When framing, the graph format changes to that of a "time series"
1082     where horizontal axis denotes the frame number. This is to aid you in the
1083     framing process as you can see how HFR changes between frames. </para>
1084 
1085     <screenshot>
1086       <screeninfo> V-Curve as timeseries</screeninfo>
1087 
1088       <mediaobject>
1089         <imageobject>
1090           <imagedata fileref="focus_vcurve_timeseries.png" format="PNG"
1091                      width="50%"/>
1092         </imageobject>
1093 
1094         <textobject>
1095           <phrase>Focus V-Curve Timeseries</phrase>
1096         </textobject>
1097       </mediaobject>
1098     </screenshot>
1099   </sect3>
1100 
1101   <sect3 id="focus-relative-profile">
1102     <title>Relative Profile</title>
1103 
1104     <screenshot>
1105       <screeninfo> Focus Relative Profile </screeninfo>
1106 
1107       <mediaobject>
1108         <imageobject>
1109           <imagedata fileref="focus_relative_profile.png" format="PNG"
1110                      width="50%"/>
1111         </imageobject>
1112 
1113         <textobject>
1114           <phrase>Focus Relative Profile</phrase>
1115         </textobject>
1116       </mediaobject>
1117     </screenshot>
1118 
1119     <para> The relative profile is a graph that displays the relative HFR
1120     values plotted against each other. Lower HFR values correspond to narrower
1121     shapes and vice-versa. The solid red curve is the profile of the current
1122     HFR value, while the dotted green curve is for the previous HFR value.
1123     Finally, the magenta curve denotes the first measured HFR. This enables
1124     you to judge how well the Autofocus process improved the relative focus
1125     quality. </para>
1126   </sect3>
1127 
1128   <sect3 id="How_to_Setup_for_an_Auto_Focus_Run">
1129     <title>How to Setup for an Autofocus Run</title>
1130 
1131     <para> The exact settings that work best for a given astronomical setup
1132     need to be worked out by the user using trial and error, but this section
1133     gives some pointers. It uses the Linear 1 Pass algorithm:</para>
1134 
1135     <itemizedlist>
1136       <listitem>
1137         <para> Start near to focus by manually finding focus. Use the
1138         <guibutton>Start Framing</guibutton> option and manually adjust focus
1139         to get to approximate focus.</para>
1140       </listitem>
1141 
1142       <listitem>
1143         <para> Select Linear 1 Pass and your curve of choice, say Hyperbola.
1144         Select Use Weights.</para>
1145       </listitem>
1146 
1147       <listitem>
1148         <para> Make sure you are finding enough stars.</para>
1149 
1150         <itemizedlist>
1151           <listitem>
1152             <para> Start with the SEP star detection method and the
1153             1-Focus-Default profile unless you have reason to use a different
1154             setup.</para>
1155           </listitem>
1156 
1157           <listitem>
1158             <para> On the Settings tab, use Full Field (rather than Sub Frame)
1159             which will use many stars rather than just one. Select Auto Select
1160             Star to let the system select the stars to use.</para>
1161           </listitem>
1162 
1163           <listitem>
1164             <para> Make sure Annulus is set to use a large amount of frame to
1165             make use of as many stars as possible. Note that there may be
1166             other factors that prevent you using all of the field such as
1167             issues with an un-flat field in the corners of the sensor, but
1168             don’t overdo the restriction.</para>
1169           </listitem>
1170 
1171           <listitem>
1172             <para> Set the camera settings such as exposure, gain and binning
1173             such that you are getting a good number of stars. Its impossible
1174             to be prescriptive here but try for between 20 and 100 (obviously
1175             if your focal length and target can’t find that many then the
1176             process should still work but may be less optimal from a curve
1177             fitting perspective). As a suggestion start with 2 sec exposures,
1178             unity gain for your camera and 1x1 binning.</para>
1179           </listitem>
1180 
1181           <listitem>
1182             <para> Upping the exposure usually finds more stars (but makes the
1183             focus process longer). You can also try taking multiple frames at
1184             the same point by setting the Average Over field &gt; 1
1185             frame.</para>
1186           </listitem>
1187         </itemizedlist>
1188       </listitem>
1189 
1190       <listitem>
1191         <para> Setup the Mechanics tab.</para>
1192 
1193         <itemizedlist>
1194           <listitem>
1195             <para> Setup Backlash. See the Backlash section for more details
1196             but if you do not know the value for your equipment then set to
1197             0.</para>
1198           </listitem>
1199 
1200           <listitem>
1201             <para> Setup Max Travel. This should be appropriate for your
1202             focuser to prevent overextending it. It needs to be big enough to
1203             support the values set in Initial Step Size and Out Step Multiple.
1204             It will need a minimum of just over Initial Step Size * Out Step
1205             Multiple. If you can, set it to, say, double this.</para>
1206           </listitem>
1207 
1208           <listitem>
1209             <para> Settle. If your focuser causes vibration in the optical
1210             train then you need to set this value so that after moving, the
1211             system waits for Settle seconds before taking the next frame. Try
1212             moving the focuser then taking a few frames at the same position.
1213             If the first frame after movement has bigger HFRs than subsequent
1214             frames, then you probably need to up the value in Settle.</para>
1215           </listitem>
1216 
1217           <listitem>
1218             <para> Out Step Multiple. Start with 4 or 5. This will give you
1219             9-10 or 11-12 datapoints which is a good place to start. You need
1220             enough datapoints to form a curve, but the more you have the
1221             longer the process will take to complete.</para>
1222           </listitem>
1223 
1224           <listitem>
1225             <para> Initial Step Size. The following shows a “good curve”.
1226             There is significant movement in the HFR axis to clearly
1227             demonstrate the curve, in this case max HFR is about 2.2 whilst
1228             min is 0.75 which gives a max / min of about 3.</para>
1229 
1230             <screenshot>
1231               <screeninfo> Good Focus Curve </screeninfo>
1232 
1233               <mediaobject>
1234                 <imageobject>
1235                   <imagedata fileref="focus_good_focus.png" format="PNG"
1236                              width="50%"/>
1237                 </imageobject>
1238 
1239                 <textobject>
1240                   <phrase>Good Focus Curve</phrase>
1241                 </textobject>
1242               </mediaobject>
1243             </screenshot>
1244           </listitem>
1245 
1246           <listitem>
1247             <para> In contrast, the next picture shows an Initial Step Size
1248             that has been set too low. The HFR varies from about 0.78 to 0.72.
1249             Which gives a max / min just over 1. The other clue that this is a
1250             poor setup is that the Error Bar range is very large compared to
1251             HFR movement which means that the curve solver is drawing a curve
1252             through a lot of noise, which means the results will not be very
1253             accurate.</para>
1254 
1255             <screenshot>
1256               <screeninfo> Bad Focus Curve </screeninfo>
1257 
1258               <mediaobject>
1259                 <imageobject>
1260                   <imagedata fileref="focus_bad_focus.png" format="PNG"
1261                              width="50%"/>
1262                 </imageobject>
1263 
1264                 <textobject>
1265                   <phrase>Bad Focus Curve</phrase>
1266                 </textobject>
1267               </mediaobject>
1268             </screenshot>
1269           </listitem>
1270         </itemizedlist>
1271       </listitem>
1272     </itemizedlist>
1273   </sect3>
1274 
1275   <sect3 id="Coefficient_of_Determination">
1276     <title>Coefficient of Determination, R²</title>
1277 
1278     <para> The Coefficient of Determination, or R², is calculated in order to
1279     give a measure of how well the fitted curve matches the datapoints. More
1280     information is available <ulink
1281     url="https://en.wikipedia.org/wiki/Coefficient_of_determination">here</ulink>.
1282     This is an experimental feature that is available for the Linear 1 Pass
1283     focus algorithm. In essence, R² gives a value between 0 and 1, with 1
1284     meaning a perfect fit where all datapoints sit on the curve, and 0 meaning
1285     that there is no correlation between the datapoints and the curve. The
1286     user should experiment with their equipment to see what values they can
1287     obtain, but as a guide, a value above, say 0.8 would be a good fit.</para>
1288 
1289     <para> There is an option to set an “R² Limit” in the Settings tab of the
1290     Focus window that is compared to the calculated R² after the auto focus
1291     run has completed. If the limit value has not been achieved, then the auto
1292     focus is rerun.</para>
1293 
1294     <para> Setting an R² Limit could be useful for unattended observation if
1295     the focus run produces a bad result for a 1-off reason. Obviously if the
1296     reason is not transitory then rerunning will not improve anything.</para>
1297 
1298     <para> If the R² Limit is not achieved and the focus process is rerun, and
1299     again fails to achieve the R² Limit, then the focus run is marked as
1300     successful to avoid the process getting stuck rerunning auto focus
1301     forever.</para>
1302 
1303     <para> This feature is turned off by setting the R² Limit to 0.</para>
1304   </sect3>
1305 
1306   <sect3 id="Levenberg-Marquardt">
1307     <title>Levenberg–Marquardt Solver</title>
1308 
1309     <para> The Levenberg-Marquardt (LM) algorithm is used to solve non-linear
1310     least squares problems. The GNU Science Library provides an implementation
1311     of the solver. These resources provide more details: </para>
1312 
1313     <itemizedlist>
1314       <listitem>
1315         <para>
1316           <ulink url="https://en.wikipedia.org/wiki/Levenberg–Marquardt_algorithm"/>
1317         </para>
1318       </listitem>
1319 
1320       <listitem>
1321         <para>
1322           <ulink url="https://www.gnu.org/software/gsl/doc/html/nls.html"/>
1323         </para>
1324       </listitem>
1325     </itemizedlist>
1326 
1327     <para> The Levenberg-Marquardt algorithm is a new feature added for the
1328     Linear 1 Pass focus algorithm. It is a non-linear least-squares solver and
1329     thus suitable for many different equations. The basic idea is to adjust
1330     the equation y = f(x,P) so that the computed y values are as close as
1331     possible to the y values of the datapoints provided, so that the resultant
1332     curve fits the data as best as it can. P is a set of parameters that are
1333     varied by the solver in order to find the best fit. The solver measures
1334     how far away the curve is at each data point, squares the result and adds
1335     them all up. This is the number to be minimized, let's call it S. The
1336     solver is supplied with an initial guess for the parameters, P. It
1337     calculates S, makes an adjustment to P and calculates a new S1. Provided
1338     S1 &lt; S then we are moving in the right direction. It iterates through
1339     the procedure until:</para>
1340 
1341     <itemizedlist>
1342       <listitem>
1343         <para> the delta in S is less than a supplied limit (convergence has
1344         been reached), or</para>
1345       </listitem>
1346 
1347       <listitem>
1348         <para> the maximum number of iterations has been reached, or</para>
1349       </listitem>
1350 
1351       <listitem>
1352         <para> the solver encountered an error.</para>
1353       </listitem>
1354     </itemizedlist>
1355 
1356     <para> The solver is capable of solving either an unweighted or weighted
1357     set of datapoints. In essence, an unweighted set of data gives equal
1358     weight to each datapoint when trying to fit a curve. An alternative is to
1359     weight each datapoint with a measure that corresponds to how accurate the
1360     measurement of the datapoint actually is. In our case this is the variance
1361     of star HFRs associated with the datapoint. The variance is the standard
1362     deviation squared.</para>
1363 
1364     <para> Currently the solver is used to fit either a parabolic or a
1365     hyperbolic curve.</para>
1366   </sect3>
1367 </sect2>