[education/kstars] /: Add documentation

Sun May 12 01:33:18 BST 2024

Git commit a35490ed6fa00d572a59a4d50c8fa87e1ef1f4d0 by Hy Murveit.
Committed on 12/05/2024 at 00:33.
Pushed by murveit into branch 'master'.

Add documentation

Adds a guide comment and updates the Analyze sections of the KStars Handbook.

M  +5    -2    doc/ekos-analyze.docbook
M  +14   -0    doc/ekos-user-interface.docbook
M  +-    --    doc/ekos_analyze.png
M  +-    --    doc/ekos_page.png
M  +13   -2    kstars/ekos/guide/guide.cpp

https://invent.kde.org/education/kstars/-/commit/a35490ed6fa00d572a59a4d50c8fa87e1ef1f4d0

diff --git a/doc/ekos-analyze.docbook b/doc/ekos-analyze.docbook
index cb7e8b3431..e52d9aaf0e 100644
--- a/doc/ekos-analyze.docbook
+++ b/doc/ekos-analyze.docbook
@@ -24,7 +24,10 @@
             The Analyze Module records and displays what happened in an imaging session. That is, it does not control any if your imaging, but rather reviews what occurred. Sessions are stored in an <filename class="directory">analyze</filename> folder, a sister folder to the main logging folder. The <literal role="extension">.analyze</literal> files written there can be loaded into the <guilabel>Analyze</guilabel> tab to be viewed. <guilabel>Analyze</guilabel> also can display data from the current imaging session.
         </para>
         <para>
-            There are two main graphs, <guilabel>Timeline</guilabel> and <guilabel>Stats</guilabel>. They are coordinated—they always display the same time interval from the Ekos session, though the x-axis of the <guilabel>Timeline</guilabel> shows seconds elapsed from the start of the log, and <guilabel>Stats</guilabel> shows clock time. The x-axis can be zoomed in and out with the <guibutton>+/-</guibutton> buttons, as well as with standard keyboard shortcuts (⪚ zoom-in == <keycombo>&Ctrl;<keycap>+</keycap></keycombo>) The x-axis can be panned with the scroll bar as well as with the left and right arrow keys. You can view your current imaging session, or review old sessions by loading <literal role="extension">.analyze</literal> files using the <guilabel>Input</guilabel> dropdown. Checking <guilabel>Full Width</guilabel> displays all the data, and <guilabel>Latest</guilabel> displays the most recent data (you can control the width by zooming).
+          When a new session begins (e.g. Ekos is disconnected at dawn, then reconnected at sunset) the system will start writing a new .analyze file. (This behavior can be controlled from the Analyze settings reached by clicking the options button on the lower right.)
+        </para>        
+        <para>
+            There are two main graphs, <guilabel>Timeline</guilabel> and <guilabel>Stats</guilabel>. They are coordinated—they always display the same time interval from the Ekos session, though the x-axis of the <guilabel>Timeline</guilabel> shows seconds elapsed from the start of the log, and <guilabel>Stats</guilabel> shows clock time. The x-axis can be zoomed in and out with the <guibutton>+/-</guibutton> buttons, as well as with standard keyboard shortcuts (⪚ zoom-in == <keycombo>&Ctrl;<keycap>+</keycap></keycombo>) The x-axis can be panned with the scroll bar as well as with the left and right arrow keys. You can view your current imaging session, or review old sessions by loading <literal role="extension">.analyze</literal> files using the <guilabel>Input</guilabel> dropdown. Using the << and >> buttons allows you to display the previous or following .analyze files chronologically. Checking <guilabel>Full Width</guilabel> displays all the data, and <guilabel>Latest</guilabel> displays the most recent data (you can control the width by zooming).
         </para>
         <para>
             The three main displays can be hidden to make more room for the other displays. There are checkboxes to the left of the section titles (Timeline, Statistics, and Details) that enable and hide the displays.
@@ -37,7 +40,7 @@
         </para>
         <note>
             <para>
-                If you have moved your captured images, you can set <guilabel>alternate directory</guilabel> in the input menu to a directory which is the base of part of the original file path.
+                If you have moved your captured images, you can set an <guilabel>alternate directory</guilabel> in the analyze settings page you can reach from the Options button in the lower right. This alternate directory would be prepended to the base of part of the original file path and would be checked if the image file is not in its original location.
             </para>
         </note>
         <para>
diff --git a/doc/ekos-user-interface.docbook b/doc/ekos-user-interface.docbook
index 37ac6f31eb..fd943492b3 100644
--- a/doc/ekos-user-interface.docbook
+++ b/doc/ekos-user-interface.docbook
@@ -21,6 +21,12 @@
             </para>
         </listitem>
 
+        <listitem>
+            <para>
+                Analyze Module
+            </para>
+        </listitem>
+        
         <listitem>
             <para>
                 Capture Module
@@ -83,6 +89,14 @@
                 </para>
             </listitem>
         </varlistentry>
+        <varlistentry>
+            <term>Analyze Module</term>
+            <listitem>
+                <para>
+                    Analyze displays a high-level summary of what happened during an imaging session. It shows plots and graphs describing the many captures takes during a night, the focus sessions, the guiding, mount movement, meridian flips, etc. Use it to get a feel of "what happened last night" or to see the current state of the system.
+                </para>
+            </listitem>
+        </varlistentry>
         <varlistentry>
             <term>Capture Module</term>
             <listitem>
diff --git a/doc/ekos_analyze.png b/doc/ekos_analyze.png
index 42c5612fa7..f234c0ed25 100644
Binary files a/doc/ekos_analyze.png and b/doc/ekos_analyze.png differ
diff --git a/doc/ekos_page.png b/doc/ekos_page.png
index 102d73b09d..d115e996b2 100644
Binary files a/doc/ekos_page.png and b/doc/ekos_page.png differ
diff --git a/kstars/ekos/guide/guide.cpp b/kstars/ekos/guide/guide.cpp
index e474011798..6d927cf879 100644
--- a/kstars/ekos/guide/guide.cpp
+++ b/kstars/ekos/guide/guide.cpp
@@ -768,8 +768,19 @@ QString Guide::guider()
 
 bool Guide::capture()
 {
-    // Should only capture if we're not already capturing...
-    // Really a hack, guider wasn't designed with the dither/capture concurrency in mind :(
+    // Only capture if we're not already capturing.
+    //
+    // The situation I'm seeting this fire is with the internal guider, using GPG,
+    // set to suspend guiding during focus, when focus has been completed and guiding moves
+    // back from suspended to guiding. Here's why:
+    // During focus, even though guiding is suspended and not sending guide pulses, it still
+    // captures images and compute guide offsets and send those offset values to gpg
+    // (see setCaptureComple() case GUIDE_SUSPENDED). When focus completes, guiding moves from
+    // suspended back to guiding--resume() gets called (from the focuser connected through the
+    // manager) which calls InternalGuider::resume() which emits frameCaptureRequested() which
+    // calls Guide::capture().  So, there would likely be a call to capture() while the previous
+    // gpg-induced capture is still running (above setCaptureComplete case GUIDE_SUSPENDED).
+    // I'm leaving this behavior in the code, as this seems like an ok solution.
     if (guiderType == GUIDE_INTERNAL && captureTimeout.isActive() && captureTimeout.remainingTime() > 0)
     {
         qCDebug(KSTARS_EKOS_GUIDE) << "Internal guider skipping capture, already running with remaining seconds =" <<
