[education/kstars] doc: Aberration Inspector Handbook Update
John Evans
null at kde.org
Fri Dec 1 12:59:33 GMT 2023
Git commit e3e305a178c46f4441f27b367b42570f7898e648 by John Evans.
Committed on 01/12/2023 at 13:59.
Pushed by johnevans into branch 'master'.
Aberration Inspector Handbook Update
Update to the KStars Handbook for Aberration Inspector.
A +- -- doc/aberration_inspector.png
A +- -- doc/aberration_inspector_3dgraphic.png
A +- -- doc/aberration_inspector_results.png
A +- -- doc/aberration_inspector_table.png
A +- -- doc/aberration_inspector_vcurve.png
M +405 -0 doc/ekos-focus.docbook
M +- -- doc/focuser_group.png
M +2 -2 doc/index.docbook
https://invent.kde.org/education/kstars/-/commit/e3e305a178c46f4441f27b367b42570f7898e648
diff --git a/doc/aberration_inspector.png b/doc/aberration_inspector.png
new file mode 100644
index 0000000000..4c9a1cd86e
Binary files /dev/null and b/doc/aberration_inspector.png differ
diff --git a/doc/aberration_inspector_3dgraphic.png b/doc/aberration_inspector_3dgraphic.png
new file mode 100644
index 0000000000..1d22dfc249
Binary files /dev/null and b/doc/aberration_inspector_3dgraphic.png differ
diff --git a/doc/aberration_inspector_results.png b/doc/aberration_inspector_results.png
new file mode 100644
index 0000000000..8abd4a6717
Binary files /dev/null and b/doc/aberration_inspector_results.png differ
diff --git a/doc/aberration_inspector_table.png b/doc/aberration_inspector_table.png
new file mode 100644
index 0000000000..08787c0f2e
Binary files /dev/null and b/doc/aberration_inspector_table.png differ
diff --git a/doc/aberration_inspector_vcurve.png b/doc/aberration_inspector_vcurve.png
new file mode 100644
index 0000000000..cdb68265e9
Binary files /dev/null and b/doc/aberration_inspector_vcurve.png differ
diff --git a/doc/ekos-focus.docbook b/doc/ekos-focus.docbook
index 2954b8a9be..048c1ade91 100644
--- a/doc/ekos-focus.docbook
+++ b/doc/ekos-focus.docbook
@@ -321,6 +321,11 @@
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>
@@ -2285,4 +2290,404 @@
<para> Currently the solver is used to fit either a parabolic or a
hyperbolic curve.</para>
</sect3>
+
+ <sect3 id="focus-aberration-inspector">
+ <title>Aberration Inspector</title>
+
+ <screenshot>
+ <screeninfo> Aberration Inspector </screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="aberration_inspector.png" format="PNG" width="75%"/>
+ </imageobject>
+
+ <textobject>
+ <phrase>Aberration Inspector</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <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>
+
+ <itemizedlist>
+ <listitem>
+ <para>The focuser must be an absolute focuser.</para>
+ </listitem>
+
+ <listitem>
+ <para>The focus algorithm must be Linear 1 Pass.</para>
+ </listitem>
+
+ <listitem>
+ <para>A mosaic mask must be applied.</para>
+ </listitem>
+
+ <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
+ <link linkend="focus-cfz">CFZ section</link> for more details.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>When the Inspector button is pressed, AutoFocus will run, but in addition, for each datapoint, extra information
+ is captured for later use by Aberration Inspector. Once Autofocus completes, the Aberration Inspector dialog is
+ displayed.</para>
+
+ <para>To initially setup to use the tool it is recommended to do the following:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Point to a part of the sky where Autofocus solves well. Typically this would be high in the sky away from
+ any obstacles. Choose somewhere with lots of stars such as the Milky Way. The reason this is more important
+ for Aberration Inspector than Autofocus is that focus analysis needs to be performed for each tile in the mosaic.
+ Therefore, it is important that each tile has enough stars to perform accurate Autofocus.</para>
+ </listitem>
+
+ <listitem>
+ <para>Run Autofocus a couple of times to ensure it is solving correctly and that you have a good set of
+ stars in each mosaic tile. Whilst most focus parameters can be used it is recommended to use the
+ parameters that work best for Autofocus with your equipment. The reason for this is that Aberration
+ Inspector needs be focus solve each mosaic tile and not just the sensor as a whole.</para>
+ </listitem>
+
+ <listitem>
+ <para>A mosaic mask must be applied. Some experimentation will be required to set this up optimally for
+ your equipment. The configuration parameter to adjust is the tile size which is the size of tile as a
+ percentage of sensor width. The higher the percentage, the bigger each tile, e.g. for a 4:3 sensor using a
+ tile size of 25% means each tile is 8% of the sensor's area. Using a tile size of 10% means each tile is
+ 1% of the sensor's area. The bigger the area the more stars will be present and the better the focus
+ algorithm will solve. However, the purpose of the Aberration Inspector is to provide information
+ on aberrations (backfocus and tilt) across the sensor, so ideally the information for each tile would be
+ specific to as small an area as possible.</para>
+ <para>The sweet spot for tile size is as small a value as possible that still contains enough stars to
+ solve well in each tile.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The Aberration Inspector can be used in conjunction with a device to adjust tilt and / or backfocus. The
+ method to do this is an iterative approach, like for example, collimating a telescope. The steps are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Run the Aberration Inspector and obtain results.</para>
+ </listitem>
+
+ <listitem>
+ <para>Inspect the results and make sure they are good, e.g. number of stars in each tile is sufficient and
+ the R² is acceptable for all relevant tiles.</para>
+ </listitem>
+
+ <listitem>
+ <para>Adjust tilt and / or backfocus using your device, based on Aberration Inspector results.</para>
+ </listitem>
+
+ <listitem>
+ <para>Re-run Aberration Inspector. It will launch another dialog. Check results as before.
+ If the tilt and / or backfocus is getting better then the adjustment was made in the correct sense;
+ if not reverse the sense and retry. Use the feedback from the previous adjustment for the next adjustment.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Repeat the above process until the limit of sensitivity of the equipment is reached.</para>
+
+ <para>Note the amount of adjustment, e.g. how far to turn bolts, and the sense, counterwise or counter-clockwise,
+ will vary by equipment and must be discovered by the user by trial and error. Always follow the recommendations of
+ the tilt / backfocus device manufacturer.</para>
+
+ <para>Each time Aberration Inspector is run it lauches a new dialog with the run number appended to the title.
+ This way several runs can be performed and the results compared. Note, however, that the dialog holds a lot of
+ data (roughtly 10x the amount of a standard Autofocus run). The system resources associated with this are released
+ when the dialog is closed. For this reason on lower powered machines, once the tool has been used, it is recommended
+ to close all Aberration Inspector dialogs before imaging.</para>
+
+ <para>The following sections describe the sections of the Aberration Inspector dialog.</para>
+
+ <sect4 id="aberration-inspector-vcurve">
+ <title>Aberration Inspector V-Curve</title>
+
+ <screenshot>
+ <screeninfo> Aberration Inspector V-Curve </screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="aberration_inspector_vcurve.png" format="PNG" width="50%"/>
+ </imageobject>
+
+ <textobject>
+ <phrase>Aberration Inspector V-Curve</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para> At the top of the dialog are some controls, followed by the V-Curve. The controls are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Tiles</guilabel>: Three options are available:</para>
+ <itemizedlist>
+ <listitem>
+ <para>All: All 9 tiles are displayed.</para>
+ </listitem>
+ <listitem>
+ <para>Centre and outer corners: The centre and 4 corner tiles are displayed.</para>
+ </listitem>
+ <listitem>
+ <para>Centre and inner diamond: The centre and 4 inner diamond tiles are displayed.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Labels</guilabel>: Checkbox toggles focus point labels on the V-Curve.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>CFZ</guilabel>: Checkbox toggles whether the CFZ moustache is displayed on the V-Curve.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Optimise Tile Centres</guilabel>: If unchecked, the geometrical centre of the tile is used;
+ if checked, the centre of the tile is calculated as an average of the star positions within the tile.
+ Whilst theoretically more accurate to check this option, it is likely to have a significant impact only if the
+ number of stars is small.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Close</guilabel>: Close the Aberration Inspector dialog.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The V-Curve is similar to the V-Curve on the main Focus tab, except each tile is represented by its own curve.
+ The number of curves is determined by the setting of the <guilabel>Tiles</guilabel> combobox. The x-axis displays
+ the focuser position and the y-axis the measure (e.g. HFR) used by Autofocus. Each curve has its own colour
+ and 2 character identifier as displayed in the legend.</para>
+
+ <para>Hover the mouse over a curve minimum to see more information about that curve.</para>
+ </sect4>
+
+ <sect4 id="aberration-inspector-table">
+ <title>Aberration Inspector Table</title>
+
+ <screenshot>
+ <screeninfo> Aberration Inspector Table </screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="aberration_inspector_table.png" format="PNG" width="50%"/>
+ </imageobject>
+
+ <textobject>
+ <phrase>Aberration Inspector Table</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>The table displays information pertinent to each tile as selected by the
+ <guilabel>Tiles</guilabel> setting.</para>
+
+ <para>A tooltip like graphic is displayed when the mouse is hovered over either of the leftmost 2 columns.
+ The graphic displays a picture of the sensor scaled to the dimensions of the sensor. Overlayed on the
+ sensor are the tiles as selected by the <guilabel>Tiles</guilabel> setting. The tiles are scaled
+ appropriately for the tile settings. Each tile is labelled with the Tile Name and the tile corresponding
+ to the row that the mouse is hovering over, is highlighted in the colour of that tile.</para>
+
+ <para>The following columns are displayed:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Tile</guilabel>: The 1 or 2 character name of the tile, e.g. TL = Top Left,
+ C = Centre, etc.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Description</guilabel>: Tile Description, e.g. Top Left, Centre, etc.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Solution</guilabel>: The focus solution. This matches the solution on the V_Curve.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Delta (ticks)</guilabel>: This is the delta of the solution for the current table row
+ from the solution of the Centre tile. The Delta of the Centre row will, of course, be zero.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Delta (μm)</guilabel>: This is Delta (ticks) converted to microns using the step size
+ in microns as specified in the CFZ Focus tab.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Num Stars</guilabel>: This shows the min / max number of stars detected during the
+ Autofocus run. Usually, the minimum number would be a far out of focus datapoint and the max number
+ would be the in focus datapoint.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>R²</guilabel>: R-squared of the curve fit for this tile. See
+ <link linkend="Coefficient_of_Determination">Coefficient of Determination</link> for more details.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Exclude</guilabel>: Checkbox to include / exclude this tile in calculations. By
+ default, if a tile has been curve fitted it will be included; if a tile was not curve fitted then
+ it will be excluded. In addition, the user may decide that a particular tile may contain poor
+ quality data, for example the R² is low; or the number of stars is low. In this case the Exclude
+ can be checked and this row will be excluded from calculations. Note that by excluding some rows,
+ some calculations may not be performed. If the Centre tile is excluded, no calculations can be
+ performed.</para>
+
+ <para>Note that whilst its possible to exclude tiles and still get calculated values, if the data
+ is poor quality then it is recommended to rerun Aberration Inspector rather than persist with poor
+ quality data.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The recommended approach is to check the table for quality data and once achieved, move onto
+ analysing the <link linkend="aberration-inspector-results">Aberration Inspector Results</link>.</para>
+ </sect4>
+
+ <sect4 id="aberration-inspector-results">
+ <title>Aberration Inspector Results</title>
+
+ <screenshot>
+ <screeninfo> Aberration Inspector Results </screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="aberration_inspector_results.png" format="PNG" width="50%"/>
+ </imageobject>
+
+ <textobject>
+ <phrase>Aberration Inspector Results</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>The calculation results are displayed in this section, based on the data displayed in the table:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Backfocus Δ</guilabel>: This is the value of the Backfocus delta. The nearer to
+ perfect backfocus, the lower the backfocus delta. Note that the Backfocus delta gives a clue as to
+ how far out the Backfocus is, in terms of scale and direction, but is not the amount by which the
+ sensor needs to be moved. The relationship between backfocus Delta and how far to move the sensor
+ will vary with the equipment used, and needs to be worked out by the user.</para>
+
+ <para>The field gives the sense of the backfocus movement required to improve backfocus: either move
+ the sensor nearer to the field flattener (telescope) or move it further away.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Left-Right Tilt</guilabel>: Gives the Left to Right tilt in microns and as a
+ percentage.</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Top-Bottom Tilt</guilabel>: Gives the Top to Bottom tilt in microns and as a
+ percentage</para>
+ </listitem>
+ <listitem>
+ <para> <guilabel>Total Tilt</guilabel>: The diagonal tilt in microns and as a percentage.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The smaller the backfocus delta the nearer the sensor is to perfect backfocus. If the field flattner
+ does not flatten the field all the way to the edges of the sensor then this will be visible by switching the
+ Tiles option between "Centre and outer corners" and "Centre and inner diamond". If the backfocus delta results
+ are consistent when the Tiles option is changed then this indicates that the field flattener is working to the
+ corners of the sensor.</para>
+
+ <para>There will always be some backfocus delta at least because of noise in the observation data. The important
+ thing is that when in focus, stars are circular in all parts of the sensor.</para>
+
+ <para>The smaller the tilt percentages, the nearer the sensor is to being flat to the plane of light from the
+ flattener / telescope. As with backfocus delta, there is always going to be some noise in the data, which will
+ present as tilt. The important thing is that when in focus the star sizes are consistent across all parts of the
+ sensor.</para>
+
+ <para>Because of the nature of the backfocus delta and tilt calculations, one will affect the other so it will
+ probably be better to try and adjust both together, in small increments, rather than trying to perfect one in
+ isolation, before adjusting the other.</para>
+ </sect4>
+
+ <sect4 id="aberration-inspector-3dgraphic">
+ <title>Aberration Inspector 3D Graphic</title>
+
+ <screenshot>
+ <screeninfo> Aberration Inspector 3D Graphic </screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="aberration_inspector_3dgraphic.png" format="PNG" width="50%"/>
+ </imageobject>
+
+ <textobject>
+ <phrase>Aberration Inspector 3D Graphic</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>The 3D graphic displays the sensor tilted as per the
+ <link linkend="aberration-inspector-results">Aberration Inspector Results</link>. To help
+ visualise the Petzval surface (see <ulink
+ url="https://en.wikipedia.org/wiki/Petzval_field_curvature">Petzval Field Curvature</ulink> for more details)
+ of light coming out of the telescope and incident on the sensor the surface is also modelled. The higher the
+ backfocus error, the more curved the Petzval surface.</para>
+
+ <para>The graphic can be zoomed and rotated using gestures. To zoom use pinch. To rotate use
+ touch-and-move.</para>
+
+ <para>The graphic has a Simulation Mode that allows backfocus and tilt to be adjusted by the
+ sliders. The effect on the sensor's tilt and Petzval surface is displayed in the graphic.</para>
+
+ <para>The following options are available for the graphic:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para> <guilabel>Selection</guilabel>: The following options are available:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>None: No selection is possible.</para>
+ </listitem>
+
+ <listitem>
+ <para>Item: A datapoint may be selected and data values are displayed.</para>
+ </listitem>
+
+ <listitem>
+ <para>Slice: A 2D slice throught the 3D graphic is displayed.</para>
+ </listitem>
+ </itemizedlist>
+
+ </listitem>
+ <listitem>
+ <para> <guilabel>Theme</guilabel>: A number of colour themes are available.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Labels</guilabel>: Checkbox to show / hide tile labels on the graphic.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Sensor</guilabel>: Checkbox to show / hide the sensor.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Petzval Wire</guilabel>: Checkbox to show / hide the Petzval surface as a graphic wire.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Petzval Surface</guilabel>: Checkbox to show / hide the Petzval surface.</para>
+ </listitem>
+
+ <listitem>
+ <para> <guilabel>Sim Mode</guilabel>: Checkbox to toggle Simulation Mode on / off. When off, the
+ graphic displays the sensor and Petzval surface based on the calculated results of the Aberration Inspector
+ run. When on, the sliders for Backfocus, Left-to-Right tilt and Top-to-Bottom tilt are activated, and these can be
+ dragged by the user to adjust the graphic. Hover the mouse over each slider to see the tooltips describing what
+ each slider does.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The 3D graphic is not essential to using Aberration Inspector. All relevent information is displayed in the
+ <link linkend="aberration-inspector-table">Table</link> and <link linkend="aberration-inspector-results">Results</link>
+ sections of the dialog. Its purpose is to aid the user in undertanding Aberration Inspector and to orient themselves
+ with the information the tool provides.</para>
+ </sect4>
+ </sect3>
</sect2>
diff --git a/doc/focuser_group.png b/doc/focuser_group.png
index 9562e4e325..1f4ea6cfc3 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 dcff76b8f1..5e535006b7 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -225,8 +225,8 @@
<legalnotice>&FDLNotice;</legalnotice>
-<date>2023-08-01</date>
-<releaseinfo>3.6.6</releaseinfo>
+<date>2023-12-01</date>
+<releaseinfo>3.6.8</releaseinfo>
<abstract>
<para>
More information about the kde-doc-english
mailing list