[education/kstars] doc: Update focus section of user manual including Linear 1 Pass
Jasem Mutlaq
null at kde.org
Fri Jul 22 06:51:37 BST 2022
Git commit 8b1833fc1a32a39ec5dcab5fedc00bd05ad652a1 by Jasem Mutlaq, on behalf of John Evans.
Committed on 22/07/2022 at 05:51.
Pushed by mutlaqja into branch 'master'.
Update focus section of user manual including Linear 1 Pass
Update to the User Manual's section on Focus:
1. General update. All pictures updated to reflect current state and text generally updated so all options are now covered to at least some degree.
2. Added Linear 1 Pass.
M +1213 -227 doc/ekos-focus.docbook
M +- -- doc/ekos_focus.png
A +- -- doc/focus_bad_focus.png
M +- -- doc/focus_ccdfw_group.png
A +- -- doc/focus_display.png
A +- -- doc/focus_good_focus.png
A +- -- doc/focus_mechanics.png
A +- -- doc/focus_process.png
M +- -- doc/focus_relative_profile.png
M +- -- doc/focus_settings.png
M +- -- doc/focus_vcurve.png
A +- -- doc/focus_vcurve_timeseries.png
M +- -- doc/focuser_group.png
https://invent.kde.org/education/kstars/commit/8b1833fc1a32a39ec5dcab5fedc00bd05ad652a1
diff --git a/doc/ekos-focus.docbook b/doc/ekos-focus.docbook
index b3d44b94b..0f3a6142f 100644
--- a/doc/ekos-focus.docbook
+++ b/doc/ekos-focus.docbook
@@ -1,259 +1,1245 @@
+<?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"/>
- </imageobject>
- <textobject>
- <phrase>Ekos Focus</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
+ <title>Focus</title>
- <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 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 stars 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 the brightest star and starts measuring its HFR. It can automatically select the star, or you can select the star manually. It is usually recommended to select stars that are not too bright as they might get saturated during the focusing process. A magnitude 3 or 4 star is often sufficient.
- </para>
- <para>
- Ekos then begins the focusing process by commanding the focuser to focus inwards or outwards, and re-measures the HFR. This establishes a V-shaped curve in which the sweet spot of optimal focus is at the center of the V-curve, and the slope of which depends on the properties of the telescope and camera in use. In Ekos, a full V-curve is never constructed as the focusing process works iteratively, so under most circumstances, a half V-curve shape as illustrated in the Focus Module image is measured.
- </para>
- <para>
- Because the HFR varies linearly with focus distance, it is possible to calculate the optimal focus point. In practice, 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. In the default <guilabel>Iterative</guilabel> algorithm, 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 <guilabel>Step</guilabel> options specify the number of <emphasis>initial</emphasis> ticks the focuser has to move. If the image is severely out of focus, we set the step size high (&ie; > 250). On the other hand, if the focus is close to optimal focus, we set the step size to a more reasonable range (< 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.
- </para>
- <para>
- When using the <guilabel>Polynomial</guilabel> algorithm, the process starts in the <guilabel>Iterative</guilabel> mode, but once we cross to the other side of the V-curve (&ie; once HFR values start increasing again after decreasing for a while), the Ekos performs polynomial fitting to find a solution that predicts the minimum possible HFR position. If a valid solution is found, the autofocus process is considered successful.
- </para>
- <para>
- While Ekos Focus Module supports relative focusers, it is <emphasis role="bold">highly recommended</emphasis> to use absolute focusers.
- </para>
- </sect3>
+ <indexterm>
+ <primary>Tools</primary>
- <sect3 id="focus-focuser-group">
- <title>Focuser Group</title>
+ <secondary>Ekos</secondary>
- <screenshot>
- <screeninfo>
- Focuser Settings
- </screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="focuser_group.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Focuser Settings</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
+ <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>
- <para>
- Any INDI-compatible focuser is supported. It is recommended to use <emphasis role="bold">absolute</emphasis> focusers 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, &etc;
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Relative</emphasis>: Relative Position Focusers.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Simple Focusers</emphasis>: DC/PWM focusers with no position feedback.
- </para>
- </listitem>
+ <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 mimimum.
+ </para>
+ </listitem>
</itemizedlist>
- <para>
- For absolute focusers, you can set the ticks count. To view a continuous feed of the camera, click the <guibutton>Framing</guibutton> button. An image shall be captured repeatedly according to the CCD settings in the <guilabel>CCD and Filter Wheel</guilabel> group. You can focus in and out by pressing the respective buttons, and each shall move by the step size indicated in the focus settings. For absolute and relative focusers, the step size is in units of <emphasis>ticks</emphasis> and for simple DC focusers, the step size is in <emphasis>milliseconds</emphasis>.
- </para>
- <para>
- To begin the autofocus process, simply click the <guibutton>Auto Focus</guibutton> button.
- </para>
- </sect3>
+ </listitem>
- <sect3 id="focus-ccd-filter-wheel">
- <title>CCD & Filter Wheel Group</title>
+ <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>
- <screenshot>
- <screeninfo>
- Focus CCD & Filter Wheel Group
- </screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="focus_ccdfw_group.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Focus CCD & Filter Wheel Group</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
+ <itemizedlist>
+ <listitem>
+ <para> The algorithm relies on the focuser having well controlled
+ backlash. </para>
+ </listitem>
- <para>
- You must specify the CCD and Filter Wheel (if any) to be used during the focusing process. You can <emphasis role="bold">lock</emphasis> a specific filter within the filter wheel to be utilized whenever the autofocus process is invoked. Usually, the user should select the Clear/Luminescence filter for this purpose so that Ekos always uses the same filter to perform the autofocus process. This locked filter is also used in the <link linkend="ekos-align">Alignment Module</link> whenever it performs any astrometry capture.
- </para>
- <para>
- You may also 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 DSLRs cameras, you can change the ISO settings. You may reset the focusing subframe to full frame capture if you click the <guibutton>Reset</guibutton> button.
- </para>
- </sect3>
+ <listitem>
+ <para> The algorithm can be fast using a minimum number of steps.
+ </para>
+ </listitem>
- <sect3 id="focus-settings">
- <title>Settings</title>
+ <listitem>
+ <para> The algorithm uses curve fitting to pinpoint the optimum
+ focus position. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <screenshot>
- <screeninfo>
- Focus Settings
- </screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="focus_settings.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Focus Settings</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
+ <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="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 minimise 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>CCD & Filter Wheel Group</title>
+
+ <screenshot>
+ <screeninfo> Focus CCD & Filter Wheel Group </screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="focus_ccdfw_group.png" format="PNG" width="50%"/>
+ </imageobject>
+
+ <textobject>
+ <phrase>Focus CCD & Filter Wheel Group</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para> Set the CCD to be used in the focus process from the dropdown. The
+ <guibutton>Live Video</guibutton> button brings up the associated popup.
+ Next set the exposure length. 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. The <guibutton>Show in FITS Viewer</guibutton> button pops-up a
+ separate FITS Viewer window to display the focus frame, in addition to
+ focus frame displayed within the focus window.</para>
+
+ <para> The next row of controls allows CCD 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 / ISO</guilabel>: Set the Gain / ISO for the CCD
+ 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>
+ </itemizedlist>
+
+ <para> The next row of controls deals with the Filter Wheel, if there is
+ one. Firstly, choose the Filter Wheel from the dropdown and the filter to
+ use. 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 used in the <link
+ linkend="ekos-align">Alignment Module</link> whenever it performs a
+ capture for astrometry.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para> You may select the temperature source from the dropdown on the next
+ row of controls. 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. You may reset the focusing subframe to
+ full frame capture if you click the <guibutton>Reset</guibutton> button.
+ </para>
+ </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>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">Levenburg-Marquardt
+ Solver</link> for more details.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>R2 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,
+ R2</link>, is calculated. This option allow a minimum acceptable value
+ of R2 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 R2 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
+ build 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">Levenburg-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>Kernal Size</guilabel>: The kernal 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">Levenburg-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">Levenburg-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 > 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 >= the actual backlash value. For example, if you
+ measure backlash and get a value around 100, any value >=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>
- <para>
- You may need to adjust focus settings in order to achieve a successful and reliable autofocus process. The settings are retained between sessions.
- </para>
<itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">Auto Star Select</emphasis>: Automatically select the best focus star from the image.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Subframe</emphasis>: Subframe around the focus star during the autofocus procedure. Enabling subframing can significantly speed up the focus process.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Dark Frame</emphasis>: Check this option to capture a dark frame if necessary and perform dark-frame subtraction. This option can be useful in noisy images.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Suspend Guiding</emphasis>: Suspend Guiding while autofocus in progress. If the focus process can disrupt the guide star (⪚ when using Integrated Guide Port IGP whereas the guider is physically attached to the primary CCD), then it is recommended to enable this option. When using Off-Axis guider, then this option is not necessary.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Box size</emphasis>: Sets the box size used to enclose the focus star. 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>
- <emphasis role="bold">Max Travel</emphasis>: Maximum travel in ticks before the autofocus process aborts.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Step</emphasis>: <emphasis>Initial</emphasis> step size in ticks to cause a noticeable change in HFR value. For timer-based focuser, it is the initial time in milliseconds to move the focuser inward or outward.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Tolerance</emphasis>: The tolerance percentage values decides when the autofocus process stops in the <guilabel>Iterative</guilabel> algorithm. 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 value to narrow 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>
- <emphasis role="bold">Threshold</emphasis>: 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>
- <emphasis role="bold">Algorithm</emphasis>: Select the autofocus process algorithm:
- <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 percentage tolerance 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>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Frames</emphasis>: Number of average frames to capture. During each capture, an HFR is recorded. If the instantaneous HFR value is unreliable, you can average a number of frames to increase the signal to noise ratio.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Detection</emphasis>: Select star detection algorithm. Each algorithm has its strengths and weaknesses. It is recommended to keep the default value unless it fails to properly detect stars.</para>
- <itemizedlist>
- <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 'Num. of rows' 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> 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 > 1
+ frame.</para>
+ </listitem>
</itemizedlist>
- </sect3>
+ </listitem>
- <sect3 id="focus-v-curve">
- <title>V-Curve</title>
+ <listitem>
+ <para> Setup the Mechanics tab.</para>
- <screenshot>
- <screeninfo>
- Focus V-Curve
- </screeninfo>
- <mediaobject>
+ <itemizedlist>
+ <listitem>
+ <para> Setup Backlash. See the Backlash section for more details
+ but if you don’tknow 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_vcurve.png" format="PNG"/>
+ <imagedata fileref="focus_good_focus.png" format="PNG"
+ width="50%"/>
</imageobject>
+
<textobject>
- <phrase>Focus V-Curve</phrase>
+ <phrase>Good Focus Curve</phrase>
</textobject>
- </mediaobject>
- </screenshot>
+ </mediaobject>
+ </screenshot>
+ </listitem>
- <para>
- The V-shaped curve displays absolute position versus Half-Flux-Radius (HFR) values. The center of the V-curve is the optimal focus position. Once Ekos crosses from one side of the V-curve to the other, it backtracks and tries to find the optimal focus position. The final focus position is decided by which algorithm is selected.
- </para>
- <para>
- When framing, the 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>
- </sect3>
+ <listitem>
+ <para> In contract, 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>
- <sect3 id="focus-relative-profile">
- <title>Relative Profile</title>
+ <screenshot>
+ <screeninfo> Bad Focus Curve </screeninfo>
- <screenshot>
- <screeninfo>
- Focus Relative Profile
- </screeninfo>
- <mediaobject>
+ <mediaobject>
<imageobject>
- <imagedata fileref="focus_relative_profile.png" format="PNG"/>
+ <imagedata fileref="focus_bad_focus.png" format="PNG"
+ width="50%"/>
</imageobject>
+
<textobject>
- <phrase>Focus Relative Profile</phrase>
+ <phrase>Bad Focus Curve</phrase>
</textobject>
- </mediaobject>
- </screenshot>
+ </mediaobject>
+ </screenshot>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="Coefficient_of_Determination">
+ <title>Coefficient of Determination, R2</title>
+
+ <para> The Coefficient of Determination, or R2, 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, R2 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 “R2 Limit” in the Settings tab of the
+ Focus window that is compared to the calculated R2 after the auto focu run
+ has completed. If the limit value has not been achieved, then the auto
+ focus is rerun.</para>
+
+ <para> Setting an R2 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 R2 Limit is not achieved and the focus process is rerun, and
+ again fails to achieve the R2 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 R2 Limit to 0.</para>
+ </sect3>
+
+ <sect3 id="Levenberg–Marquardt">
+ <title>Levenberg–Marquardt Solver</title>
+
+ <para> The Levenburg-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>
- 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 and is displayed when the autofocus process concludes. This enables you to judge how well the autofocus process improved the relative focus quality.
+ <ulink url="https://en.wikipedia.org/wiki/Levenberg–Marquardt_algorithm"/>
</para>
- </sect3>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink url="https://www.gnu.org/software/gsl/doc/html/nls.html"/>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para> The Levenberg-Marquart 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 minimised, lets call is 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 < 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>
diff --git a/doc/ekos_focus.png b/doc/ekos_focus.png
index 3b2ee5e3e..47a042c29 100644
Binary files a/doc/ekos_focus.png and b/doc/ekos_focus.png differ
diff --git a/doc/focus_bad_focus.png b/doc/focus_bad_focus.png
new file mode 100644
index 000000000..2357eb29d
Binary files /dev/null and b/doc/focus_bad_focus.png differ
diff --git a/doc/focus_ccdfw_group.png b/doc/focus_ccdfw_group.png
index b043e8ecb..79224062c 100644
Binary files a/doc/focus_ccdfw_group.png and b/doc/focus_ccdfw_group.png differ
diff --git a/doc/focus_display.png b/doc/focus_display.png
new file mode 100644
index 000000000..a3d4d1355
Binary files /dev/null and b/doc/focus_display.png differ
diff --git a/doc/focus_good_focus.png b/doc/focus_good_focus.png
new file mode 100644
index 000000000..3eac58fca
Binary files /dev/null and b/doc/focus_good_focus.png differ
diff --git a/doc/focus_mechanics.png b/doc/focus_mechanics.png
new file mode 100644
index 000000000..624a80a06
Binary files /dev/null and b/doc/focus_mechanics.png differ
diff --git a/doc/focus_process.png b/doc/focus_process.png
new file mode 100644
index 000000000..7c545da46
Binary files /dev/null and b/doc/focus_process.png differ
diff --git a/doc/focus_relative_profile.png b/doc/focus_relative_profile.png
index 0f499462d..4680f69ad 100644
Binary files a/doc/focus_relative_profile.png and b/doc/focus_relative_profile.png differ
diff --git a/doc/focus_settings.png b/doc/focus_settings.png
index 14a1e4190..6f9915797 100644
Binary files a/doc/focus_settings.png and b/doc/focus_settings.png differ
diff --git a/doc/focus_vcurve.png b/doc/focus_vcurve.png
index 14e3c0b1d..03725ba2a 100644
Binary files a/doc/focus_vcurve.png and b/doc/focus_vcurve.png differ
diff --git a/doc/focus_vcurve_timeseries.png b/doc/focus_vcurve_timeseries.png
new file mode 100644
index 000000000..f3f9ccbb0
Binary files /dev/null and b/doc/focus_vcurve_timeseries.png differ
diff --git a/doc/focuser_group.png b/doc/focuser_group.png
index 64443810c..af3bcbc90 100644
Binary files a/doc/focuser_group.png and b/doc/focuser_group.png differ
More information about the kde-doc-english
mailing list