Git commit 2f5d84b8f7fc81e3744c2cc98d647a8dff9a5f7e by John Evans. Committed on 07/02/2024 at 13:56. Pushed by johnevans into branch 'master'.
Focus Docbook Update 3.6.9 Update to the Kstars Manual for focus changes in 3.6.9 M +339 -241 doc/ekos-focus.docbook M +- -- doc/ekos_focus.png M +- -- doc/focus_adaptive_focus.png M +- -- doc/focus_advisor.png M +- -- doc/focus_cfz_classic.png M +- -- doc/focus_cfz_gold.png M +- -- doc/focus_cfz_moustache.png M +- -- doc/focus_cfz_wavefront.png M +- -- doc/focus_mechanics.png M +- -- doc/focus_mechanics1.png M +- -- doc/focus_process.png M +- -- doc/focus_settings.png M +- -- doc/focuser_group.png M +3 -3 doc/index.docbook https://invent.kde.org/education/kstars/-/commit/2f5d84b8f7fc81e3744c2cc98d647a8dff9a5f7e diff --git a/doc/ekos-focus.docbook b/doc/ekos-focus.docbook index 39fd1d75f6..f306a3e0e3 100644 --- a/doc/ekos-focus.docbook +++ b/doc/ekos-focus.docbook @@ -321,11 +321,6 @@ run. The <guibutton>Stop</guibutton> button is used to stop the run. </para> - <para> The <guibutton>Inspector</guibutton> button starts an - <link linkend="focus-aberration-inspector">Aberration Inspector</link> run. - The <guibutton>Stop</guibutton> button is used to stop the run. - </para> - <para> The <guibutton>Capture Image</guibutton> button will take a frame based on the current settings in the <link linkend="focus-ccd-filter-wheel"> Camera & Filter Wheel Group</link>. The <guibutton>Start Framing</guibutton> @@ -456,7 +451,82 @@ </itemizedlist> </sect2> - <sect2 id="focus-settings"> + <sect2 id="focus-tools"> + <title>Tools Group</title> + + <screenshot> + <screeninfo> Focus Tools Group </screeninfo> + + <mediaobject> + <imageobject> + <imagedata fileref="focus_tools_group.png" format="PNG" width="50%"/> + </imageobject> + + <textobject> + <phrase>Focus Tools Group</phrase> + </textobject> + </mediaobject> + </screenshot> + + <para> This section describes the focus tools that are currently available.</para> + + <itemizedlist> + <listitem> + <para> The <guibutton>Aberration Inspector</guibutton> button starts an + <link linkend="focus-aberration-inspector">Aberration Inspector</link> run. + The <guibutton>Stop</guibutton> button can be used to stop the run. + </para> + </listitem> + <listitem> + <para> The <guibutton>CFZ</guibutton> button launches the + <link linkend="focus-cfz">Critical Focus Zone</link> tool. + </para> + </listitem> + <listitem> + <para> The <guibutton>Advisor</guibutton> button launches the + <link linkend="focus-advisor">Focus Advisor</link> tool. + </para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 id="focus-options"> + <title>Focus Options</title> + + <screenshot> + <screeninfo> Focus Options </screeninfo> + + <mediaobject> + <imageobject> + <imagedata fileref="focus_options.png" format="PNG" width="50%"/> + </imageobject> + + <textobject> + <phrase>Focus Options</phrase> + </textobject> + </mediaobject> + </screenshot> + + <para>Parameters to configure Focus are accessed by pressing the <guibutton>Options...</guibutton> + button. This launches the Options dialog with three panes:</para> + + <itemizedlist> + <listitem> + <para><link linkend="focus-settings">Settings</link>: These are general Focus settings.</para> + </listitem> + <listitem> + <para><link linkend="focus-process">Process</link>: Parameters associated with the Autofocus process.</para> + </listitem> + <listitem> + <para><link linkend="focus-mechanics">Mechanics</link>: Parameters associated with the focuser mechanics.</para> + </listitem> + </itemizedlist> + + <para>The parameters are stored for each Optical Train. This allows different configurations to be stored for + different equipment. Parameters are stored when they are changed, so on startup the last used configuration for + the selected Optical Train is loaded.</para> + + <sect3 id="focus-settings"> <title>Focus Settings</title> <screenshot> @@ -473,9 +543,7 @@ </mediaobject> </screenshot> - <para> Next are 5 tabbed panes of parameters. These parameters are - retained between sessions. First up is the Settings pane.</para> - + <para>General section parameters:</para> <itemizedlist> <listitem> <para> <guilabel>Auto Select Star</guilabel>: This setting is only relevant if @@ -510,7 +578,7 @@ <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> <listitem> <para> <guilabel>Sub Frame</guilabel>: Select to use a single star for the @@ -539,83 +607,87 @@ the optical train to settle by waiting this many seconds after the Autofocus process has completed, before restarting guiding.</para> </listitem> + </itemizedlist> + <para>Mask Section Paramters:</para> + + <para>These controls relate to <emphasis role="bold">Masking Options</emphasis> + to be used when in <guilabel>Full Field</guilabel> mode. The effect of Masking Options can be seen in the + <link linkend="focus-display">FITS Viewer</link>.</para> + <itemizedlist> <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 - if all stars of the field should be considered for focusing.</para> - </listitem> + <para> <guilabel>Use all stars for focusing</guilabel>: Select this option + if all stars of the field should be considered for focusing.</para> + </listitem> - <listitem> - <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 - of your FOV.</para> - </listitem> - - <listitem> - <para> <guilabel>Mosaic Mask</guilabel>: A 3x3 mosaic is composed with tiles - 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 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, especially 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> - </listitem> - - <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> - - <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> 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> - - <para> The following controls are available: + <listitem> + <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 + of your FOV.</para> + </listitem> + + <listitem> + <para> <guilabel>Mosaic Mask</guilabel>: A 3x3 mosaic is composed with tiles + 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 specifying the space between + the tiles.</para> + <para> There are four 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, especially 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> + <listitem> + <para>Running the <link linkend="focus-aberration-inspector">Aberration Inspector</link> tool.</para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist> + + <para>Adaptive Focus Parameters:</para> + + <para> The next set of controls relate to <emphasis role="bold">Adaptive Focus</emphasis>. + 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> + + <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> 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> + + <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> @@ -656,13 +728,11 @@ <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> - </sect2> + </itemizedlist> + </para> + </sect3> - <sect2 id="focus-process"> + <sect3 id="focus-process"> <title>Focus Process</title> <screenshot> @@ -679,8 +749,7 @@ </mediaobject> </screenshot> - <para> This is the Focus Process parameters pane. Widgets are only displayed if they are relevant to - the selections made.</para> + <para>Focus Process Parameters:</para> <itemizedlist> <listitem> @@ -737,7 +806,7 @@ <para> <guilabel>Algorithm</guilabel>: Select the Autofocus process algorithm: </para> - <itemizedlist> + <itemizedlist> <listitem> <para> <emphasis role="bold">Linear 1 Pass</emphasis>: This is the recommended algorithm. In this algorithm, Ekos establishes a V-Curve @@ -783,150 +852,152 @@ 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> + </listitem> - <para> This is the recommended option.</para> - </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> - <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> + <para> This is the recommended option.</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> + <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> - <para> It is no longer recommended to use this curve.</para> - </listitem> - </itemizedlist> - </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> - <listitem> - <para> <guilabel>Measure</guilabel>: Select Measure to use in the focus process. - The following are available:</para> + <para> It is no longer recommended to use this curve.</para> + </listitem> + </itemizedlist> + </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> + <para> <guilabel>Measure</guilabel>: Select Measure to use in the focus process. + The following are available:</para> - <para>The point of best focus corresponds to the minimum HFR.</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">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 point of best focus corresponds to the minimum HFR.</para> + </listitem> - <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> + <listitem> + <para> <emphasis role="bold">HFR Adj</emphasis>: This feature + 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> 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 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>The point of best focus corresponds to the minimum adjusted HFR.</para> - </listitem> + <para> When using this Measure it is usual to get smaller error bars on the datapoints when + <guilabel>Use Weights</guilabel> is selected.</para> - <listitem> - <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 adjusted HFR.</para> + </listitem> - <para>The point of best focus corresponds to the minimum FWHM.</para> + <listitem> + <para> <emphasis role="bold">FWHM</emphasis>: This feature 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>Expect the FWHM to be approximately twice the HFR of a star.</para> - </listitem> + <para>The point of best focus corresponds to the minimum FWHM.</para> - <listitem> - <para> <emphasis role="bold"># Stars</emphasis>: This is 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>Expect the FWHM to be approximately twice the HFR of a star.</para> + </listitem> - <para> The advantage of this Measure is that it is very simple and does not require - algorithms to calculate HFRs or FWHMs.</para> + <listitem> + <para> <emphasis role="bold"># Stars</emphasis>: This feature + 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 point of best focus corresponds to a maximum number of stars.</para> - </listitem> + <para> The advantage of this Measure is that it is very simple and does not require + algorithms to calculate HFRs or FWHMs.</para> - <listitem> - <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>The point of best focus corresponds to a maximum number of stars.</para> + </listitem> - <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 + <listitem> + <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> + <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> - </itemizedlist> - </listitem> - <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 present just Gaussian is - supported.</para> - </listitem> + <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 present 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> + <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> 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> It is recommended to check this option.</para> - <para> See the <link linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link> for more details.</para> - </listitem> + <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>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> - <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 Criterion</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> Experiment to find an appropriate value but a good starting point would be 0.8 or 0.9</para> + </listitem> - <para> Outliers are clearly marked on the V-Curve with an X through the datapoint.</para> + <listitem> + <para> <guilabel>Refine Curve Fit</guilabel>: This option is 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 Criterion</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> + + <para> It is recommended to check this option.</para> </listitem> <listitem> @@ -935,6 +1006,30 @@ selected.</para> </listitem> + <listitem> + <warning> + <para><guilabel>Donut Buster</guilabel>: This is an experimental feature and should be used with caution. The + intention of Donut Buster is to improve focusing for telescopes with central + obstructions that create donut shaped stars when defocused. In future it is likely that more functionality + will be developed for Donut Buster. In this release the functionality is aimed at data collection in order + to research methods of improving focus.</para> + </warning> + </listitem> + <listitem> + <warning> + <para> <guilabel>Time Dilation Factor</guilabel>: This is an experimental feature of Donut Buster and should be + used with caution. This feature scales the exposure time during Autofocus from the Exposure value entered in the + Exposure field for the furthest datapoints from focus. Datapoints near focus are taken with an unscaled exposure. + For example, if Focus is setup with an Exposure of 2s and Time Dilation Factor is set to 4, then when Autofocus + moves out to take its first datapoint, an exposure of 2s * 4 = 8s is used. On each successive datapoint the + exposure is reduced down to 2s around the point of optimum focus. As the focuser moves through focus, so the + exposure is scaled upwards to 8s for the last datapoint.</para> + <para> The purpose of this feature is to increase the brighness of out of focus datapoints which will be dimmer than + in-focus datapoints and therefore harder for star detection to resolve from the background noise.</para> + <para> This feature assumes Autofocus is run from near to optimum focus.</para> + </warning> + </listitem> + <listitem> <para> If <guilabel>Detection</guilabel> is set to Threshold then the following additional field is available:</para> @@ -987,9 +1082,9 @@ </itemizedlist> </listitem> </itemizedlist> - </sect2> + </sect3> - <sect2 id="focus-mechanics"> + <sect3 id="focus-mechanics"> <title>Focus Mechanics</title> <screenshot> @@ -1006,7 +1101,7 @@ </mediaobject> </screenshot> - <para> This is the Focus Mechanics parameters pane.</para> + <para> Focus Mechanics Parameters:</para> <itemizedlist> <listitem> @@ -1028,7 +1123,7 @@ </listitem> <listitem> - <para> <emphasis role="bold">Fixed Steps</emphasis>: This experimental option is available in the Linear 1 Pass + <para> <emphasis role="bold">Fixed Steps</emphasis>: This feature 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 @@ -1044,7 +1139,7 @@ </para> </listitem> <listitem> - <para> <emphasis role="bold">CFZ Shuffle</emphasis>: This experimental option is available in the Linear 1 Pass + <para> <emphasis role="bold">CFZ Shuffle</emphasis>: This feature 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> @@ -1137,6 +1232,7 @@ to a high enough value that it will not occur during normal operation.</para> </listitem> </itemizedlist> + </sect3> </sect2> <sect2 id="focus-cfz"> @@ -1156,7 +1252,7 @@ </mediaobject> </screenshot> - <para> This is the Focus CFZ parameters pane.</para> + <para> Focus CFZ Parameters:.</para> <itemizedlist> <listitem> @@ -1166,7 +1262,7 @@ <para> It requires some knowledge to configure it correctly. There is plenty of information available on the internet.</para> - <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 + <para> The idea of the CFZ dialog is that it starts with data from the Optical Train used in the Focus tab and uses that to 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> @@ -1174,24 +1270,26 @@ successfully completes. <screenshot> <screeninfo> Focus Mechanics </screeninfo> - <mediaobject> <imageobject> <imagedata fileref="focus_cfz_moustache.png" format="PNG" width="75%"/> + <mediaobject> <imageobject> <imagedata fileref="focus_cfz_moustache.png" format="PNG" width="50%"/> </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> + moves the focal plane. For refractors there is uaually a 1-to-1 relationship between moving the focuser which moves the + telescope draw-tube mechanism and the focal plane movement. For other types of telescope the relationship is likely to be + more complex. Refer to details of your telescope / manufacturer for this inmformation.</para> <para> The following algorithms are available: <itemizedlist> <listitem> <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 + in the top right of the dialog 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> <emphasis role="bold">Wavefront</emphasis>: The equation used is displayed in the top right of the panel. + <para> <emphasis role="bold">Wavefront</emphasis>: The equation used is displayed in the top right of the dialog. 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> @@ -1301,7 +1399,7 @@ <mediaobject> <imageobject> - <imagedata fileref="focus_advisor.png" format="PNG" width="50%"/> + <imagedata fileref="focus_advisor.png" format="PNG" width="33%"/> </imageobject> <textobject> @@ -1310,7 +1408,7 @@ </mediaobject> </screenshot> - <para> This is the Focus Advisor pane. It is an experimental feature to assist with management of focus parameters.</para> + <para> This is the Focus Advisor dialog. It is a 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 @@ -1321,9 +1419,9 @@ <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 + <para> When you click on Focus Advisor 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 + <para> At the top of the dialog 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> @@ -1331,7 +1429,7 @@ <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 + defaulted from the Critical Focus Zone (CFZ) dialog. So the first thing to do is set this dialog 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> @@ -1346,20 +1444,20 @@ </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 + <para> <guilabel>Settings Parameters</guilabel>: This sets the parameters in + <link linkend="focus-settings">Focus Settings</link>. 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 + <para> <guilabel>Process Parameters</guilabel>: This sets the parameters in + <link linkend="focus-process">Focus Process</link>. 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 + <para> <guilabel>Mechanics Parameters</guilabel>: This sets the parameters in + <link linkend="focus-mechanics">Focus Mechanics</link>. By hovering the mouse over this label you can see in the tooltip what values Focus Advisor is recommending.</para> </listitem> @@ -2077,7 +2175,7 @@ <mediaobject> <imageobject> - <imagedata fileref="focus_adaptive_focus.png" format="PNG" width="75%"/> + <imagedata fileref="focus_adaptive_focus.png" format="PNG" width="50%"/> </imageobject> <textobject> @@ -2086,7 +2184,7 @@ </mediaobject> </screenshot> - <para> Ekos support the concept of Adaptive Focus (AF). Without AF, a typical imaging plan would start + <para> Ekos supports 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 @@ -2097,10 +2195,10 @@ each subframe but without the overhead of actually 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> + it is not necessary to change the Autofocus triggers when starting to use AF. Indeed, at the start, 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 @@ -2184,7 +2282,7 @@ </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 + popup. Then in Focus, switch on Adaptive Focus in <link linkend="focus-settings">Focus Settings</link>. 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> @@ -2213,10 +2311,10 @@ user should experiment with their equipment to see what values they can 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 - run has completed. If the limit value has not been achieved, then the auto - focus is rerun.</para> + <para> There is an option to set an “R² Limit” in + <link linkend="focus-settings">Focus Settings</link> that is compared + to the calculated R² after the auto focus run has completed. If the limit value + has not been achieved, then the auto focus is rerun.</para> <para> Setting an R² Limit could be useful for unattended observation if the focus run produces a bad result for a 1-off reason. Obviously if the @@ -2310,9 +2408,9 @@ <para>The Aberration Inspector is a tool that makes use of Autofocus to analyze backfocus and sensor tilt in the connected optical train.</para> - <para>To run Aberration Inspector press the Inspector button on the focus screen located next to the Autofocus button. - See <link linkend="focus-focuser-group">Focuser Group</link> for more details. The following criteria must be met in - order for the tool to work:</para> + <para>To run Aberration Inspector press the <guibutton>Aberration Inspector</guibutton> button. + See <link linkend="focus-tools">Focus Tools</link> for more details. The following criteria must be met in + order for the button to be active and the tool to work:</para> <itemizedlist> <listitem> @@ -2329,7 +2427,7 @@ <listitem> <para>Focuser step size needs to be setup. It is the number of microns the focal plane moves for 1 focuser tick. - This is setup in the CFZ parameters tab. See the + This is setup in the CFZ dialog. See the <link linkend="focus-cfz">CFZ section</link> for more details.</para> </listitem> diff --git a/doc/ekos_focus.png b/doc/ekos_focus.png index d221baa30d..535f5061d8 100644 Binary files a/doc/ekos_focus.png and b/doc/ekos_focus.png differ diff --git a/doc/focus_adaptive_focus.png b/doc/focus_adaptive_focus.png index ac8d7dd6a0..5c3ee2fc8a 100644 Binary files a/doc/focus_adaptive_focus.png and b/doc/focus_adaptive_focus.png differ diff --git a/doc/focus_advisor.png b/doc/focus_advisor.png index 02f434ea3a..b13d1d1190 100644 Binary files a/doc/focus_advisor.png and b/doc/focus_advisor.png differ diff --git a/doc/focus_cfz_classic.png b/doc/focus_cfz_classic.png index 20081f9e4b..52b26677f3 100644 Binary files a/doc/focus_cfz_classic.png and b/doc/focus_cfz_classic.png differ diff --git a/doc/focus_cfz_gold.png b/doc/focus_cfz_gold.png index 9a2f8afcea..63d8432cba 100644 Binary files a/doc/focus_cfz_gold.png and b/doc/focus_cfz_gold.png differ diff --git a/doc/focus_cfz_moustache.png b/doc/focus_cfz_moustache.png index 1c9eb71ec6..acd08133c8 100644 Binary files a/doc/focus_cfz_moustache.png and b/doc/focus_cfz_moustache.png differ diff --git a/doc/focus_cfz_wavefront.png b/doc/focus_cfz_wavefront.png index ad8902d00f..549ea463ad 100644 Binary files a/doc/focus_cfz_wavefront.png and b/doc/focus_cfz_wavefront.png differ diff --git a/doc/focus_mechanics.png b/doc/focus_mechanics.png index ef9e59d5e0..e61b9199ff 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 index ebfe4f6e34..6c129503bf 100644 Binary files a/doc/focus_mechanics1.png and b/doc/focus_mechanics1.png differ diff --git a/doc/focus_process.png b/doc/focus_process.png index 471de08d60..023efb0113 100644 Binary files a/doc/focus_process.png and b/doc/focus_process.png differ diff --git a/doc/focus_settings.png b/doc/focus_settings.png index 6d4d0c1e6c..6bdb232537 100644 Binary files a/doc/focus_settings.png and b/doc/focus_settings.png differ diff --git a/doc/focuser_group.png b/doc/focuser_group.png index 1f4ea6cfc3..08ec890f43 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 f5914123d0..d1e93c6157 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -220,14 +220,14 @@ </authorgroup> <copyright> -<year>2001-2023</year> +<year>2001-2024</year> <holder>&Jason.Harris; and the &kstars; Team</holder> </copyright> <legalnotice>&FDLNotice;</legalnotice> -<date>2023-12-01</date> -<releaseinfo>3.6.8</releaseinfo> +<date>2024-02-06</date> +<releaseinfo>3.6.9</releaseinfo> <abstract> <para>
