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>
