[education/kstars] doc: L1PPhase2 Focus Updates to Handbook
John Evans
null at kde.org
Mon Jun 19 13:09:23 BST 2023
Git commit 312643c3e04c05c7ea70c70b99991a66b3049dfe by John Evans.
Committed on 19/06/2023 at 12:09.
Pushed by johnevans into branch 'master'.
L1PPhase2 Focus Updates to Handbook
L1P Phase2 Focus changes documentation update to the Kstars Handbook.
A +- -- doc/build_filter_offsets.png
A +- -- doc/build_filter_offsets2.png
A +- -- doc/build_filter_offsets3.png
M +0 -87 doc/ekos-capture.docbook
M +1370 -550 doc/ekos-focus.docbook
M +- -- doc/filter_settings.png
A +- -- doc/focus_adaptive_focus.png
A +- -- doc/focus_advisor.png
A +- -- doc/focus_analyze.png
A +- -- doc/focus_autofocus_log.png
A +- -- doc/focus_cfz_classic.png
A +- -- doc/focus_cfz_gold.png
A +- -- doc/focus_cfz_moustache.png
A +- -- doc/focus_cfz_wavefront.png
A +- -- doc/focus_display_mosaic.png
M +- -- doc/focus_mechanics.png
A +- -- doc/focus_mechanics1.png
M +- -- doc/focus_process.png
M +- -- doc/focus_vcurve.png
A +- -- doc/focus_vcurve_fourier.png
A +- -- doc/focus_vcurve_fwhm.png
A +- -- doc/focus_vcurve_hfradj.png
A +- -- doc/focus_vcurve_numstars.png
M +- -- doc/focuser_group.png
M +2 -2 doc/index.docbook
https://invent.kde.org/education/kstars/-/commit/312643c3e04c05c7ea70c70b99991a66b3049dfe
diff --git a/doc/build_filter_offsets.png b/doc/build_filter_offsets.png
new file mode 100644
index 0000000000..325cfdff13
Binary files /dev/null and b/doc/build_filter_offsets.png differ
diff --git a/doc/build_filter_offsets2.png b/doc/build_filter_offsets2.png
new file mode 100644
index 0000000000..3aaa73ead6
Binary files /dev/null and b/doc/build_filter_offsets2.png differ
diff --git a/doc/build_filter_offsets3.png b/doc/build_filter_offsets3.png
new file mode 100644
index 0000000000..f964bc3f16
Binary files /dev/null and b/doc/build_filter_offsets3.png differ
diff --git a/doc/ekos-capture.docbook b/doc/ekos-capture.docbook
index 6283afe0da..81d6fcd983 100644
--- a/doc/ekos-capture.docbook
+++ b/doc/ekos-capture.docbook
@@ -358,93 +358,6 @@
</mediaobject>
</sect3>
- <sect3 id="capture-filter-settings">
- <title>Filter Settings</title>
-
- <screenshot>
- <screeninfo>
- Filter Queue
- </screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="filter_settings.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Filter Queue</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
-
- <para>
- Click the filter icon <inlinemediaobject><imageobject><imagedata fileref="view-filter.png" format="PNG"/></imageobject></inlinemediaobject> next to the filter wheel selection box to open the filter settings dialog. If you are using filters that are not parafocal with each other and require a specific amount of focus offsets in order to get them into proper then set all the relative focus offsets in the dialog.
- </para>
- <para>
- Configure settings for each filter individually:
- </para>
- <orderedlist>
- <listitem>
- <para>
- <guilabel>Filter</guilabel>: Filter Name.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Exposure</guilabel>: Set exposure time used when performing focus under this filter. By default, it is set to 1 second.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Offset</guilabel>: Set relative offsets. Ekos will command a focus offset change if there is a difference between the current and target filter offsets. For example, given the values in the example image, if the current filter is set to <emphasis>Red</emphasis> and next filter is <emphasis>Green</emphasis>, then Ekos shall command the focuser to Focus In by +300 ticks. Relative positive focus offsets denote Focus Out while negative values denote Focus In.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Auto Focus</guilabel>: Check this option to initial AutoFocus process whenever the filter is changed to this filter.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Lock Filter</guilabel>: Set which filter should be set and <emphasis>locked</emphasis> when performing autofocus for this filter.
- </para>
- </listitem>
- </orderedlist>
- <para>
- Let's take an example. Suppose the capture sequence is running and the current filter is <guilabel>Green</guilabel>, so the relative offset is already set to +300. The next image in the sequence uses Hydrogen Alpha (H_Alpha) so before Ekos captures the next frame, the following actions take place:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Since Luminosity is specified as the locked filter and auto-focus is checked, the filter is changed to Luminosity.
- </para>
- </listitem>
- <listitem>
- <para>
- A focus offset is -300 is applied since the prior filter <guilabel>Green</guilabel> was moved +300 previously.
- </para>
- </listitem>
- <listitem>
- <para>
- Auto Focus process is initiated.
- </para>
- </listitem>
- <listitem>
- <para>
- Once Auto Focus is complete, the filter is changed to H_Alpha.
- </para>
- </listitem>
- <listitem>
- <para>
- A focus offset of -1200 is applied.
- </para>
- </listitem>
- <listitem>
- <para>
- Capture sequence is resumed.
- </para>
- </listitem>
- </itemizedlist>
- </sect3>
-
<sect3 id="capture-fits-viewer">
<title>FITS Viewer</title>
diff --git a/doc/ekos-focus.docbook b/doc/ekos-focus.docbook
index 2879607e9c..51253ca27f 100755
--- a/doc/ekos-focus.docbook
+++ b/doc/ekos-focus.docbook
@@ -33,18 +33,18 @@
<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
+ <para> The most tried and tested 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>
+ the accumulated intensity is half of the total flux of the star. As you move
+ closer to the point of optimum focus, so the HFR gets smaller, reaching a
+ minimum at the point of focus before increasing as you start to move away
+ from focus. HFR has been used on lots of different types of equipment and has
+ proved to be stable in a wide range of circumstances. </para>
+
+ <para> In addition to HFR, Ekos supports other focus measures, including
+ an adjusted HFR measure, FWHM, Number of Stars and Fourier Power. It is
+ recommended to start with HFR and when the user has become proficient in
+ focusing their equipment, to try the other measures. </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
@@ -52,75 +52,40 @@
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>
+ <para> Ekos supports 4 different focus algorithms: Linear 1 Pass, Linear,
+ Iterative, Polynominal. Linear 1 Pass is the recommended algorithm. </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> <emphasis role="bold">Linear 1 Pass</emphasis>: In the Linear 1
+ Pass algorithm, Ekos establishes a V-Curve and fits a curve to the data
+ to find the focus solution. It then moves to the calculated minimum.
+ 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>
+ <para> The algorithm compensates for focuser backlash. </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>
+ <para> The algorithm is fast, taking 1 pass to identify optimum
+ focus. </para>
</listitem>
<listitem>
- <para> The algorithm can be fast using a minimum number of steps.
- </para>
+ <para> The algorithm uses more sophisticated curve fitting to
+ pinpoint the optimum focus position. </para>
</listitem>
<listitem>
- <para> The algorithm uses curve fitting to pinpoint the optimum
- focus position. </para>
+ <para> The algorithm is highly configurable with user control over
+ many parameters like step size, number of steps and how to deal with
+ outliers in the datapoints. </para>
</listitem>
</itemizedlist>
+ <para> Providing the focuser behaves in a repeatable way, i.e. when commanded
+ to go to position X, it always goes to the same position, then this algorithm
+ will be the best to use.</para>
</listitem>
<listitem>
@@ -137,8 +102,7 @@
<itemizedlist>
<listitem>
- <para> The algorithm compensates for focuser backlash and can deal
- with both consistent and inconsistent backlash. </para>
+ <para> The algorithm compensates for focuser backlash. </para>
</listitem>
<listitem>
@@ -157,34 +121,75 @@
many parameters like step size and number of steps. </para>
</listitem>
</itemizedlist>
+ <para> If the focuser behaves in an inconsistent way, i.e. when commanded
+ to go to position X, there is variability in the position it goes to, then
+ this algorithm will be the best to use as it has some built in tolerance
+ for this variability.</para>
</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>
+ <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 compensates for focuser backlash, providing
- that backlash is consistent. </para>
+ <para> The algorithm relies on the focuser having well controlled
+ backlash. </para>
</listitem>
<listitem>
- <para> The algorithm is fast, taking 1 pass to identify optimum
- focus. </para>
+ <para> The algorithm can be fast using a minimum number of steps.
+ </para>
</listitem>
<listitem>
- <para> The algorithm uses more sophisticated curve fitting to
- pinpoint the optimum focus position. </para>
+ <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 is highly configurable with user control over
- many parameters like step size and number of steps. </para>
+ <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>
@@ -271,15 +276,16 @@
</listitem>
</itemizedlist>
- <para> Start off by selecting the Focuser from the dropdown. </para>
+ <para> The <guibutton>Focuser</guibutton> field contains the focuser in the
+ attached Optical Train. </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
+ <para> 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>
+ be used to move the focuser by the number of ticks defined in the
+ <guibutton>Initial Step Size</guibutton> field in the
+ <link linkend="focus-mechanics">Mechanics</link> tab.</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
@@ -301,9 +307,9 @@
</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
+ based on the current settings in the <link linkend="focus-ccd-filter-wheel">
+ Camera & Filter Wheel Group</link>. 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
@@ -375,9 +381,11 @@
<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>
+ change the image scale as well as resulting in brighter pixels. It is
+ generally only worth binning above 1x1 if your image scale is oversampled
+ where the increase in image scale does not lead to a loss of resolution.
+ If you wish to increase star brightness try increasing the exposure
+ and / or gain. If you are unsure bin 1x1.</para>
</listitem>
<listitem>
@@ -414,39 +422,11 @@
<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>
+ Click the filter icon <inlinemediaobject><imageobject><imagedata
+ fileref="view-filter.png" format="PNG"/></imageobject></inlinemediaobject>
+ to launch the <link linkend="focus-filter-settings">Filter Settings</link>
+ popup. This allows a number of parameters to be set per filter to be used during
+ an Autofocus run.</para>
</listitem>
<listitem>
@@ -473,23 +453,23 @@
</mediaobject>
</screenshot>
- <para> Next are 3 tabbed panes of parameters. These parameters are
+ <para> Next are 5 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>
+ <para> <guilabel>Auto Select Star</guilabel>: This setting is only relevant if
+ <guilabel>Sub Frame</guilabel> is selected. In this case if <guilabel>Auto Select Star</guilabel>
+ is selected then Ekos will select the star to use for focus; otherwise
+ the user will have to manually select the star using FitsViewer.</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
+ suspend guiding during an Autofocus run. The purpose of this
is to prevent guiding from having problems with defocused stars during
- the focus process.</para>
+ the focus process where, for example, the guide scope is attached to the
+ main telescope using an OAG.</para>
</listitem>
<listitem>
@@ -498,65 +478,25 @@
where a pretaken dark is subtracted from the focus image before
further processing.</para>
+ <para> If hot pixels are causing problems with focus, select Dark Frames and
+ either setup a regular Master Dark frame or a Defect Map.</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>
+ <para> <guilabel>Full Field</guilabel>: Select to use the full field of
+ the camera. In this mode, focus will automatically select multiple stars for
+ use in an Autofocus run. The alternative to this is <guilabel>Sub Frame</guilabel>.</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>
+ <para> <guilabel>Sub Frame</guilabel>: Select to use a single star for the
+ Autofocus process. The alternative to this is <guilabel>Full Field</guilabel> where
+ multiple stars will be used by Autofocus. Depending on the setting of
+ <guilabel>Auto Select Star</guilabel> either the user or Ekos will select the star.</para>
</listitem>
<listitem>
@@ -568,10 +508,22 @@
</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> <guilabel>Display Units</guilabel>: Select the units for display on the Autofocus V-Curve
+ when HFR or FWHM is selected. <emphasis role="bold">Pixels</emphasis>
+ and <emphasis role="bold">Arc Seconds</emphasis> are supported.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Guide 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> The next set of radio button controls relate to <emphasis role="bold">Masking Options</emphasis>
+ to be used when in <guilabel>Full Field</guilabel> mode.</para>
+ <para> The effect of Masking Options can be seen on the <link linkend="focus-display">FITS Viewer</link>.</para>
<itemizedlist>
<listitem>
<para> <guilabel>Use all stars for focusing</guilabel>: Select this option
@@ -579,12 +531,11 @@
</listitem>
<listitem>
- <para> <guilabel>Ring Mask</guilabel>: Used in conjunction with Full
- Field, this option 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
+ <para> <guilabel>Ring Mask</guilabel>: This option 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
@@ -593,56 +544,100 @@
<listitem>
<para> <guilabel>Mosaic Mask</guilabel>: A 3x3 mosaic is composed with tiles
- from the imagecenter, its corners and from the edges. This option is useful
+ from the image center, its corners and from the edges. This option is useful
if you want to inspect the optics performance - you might know this from the
PixInsight Aberration Inspector script. The tile size can be configured in
- percent of the frame width, with the spacer value the space between the tiles
- is defined.</para>
- </listitem>
-
+ percent of the frame width, with the spacer value specifying the space between
+ the tiles.</para>
+ <para> There are three use-cases for the Mosaic Mask:
+ <itemizedlist>
+ <listitem>
+ <para> Checking focus in all parts of the sensor: The mask allows an easy
+ visual inspection and comparisons of stars in the center, corners and edges
+ of the sensor. This is especially useful for optics that show aberration if
+ the focus is not 100% met.</para>
+ </listitem>
+ <listitem>
+ <para>Correcting image tilt: especially large sensors are very sensitive to
+ incorrect distance and tilting of the sensor. In such cases, the image
+ shows aberration, expecially in the image corners. If all corners show the same
+ effect, the distance needs to be corrected. If the aberrations in the corners
+ differ, this is typically the result of a tilted sensor.</para>
+ </listitem>
+ <listitem>
+ <para>Collimating Newtonians: inspecting frames in a defocused state is typically
+ used for collimating Newtonians. See, for example, Tommy Nawratil's
+ <ulink url="https://teleskop-austria.at/information/pdf/JUS_Photonewton_Collimation_Primer_EN.pdf">
+ The Photonewton Collimation Primer</ulink> for more details.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
</itemizedlist>
- </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>
+ <para> The next set of controls relate to <emphasis role="bold">Adaptive Focus</emphasis>.
+ This is an experimental feature in Ekos. The idea here is to keep the telescope focused by
+ adapting the focuser position based on changes in environmental conditions without having to
+ perform a full Autofocus run. See the <link linkend="focus-adaptive">Adaptive Focus</link> section
+ for more details.</para>
- <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> For example, as temperature changes during an imaging session so the focus
+ point will change. By sampling the temperature between subframes it is possible to
+ firstly calculate the change in temperature and then to convert this to a number of
+ ticks of focuser movement to apply between subframes.</para>
- <para> See the <link linkend="Levenberg-Marquardt">Levenberg-Marquardt
- Solver</link> for more details.</para>
- </listitem>
+ <para> In order to use <emphasis role="bold">Adaptive Focus</emphasis> it is necessary
+ to setup some data for your system. In particular you need to tell Ekos how many ticks (and
+ in which direction) to move the focuser when the environmental conditions change. This is
+ covered in the <link linkend="focus-filter-settings">Filter Settings</link> popup. The
+ popup is launched by clicking the filter icon <inlinemediaobject><imageobject><imagedata
+ fileref="view-filter.png" format="PNG"/></imageobject></inlinemediaobject>.</para>
- <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> The following controls are available:
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Adaptive Focus</guilabel>: Select this option to activate
+ <emphasis role="bold">Adaptive Focus</emphasis>.</para>
+ </listitem>
- <para> Experiment to find an appropriate value but a good starting
- point would be 0.8 or 0.9</para>
+ <listitem>
+ <para> <guilabel>Min Move</guilabel>: The minimum Adaptive Focus movement allowed.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Adapt Start Pos</guilabel>: Check to allow Adaptive Focus to calculate the
+ start position for an Autofocus run. The starting position is the last good solve position for
+ the selected filter, adapted for environmental changes.</para>
+
+ <para> For example, if the current focuser position is 1000, temperature = 4C, and if the Red
+ filter is selected (last good focus position for Red is 990 @ 5C and Ekos is configured to move
+ +3 <guilabel>Ticks / °C</guilabel>). Then, if Adapt Start Pos is off,
+ Autofocus will start at 1000. If Adapt Start Pos is on, Autofocus will start at 990 + (5 - 4) * 3
+ = 993.</para>
+
+ <para> This feature is useful to ensure that Autofocus starts from close to the focus point
+ which will mean a more symmetric V-curve. It is particularly useful when changing between filters
+ which have large differences in focus points.</para>
+
+ <para> It is possible to use this feature on its own without Adaptive Focus. Just set the checkbox
+ and leave the ticks per degree C set to zero. This way the Autofocus start position will be
+ filter dependent and will start each Autofocus run at the focus point of the last successful
+ Autofocus run for that filter.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Max Total Move</guilabel>: The maximum total focuser movement that
+ Adaptive Focus is allowed in the observing session. The purpose of this is as a "dead man's
+ handle" on Adaptive Focus in case it runs away. For example, if the temperature source fails
+ and returns bad temperature readings whilst the equipment is unattended, this could result in
+ Adaptive Focus attempting to make large focuser movements.</para>
+
+ <para> If the Max Total Move is reached then <guilabel>Adaptive Focus</guilabel> is unchecked
+ until manually re-checked by the user.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
</listitem>
</itemizedlist>
</sect3>
@@ -664,14 +659,15 @@
</mediaobject>
</screenshot>
- <para> This is the Focus Process parameters pane.</para>
+ <para> This is the Focus Process parameters pane. Widgets are only displayed if they are relevant to
+ the selections made.</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>
+ recommended to use SEP, unless you have a specialized
+ use. The following are available:</para>
<itemizedlist>
<listitem>
@@ -717,145 +713,256 @@
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">Linear 1 Pass</emphasis>: This is the
+ recommended algorithm. In this algorithm, Ekos establishes a V-Curve
+ and fits a curve to the data to find the focus solution. It then moves
+ to the calculated solution.</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 <guilabel>Use Weights</guilabel>
+ is checked and run a refinement process if <guilabel>Refine Curve Fit
+ </guilabel> is selected.</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">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>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Curve Fit</guilabel>: The type of curve to fit to the datapoints. </para>
+ <itemizedlist>
+ <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>
+
+ <para> This is the recommended option.</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>
+
+ <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>
+
+ <para> It is no longer recommended to use this curve.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Measure</guilabel>: Select Measure to use in the focus process.
+ The following are available:</para>
- <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>
+ <itemizedlist>
+ <listitem>
+ <para> <emphasis role="bold">HFR</emphasis>: Half Flux Radius (HFR) is the
+ recommended measure. When a star is detected, Ekos will calculate the HFR for
+ the star. This is the radius of an imaginary circle, centered on the star
+ center, that encloses half the star's total flux.</para>
- <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>
+ <para>The point of best focus corresponds to the minimum HFR.</para>
</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>
+ <para> <emphasis role="bold">HFR Adj</emphasis>: This is an experimental feature that
+ uses a brightness adjusted HFR calculation to take account of the fact that the HFR for
+ brighter stars is larger than for smaller stars.</para>
+
+ <para> The algorithm adjusts the value of the measured HFR, usually upwards, so the HFRs obtained
+ by the HFR Adj method will be higher than the measured HFR values. This does not mean that you are
+ getting worse results by using HFR Adj, simply that the measure is different.</para>
+
+ <para> When using this Measure it is usual to get smaller error bars on the datapoints when
+ <guilabel>Use Weights</guilabel> is selected.</para>
+
+ <para>The point of best focus corresponds to the minimum adjusted HFR.</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>
+ <para> <emphasis role="bold">FWHM</emphasis>: This is an experimental feature that fits
+ a Gaussian surface to each star and uses that to calculate the Full Width Half Maximum
+ (FWHM) of the star. The FWHM is the width of an circle (or ellipse) centered on the star center
+ reaching the edge of the star at half its maximum intensity.</para>
+
+ <para>The point of best focus corresponds to the minimum FWHM.</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>
+ <para>Expect the FWHM to be approximately twice the HFR of a star.</para>
</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>
+ <para> <emphasis role="bold"># Stars</emphasis>: This ia an experimental feature that
+ calculates the number of stars in the image and uses this number as the focus measure.
+ The idea is that as you move nearer focus so more stars become detectable.</para>
+
+ <para> The advantage of this Measure is that it is very simple and does not require
+ algorithms to calculate HFRs or FWHMs.</para>
+
+ <para>The point of best focus corresponds to a maximum number of stars.</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>
+ <para> <emphasis role="bold">Fourier</emphasis>: Fourier takes a Fourier transform of the
+ image and calculates the image power in frequency space. The assumption is that for an astronomical
+ image of stars and background, the stars will be gaussians. Under a Fourier
+ transform, a gaussian transforms to another gaussian; but wider stars transform to narrower
+ gaussians in frequency space, and vice-versa. So, at focus, summing up the contents in
+ frequency space, which is in effect a measure of power, will be a maximum.</para>
+
+ <para>This follows the main idea suggested by Tan and Schulz in their paper:
+ <ulink url="https://arxiv.org/pdf/2201.12466.pdf">A Fourier method for the determination of focus
+ for telescopes with stars</ulink>. Please note that this paper makes other processing suggestions
+ beyond the idea of using Fourier Transforms that are not included within Ekos</para>
+
+ <para> This is a relatively new method in the Astro Community, and does not require star detection.
+ Tan and Schulz report good results with both amateur and professional telescopes.</para>
</listitem>
+ </itemizedlist>
+ </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>
+ <para> <guilabel>PSF</guilabel>: If <guilabel>Measure</guilabel> is set to FWHM, then the PSF
+ widget can be selected for use in fitting a surface to the star. At pressent just Gaussian is
+ supported.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Use Weights</guilabel>: This is only available with the Linear 1 Pass focus algorithm
+ and Curve Fits of Hyperbola and Parabola. It requires Full Field to be selected. The option calculates
+ the standard deviation of star Measure 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> The standard deviation is drawn on the V-Curve for each datapoint as an error bar.</para>
+
+ <para> It is recommended to check this option.</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 only available with the Linear 1 Pass focus algorithm
+ and Curve Fits 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>
+
+ <listitem>
+ <para> <guilabel>Refine Curve Fit</guilabel>: This is an experimental option only available with the Linear
+ 1 Pass focus algorithm and Curve Fits of Hyperbola and Parabola. If this option is checked then at the end
+ of the sweep of datapoints, Ekos fits a curve and measures the R². It then applies Peirce's Criterion
+ based on Gould's methodology for outlier identification. See <ulink
+ url="https://en.wikipedia.org/wiki/Peirce%27s_criterion">Peirce's Criterian</ulink> for details incl
+ Peirce's original paper and Gould's paper which are both referenced in the notes. If Peirce's Criterion
+ detects 1 or more outliers then another curve fit is attempted with the outliers removed. Again the R²
+ is calculated and compared with the original curve fit R². If the R² is better, then the latest run is used,
+ if not, the original curve fit (with the outliers included) is used.</para>
+
+ <para> Outliers are clearly marked on the V-Curve with an X through the datapoint.</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>
+ <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 for the star Measure
+ selected.</para>
</listitem>
<listitem>
- <para> <guilabel>Curve Fit</guilabel>: The type of curve to fit to the
- datapoints. </para>
+ <para> If <guilabel>Detection</guilabel> is set to Threshold then the following additional field is
+ available:</para>
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Threshold</guilabel>: This contains a percentage value 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>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para> If <guilabel>Detection</guilabel> is set to Bahtinov then the following additional widgets are
+ available:</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>
+ <para> <guilabel>Num. of rows</guilabel>: The number of lines displayed on screen when using a
+ Bahtinov mask.</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>
+ <para> <guilabel>Sigma</guilabel>: The sigma of the gaussian blur applied to the image before applying
+ Bahtinov edge detection.</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>
+ <para> <guilabel>Kernel Size</guilabel>: The kernel size of the gaussian blur applied to the image
+ before applying Bahtinov edge detection.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para> If <guilabel>Algorithm</guilabel> is set to Linear or Iterative then the following additional widget is
+ available:</para>
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Tolerance</guilabel>: The tolerance percentage value is used to help decide when the
+ Autofocus process stops. 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 session 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 Tolerance value too low might result in a repetitive loop and would most likely result in a
+ failed Autofocus process. </para>
+ </warning>
</listitem>
</itemizedlist>
</listitem>
@@ -881,102 +988,695 @@
<para> This is the Focus Mechanics parameters pane.</para>
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Walk</guilabel>: This specifies the way Autofocus will "walk" inwards through its
+ sweep to produce the V-Curve from which the focus solution will be calculated.</para>
+
+ <para> The following are available:
+ <itemizedlist>
+ <listitem>
+ <para> <emphasis role="bold">Classic</emphasis>: This is the recommended setting. The inward sweep
+ follows a series of steps of equal size (<guilabel>Initial Step Size</guilabel>). The algorithm includes
+ logic to determine when to stop that makes the exact number of steps unpredictable but it will be about
+ 2 * (<guilabel>Out Step Multiple</guilabel>) + 1.</para>
+ <para> This Walk is tolerant of curve fitting failures in the last step where it will take a further
+ step and try again to solve. It is also somewhat tolerant of not being started near to focus so is a good
+ choice for the initial Autofocus run.</para>
+ <para> Because of the "tolerance" of this Walk to less than perfect setup it is a conservative option
+ to chose, but comes at the expense of extra steps and therefore extra time in the Autofocus process.</para>
+ </listitem>
+
+ <listitem>
+ <para> <emphasis role="bold">Fixed Steps</emphasis>: This experimental option is available in the Linear 1 Pass
+ <guilabel>Algorithm</guilabel>. It is quite similar to Classic but <guilabel>Fixed Steps</guilabel>
+ is used to control the total number of steps taken.</para>
+ <para> This algorithm is more predicable than Classic in that it takes a definite number of steps (so
+ will be faster), but is less tolerant of issues curve fitting the last data point and needs to be
+ started near to focus.</para>
+ <para> When selected, the <guilabel>Out Steps Multiple</guilabel> is replaced by
+ <guilabel>Fixed Steps:</guilabel>
+ <screenshot>
+ <screeninfo> Focus Mechanics </screeninfo>
+ <mediaobject> <imageobject> <imagedata fileref="focus_mechanics1.png" format="PNG" width="50%"/>
+ </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
+ </screenshot>
+ </para>
+ </listitem>
+ <listitem>
+ <para> <emphasis role="bold">CFZ Shuffle</emphasis>: This experimental option is available in the Linear 1 Pass
+ <guilabel>Algorithm</guilabel>. It is a variation on Fixed Steps so the comments on that Walk are
+ applicable here as well.</para>
+
+ <para> The difference between CFZ Shuffle and Fixed Steps is that near the center of the sweep (which
+ should be around the Critical Focus Zone (CFZ) the algorithm takes steps of half the specified size.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Focuser 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>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>Out Step Multiple</guilabel>: Used by the Linear and Linear 1 Pass focus algorithms in the
+ Classic walk, this parameter specifies the initial number of outward steps the focuser takes at the start of
+ an Autofocus run.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Number Steps</guilabel>: Used by the Linear 1 Pass algorithm in the Fixed Steps and CFZ
+ Shuffle walks, this parameter specifies the total number of steps the focuser takes to create the V-Curve in
+ an Autofocus run.</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 algorithm to limit the maximum step size that
+ can be used.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Driver Backlash</guilabel>: See the section on <link linkend="focus-backlash">Backlash</link>.</para>
+
+ <para>There are 2 schemes that can be used:</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>
+ <para>Set <guilabel>Driver Backlash</guilabel> to 0 to switch it off and deal with Backlash elsewhere.</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>
+ <para>Set <guilabel>Driver Backlash</guilabel> > 0 to use Driver Backlash to manage Backlash in the device driver. Note
+ that this field is only editable if the device driver supports Backlash.</para>
+ <para>This is the same data field that is displayed in the Indi Control Panel for the focuser device. It can be set
+ in either place.</para>
</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para> <guilabel>AF Overscan</guilabel>: See the section on <link linkend="focus-backlash">Backlash</link>.</para>
+
+ <para> There are 2 schemes that can be used:</para>
+ <itemizedlist>
<listitem>
- <para> <guilabel>Max Step size</guilabel>: Used by the Iterative focus
- algorithm to limit the maximum step size that can be used.</para>
+ <para> Set <guilabel>AF Overscan</guilabel> to 0 to switch it off and deal with Backlash elsewhere.</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> Set <guilabel>AF Overscan</guilabel> > 0 to have the Focus module manage Backlash.</para>
+ </listitem>
+ </itemizedlist>
+ </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. This should only be triggered if there are problems with the camera during the Focus process so set this
+ to a high enough value that it will not occur during normal operation.</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. This should only be triggered if there are problems with the focuser during the Focus process so set this
+ to a high enough value that it will not occur during normal operation.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
- <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>
+ <sect3 id="focus-cfz">
+ <title>Focus Critical Focus Zone (CFZ)</title>
- <itemizedlist>
- <listitem>
- <para> The initial outward movement of Initial Step Size * Out
- Step Multiple at the start of the run.</para>
- </listitem>
+ <screenshot>
+ <screeninfo> Focus CFZ </screeninfo>
- <listitem>
- <para> When the inward pass is complete and Ekos has determined
- the best focus position and moves outward to it.</para>
- </listitem>
- </itemizedlist>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="focus_cfz_classic.png" format="PNG" width="50%"/>
+ </imageobject>
- <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>
+ <textobject>
+ <phrase>Focus CFZ</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
- <para>There are 2 schemes that can be used:</para>
+ <para> This is the Focus CFZ parameters pane.</para>
- <itemizedlist>
- <listitem>
- <para>Set Backlash to 0. Ekos will use a value of 5 * Initial Step
- Size.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Algorithm</guilabel>: This specifies the Critical Focus Zone (CFZ) algorithm. The purpose of this is
+ to calculate the CFZ for the equipment attached in the Optical Train. It is not necessary to use this functionality
+ in order to successfully focus, but it provides useful information if correctly configured.</para>
- <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>
+ <para> It requires some knowledge to configure it correctly. There is plenty of information available on the internet.</para>
- <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>
+ <para> The idea of the CFZ tab is that it starts with data from the Optical Train used in the Focus tab and uses that to
+ calculate the CFZ. The user can adjust parameters to do "what-if" scenarios to see how it affects the CFZ. Clicking the
+ <guilabel>Reset to OT</guilabel> button resets any adjusted parameters to the Optical Train values.</para>
+
+ <para> If the <guilabel>Display</guilabel> box is checked then the CFZ is drawn on the V-Curve after Autofocus
+ successfully completes.
+ <screenshot>
+ <screeninfo> Focus Mechanics </screeninfo>
+ <mediaobject> <imageobject> <imagedata fileref="focus_cfz_moustache.png" format="PNG" width="75%"/>
+ </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
+ </screenshot></para>
+ <para> It is necessary to specify the <guilabel>Step Size</guilabel> parameter which specifies in microns how far one tick
+ moves the focuser.</para>
+ <para> The following algorithms are available:
+ <itemizedlist>
<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>
+ <para> <emphasis role="bold">Classic</emphasis>: This is the recommended setting. The equation used is displayed
+ in the top right of the panel and is the equation most commonly seen on the internet. The equation comes from a
+ linear optics treatment using the Airy Disc and is acknowledged to have limitations. For this reason it includes
+ a "tolerance" factor that can be adjusted by the user. For example, in the often quoted “In Perfect Focus” article
+ by Don Goldman and Barry Megdal in Sky & Telescope 2010 they suggest setting t=1/3.</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>
+ <para> <emphasis role="bold">Wavefront</emphasis>: The equation used is displayed in the top right of the panel.
+ The equation comes from a wavefront approach to the CFZ. Again, it has limitations and again, for this reason it
+ includes a "tolerance" factor that can be adjusted by the user.
+ <screenshot>
+ <screeninfo> Focus Mechanics </screeninfo>
+ <mediaobject> <imageobject> <imagedata fileref="focus_cfz_wavefront.png" format="PNG" width="50%"/>
+ </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
+ </screenshot>
+ </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>
+ <para> <emphasis role="bold">Gold</emphasis>: This method is based on work done by Gold Astro and presented
+ <ulink url="http://www.goldastro.com/goldfocus/ncfz.php">here</ulink>.</para>
+ <screenshot>
+ <screeninfo> Focus Mechanics </screeninfo>
+ <mediaobject> <imageobject> <imagedata fileref="focus_cfz_gold.png" format="PNG" width="50%"/>
+ </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
+ </screenshot>
</listitem>
</itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Tolerance</guilabel>: This is used by Classic and Wavwfront algorithms and is a scaling factor
+ between 0 and 1.</para>
+ <para> For the Classic algorithm, Goldman and Megdal suggest 1/3.</para>
+ <para> For the Wavefront algorithm, some have suggested 1/3 or even 1/10.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Tolerance (τ)</guilabel>: This is used by the Gold algorithm and is a focus tolerance as a percentage of
+ total seeing. The Gold website suggests 3-5% for a good focuser or 1-2% for a top quality focuser. See the
+ <ulink url="http://www.goldastro.com/goldfocus/ncfz.php">Gold Astro website</ulink> for more details.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Display</guilabel>: Check this box to display the calculated CFZ on the V-Curve after a
+ successful Autofocus run. It is displayed as a yellow moustache.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Reset to OT</guilabel>: Press this button to reset any parameters to values defaulted from the
+ currently connected Optical Train.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Wavelength (λ)</guilabel>: This is the light wavelength to use. It is defaulted from the currently used
+ filter. Remember to set this up in <link linkend="focus-filter-settings">Filter Settings</link> for your filters.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Aperture (A)</guilabel>: This is the aperture of the telescope in mm. It is defaulted from the
+ currently connected Optical Train.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Focal Ratio (f)</guilabel>: This is the focal ratio of the telescope. It is defaulted from the
+ currently connected Optical Train.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>FWHM (θ)</guilabel>: This is used by the Gold Algorithm and is the total seeing. This is the combined
+ contribution of the diffraction limit of your telescope and the astronomical seeing. The
+ <ulink url="http://www.goldastro.com/goldfocus/ncfz.php">Gold Astro website</ulink> describes how you might approximate
+ the total once you have values for the individual contributions.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>CFZ</guilabel>: This is calculated CFZ in microns and in ticks.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Step Size</guilabel>: This must be input by the user (as it cannot be calculated by Ekos). It relates how far
+ 1 tick moves the focal plane in microns. </para>
+ <para> For a refractor this is how far the drawtube moves when the focuser is moved by 1 tick. You might be able to get this
+ value from the spefication of your focuser (how many ticks for a complete revolution of your focuser) and the thread pitch of
+ your telescope drawtube along with any gearing involved.</para>
+ <para> Alternatively, you can measure how far the drawtube moves from end to end (be careful not to force the drawtube) with
+ a set of calipers or a ruler. By subtracting the furthest "in" position (in ticks) from the furthest "out" position (in ticks) you
+ have how many ticks moved the drawtube the distance you measured. From this you can calculate the distance in microns a single
+ tick moves the drawtube.</para>
+ <para> Other types of telescope will have other ways to adjust the focal plane, for example, by moving the primary or
+ secondary mirrors. You will need to either get the Step Size from the documentation for your equipment of work out how to
+ measure it in a way that are consistent with that described above.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>CFZ Camera</guilabel>: The pixel size of the camera attached via the Optical Train may have a limiting
+ effect on the CFZ. So an equivalent CFZ for the attached camera is calculated assuming a Nyquist 2* limit.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Final CFZ</guilabel>: This is the larger of the CFZ calculated using the selected algorithm for the specified
+ parameter and the <guilabel>CFZ Camera</guilabel>. It is the display value and is, in effect, the CFZ of your equipment.</para>
+ </listitem>
+
+ </itemizedlist>
+ </sect3>
+
+
+ <sect3 id="focus-advisor">
+ <title>Focus Advisor</title>
+
+ <screenshot>
+ <screeninfo> Focus Advisor </screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="focus_advisor.png" format="PNG" width="50%"/>
+ </imageobject>
+
+ <textobject>
+ <phrase>Focus Advisor</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para> This is the Focus Advisor pane. It is an experimental feature to assist with management of focus parameters.</para>
+
+ <para> The purpose of Focus Advisor is to help people struggling to use the Focus module within Ekos. The Focus module is
+ functionally rich and contains a lot of parameters that need to be set self-consistently to achieve good results. Focus
+ Advisor is designed to help with basic parameter setup that should achieve focus. It is not designed to achieve the best possible
+ focus for your equipment; you will have to experiment with your setup to achieve that. But Focus Advisor provides a place to
+ start that experimentation.</para>
+
+ <para> So Focus Advisor is aimed towards the less experienced users.</para>
+ <para> If Focus Advisor does not appear to give good results on your setup why not start a discussion on the forum so it can
+ be enhanced to give better results in the future. This way it will build over time to be more useful.</para>
+ <para> When you click on the Focus Advisor pane it works out a series of parameter recommendations based on the Optical
+ Train you are using in Focus.</para>
+ <para> At the top of the pane it displays information about the connected Optical Train. Then it displays 6 lines relating
+ to various sets of parameters used within Focus. Against each line is a checkbox to update the associated Focus fields
+ with Focus Advisor's recommendations.</para>
+ <para> Focus parameters are broken into the following groupings:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Step Size</guilabel>: This is the suggested focus step size to use. This is a critical parameter. It is
+ defaulted from the Critical Focus Zone (CFZ) pane. So the first thing to do is set this panel up and get a reasonable value
+ for the CFZ. Alternatively, if you know a reasonable value for your equipment from other sources you can just enter that.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Out Step Multiple</guilabel>: This is the suggested outward step multiple to use.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Camera & Filter Wheel Parameters</guilabel>: This sets the parameters in the
+ <link linkend="focus-ccd-filter-wheel">CCD & Filter Wheel</link> section of the Focus screen. By hovering the mouse over this
+ label you can see in the tooltip what values Focus Advisor is recommending.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Settings Tab Parameters</guilabel>: This sets the parameters in the
+ <link linkend="focus-settings">Focus Settings</link> pane of the Focus screen. By hovering the mouse over this
+ label you can see in the tooltip what values Focus Advisor is recommending.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Process Tab Parameters</guilabel>: This sets the parameters in the
+ <link linkend="focus-process">Focus Process</link> pane of the Focus screen. By hovering the mouse over this
+ label you can see in the tooltip what values Focus Advisor is recommending.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Mechanics Tab Parameters</guilabel>: This sets the parameters in the
+ <link linkend="focus-mechanics">Focus Mechanics</link> pane of the Focus screen. By hovering the mouse over this
+ label you can see in the tooltip what values Focus Advisor is recommending.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Help</guilabel>: Press this button to get help on using Focus Advisor.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Update Params</guilabel>: Press this button to accept the Focus Advisor recommendations and update
+ the Focus parameters where the associated <guilabel>Update</guilabel> checkbox is checked..</para>
+ </listitem>
+
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="focus-filter-settings">
+ <title>Filter Settings</title>
+
+ <screenshot>
+ <screeninfo>
+ Filter Queue
+ </screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="filter_settings.png" format="PNG" width="50%"/>
+ </imageobject>
+ <textobject>
+ <phrase>Filter Queue</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para> Click the filter icon <inlinemediaobject><imageobject><imagedata fileref="view-filter.png" format="PNG"/></imageobject>
+ </inlinemediaobject> from either Capture or Focus to open the filter settings dialog. This popup allows the user to
+ configure data associated with each filter, and used for various functions within the system.</para>
+
+ <para> Focusing with different filters can be done in one of three ways within Ekos.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para> <emphasis role="bold">Direct Autofocus</emphasis>: When Capture changes to this filter it is possible to automatically
+ refocus this filter. The exposure to use for the selected filter is taken from the <guilabel>Exposure</guilabel> field. This
+ allows, for example, narrowband filters to use a longer exposure than broadband filters during Autofocus.</para>
+
+ <para> Check <guilabel>Auto Focus</guilabel> to use the filter in this way.</para>
+ </listitem>
+
+ <listitem>
+ <para> <emphasis role="bold">Autofocus on Lock Filter</emphasis>: It is possible to specify a Lock filter to use when it is
+ required to focus this filter. For example, if the Ha filter is used and an Autofocus run required, it is possible to run
+ 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 Ha filters (100 ticks in this example). 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>
+
+ <para> To use a filter in this way, check <guilabel>Auto Focus</guilabel>, specify the <guilabel>Lock Filter</guilabel> to use
+ and make sure that the Offsets for this filter and the <guilabel>Lock Filter</guilabel> are set.</para>
+ </listitem>
+
+ <listitem>
+ <para> <emphasis role="bold">Use Offsets</emphasis>: It is possible to use filter offsets to adjust focus when swapping
+ between filters, without running Autofocus. This requires some setup work ahead of time but has the advantage of
+ reduciung the number of Autofocus runs and therefore reducing the time spent autofocusing.</para>
+
+ <para> In order to use this feature it is necessary to work out the relative focus position between all filters that you
+ wish to use this functionality for. For examplke, if Lum and Red have the same focus position (they are parfocal) but Green
+ focuses 300 ticks further out than Lum (or Red) then setup Offsets for Lum, Red and Grren as 0, 0, 300 as shown above. If a
+ sequence is created to take 10 subframes of Lum, then 10 Red, then 10 Green, then at the start, since Lum has
+ <guilabel>Auto Focus</guilabel> checked, an Autofocus will be run on Lum and the 10 subs taken. Capture will then switch
+ filters to Red. Since Red has <guilabel>Auto Focus</guilabel> unchecked no Autofocus will happen and Ekos will look to the
+ Offsets between Red and Lum. In this case 0 - 0 = 0. So the focuser will not be moved and Copture will take 10 subs of Red.
+ Then Capture will swap from Red to Green. Again, Green has <guilabel>Auto Focus</guilabel> unchecked no Autofocus will happen
+ and Ekos will look to the Offsets between Green and Red. In this case 300 - 0 = 300. So Focus will adjust the focus position
+ by +300 (move the focuser out by 300 ticks). Capture will then take the 10 Green subs.</para>
+
+ <para> To use a filter in this way, uncheck <guilabel>Auto Focus</guilabel> and make sure that the Offsets for this filter
+ and all other filters that can precede this filter in a sequence are set.</para>
+
+ <para> The Offsets can either be worked out by running Autofocus with different filters and manually calculating the relative
+ offsets and entering them into the table or by using the <link linkend="build-filter-offsets">Build Offsets</link> tool.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Configure settings for each filter in the table:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para><guilabel>Filter</guilabel>: Filter Name.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Exposure</guilabel>: Set exposure time (in seconds) to be used when performing Autofocus on this filter.
+ By default, it is set to 1 second.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Offset</guilabel>: Set relative offsets. Ekos will command a focus offset change if there is a
+ difference between the current and target filter offsets. For example, given the values in the example image, if the
+ current filter is set to <emphasis>Red</emphasis> and next filter is <emphasis>Green</emphasis>, then Ekos shall
+ command the focuser to Focus In by +300 ticks. Relative positive focus offsets denote Focus Out while negative
+ values denote Focus In.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Auto Focus</guilabel>: Check this option to perform AutoFocus whenever the filter is changed
+ to this filter.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Lock Filter</guilabel>: Set which filter should be set and <emphasis>locked</emphasis> when
+ performing autofocus for this filter. "--" indicates no Lock Filter. It is not allowed to next filters more than
+ 1 deep, i.e. Red cannot be locked to Blue which is itself locked to Green. A filter cannot be locked to itself.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Last AF Solution</guilabel>: The last successful Autofocus position. Under normal operation Ekos will
+ automatically update this field.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Last AF Temp (°C)</guilabel>: The temperature of the <guilabel>Last AF Solution</guilabel>. Under
+ normal operation Ekos will automatically update this field.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Last AF Alt (°Alt)</guilabel>: The altitude of the <guilabel>Last AF Solution</guilabel>. Under
+ normal operation Ekos will automatically update this field.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Ticks / °C</guilabel>: The number of ticks to move the focuser when the temperature changes by 1°C.
+ For example, if focus moves out by 5 ticks when temperature increases by 1°C, set this field to 5. If focus moves
+ in by 5 ticks when temperature increases by 1°C, set this field to -5.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Ticks / °Alt</guilabel>: The number of ticks to move the focuser when the altitude changes by 1°Alt.
+ For example, if focus moves out by 0.5 tick when altitude increases by 1°Alt, set this field to 0.5. If focus moves in
+ by 0.5 tick when altitude increases by 1°Alt, set this field to -0.5.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Wavelength</guilabel>: The center of the passband of the filter in nanometers. This is used in
+ some Critical Focus Zone (CFZ) calculations in Focus.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>In addition to the data table, the following controls are available at the bottom of the popup:</para>
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Build Offsets</guilabel>: Press the <guibutton>Build Offsets</guibutton> button to launch the
+ <link linkend="build-filter-offsets">Build Offsets</link> popup.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Capture flats at the same focus as lights</guilabel>: When checked, flats will be taken at the
+ <guilabel>Last AF Solution</guilabel> focuser position.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Let's take an example. If we have a capture sequence starting with Lum -> Red -> Green -> Blue -> Sii -> Ha -> Oiii
+ using the setup in the Filter Settings popup:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Lum: The Lum filter is configured to Autofocus initially so an Autofocus run is performed, then the Lum sequence
+ runs.</para>
+ </listitem>
+ <listitem>
+ <para>Red: The Red filter is not configured for Autofocus and has an Offset of 0. So when the Red sequence starts,
+ there is no Autofocus run and the relative Offset between Lum and Red is 0, so the focuser is not moved.</para>
+ </listitem>
+ <listitem>
+ <para>Green: The Green filter is not configured for Autofocus and has an Offset of 300. So when the Green sequence
+ starts, there is no Autofocus run and the relative Offset between Red and Green is 300 - 0 = +300, so the focuser moves
+ out by 300.</para>
+ </listitem>
+ <listitem>
+ <para>Blue: The Blue filter is not configured for Autofocus and has an Offset of 0. So when the Blue sequence starts,
+ there is no Autofocus run and the relative Offset between Green and Blue is 0 - 300 = -300, so the focuser moves in
+ by 300.</para>
+ </listitem>
+ <listitem>
+ <para>Sii: The Sii filter is configured for Autofocus, is locked to Lum and has an Offset of 0. So when the Sii sequence
+ starts, there is an Autofocus run on Lum and the relative Offset between Lum and Sii is 0 - 0 = 0, so the focuser moves
+ to the Lum Autofocus run solution.</para>
+ </listitem>
+ <listitem>
+ <para>Ha: The Ha filter is configured for Autofocus, is locked to Lum and has an Offset of 100. So when the Ha sequence
+ starts, there is an Autofocus run on Lum and the relative Offset between Lum and Ha is 100 - 0 = +100, so the focuser
+ moves to the Lum Autofocus run solution then out by 100.</para>
+ </listitem>
+ <listitem>
+ <para>Oiii: The Oiii filter is configured for Autofocus, is locked to Lum and has an Offset of -100. So when the Oiii
+ sequence starts, there is an Autofocus run on Lum and the relative Offset between Lum and Oiii is -100 - 0 = -100, so
+ the focuser moves to the Lum Autofocus run solution then in by 100.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+
+ <sect3 id="build-filter-offsets">
+ <title>Build Offsets</title>
+
+ <screenshot>
+ <screeninfo>
+ Build Filter Offsets
+ </screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="build_filter_offsets.png" format="PNG" width="25%"/>
+ </imageobject>
+ <textobject>
+ <phrase>Build Filter Offsets</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>
+ Click the <guilabel>Build Offsets</guilabel> button on the <link linkend="focus-filter-settings">Filter Settings</link>
+ popup to launch the Build Offsets tool. Filter Offsets can either be entered manually into the table
+ in the Filter Settings popup or this tool can be used to assist in creating them.
+ </para>
+ <para>
+ <emphasis>Note: This utility should not be run during an imaging session as it takes exclusive control of the
+ Focus process whilst it is running.</emphasis>
+ </para>
+ <para>
+ To start with, configure settings for each filter in the table in the Filter Settings popup and then launch
+ Build Filter Offsets. The popup is launched with a table of filters.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>Filter</guilabel>: Filter Name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Offset</guilabel>: The current offset.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Lock Filter</guilabel>: The current Lock filter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel># Focus Runs</guilabel>: The number of focus runs for this filter. The default is 5.
+ To exclude a filter from the process set this field to zero.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ When the <guilabel># Focus Runs</guilabel> have been configured press the <guilabel>Run</guilabel>
+ button to start the automated process.
+ </para>
+ <para>
+ Press the <guilabel>Stop</guilabel> button to stop the process at any time.
+ </para>
+ <para>
+ Let's take an example where we have 4 filters: Lum, Sii, Ha and Oiii. We have run the process with
+ 5 runs for Lum, Sii and Ha and 0 for Oiii (effectively excluding this filter from the process). In this
+ case 8 extra columns have been created in the table.
+ </para>
+ <screenshot>
+ <screeninfo>
+ Build Filter Offsets
+ </screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="build_filter_offsets2.png" format="PNG" width="50%"/>
+ </imageobject>
+ <textobject>
+ <phrase>Build Filter Offsets</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <itemizedlist>
+ <listitem>
+ <para>
+ AF Run 1-5: The maximum <guilabel># Focus Runs</guilabel> selected by the user is 5, so 5 columns
+ have been created, 1 for each AF run solution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Average: The average (mean) of the AF solutions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ New Offset: The offset calculated from the Lum filter. E.g. for Sii 36731 - 36743 = -12
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Save: Check to save the offset for this filter when the <guilabel>Save</guilabel> button is pressed.
+ The default is to check these boxes but unchecking allows a value to be ignored whilst saving
+ other filters.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ At this stage, it is recommended to review the AF runs to make sure they are all good. For example, lets
+ assume we are unhappy with the 5th AF run on Ha. In this case we could either:</para>
+ <itemizedlist>
+ <listitem>
+ <para> Edit AF Run 5 and set the value to whatever value you want.</para>
+ </listitem>
+ <listitem>
+ <para> Edit the New Offset column and set the value.</para>
+ </listitem>
+ <listitem>
+ <para> Discard the AF Run 5 by setting the value to 0 (see below). In this case, the Average and New Offset
+ for Ha is recalculated based on AF Run 1-4.</para>
+ </listitem>
+ </itemizedlist>
+ <screenshot>
+ <screeninfo>
+ Build Filter Offsets
+ </screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="build_filter_offsets3.png" format="PNG" width="50%"/>
+ </imageobject>
+ <textobject>
+ <phrase>Build Filter Offsets</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ After reviewing the results, the user can press:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Save: All filters where the <guilabel>Save</guilabel> checkbox is checked will have the New Offset
+ value saved in Filter Offsets for use during the next imaging session.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Close: The Build Filter Offsets tool is closed without saving any data.
+ </para>
+ </listitem>
+ </itemizedlist>
</sect3>
<sect3 id="focus-display">
@@ -997,10 +1697,15 @@
</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>
+ taken during the focus process. If <guilabel>Ring Mask</guilabel> is selected, then the mask
+ is drawn on the image. All the stars detected by Ekos based on the selected parameters, have their
+ HFR value displayed next to the associated star (unless Measure is set to FWHM). </para>
+
+ <para> If <guilabel>Mosaic Mask</guilabel> has been selected then the FITS viewer displays the
+ mosaic 3x3 grid showing the center, edges and sides as configured in the Mosaic Mask options.
+ <screenshot><screeninfo> Focus Display Mosaic</screeninfo><mediaobject>
+ <imageobject><imagedata fileref="focus_display_mosaic.png" format="PNG" width="50%"/></imageobject>
+ <textobject><phrase>Focus Display Mosaic</phrase></textobject></mediaobject></screenshot></para>
<para> The window supports the following FITS viewer options (at the top
of the window):</para>
@@ -1035,6 +1740,10 @@
<para> <guibutton>Toggle Stars</guibutton>: Toggle star detection on
or off.</para>
</listitem>
+
+ <listitem>
+ <para> <guibutton>View Star Profile</guibutton>: Launches the View Star Profile dialog.</para>
+ </listitem>
</itemizedlist>
</sect3>
@@ -1055,49 +1764,75 @@
</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> The V-Curve displays focuser position (x-axis) versus focus Measure, e.g. 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 value.</para>
+
+ <para> The units of the y-axis depend on the selected focus Measure. For example, for HFR, the y-axis will either be in Pixels
+ or Arc Sseconds depending on how <guilabel>Display Units</guilabel> is set.</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> If <guilabel>Refine Curve Fit</guilabel> is selected, Focus will check for and potentially exclude outlying datapoonts.
+ In this case datapoints 1, 5 and 7 were excluded.</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>
+ <para> <guilabel>HFR</guilabel>: Displays the star HFR for the most recent datapoint if relevant.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>FWHM</guilabel>: Displays the star FWHM for the most recent datapoint if relevant.</para>
</listitem>
<listitem>
- <para> <guilabel>Stars</guilabel>: The number of stars used for the
- most recent datapoint.</para>
+ <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>
+ <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>
+ <para> <guibutton>Relative Profile...</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>
+ <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>
+ <para> Here is a V-Curve when Measure is set to HFR Adj:
+ <screenshot><screeninfo> V-Curve HFR Adj</screeninfo><mediaobject><imageobject>
+ <imagedata fileref="focus_vcurve_hfradj.png" format="PNG" width="50%"/></imageobject><textobject>
+ <phrase>Focus V-Curve HFR Adj</phrase></textobject></mediaobject></screenshot></para>
+
+ <para> Here is a V-Curve when Measure is set to FWHM:
+ <screenshot><screeninfo> V-Curve FWHM</screeninfo><mediaobject><imageobject>
+ <imagedata fileref="focus_vcurve_fwhm.png" format="PNG" width="50%"/></imageobject><textobject>
+ <phrase>Focus V-Curve FWHM</phrase></textobject></mediaobject></screenshot></para>
+
+ <para> Here is a V-Curve when Measure is set to # Stars. In this case the Critical Focus Zone (CFZ)
+ <guilabel>Display</guilabel> checkbox has been checked so the CFZ is displayed as well:
+ <screenshot><screeninfo> V-Curve Num Stars</screeninfo><mediaobject><imageobject>
+ <imagedata fileref="focus_vcurve_numstars.png" format="PNG" width="50%"/></imageobject><textobject>
+ <phrase>Focus V-Curve Num Stars</phrase></textobject></mediaobject></screenshot></para>
+
+ <para> Here is a V-Curve when Measure is set to Fourier:
+ <screenshot><screeninfo> V-Curve Fourier</screeninfo><mediaobject><imageobject>
+ <imagedata fileref="focus_vcurve_fourier.png" format="PNG" width="50%"/></imageobject><textobject>
+ <phrase>Focus V-Curve Fourierj</phrase></textobject></mediaobject></screenshot></para>
+
+ <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 Measure, in this case HFR, changes between frames. </para>
+
+ <para> This is very useful, for example, when trying to get the system into approximate focus before starting an Autofocus run.
+ In this case Framing is started and the Step In and Step Out buttons used to adjust focus and the effect on the V-Curve
+ observed.</para>
<screenshot>
<screeninfo> V-Curve as timeseries</screeninfo>
@@ -1145,150 +1880,236 @@
<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>
+ <para> The exact settings that work best for a given astronomical setup need to be worked out by the user using trial and error.
+ A good place to start is the <link linkend="focus-advisor">Focus Advisor</link> section. Run Focus Advisor and accept its
+ recommendations. 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>
+ <para> Setup Backlash. See the <link linkend="focus-backlash">Backlash</link> section for more details.</para>
</listitem>
<listitem>
- <para> Select Linear 1 Pass and your curve of choice, say Hyperbola.
- Select Use Weights.</para>
+ <para> Initial Step Size. This is a critical parameter. You may have an idea from other people with a similar setup.
+ If not you can try setting it from the Critical Focus Zone (CFZ) for your equipment. See the
+ <link linkend="focus-cfz">CFZ section</link> for more details.</para>
+ </listitem>
+
+ <listitem>
+ <para> Start near to focus by manually finding focus. Use the <guibutton>Start Framing</guibutton> option and manually adjust
+ the focus to get to approximate focus.</para>
</listitem>
<listitem>
- <para> Make sure you are finding enough stars.</para>
+ <para> Make sure you are finding enough stars. Increasing the exposure usually finds more stars (but makes the focus process
+ longer).</para>
+ </listitem>
+ </itemizedlist>
- <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>
+ <para> Run Autofocus. This is the sort of V-Curve you are after:</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>
+
+ <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>
+ </sect3>
- <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>
+ <sect3 id="focus-backlash">
+ <title>Focuser Backlash</title>
- <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>
+ <para>Backlash in the focuser setup is due 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 even if the same focuser is used.</para>
- <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>
+ <para> It is important to have a clear strategy for dealing with Backlash and to setup Focus appropriately for the chosen
+ strategy. It is best to have backlash managed in one place to avoid conflicts. Whilst it is possible to have backlash
+ managed in multiple places (this has been done successfully) it is not recommended in general because it can lead to conflicts
+ between software components and the focuser.</para>
- <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>
+ <para> There are several ways to measure backlash in ticks. Consult the documentation on your focuser or use the internet
+ including the Indi Forum.</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 <guibutton>Device Backlash</guibutton> and <guibutton>AF Overscan</guibutton> off (set to zero).</para>
</listitem>
<listitem>
- <para> Setup the Mechanics tab.</para>
+ <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 <guibutton>Device Backlash</guibutton> and <guibutton>AF Overscan</guibutton> off
+ (set to zero). Alternatively, if it's possible, you could turn off the focuser's backlash facility and use either the
+ Device Driver or AF Overscan to manage backlash.</para>
+ </listitem>
- <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> <emphasis role="bold">Backlash Managed by Device Driver</emphasis>: If your device driver has the ability to
+ manage backlash then you can use this facility and turn off AF Overscan (set to zero). Alternatively,
+ you could turn off the device driver's backlash facility and set AF Overscan.</para>
- <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>
+ <para> To know whether the device driver supports backlash, check the <guibutton>Device Backlash</guibutton> field.
+ If it is enabled and you can set values then the driver supports Backlash. If the field is disabled then the driver
+ does not support Backlash.</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> <emphasis role="bold">AF Overscan</emphasis>: The Focus module can manage Backlash itself by over scanning
+ outward motions by the value in the <guibutton>AF Overscan</guibutton> field. For example, if <guibutton>AF Overscan</guibutton>
+ is set to 40 then whenever Focus moves the focuser outwards, it does this as a 2-step process. Firstly it moves the
+ focuser 40 ticks past where it wants to end up; secondly it moves back in by 40 ticks.</para>
- <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>
+ <para> The advantage of <guibutton>AF Overscan</guibutton> is that you do not need to know Backlash exactly, you just need
+ to set the <guibutton>AF Overscan</guibutton> >= backlash. So, for example, if you measure backlash as around 60 ticks
+ then you could set <guibutton>AF Overscan</guibutton> to 80.</para>
- <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>
+ <para> <guibutton>AF Overscan</guibutton> is also useful where Backlash is not exactly predictable. For example, if Backlash
+ measurements yield slightly different values, e.g. 61, 60, 59 ticks then by using <guibutton>AF Overscan</guibutton> this
+ inconsistency can be effectively neutralised. Were you to use <guibutton>Focuser Backlash</guibutton> you would probably
+ average the readings and set the value to 60. Sometimes this will correctly take up all the backlash; sometimes it will
+ be a little short; and sometimes it will over correct.</para>
- <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>
+ <para> All focuser movements managed by Focus will have <guibutton>AF Overscan</guibutton> applied, including Step Out, Goto,
+ Autofocus runs, Adaptive Focus movements, Adapt Start Pos movements and Take flats at the same position as lights.</para>
</listitem>
</itemizedlist>
+ </para>
</sect3>
+ <sect3 id="focus-adaptive">
+ <title>Adaptive Focus</title>
+
+ <screenshot>
+ <screeninfo> Adaptive Focus </screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="focus_adaptive_focus.png" format="PNG" width="75%"/>
+ </imageobject>
+
+ <textobject>
+ <phrase>Adaptive Focus</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para> Ekos support the concept of Adaptive Focus (AF). Without AF, a typical imaging plan would start
+ with an Autofocus run then a sequence of subframes, then an Autofocus run, etc. The Autofocus runs would be triggered by
+ a number of factors such as time, filter change, temperature change, etc. So basically as a sequence
+ runs subframes are being taken slightly away from optimum focus until a threshold (e.g. temperature
+ change) triggers an Autofocus run.</para>
+
+ <para> The idea of AF is to adjust focus as environmental factors change to try to take each subframe
+ as close as possible to optimum focus. The effect is like performing an Autofocus run before but without the
+ overhead of doing the run.</para>
+
+ <para> AF works as a complement to the various triggers for Autofocus that are available in Ekos now. So
+ it is not necessary to change the Autofocus triggers when starting to use AF. Indeed, at the start, given
+ that AF is an experimental feature, it is not recommended to relax Autofocus conditions when using AF. However,
+ over time, as confidence grows in AF it would be possible to do less Autofocusing (and therefore more
+ imaging). But either way, each subframe should be more in focus when using AF, providing it is setup correctly. </para>
+
+ <para> So how do you know if AF would be useful for your setup or not? Perhaps the simplest way would be to
+ examine subframes just after an Autofocus and compare them with subframes just before the next Autofocus. Can you
+ see a difference in focus? If you have a setup where the focus point is tolerant of environmental changes between
+ Autofocus runs then AF may not add anything to your images; if however you have a setup that is sensitive to
+ environmental changes and the frequency of Autofocus runs is a compromise between quality and imaging time then
+ AF ought to improve the quality of your subframes.</para>
+
+ <para>AF currently supports two environmental dimensions: Temperature and Altitude (of the imaged target):</para>
+ <itemizedlist>
+ <listitem>
+ <para> Temperature. All the components of the imaging system will be affected by changes in ambient temperature.
+ The most obvious will be the telescope tube. Typically this will expand as temperature increases and contract as
+ it descreases. This will affect the focus point. But also the optical path the light from the imaged target takes
+ through the atmosphere and through the imaging components of the telescope will be affected by temperature and
+ therefore will affect the focus point.</para>
+
+ <para> It is necessary to have a reliable source of temperature information available to the focus module in order
+ to use the temperature feature of AF.</para>
+
+ <para> Where the temperature source is located is, of course, upto the user. Given the changes in temperature effect
+ many components it is not obvious where the best location would be. Some experimentation may be required to get
+ the best results but as a guide, the source should be near the imaging train but not near any heating effect of
+ electrical equipment that would say, heat the temperature source but not the optical train. Consistency of location
+ is likely to be important.</para>
+ </listitem>
+
+ <listitem>
+ <para> Altitude. Some users have reported that the focus point changes with the altitude of the target. This effect
+ is likely to be smaller than the temperature effect and may be negligible for some setups.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para> To use AF you need to work out firstly whether you want to adapt for Temperature, Altitude or both. If you are
+ new to AF it is recommended to start with Temperature and once you have that working, determine whether your setup would
+ benefit from adding Altitude.</para>
+
+ <para> The first step is to workout the <guilabel>Ticks / °C</guilabel> and/or <guilabel>Ticks / °Alt</guilabel> for your
+ equipment. To do this there is an existing utility in Ekos whereby when Focus logging is enabled, in addition to adding focus
+ messages to the debug log, every time an Autofocus run completes, information is written to a text file in a directory called
+ focuslogs located in the same place as the debug logs directory. The files are called “autofocus-(datetime).txt”. The data
+ written are: date, time, position, temperature, filter, HFR, altitude. This data will need to be analysed outside of Ekos to
+ determine the <guilabel>Ticks / °C</guilabel> and if required the <guilabel>Ticks / °Alt</guilabel>.</para>
+
+ <para> Here is an example of a “autofocus-(datetime).txt” file:
+ <screenshot>
+ <screeninfo> Focus Autofocus Log </screeninfo>
+ <mediaobject> <imageobject> <imagedata fileref="focus_autofocus_log.png" format="PNG" width="50%"/>
+ </imageobject><textobject><phrase>Focus Autofocus Log</phrase></textobject></mediaobject>
+ </screenshot></para>
+
+ <para> Currently Ekos supports a simple linear relationship between temperature, or altitude, and ticks. In the future,
+ if there is demand, more sophisticated relationships could be supported. A linear relationship will deliver the majority
+ of the benefit of AF and is fairly straight-forward to adminster. More complex relationships could be more accurate but
+ come with more complex administration. Note also that more complex focus point vs temperature relationships will likely
+ be more or less linear for small changes in temperature.</para>
+
+ <para> A way to get a value for <guilabel>Ticks / °C</guilabel> would be to take the data from the
+ autofocus-(datetime).txt files from a few nights of observing into a spreadsheet and graph focus position against temperature
+ for each filter. Review the data and remove any outliers and plot a line of best fit. Use the line to get
+ <guilabel>Ticks / °C</guilabel>. If you intend to adapt for altitude as well as temperature, then it would be better to use a
+ set of data at similar altitude when calibrating temperature. Then its possible to calculate the effect of Temperature and
+ remove this from the data when calculating the effect of Altitude.</para>
+
+ <para> You will need to ensure that your focus position is repeatable at the same temperature and altitude and that there
+ is no slipping of the focuser or uncompensated backlash. In addition, when calibrating it is better to avoid changing the
+ optical train in a way that could change the focus position. If this is unavoidable and if the change affected the focus
+ position then you will need to appropriately adjust the historical focus data so they can be compared.</para>
+
+ <para> A simple approach is to start with a small amount of data, say 1 night and use this to calculate, say the Ticks /
+ degree C. Run with this and adjust it over time as you collect more data. A way to check how well AF is performing would be
+ to use Analyze to review how AF had moved the focus over 1 hour. If things are spot on, then where ever AF had positioned
+ the focuser after 1 hour would match the Autofocus result. Where there is a discrepancy, it will be because of randomness
+ in the Autofocus result and miscalibration in the AF <guilabel>Ticks / °C</guilabel>. By doing this regularly you will build
+ knowledge of your equipment and be able to fine tune AF. Below is a screenshot of Analze configured for Focus where you can
+ see how Focus position changes throughout the imaging session:
+ <screenshot>
+ <screeninfo> Focus Analyze </screeninfo>
+ <mediaobject> <imageobject> <imagedata fileref="focus_analyze.png" format="PNG" width="50%"/>
+ </imageobject><textobject><phrase>Focus Analyze</phrase></textobject></mediaobject>
+ </screenshot></para>
+
+ <para> Once you have your data you can configure it in the <link linkend="focus-filter-settings">Filter Settings</link>
+ popup. Then in Focus, switch on Adaptive Focus on the <link linkend="focus-settings">Focus Settings</link> tab. At this
+ point, when you run a sequence, Ekos will check after each subframe whether it needs to adapt the focuser position. If so,
+ Focus will do that and then Capture will continue with the next Subframe.</para>
+
+ <para> The screenshot at the top of this section shows an example. <guilabel>Ticks / °C</guilabel> is set to 9.
+ Autofocus ran and it solved at 36580 at 10C. Then a simple sequence of 5 subframes was run. The temperature was firstly set to 9C
+ then to 8C. After each subframe completed, Ekos performed an adaptive focus run and where there was a temperature change it calculates
+ the number of ticks to move the focuser. In this example, the focuser was moved inward by 9 ticks on 2 separate occasions,
+ starting at 36580, before moving to 36571 and then to 36562 as shown on the Focus Tab in the Current Position widget and in
+ the message box.</para>
+ </sect3>
+
+
<sect3 id="Coefficient_of_Determination">
<title>Coefficient of Determination, R²</title>
@@ -1296,12 +2117,12 @@
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
+ This 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>
+ obtain, but as a guide, a value above, say 0.9 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
@@ -1341,8 +2162,7 @@
</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
+ <para> The Levenberg-Marquardt algorithm 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
diff --git a/doc/filter_settings.png b/doc/filter_settings.png
index 9972fbef46..0a25f0c860 100644
Binary files a/doc/filter_settings.png and b/doc/filter_settings.png differ
diff --git a/doc/focus_adaptive_focus.png b/doc/focus_adaptive_focus.png
new file mode 100644
index 0000000000..ac8d7dd6a0
Binary files /dev/null and b/doc/focus_adaptive_focus.png differ
diff --git a/doc/focus_advisor.png b/doc/focus_advisor.png
new file mode 100644
index 0000000000..02f434ea3a
Binary files /dev/null and b/doc/focus_advisor.png differ
diff --git a/doc/focus_analyze.png b/doc/focus_analyze.png
new file mode 100644
index 0000000000..b1c6b1989d
Binary files /dev/null and b/doc/focus_analyze.png differ
diff --git a/doc/focus_autofocus_log.png b/doc/focus_autofocus_log.png
new file mode 100644
index 0000000000..c93049538a
Binary files /dev/null and b/doc/focus_autofocus_log.png differ
diff --git a/doc/focus_cfz_classic.png b/doc/focus_cfz_classic.png
new file mode 100644
index 0000000000..20081f9e4b
Binary files /dev/null and b/doc/focus_cfz_classic.png differ
diff --git a/doc/focus_cfz_gold.png b/doc/focus_cfz_gold.png
new file mode 100644
index 0000000000..9a2f8afcea
Binary files /dev/null and b/doc/focus_cfz_gold.png differ
diff --git a/doc/focus_cfz_moustache.png b/doc/focus_cfz_moustache.png
new file mode 100644
index 0000000000..1c9eb71ec6
Binary files /dev/null and b/doc/focus_cfz_moustache.png differ
diff --git a/doc/focus_cfz_wavefront.png b/doc/focus_cfz_wavefront.png
new file mode 100644
index 0000000000..ad8902d00f
Binary files /dev/null and b/doc/focus_cfz_wavefront.png differ
diff --git a/doc/focus_display_mosaic.png b/doc/focus_display_mosaic.png
new file mode 100644
index 0000000000..d843bea8b8
Binary files /dev/null and b/doc/focus_display_mosaic.png differ
diff --git a/doc/focus_mechanics.png b/doc/focus_mechanics.png
index 624a80a06d..ef9e59d5e0 100644
Binary files a/doc/focus_mechanics.png and b/doc/focus_mechanics.png differ
diff --git a/doc/focus_mechanics1.png b/doc/focus_mechanics1.png
new file mode 100644
index 0000000000..ebfe4f6e34
Binary files /dev/null and b/doc/focus_mechanics1.png differ
diff --git a/doc/focus_process.png b/doc/focus_process.png
index 7c545da468..471de08d60 100644
Binary files a/doc/focus_process.png and b/doc/focus_process.png differ
diff --git a/doc/focus_vcurve.png b/doc/focus_vcurve.png
index 03725ba2a7..b84ce07097 100644
Binary files a/doc/focus_vcurve.png and b/doc/focus_vcurve.png differ
diff --git a/doc/focus_vcurve_fourier.png b/doc/focus_vcurve_fourier.png
new file mode 100644
index 0000000000..fa59d225f9
Binary files /dev/null and b/doc/focus_vcurve_fourier.png differ
diff --git a/doc/focus_vcurve_fwhm.png b/doc/focus_vcurve_fwhm.png
new file mode 100644
index 0000000000..754f79db1d
Binary files /dev/null and b/doc/focus_vcurve_fwhm.png differ
diff --git a/doc/focus_vcurve_hfradj.png b/doc/focus_vcurve_hfradj.png
new file mode 100644
index 0000000000..7a70c3bc11
Binary files /dev/null and b/doc/focus_vcurve_hfradj.png differ
diff --git a/doc/focus_vcurve_numstars.png b/doc/focus_vcurve_numstars.png
new file mode 100644
index 0000000000..e0c868f72f
Binary files /dev/null and b/doc/focus_vcurve_numstars.png differ
diff --git a/doc/focuser_group.png b/doc/focuser_group.png
index af3bcbc90a..9562e4e325 100644
Binary files a/doc/focuser_group.png and b/doc/focuser_group.png differ
diff --git a/doc/index.docbook b/doc/index.docbook
index ea032690e8..5da1423d05 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -216,8 +216,8 @@
<legalnotice>&FDLNotice;</legalnotice>
-<date>2023-02-01</date>
-<releaseinfo>3.6.3</releaseinfo>
+<date>2023-06-01</date>
+<releaseinfo>3.6.5</releaseinfo>
<abstract>
<para>
More information about the kde-doc-english
mailing list