<?xml version="1.0" encoding="UTF-8"?>
<sect2 id="ekos-focus">
  <title>Focus</title>

  <indexterm>
    <primary>Tools</primary>

    <secondary>Ekos</secondary>

    <tertiary>Focus</tertiary>
  </indexterm>

  <sect3 id="focus-theory">
    <title>Theory Of Operation</title>

    <screenshot>
      <screeninfo> Ekos Focus </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="ekos_focus.png" format="PNG" width="75%"/>
        </imageobject>

        <textobject>
          <phrase>Ekos Focus</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> In order to focus an image, Ekos needs to establish a numerical
    method for gauging how <emphasis>good</emphasis> your focus is. It's easy
    when you look at an image and can see it as
    <emphasis>unfocused</emphasis>, as the human eye is very good at detecting
    that, but <emphasis>how</emphasis> can Ekos possibly know that? </para>

    <para> There are multiple methods. One is to calculate the Full Width at
    Half Maximum (FHWM) of a star profile within an image, and then adjust the
    focus until an optimal (narrower) FWHM is reached. The problem with FWHM
    is that it assumes the initial focus position to be close to the critical
    focus. Additionally, FWHM does not perform very well under low-intensity
    fluxes. An Alternative method is Half-Flux-Radius (HFR), which is a
    measure of the width in pixels counting from the center of the star until
    the accumulated intensity is half of the total flux of the star. HFR
    proved to be much more stable in conditions where you might have
    unfavorable sky conditions, when the brightness profile of the stars is
    low, and when the starting position of the focus is far from the optimal
    focus. </para>

    <para> After Ekos processes an image, it selects either a single star and
    starts measuring its HFR, or it selects a set of stars matching the
    criteria that have been set and calculates an average HFR. It can
    automatically select stars, or you can select a single star manually. It
    is recommended to allow Ekos to select a set of stars. </para>

    <para> Ekos supports 4 different focus algorithms: Iterative, Polynominal,
    Linear and Linear 1 Pass. </para>

    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">Iterative</emphasis>: In the Iterative
        algorithm, Ekos operates iteratively by moving in discrete steps,
        decided initially by the user-configurable step size and later by the
        slope of the V-Curve, to get closer to the optimal focus position
        where it then changes gears and performs smaller, finer moves to reach
        the optimal focus. The focus process stops when the measured HFR is
        within the configurable tolerance of the minimum recorded HFR in the
        process. In other words, whenever the process starts searching for a
        solution within a narrowly limited range, it checks if the current HFR
        is within % difference compared to the minimum HFR recorded, and if
        this condition is met then the Autofocus process is considered
        successful. The default value is set to 1% and is sufficient for most
        situations. The Step options specify the number of initial ticks the
        focuser has to move. If the image is severely out of focus, we set the
        step size high (i.e. greater than 250). On the other hand, if the
        focus is close to optimal focus, we set the step size to a more
        reasonable range (less than 50). It takes trial and error to find the
        best starting tick, but Ekos only uses that for the first focus
        motion, as all subsequent motions depend on the V-Curve slope
        calculations. Key features include:</para>

        <itemizedlist>
          <listitem>
            <para> The algorithm relies on the focuser having well controlled
            backlash. </para>
          </listitem>

          <listitem>
            <para> The algorithm can be fast using a minimum number of steps.
            </para>
          </listitem>

          <listitem>
            <para> The algorithm works on a "good enough" paradigm whereby it
            stops when the HFR is within % Tolerance of the perceived minimum.
            </para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Polynomial</emphasis>: In the Polynomial
        algorithm, the process starts off in Iterative mode, but once we cross
        to the other side of the V-Curve (once HFR values start increasing
        again after decreasing for a while), then Ekos performs quadratic
        curve fitting to find a solution that predicts the minimum possible
        HFR position. Key features include:</para>

        <itemizedlist>
          <listitem>
            <para> The algorithm relies on the focuser having well controlled
            backlash. </para>
          </listitem>

          <listitem>
            <para> The algorithm can be fast using a minimum number of steps.
            </para>
          </listitem>

          <listitem>
            <para> The algorithm uses curve fitting to pinpoint the optimum
            focus position. </para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Linear</emphasis>: In the Linear
        algorithm, Ekos steps outward from its starting point then moves
        inward taking regular datapoints through the point of optimum focus
        and then further inward, to draw a V-Curve. It then fits a quadratic
        curve to the datapoints and calculates the point of optimum focus. It
        then moves out again past the point of optimum focus, halves the
        stepsize and moves in again for a second pass. It looks to follow the
        curve from the first pass and find the minimum HFR. Due to randomness
        in the HFR measurements it uses the % tolerance to help decide when it
        has found a solution. Key features include: </para>

        <itemizedlist>
          <listitem>
            <para> The algorithm compensates for focuser backlash and can deal
            with both consistent and inconsistent backlash. </para>
          </listitem>

          <listitem>
            <para> The algorithm is slow, taking 2 passes to identify optimum
            focus. </para>
          </listitem>

          <listitem>
            <para> The algorithm uses curve fitting to pinpoint the optimum
            focus position in pass 1, but then uses % Tolerance to try to stop
            as close as possible to this HFR on pass 2. </para>
          </listitem>

          <listitem>
            <para> The algorithm is highly configurable with user control over
            many parameters like step size and number of steps. </para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Linear 1 Pass</emphasis>: In the Linear 1
        Pass algorithm, Ekos initially performs like the Linear algorithm in
        establishing the first pass V-Curve and fitting a curve to it to find
        the solution. Then, however, it moves directly to the calculated
        minimum. Key features include: </para>

        <itemizedlist>
          <listitem>
            <para> The algorithm compensates for focuser backlash, providing
            that backlash is consistent. </para>
          </listitem>

          <listitem>
            <para> The algorithm is fast, taking 1 pass to identify optimum
            focus. </para>
          </listitem>

          <listitem>
            <para> The algorithm uses more sophisticated curve fitting to
            pinpoint the optimum focus position. </para>
          </listitem>

          <listitem>
            <para> The algorithm is highly configurable with user control over
            many parameters like step size and number of steps. </para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="optical-train-group">
    <title>Optical Train Group</title>

    <screenshot>
      <screeninfo> Optical Train </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="optical_train_group.png" format="PNG"
                     width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Optical Train Settings</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> The Optical Train group displays the currently selected Optical
    Train. By default this will be the primary imaging train, but other trains
    can be selected. The group consists of:</para>

    <itemizedlist>
      <listitem>
        <para> <guibutton>Train</guibutton>: The Optical Train currently in
        use by the Focus tab. Hover the mouse over this field for a more
        detailed description of the selected train.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Edit Button</guibutton>: Brings up the Optical Train
        dialog to view and potentially change the optical trains.</para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-focuser-group">
    <title>Focuser Group</title>

    <screenshot>
      <screeninfo> Focuser Settings </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focuser_group.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focuser Settings</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> All INDI-compatible focusers are supported. It is recommended to
    use <emphasis role="bold">absolute</emphasis> focusers for the best
    results since their absolute position is known on power up. In INDI, the
    focuser <emphasis>zero</emphasis> position is when the drawtube is
    <emphasis role="bold">fully retracted</emphasis>. When focusing
    <emphasis>outwards</emphasis>, the focuser position increases, while it
    decreases when focusing <emphasis>inwards</emphasis>. The following
    focuser types are supported: </para>

    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">Absolute</emphasis>: Absolute Position
        Focusers such as RoboFocus, MoonLite, ASI ZWO </para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Relative</emphasis>: Relative Position
        Focusers. </para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Time Based</emphasis>: Time based
        focusers with no position feedback that adjust focus position by
        moving for a certain amount of time. </para>
      </listitem>
    </itemizedlist>

    <para> Start off by selecting the Focuser from the dropdown. </para>

    <para> For absolute focusers, you can set the ticks count in the Initial
    Steps Size field in the <link linkend="focus-mechanics">Mechanics</link>
    tab. For absolute and relative focusers, the step size is in units of
    <emphasis>ticks</emphasis> and for simple, or time based, focusers, the
    step size is in <emphasis>milliseconds</emphasis>. The
    <guibutton>In</guibutton> and <guibutton>Out</guibutton> buttons can then
    be used to move the focuser by this number of ticks.</para>

    <para> The Steps fields will initially contain the starting point in ticks
    for the focuser. As the focuser moves, the left field will update to
    reflect the focuser's current position. The right field will initially
    contain the starting position of the focuser but will update each time a
    successful Autofocus run completes, to keep a last good focus position. In
    addition you can set the right field to whatever value you like, and use
    the <guibutton>Goto</guibutton> button to move the focuser to this
    position.</para>

    <para> The <guibutton>Goto Focus Position</guibutton> button moves the
    focuser to the position in the righthand Steps field. </para>

    <para> The <guibutton>Stop Focuser Motion</guibutton> button stops the
    in-progress focuser motion. </para>

    <para> The <guibutton>Auto Focus</guibutton> button starts an Autofocus
    run. The <guibutton>Stop</guibutton> button is used to stop the run.
    </para>

    <para> The <guibutton>Capture Image</guibutton> button will take a frame
    based on the current settings in the <guilabel>CCD and Filter
    Wheel</guilabel> group. The <guibutton>Start Framing</guibutton> button
    will start repeatedly capturing frames until the
    <guibutton>Stop</guibutton> button is pressed. </para>

    <para> Some of the focus algorithms will attempt to cope with being
    started away from the point of optimum focus, but for predictable results,
    it is best to start from a position of being approximately in focus. For
    first time setup, <guibutton>Start Framing</guibutton> can be used along
    with the <guibutton>In</guibutton> and <guibutton>Out</guibutton> buttons
    to adjust the focus position to roughly minimize the HFR of the stars in
    the captured images. When Framing is used in this way, the <link
    linkend="focus-v-curve">V-Curve</link> graph changes to show a time series
    of frames and their associated HFRs. This makes the framing process much
    easier to perform.</para>

    <para> If you are completely new to astronomy, it is always a good idea to
    get familiar with your equipment in daylight. This includes getting the
    approximate focus position on a distant object. This will provide a good
    starting position for focusing on stars when nighttime comes.</para>
  </sect3>

  <sect3 id="focus-ccd-filter-wheel">
    <title>Camera &amp; Filter Wheel Group</title>

    <screenshot>
      <screeninfo> Focus Camera &amp; Filter Wheel Group </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_ccdfw_group.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Camera &amp; Filter Wheel Group</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> This section of parameters deals with the Camera and Filter
    settings to use when focusing.</para>

    <para> The top row of controls allows CCD parameters to be set.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Exp</guilabel>: The exposure time in seconds.</para>
      </listitem>

      <listitem>
        <para> The <guibutton>Toggle Full Screen</guibutton> button pops the
        window displaying the focus frame out to a separate window. Pressing
        it again returns it within the focus window.</para>
      </listitem>

      <listitem>
        <para> The <guibutton>Show in FITS Viewer</guibutton> button pops-up a
        separate FITS Viewer window to display the focus frame, in addition to
        the focus frame displayed within the focus window.</para>
      </listitem>

      <listitem>
        <para> The <guibutton>Live Video</guibutton> button brings up the
        associated popup.</para>
      </listitem>
    </itemizedlist>

    <para> The next row of controls allows Camera parameters to be set. Choose
    a value from the binning dropdown and then set either the camera gain or
    ISO.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Binning</guilabel>: Increasing the binning will
        change the image scale as well as resulting in brighter pixels. A good
        place to start would be 1x1 and then see whether better results can be
        obtained by binning at higher levels such as 2x2 or 4x4.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Gain</guilabel>: Set the Gain for the Camera being
        used to focus. The value needs to be high enough to give a clear star
        pattern but not so high as to create too much noise to interfere with
        the focus operation. Some experimentation will be required to find an
        optimum value. If you are unsure where to start try unity gain for
        your camera and adjust from there.</para>
      </listitem>

      <listitem>
        <para> <guilabel>ISO</guilabel>: Set the ISO for the Camera being used
        to focus. Some experimentation will be required to find an optimum
        value.</para>
      </listitem>
    </itemizedlist>

    <para> The third row of controls deals with the Temperature Source and
    Filter, if there is one:</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>TS</guilabel>: Select the temperature source from the
        dropdown. Underneath are displayed the current temperature from the
        selected temperature source and the change in temperature between when
        the last successful Autofocus run completed and the current
        temperature. It is common practice to redo focus after significant
        temperature changes that alter the telescope's focus point.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Filter</guilabel>: Select the filter to use.</para>

        <para>To start focusing it will probably be easier to select the
        filter that allows the most light through, for example the Lum filter.
        The <guibutton>Filter Settings</guibutton> button brings up the <link
        linkend="capture-filter-settings">Filter Settings</link> popup. This
        allows a number of parameters to be set per filter to be used during
        an Autofocus run which could be unattended so a user would not be
        available to set parameters at run time. Broadly these allow two types
        of focus runs:</para>

        <itemizedlist>
          <listitem>
            <para> <emphasis role="bold">Per Filter</emphasis>: When another
            module, for example, the Capture module requires a filter change,
            it is possible to automatically refocus for the new filter. The
            exposure to use for each filter is taken from the <link
            linkend="capture-filter-settings">Filter Settings</link> popup.
            This is very useful where, for example, narrowband filter require
            longer exposure times than broadband filters.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Lock Filter</emphasis>: It is
            possible to specify a Lock filter to use when it is required to
            focus another filter. For example, if a Red filter is used and an
            Autofocus run required, it is possible to run the Autofocus using
            the Lum filter and then, when complete, adjust the focus position
            by an Offset value corresponding to the predetermined focus
            difference between the Lum and Red filters. This is useful when,
            for example, it is difficult to focus some filters directly
            without excessively long exposure times. Note that this locked
            filter approach may also be used in the <link
            linkend="ekos-align">Alignment Module</link> whenever it performs
            a capture for astrometry.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <guibutton>Reset</guibutton> button will reset the focusing
        subframe to full frame.</para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-settings">
    <title>Focus Settings</title>

    <screenshot>
      <screeninfo> Focus Settings </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_settings.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Settings</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> Next are 3 tabbed panes of parameters. These parameters are
    retained between sessions. First up is the Settings pane.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Auto Select Star</guilabel>: Allow Ekos to select the
        focus star(s) from the image. If not selected then the user will have
        to manually select a star.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Dark Frame</guilabel>: Check this option to perform
        dark-frame subtraction. This option can be useful in noisy images,
        where a pretaken dark is subtracted from the focus image before
        further processing.</para>

        <para> Dark frames are used by Focus, Alignment and Guiding. See the
        Dark Library feature within the <link linkend="ekos-capture">Capture
        Module</link> for more details on how to setup Dark Frames.</para>
      </listitem>

      <listitem>
        <para> <guilabel>AF Backlash Comp</guilabel>: Check this option to
        have the Autofocus algorithm perform backlash compensation. This
        option is available when using the Linear and Linear 1 Pass
        algorithms. This field should be set together with the
        <guilabel>Backlash</guilabel> field. See the <link
        linkend="focus-mechanics">Focus Mechanics</link> section for more
        details.</para>

        <para>Backlash in the focuser setup is likely to a combination of
        backlash in the electronic focuser itself (e.g. in the gearing
        mechanism), in the binding of the electronic focuser to the telescope
        drawtube, and in the telescope drawtube's mechanism. Thus, each setup
        will have its own backlash characteristic.</para>

        <para> There are several things to consider when working out how to
        deal with backlash: <itemizedlist>
            <listitem>
              <para> <emphasis role="bold">No Backlash</emphasis>: If you are
              fortunate enough to have a setup with no backlash then it would
              make sense to set AF Backlash Comp off. It should work fine if
              AF Backlash Comp is on, but the AutoFocus routine will make
              unnecessary movements.</para>
            </listitem>

            <listitem>
              <para> <emphasis role="bold">Backlash Managed by
              Focuser</emphasis>: If your focuser had the ability to manage
              backlash itself then you can use this facility and turn off AF
              Backlash Comp. Alternatively, if it's possible, you could turn
              off the focuser's backlash facility and set AF Backlash Comp
              on.</para>
            </listitem>

            <listitem>
              <para> <emphasis role="bold">Backlash Managed by Device
              Driver</emphasis>: If your device driver had the ability to
              manage backlash itself then you can use this facility and turn
              off AF Backlash Comp. Alternatively, if it's possible, you could
              turn off the device driver's backlash facility and set AF
              Backlash Comp on.</para>
            </listitem>
          </itemizedlist> </para>

        <para>It is important to have backlash managed in one place to avoid
        conflicts.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Sub Frame</guilabel>: Either use the Full Field of
        the camera or select a Subframe around the focus star during the
        Autofocus procedure. This is only relevant if a single star is used
        for focusing. Enabling subframing can speed up the focus
        process.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Box</guilabel>: Sets the box size used to enclose the
        focus star when using <emphasis role="bold">Sub Frame</emphasis>.
        Increase if you have very large stars. For Bahtinov focus the box size
        can be increased even more to better enclose the Bahtinov diffraction
        pattern.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Full Field</guilabel>: Either use the full field of
        the camera or select a Sub Frame around the focus star during the
        Autofocus procedure. If using multiple stars then this option must be
        selected.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Annulus</guilabel>: Used in conjunction with Full
        Field, Annulus provides two input fields that together define a
        doughnut over the FOV of the camera. Stars falling outside of the
        doughnut are discounted from processing. Setting an inner value above
        0% causes stars in the centre of the FOV to be discarded. This could
        be useful to avoid using stars in the target of the image (for example
        a galaxy) for focusing purposes. Setting an outer value below 100%
        causes stars in the edges of the FOV to be discarded during focusing.
        This could be useful if you do not have a flat field out to the edges
        of your FOV.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Suspend Guiding</guilabel>: Set this option to
        suspend guiding during an Autofocus run. An additional check is made
        to only suspend guiding if it is being carried out via the primary
        scope, for example when using an Off Axis Guider. The purpose of this
        is to prevent guiding from having problems with defocused stars during
        the focus process.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Settle</guilabel>: This option is used in conjunction
        with <guilabel>Suspend Guiding</guilabel>. It allows any vibrations in
        the optical train to settle by waiting this many seconds after the
        Autofocus process has completed, before restarting guiding.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Use Weights</guilabel>: This is an experimental
        option only available with the Linear 1 Pass focus algorithm and Curve
        Types of Hyperbola and Parabola. It requires Full Field to be
        selected. The option calculates the standard deviation of star HFRs
        and uses the square of this (mathematically the variance) as a
        weighting in the curve fitting process. The advantage of this is that
        datapoints with less reliable data and therefore larger HFR standard
        deviations will be given less weight than more reliable datapoints. If
        this option is unchecked, and for all other curve fitting where the
        option is not allowed, all datapoints are given equal weight in the
        curve fitting process. </para>

        <para> See the <link linkend="Levenberg-Marquardt">Levenberg-Marquardt
        Solver</link> for more details.</para>
      </listitem>

      <listitem>
        <para> <guilabel>R² Limit</guilabel>: This is an experimental option
        only available with the Linear 1 Pass focus algorithm and Curve Types
        of Hyperbola and Parabola. As part of the Linear 1 Pass algorithm, the
        degree to which the curve fits the datapoints, or <link
        linkend="Coefficient_of_Determination">Coefficient of Determination,
        R²</link>, is calculated. This option allows a minimum acceptable
        value of R² to be defined that is compared to the value obtained from
        the curve fitting process. If the minimum value has not been achieved
        then Autofocus will rerun. Only one rerun will be performed and even
        if the minimum R² has not been met the second time, the Autofocus run
        will still be deemed successful.</para>

        <para> Experiment to find an appropriate value but a good starting
        point would be 0.8 or 0.9</para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-process">
    <title>Focus Process</title>

    <screenshot>
      <screeninfo> Focus Process </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_process.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Process</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> This is the Focus Process parameters pane.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Detection</guilabel>: Select star detection
        algorithm. Each algorithm has its strengths and weaknesses. It is
        recommended to keep the default value, SEP, unless it fails to
        properly detect stars. The following are available:</para>

        <itemizedlist>
          <listitem>
            <para> <emphasis role="bold">SEP</emphasis>: Source Extraction and
            Photometry built in library. This is the default value.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Centroid</emphasis>: An extraction
            method based on estimating star mass around signal peaks.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Gradient</emphasis>: A single source
            extraction model based on the Sobel filter. </para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Threshold</emphasis>: A single source
            detection algorithm based on pixel values. </para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Bahtinov</emphasis>: This detection
            method can be used when using a Bahtinov mask for focusing. First
            take an image, then select the star to focus on. A new image will
            be taken and the diffraction pattern will be analysed. Three lines
            will be displayed on the diffraction pattern showing how well the
            pattern is recognized and how good the image is in focus. When the
            pattern is not well recognized, the <emphasis>Num. of
            rows</emphasis> parameter can be adjusted to improve recognition.
            The line with the circles at each end is a magnified indicator for
            the focus. The shorter the line, the better the image is in
            focus.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <guilabel>SEP Profile</guilabel>: If the star detection
        algorithm is set to <emphasis>SEP</emphasis>, then choose a parameter
        profile to use with the algorithm. It is recommended to use the
        default 1-Focus-Default profile as a starting point.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Threshold</guilabel>: Threshold percentage value is
        used for star detection using the <emphasis>Threshold</emphasis>
        detection algorithm. Increase to restrict the centroid to bright
        cores. Decrease to enclose fuzzy stars.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Algorithm</guilabel>: Select the Autofocus process
        algorithm: </para>

        <itemizedlist>
          <listitem>
            <para> <emphasis role="bold">Iterative</emphasis>: Moves focuser
            by discreet steps initially decided by the step size. Once a curve
            slope is calculated, further step sizes are calculated to reach an
            optimal solution. The algorithm stops when the measured HFR is
            within <emphasis role="bold">Tolerance</emphasis> of the minimum
            HFR recorded in the procedure.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Polynomial</emphasis>: Starts with
            the iterative method. Upon crossing to the other side of the
            V-Curve, polynomial fitting coefficients along with possible
            minimum solution are calculated. This algorithm can be faster than
            a purely iterative approach given a good data set.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Linear</emphasis>: This algorithm
            builds a V-Curve with approximately <emphasis role="bold">Out step
            Multiple</emphasis> steps on each side of the minimum. Having
            built the V-Curve it then fits a quadratic equation to the curve
            (parabolic shape) and uses this to calculate the focuser position
            giving the minimum HFR. Having identified the minimum it then
            performs a 2nd pass halving the step size, recreating the curve
            from the 1st pass. It attempts to stop within <emphasis
            role="bold">Tolerance</emphasis> of the minimum HFR calculated
            during the 1st pass.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Linear 1 Pass</emphasis>: This
            algorithm starts in the same way as <emphasis
            role="bold">Linear</emphasis> building a V-Curve. Having built the
            V-Curve it then fits the <emphasis role="bold">Curve
            Fit</emphasis> type to the datapoints and then calculates the
            focuser position giving the minimum HFR. Having identified the
            minimum it then moves directly to that point in a way designed to
            neutralise backlash.</para>

            <para> This algorithm supports the older style Quadratic curve
            type as well as the newer <link
            linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link>
            for Hyperbolic and Parabolic curves. It will also weight the
            datapoints in the curve fitting process if Use Weights is
            checked.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <guilabel>Effect</guilabel>: You may select an
        <guilabel>Effect</guilabel> filter to enhance the image for preview
        purposes. It is highly advisable to turn off any effects during the
        focusing process as it may interfere with HFR calculations. For DSLR
        cameras, you can change the ISO settings.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Tolerance</guilabel>: The tolerance percentage value
        is used to help decide when the Autofocus process stops in the
        <guilabel>Iterative</guilabel> and <guilabel>Linear</guilabel>
        algorithms. During the Autofocus process, HFR values are recorded, and
        once the focuser is close to an optimal position, it starts measuring
        HFRs against the minimum recorded HFR in the sessions and stops
        whenever a measured HFR value is within % difference of the minimum
        recorded HFR. Decrease the value to narrow the optimal focus point
        solution radius. Increase to expand solution radius. </para>

        <warning>
          <para> Setting the value too low might result in a repetitive loop
          and would most likely result in a failed Autofocus process. </para>
        </warning>
      </listitem>

      <listitem>
        <para> <guilabel>Kernel Size</guilabel>: The kernel size of the
        gaussian blur applied to the image before applying Bahtinov edge
        detection. Used when <emphasis role="bold">Detection</emphasis> is
        Bahtinov.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Average over</guilabel>: Number of frames to capture
        at each datapoint. It is usually sensible to start with 1 but
        increasing this will result in an averaging process over the star
        HFRs.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Sigma</guilabel>: The sigma of the gaussian blur
        applied to the image before applying Bahtinov edge detection. Used
        when <emphasis role="bold">Detection</emphasis> is Bahtinov.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Num. of rows</guilabel>: The number of lines
        displayed on screen when using a Bahtinov mask. Used when <emphasis
        role="bold">Detection</emphasis> is Bahtinov.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Curve Fit</guilabel>: The type of curve to fit to the
        datapoints. </para>

        <itemizedlist>
          <listitem>
            <para> <emphasis role="bold">Quadratic</emphasis>: Uses a
            quadratic equation using a linear style least squares algorithm
            supplied by GSL (GNU Science Library). This is, in effect, a
            parabolic curve.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Hyperbola</emphasis>: Fits a
            Hyperbola using a non-linear least squares algorithm supplied by
            GSL (GNU Science Library). See <link
            linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link>
            for more details.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Parabola</emphasis>: Fits a Parabola
            using a non-linear least squares algorithm supplied by GSL (GNU
            Science Library). See <link
            linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link>
            for more details.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-mechanics">
    <title>Focus Mechanics</title>

    <screenshot>
      <screeninfo> Focus Mechanics </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_mechanics.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Mechanics</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> This is the Focus Mechanics parameters pane.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Initial Step size</guilabel>: This sets the step size
        to be used by various focus algorithms. For absolute and relative
        focusers this is the number of ticks; for timer based focusers this is
        the number of milliseconds.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Max Travel</guilabel>: Puts bounds on the amount of
        travel from the current focuser position that is permitted by the
        Autofocus algorithms. The purpose is to protect the focuser from
        travelling too far and potentially damaging itself. On the other hand,
        the value needs to be big enough to allow sufficient focuser motion to
        permit the auto focus runs to complete.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Max Step size</guilabel>: Used by the Iterative focus
        algorithm to limit the maximum step size that can be used.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Backlash</guilabel>: All mechanical devices with
        gears suffer from backlash. In a typical focuser there will be a dead
        zone where changing direction (e.g. from “in” to “out”) results in
        movement of the focuser by a few ticks, but no actual movement of the
        optical train.</para>

        <para>The Linear 1 Pass algorithm (like the Linear algorithm) provides
        backlash compensation in the 2 places during an auto focus run when
        the focuser moves outwards:</para>

        <itemizedlist>
          <listitem>
            <para> The initial outward movement of Initial Step Size * Out
            Step Multiple at the start of the run.</para>
          </listitem>

          <listitem>
            <para> When the inward pass is complete and Ekos has determined
            the best focus position and moves outward to it.</para>
          </listitem>
        </itemizedlist>

        <para> Linear 1 Pass will extend (by x ticks) the outward movement,
        and then, as a separate movement it will move inward by x ticks. So it
        always approaches the desired position in an inward direction.</para>

        <para>There are 2 schemes that can be used:</para>

        <itemizedlist>
          <listitem>
            <para>Set Backlash to 0. Ekos will use a value of 5 * Initial Step
            Size.</para>
          </listitem>

          <listitem>
            <para>Set Backlash &gt; 0. EKOS will use this value in its
            backlash calculations. There will probably be instructions with
            your focuser for determining the value of Backlash. It is not
            necessary to set an exact value for either Linear or Linear 1 Pass
            to work correctly; all that is required is that the value set in
            Backlash is &gt;= the actual backlash value. For example, if you
            measure backlash and get a value around 100, any value &gt;=100
            will work equally well. For example, set Backlash = 200.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <guilabel>Settle</guilabel>: The number of seconds to wait,
        after moving the focuser, before starting the next capture. The
        purpose is to stop any vibrations in the optical train from affecting
        the next frame.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Out Step Multiple</guilabel>: Used by the Linear and
        Linear 1 Pass focus algorithms, this parameter specifies the initial
        number of outward steps the focuser takes at the start of a Autofocus
        run.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Capture Timeout</guilabel>: The amount of time in
        seconds to wait for a captured image to be received before declaring a
        timeout.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Motion Timeout</guilabel>: The amount of time in
        seconds to wait for the focuser to move to the requested position
        before declaring a timeout.</para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-display">
    <title>Focus Display</title>

    <screenshot>
      <screeninfo> Focus Display </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_display.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Display</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> The focus display, displays a FITS viewer window onto the frame
    taken during the focus process. It displays the
    <guilabel>Annulus</guilabel> values superimposed on the image. All the
    stars detected by Ekos based on the selected parameters, have their HFR
    value displayed next to the associated star. </para>

    <para> The window supports the following FITS viewer options (at the top
    of the window):</para>

    <itemizedlist>
      <listitem>
        <para> <guibutton>Zoom In</guibutton> and <guibutton>Zoom
        Out</guibutton>.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Default Zoom</guibutton> and <guibutton>Zoom to
        Fit</guibutton>.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Toggle Stretch</guibutton>: Toggle screen stretch on
        or off.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Toggle Crosshairs</guibutton>: Toggle crosshairs on
        or off.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Toggle Gridlines</guibutton>: Toggle pixel gridlines
        on or off.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Toggle Stars</guibutton>: Toggle star detection on
        or off.</para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-v-curve">
    <title>V-Curve</title>

    <screenshot>
      <screeninfo> Focus V-Curve </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_vcurve.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus V-Curve</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> The V-Curve displays focuser position (x-axis) versus
    Half-Flux-Radius (HFR) (y-axis). Each datapoint is drawn on the graph and
    represented by a circle with a number representing the datapoint. How many
    datapoints are taken and how the focuser moves is determined by the
    parameters chosen. </para>

    <para> For certain algorithms, Ekos will also draw a curve of best fit
    through the datapoints. If <guilabel>Use Weights</guilabel> is selected
    then error bars are indicated on each datapoint that correspond to the
    standard deviation in measured HFR value.</para>

    <para> Under the V-Curve a number of parameters are displayed:</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>HFR</guilabel>: Displays the star HFR for the most
        recent datapoint.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Stars</guilabel>: The number of stars used for the
        most recent datapoint.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Iteration</guilabel>: The number of datapoints taken
        so far.</para>
      </listitem>

      <listitem>
        <para> <guibutton>HFR</guibutton>: Invokes the <link
        linkend="focus-relative-profile">Relative Profile</link> popup.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Clear Data</guibutton>: Resets the V-Curve graph by
        clearing the displayed data.</para>
      </listitem>
    </itemizedlist>

    <para> When framing, the graph format changes to that of a "time series"
    where horizontal axis denotes the frame number. This is to aid you in the
    framing process as you can see how HFR changes between frames. </para>

    <screenshot>
      <screeninfo> V-Curve as timeseries</screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_vcurve_timeseries.png" format="PNG"
                     width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus V-Curve Timeseries</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
  </sect3>

  <sect3 id="focus-relative-profile">
    <title>Relative Profile</title>

    <screenshot>
      <screeninfo> Focus Relative Profile </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_relative_profile.png" format="PNG"
                     width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Relative Profile</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> The relative profile is a graph that displays the relative HFR
    values plotted against each other. Lower HFR values correspond to narrower
    shapes and vice-versa. The solid red curve is the profile of the current
    HFR value, while the dotted green curve is for the previous HFR value.
    Finally, the magenta curve denotes the first measured HFR. This enables
    you to judge how well the Autofocus process improved the relative focus
    quality. </para>
  </sect3>

  <sect3 id="How_to_Setup_for_an_Auto_Focus_Run">
    <title>How to Setup for an Autofocus Run</title>

    <para> The exact settings that work best for a given astronomical setup
    need to be worked out by the user using trial and error, but this section
    gives some pointers. It uses the Linear 1 Pass algorithm:</para>

    <itemizedlist>
      <listitem>
        <para> Start near to focus by manually finding focus. Use the
        <guibutton>Start Framing</guibutton> option and manually adjust focus
        to get to approximate focus.</para>
      </listitem>

      <listitem>
        <para> Select Linear 1 Pass and your curve of choice, say Hyperbola.
        Select Use Weights.</para>
      </listitem>

      <listitem>
        <para> Make sure you are finding enough stars.</para>

        <itemizedlist>
          <listitem>
            <para> Start with the SEP star detection method and the
            1-Focus-Default profile unless you have reason to use a different
            setup.</para>
          </listitem>

          <listitem>
            <para> On the Settings tab, use Full Field (rather than Sub Frame)
            which will use many stars rather than just one. Select Auto Select
            Star to let the system select the stars to use.</para>
          </listitem>

          <listitem>
            <para> Make sure Annulus is set to use a large amount of frame to
            make use of as many stars as possible. Note that there may be
            other factors that prevent you using all of the field such as
            issues with an un-flat field in the corners of the sensor, but
            don’t overdo the restriction.</para>
          </listitem>

          <listitem>
            <para> Set the camera settings such as exposure, gain and binning
            such that you are getting a good number of stars. Its impossible
            to be prescriptive here but try for between 20 and 100 (obviously
            if your focal length and target can’t find that many then the
            process should still work but may be less optimal from a curve
            fitting perspective). As a suggestion start with 2 sec exposures,
            unity gain for your camera and 1x1 binning.</para>
          </listitem>

          <listitem>
            <para> Upping the exposure usually finds more stars (but makes the
            focus process longer). You can also try taking multiple frames at
            the same point by setting the Average Over field &gt; 1
            frame.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> Setup the Mechanics tab.</para>

        <itemizedlist>
          <listitem>
            <para> Setup Backlash. See the Backlash section for more details
            but if you do not know the value for your equipment then set to
            0.</para>
          </listitem>

          <listitem>
            <para> Setup Max Travel. This should be appropriate for your
            focuser to prevent overextending it. It needs to be big enough to
            support the values set in Initial Step Size and Out Step Multiple.
            It will need a minimum of just over Initial Step Size * Out Step
            Multiple. If you can, set it to, say, double this.</para>
          </listitem>

          <listitem>
            <para> Settle. If your focuser causes vibration in the optical
            train then you need to set this value so that after moving, the
            system waits for Settle seconds before taking the next frame. Try
            moving the focuser then taking a few frames at the same position.
            If the first frame after movement has bigger HFRs than subsequent
            frames, then you probably need to up the value in Settle.</para>
          </listitem>

          <listitem>
            <para> Out Step Multiple. Start with 4 or 5. This will give you
            9-10 or 11-12 datapoints which is a good place to start. You need
            enough datapoints to form a curve, but the more you have the
            longer the process will take to complete.</para>
          </listitem>

          <listitem>
            <para> Initial Step Size. The following shows a “good curve”.
            There is significant movement in the HFR axis to clearly
            demonstrate the curve, in this case max HFR is about 2.2 whilst
            min is 0.75 which gives a max / min of about 3.</para>

            <screenshot>
              <screeninfo> Good Focus Curve </screeninfo>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="focus_good_focus.png" format="PNG"
                             width="50%"/>
                </imageobject>

                <textobject>
                  <phrase>Good Focus Curve</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </listitem>

          <listitem>
            <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.
            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 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 very
            accurate.</para>

            <screenshot>
              <screeninfo> Bad Focus Curve </screeninfo>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="focus_bad_focus.png" format="PNG"
                             width="50%"/>
                </imageobject>

                <textobject>
                  <phrase>Bad Focus Curve</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="Coefficient_of_Determination">
    <title>Coefficient of Determination, R²</title>

    <para> The Coefficient of Determination, or R², is calculated in order to
    give a measure of how well the fitted curve matches the datapoints. More
    information is available <ulink
    url="https://en.wikipedia.org/wiki/Coefficient_of_determination">here</ulink>.
    This is an experimental feature that is available for the Linear 1 Pass
    focus algorithm. In essence, R² gives a value between 0 and 1, with 1
    meaning a perfect fit where all datapoints sit on the curve, and 0 meaning
    that there is no correlation between the datapoints and the curve. The
    user should experiment with their equipment to see what values they can
    obtain, but as a guide, a value above, say 0.8 would be a good fit.</para>

    <para> There is an option to set an “R² Limit” in the Settings tab of the
    Focus window that is compared to the calculated R² after the auto focus
    run has completed. If the limit value has not been achieved, then the auto
    focus is rerun.</para>

    <para> Setting an R² Limit could be useful for unattended observation if
    the focus run produces a bad result for a 1-off reason. Obviously if the
    reason is not transitory then rerunning will not improve anything.</para>

    <para> If the R² Limit is not achieved and the focus process is rerun, and
    again fails to achieve the R² Limit, then the focus run is marked as
    successful to avoid the process getting stuck rerunning auto focus
    forever.</para>

    <para> This feature is turned off by setting the R² Limit to 0.</para>
  </sect3>

  <sect3 id="Levenberg-Marquardt">
    <title>Levenberg–Marquardt Solver</title>

    <para> The Levenberg-Marquardt (LM) algorithm is used to solve non-linear
    least squares problems. The GNU Science Library provides an implementation
    of the solver. These resources provide more details: </para>

    <itemizedlist>
      <listitem>
        <para>
          <ulink url="https://en.wikipedia.org/wiki/Levenberg–Marquardt_algorithm"/>
        </para>
      </listitem>

      <listitem>
        <para>
          <ulink url="https://www.gnu.org/software/gsl/doc/html/nls.html"/>
        </para>
      </listitem>
    </itemizedlist>

    <para> The Levenberg-Marquardt algorithm is a new feature added for the
    Linear 1 Pass focus algorithm. It is a non-linear least-squares solver and
    thus suitable for many different equations. The basic idea is to adjust
    the equation y = f(x,P) so that the computed y values are as close as
    possible to the y values of the datapoints provided, so that the resultant
    curve fits the data as best as it can. P is a set of parameters that are
    varied by the solver in order to find the best fit. The solver measures
    how far away the curve is at each data point, squares the result and adds
    them all up. This is the number to be minimized, let's call it S. The
    solver is supplied with an initial guess for the parameters, P. It
    calculates S, makes an adjustment to P and calculates a new S1. Provided
    S1 &lt; S then we are moving in the right direction. It iterates through
    the procedure until:</para>

    <itemizedlist>
      <listitem>
        <para> the delta in S is less than a supplied limit (convergence has
        been reached), or</para>
      </listitem>

      <listitem>
        <para> the maximum number of iterations has been reached, or</para>
      </listitem>

      <listitem>
        <para> the solver encountered an error.</para>
      </listitem>
    </itemizedlist>

    <para> The solver is capable of solving either an unweighted or weighted
    set of datapoints. In essence, an unweighted set of data gives equal
    weight to each datapoint when trying to fit a curve. An alternative is to
    weight each datapoint with a measure that corresponds to how accurate the
    measurement of the datapoint actually is. In our case this is the variance
    of star HFRs associated with the datapoint. The variance is the standard
    deviation squared.</para>

    <para> Currently the solver is used to fit either a parabolic or a
    hyperbolic curve.</para>
  </sect3>
</sect2>
