[documentation/kstars-docs-kde-org] /: Docs for AI guider
Jasem Mutlaq <[email protected]>
| Newsgroups | gmane.comp.kde.cvs |
|---|---|
| Message-ID | <[email protected]> |
Git commit bb7da35f7bb096d01c1ebacce9ad88673b4f89d6 by Jasem Mutlaq, on behalf of Pavan Kumar S G.
Committed on 18/07/2026 at 05:55.
Pushed by mutlaqja into branch 'master'.
Docs for AI guider
A +- -- images/ekos_guide_ai_menu.png
A +- -- images/ekos_guide_ai_options.png
A +- -- images/ekos_guide_ai_wizard_complete.png
A +- -- images/ekos_guide_ai_wizard_mount.png
A +- -- images/ekos_guide_ai_wizard_progress.png
A +- -- images/ekos_guide_ai_wizard_protocol.png
M +2 -0 user_manual/doc-index.rst
M +330 -0 user_manual/ekos-guide.rst
M +1 -1 user_manual/ekos.rst
https://invent.kde.org/documentation/kstars-docs-kde-org/-/commit/bb7da35f7bb096d01c1ebacce9ad88673b4f89d6
diff --git a/images/ekos_guide_ai_menu.png b/images/ekos_guide_ai_menu.png
new file mode 100644
index 00000000..27fbeb69
Binary files /dev/null and b/images/ekos_guide_ai_menu.png differ
diff --git a/images/ekos_guide_ai_options.png b/images/ekos_guide_ai_options.png
new file mode 100644
index 00000000..51ddc8f3
Binary files /dev/null and b/images/ekos_guide_ai_options.png differ
diff --git a/images/ekos_guide_ai_wizard_complete.png b/images/ekos_guide_ai_wizard_complete.png
new file mode 100644
index 00000000..8d88c086
Binary files /dev/null and b/images/ekos_guide_ai_wizard_complete.png differ
diff --git a/images/ekos_guide_ai_wizard_mount.png b/images/ekos_guide_ai_wizard_mount.png
new file mode 100644
index 00000000..78aca86e
Binary files /dev/null and b/images/ekos_guide_ai_wizard_mount.png differ
diff --git a/images/ekos_guide_ai_wizard_progress.png b/images/ekos_guide_ai_wizard_progress.png
new file mode 100644
index 00000000..06e5fdee
Binary files /dev/null and b/images/ekos_guide_ai_wizard_progress.png differ
diff --git a/images/ekos_guide_ai_wizard_protocol.png b/images/ekos_guide_ai_wizard_protocol.png
new file mode 100644
index 00000000..50e7c480
Binary files /dev/null and b/images/ekos_guide_ai_wizard_protocol.png differ
diff --git a/user_manual/doc-index.rst b/user_manual/doc-index.rst
index 618d3b8b..6fd45675 100755
--- a/user_manual/doc-index.rst
+++ b/user_manual/doc-index.rst
@@ -545,6 +545,8 @@ Index
Ekos
+ AI Guiding, :doc:`Guide <ekos-guide>`
+
Align, :doc:`Align <ekos-align>`
Analyze, :doc:`Analyze <ekos-analyze>`
diff --git a/user_manual/ekos-guide.rst b/user_manual/ekos-guide.rst
index d084ea31..58418494 100755
--- a/user_manual/ekos-guide.rst
+++ b/user_manual/ekos-guide.rst
@@ -257,6 +257,12 @@ Guiding
PHD2 PPEC algorithm. For technical details see `this paper <https://www.researchgate.net/publication/276459268_Gaussian_Process-Based_Predictive_Control_for_Periodic_Error_Correction>`__.
There is more detail on GPG below.
+ - AI Guider: (Experimental) Adds trained, mount-specific feed-forward
+ predictions on top of the Standard algorithm, which keeps running
+ underneath. It requires a one-time training session with the AI
+ Guiding Assistant before it can be selected. See
+ :ref:`AI Guiding Assistant <ekos-guide-ai-guiding-assistant>` below.
+
A good starting choice is ``Standard`` or ``Hysteresis`` (with a 0.1 hysteresis parameter).
You may want to use ``GPG`` for RA, as it is probably the best performing algorithm for many mounts,
however it is more complex to set up (see below). ``Linear`` is recommended for some
@@ -436,6 +442,324 @@ Guiding with GPG
exposures. All the other parameters are best left to
defaults.
+.. _ekos-guide-ai-guiding-assistant:
+
+AI Guiding Assistant (Experimental)
+===================================
+
+|AI Guiding Menu|
+
+The AI Guiding Assistant adds a trained, mount-specific *feed-forward*
+predictor to the internal guider. After a one-time training session, the
+AI learns the repeatable part of your mount's tracking error — such as
+periodic error and slow drift — and adds a predicted correction to each
+guide pulse *before* the error becomes visible in the guide image. The
+standard guiding algorithm keeps running underneath at all times and
+corrects whatever the prediction misses.
+
+The entry point is the :guilabel:`AI Guiding (Experimental)` menu button
+on the main Guide page, just below :guilabel:`Clear Calibration`. It
+offers two actions: :guilabel:`AI Guiding Assistant...`, which opens the
+data-collection wizard described below, and :guilabel:`Load Weights...`,
+which loads a previously trained model file. This feature is unrelated
+to the :doc:`AI Assistant (MCP) <ekos-mcp>` interface, which connects
+KStars to external chat assistants.
+
+.. warning::
+
+ The AI Guiding Assistant is an **experimental** feature under active
+ development. Trained models are tied to your specific mount, camera, and guide settings. Always verify
+ your guiding performance after enabling it, and be prepared to
+ switch back to the :guilabel:`Standard` or :guilabel:`GPG`
+ algorithms if your results are not better with the AI.
+
+.. _ekos-guide-ai-expectations:
+
+Expectations and Prerequisites
+------------------------------
+
+Please read this part carefully before investing time in training a
+model — it will save you from disappointment later.
+
+.. warning::
+
+ AI guiding **augments** a well-functioning guiding setup — it does
+ not repair a poorly functioning one. It predicts the *repeatable*
+ part of your mount's error and layers that prediction on top of the
+ standard guiding algorithm. It will **not** fix:
+
+ - poor polar alignment,
+ - imbalance, cable drag, or differential flexure,
+ - wind gusts, vibrations, or bad seeing,
+ - a mount or guide system that is not already well tuned.
+
+ None of these are repeatable errors, so no amount of training can
+ predict them. If standard guiding does not work well on your system,
+ fix that first. The improvement from AI guiding varies considerably
+ from mount to mount, and on some mounts you may see no measurable
+ benefit at all.
+
+Before running the assistant, make sure that:
+
+- You are using the **internal guider**, with a working guide camera
+ and a completed, successful calibration.
+- Ordinary guiding with the :guilabel:`Standard` algorithm already
+ works reliably on your setup.
+- Your mount is well polar-aligned, balanced, and free of cable snags.
+- You know your mount's drive type: worm gear (most equatorial mounts),
+ harmonic/strain-wave drive, or direct drive.
+- Your guide exposure is the one you intend to keep using: the model is
+ trained *and locked* to the guide exposure, binning, and guide
+ settings used during data collection.
+- You have 20–45 minutes of clear, reasonably steady sky to spend on
+ data collection, depending on the mount type.
+
+.. _ekos-guide-ai-wizard:
+
+Data Collection with the AI Guiding Assistant
+---------------------------------------------
+
+Training a model starts with a *system identification* session: the
+assistant points the mount at a few positions in the sky and records how
+the guide star drifts, both with guiding running and with guiding
+deliberately paused ("free drift"), so that the mount's raw error
+signature can be measured. Click :guilabel:`AI Guiding (Experimental)` →
+:guilabel:`AI Guiding Assistant...` on the Guide page to start the
+wizard.
+
+|AI Wizard Mount Page|
+
+**Page 1 — Mount Identification.** Verify the detected mount type:
+:guilabel:`Worm Gear`, :guilabel:`Harmonic Drive`, or
+:guilabel:`Direct Drive`. The wizard also recommends a guide exposure
+per drive type — 2.0 s for worm gears, 0.5–1.0 s for harmonic drives
+(depending on guide star signal), and 1.0–3.0 s for direct drives. Set
+your exposure *before* proceeding: the trained model is locked to it.
+
+|AI Wizard Protocol Page|
+
+**Page 2 — Protocol Preview.** The wizard shows the measurement protocol
+it is about to run. During data collection your guiding settings are
+temporarily switched to the :guilabel:`Standard` algorithm on both axes
+with all guide directions enabled; your original settings are restored
+when the wizard finishes. The protocol depends on the mount type:
+
+- **Worm Gear** (~45 minutes): three pointings at high, lower, and high
+ altitude, each combining standard guiding with several minutes of
+ free drift. The long free-drift phases capture roughly three full
+ worm cycles, which is what allows the periodic error to be measured.
+- **Harmonic Drive** (~35 minutes): free drift and standard guiding at
+ two pointings, plus a series of short pulse-response tests (50, 100,
+ and 200 ms pulses in all four directions) that measure how the drive
+ reacts to corrections.
+- **Direct Drive** (~20 minutes): short guiding and free-drift phases
+ at three different altitudes.
+
+|AI Wizard Progress Page|
+
+**Page 3 — System Identification Progress.** The assistant slews,
+guides, and drifts on its own. Leave the system alone while it runs —
+interrupting the process invalidates the affected phase. Use
+:guilabel:`Stop` only if something goes wrong.
+
+|AI Wizard Complete Page|
+
+**Page 4 — Data Collection Complete.** The measured data is saved, and
+you choose how to train the model: :guilabel:`Train in EkosLive` uploads
+the data to EkosLive Cloud and returns a ready-to-use model (next
+section), while :guilabel:`Export for offline training` writes a
+``sysid_data.json`` file for the Python trainer (see
+:ref:`below <ekos-guide-ai-offline-training>`).
+
+.. _ekos-guide-ai-ekoslive-training:
+
+Training via EkosLive
+---------------------
+
+The easiest way to train the model is with an `EkosLive
+<https://ekoslive.com>`__ account: click :guilabel:`Train in EkosLive`
+on wizard page 4. The data is uploaded, the model is trained in the
+cloud, and the resulting weights are automatically saved (as
+``ai_guider_weights.json`` in the KStars data folder,
+``~/.local/share/kstars/`` on Linux) and set as the active weights
+file — no further steps are needed.
+
+.. note::
+
+ The uploaded system-identification data contains **no sky
+ coordinates**: only altitude, azimuth, and parallactic angle,
+ together with pixel drift measurements, star signal-to-noise ratios,
+ and the guide pulses that were sent. It does, however, include your
+ mount's name and camera device names. If you prefer not to upload
+ anything, use offline training instead — it produces identical
+ weights.
+
+.. _ekos-guide-ai-offline-training:
+
+Training the Model Offline
+--------------------------
+
+You do not need EkosLive to train a model — the trainer is a small set
+of Python scripts that runs on any ordinary computer. Training uses only
+the CPU and finishes in under ten minutes; no GPU is required.
+
+#. On wizard page 4, click :guilabel:`Export for offline training` and
+ save ``sysid_data.json``.
+#. Copy the file to the computer where you want to train (it can be the
+ observatory computer itself, but a desktop or laptop is usually more
+ convenient).
+#. Get the trainer scripts from the ``kstars/ekos/guide/offlinetrainer/``
+ directory of the `KStars source repository
+ <https://invent.kde.org/education/kstars/-/tree/master/kstars/ekos/guide/offlinetrainer>`__.
+#. In that directory, create a Python environment and run the trainer:
+
+ .. code:: bash
+
+ python3 -m venv venv
+ source venv/bin/activate
+ pip install numpy scipy torch
+ python train.py --sysid-data ./sysid_data.json --output ./weights.json
+
+The trainer auto-detects your mount type from the data and picks the
+matching model. Should the detection ever be wrong, it can be overridden
+with ``--mount-type WORM_GEAR|HARMONIC_DRIVE|DIRECT_DRIVE``.
+
+Finally, copy the resulting ``weights.json`` back to the observatory
+computer and load it in KStars via :guilabel:`AI Guiding (Experimental)`
+→ :guilabel:`Load Weights...` on the Guide page (or set the
+:guilabel:`Weights File` on the :guilabel:`AI Guider` options page). The
+weights are applied the next time guiding starts.
+
+.. _ekos-guide-ai-activation:
+
+Activating AI Guiding and Options
+---------------------------------
+
+|AI Guider Options|
+
+With a weights file loaded, select :guilabel:`AI Guider` as the guiding
+algorithm for RA and/or DEC in the guider options, and start guiding as
+usual. The AI-related settings live on the :guilabel:`AI Guider` page of
+the guide settings dialog:
+
+- :guilabel:`Weights File`: path to the trained model weights (JSON).
+- :guilabel:`AI Prediction Gain` (default 0.5): how strongly the AI
+ prediction is blended into the guide pulses. 0.0 ignores the AI
+ entirely; 1.0 applies its full prediction. Start at the default and
+ increase gradually if guiding improves.
+- :guilabel:`Scale Down Proportional Gain During AI Correction`
+ (default off): reduces the standard proportional response by up to
+ half when the AI is highly confident, to avoid the two controllers
+ over-correcting the same error.
+- :guilabel:`Enable Predictive Dark Guiding` (default off): keeps
+ emitting predicted corrections during gaps in guide star
+ measurements — dither settling, autofocus runs, or camera downloads —
+ by extrapolating the periodic error forward in time.
+- :guilabel:`Dark Guiding Interval` (default 1.0 s): seconds between
+ predicted pulses when no guide-star measurement is available.
+
+.. note::
+
+ A weights file only works with the guide settings it was trained
+ with. When guiding starts, the file's fingerprint is checked against
+ your current guide exposure, binning, gains, minimum/maximum pulse,
+ and hysteresis settings. On a mismatch, guiding aborts with an
+ explanatory message — either restore the settings you used during
+ data collection, re-run the assistant to train new weights, or
+ switch the algorithm back to :guilabel:`Standard`.
+
+.. _ekos-guide-ai-monitoring:
+
+Monitoring AI Guiding
+---------------------
+
+The guide state display shows what the AI is doing. After guiding
+starts, the AI is in a *warm-up* phase (shown as :guilabel:`Warm up`)
+while it synchronizes its model with the live mount — about 50 guide
+frames for worm gears, 30 for harmonic drives, and 10 for direct drives.
+During warm-up, guiding is handled entirely by the standard algorithm.
+Once its predictions are verified against real measurements, the AI
+becomes :guilabel:`Active` and its corrections are blended in.
+
+The blend is weighted by a live *confidence* score. Confidence requires
+a reasonably bright guide star (it reaches its maximum around a
+signal-to-noise ratio of 30 and drops to zero below 10) and falls
+whenever the AI's predictions stop matching what the mount actually
+does. When confidence is low, the standard guiding algorithm does most
+of the work — an underperforming model degrades gracefully instead of
+ruining your subframes.
+
+Several safeguards apply at all times: every pulse respects your
+configured maximum pulse limits plus a hard 5-second ceiling; AI
+predictions are suspended during dithering; a meridian flip resets the
+AI's internal state for re-warm-up; and a lost guide star triggers the
+guider's normal reacquisition logic.
+
+.. _ekos-guide-ai-how-it-works:
+
+How It Works
+------------
+
+A mount's tracking error has two parts. The *repeatable* part comes from
+its mechanics — the worm gear's periodic error, gear imperfections,
+atmospheric refraction, and the slow drift from residual polar-alignment
+error. The *random* part comes from seeing, wind, and measurement noise.
+A conventional guider is purely reactive: it can only correct an error
+after the star has already moved. A feed-forward guider, by contrast,
+predicts the repeatable part and cancels it as it happens — but it can
+do that only for errors that repeat, which is why data collection
+matters and why the random part remains the standard algorithm's job.
+
+The AI Guider is deliberately conservative in how it uses its
+predictions. Each guide cycle, the standard controller computes its
+normal correction from the measured drift. In parallel, the AI model
+computes a predicted correction, which is scaled by the live confidence
+score and your prediction gain, and added on top. The summed pulse then
+passes through the safety clamps before being sent to the mount. If the
+AI contributes nothing useful, its term simply fades to zero and you are
+left with plain standard guiding.
+
+The model itself is chosen to match the mount's physics rather than
+being one large neural network:
+
+- **Worm gear** mounts use a physics model of the periodic error,
+ refraction, and polar drift, with its phase tracked live while
+ guiding, plus a tiny neural network (about 200 parameters) that
+ learns the leftover, mount-specific residuals.
+- **Harmonic drive** mounts use a Kalman-filter model of the drive's
+ spring wind-up and periodic error, with a small neural network
+ correcting its predictions.
+- **Direct drive** mounts have almost no mechanical error, so only
+ refraction and drift are modeled analytically — no neural network is
+ involved.
+
+.. _ekos-guide-ai-troubleshooting:
+
+Troubleshooting and Notes
+-------------------------
+
+- *Guiding aborts immediately with a weights error.* The weights file
+ failed to load or its fingerprint does not match your current guide
+ settings. Restore the settings used during data collection, retrain,
+ or switch the algorithm back to :guilabel:`Standard`.
+- *The AI stays in warm-up or never becomes active.* This is usually
+ caused by a faint guide star (low signal-to-noise) or by predictions
+ that do not match your mount's current behavior. Guiding continues
+ normally on the standard algorithm either way; consider retraining
+ under better conditions.
+- *No visible improvement.* This is a realistic outcome on some
+ mounts — especially ones with little periodic error or dominated by
+ non-repeatable errors. Compare a few guiding sessions with the AI
+ enabled and disabled under similar conditions before drawing
+ conclusions.
+- *When to retrain:* after changing the guide camera, guide exposure,
+ binning, guide optical train, mount, or any fingerprinted guide
+ setting — and whenever guiding performance degrades noticeably after
+ a remesh or mechanical adjustment.
+- *Reporting problems:* the wizard's :guilabel:`Export Logs` button
+ bundles the AI debug logs and guide logs into a single archive that
+ you can attach to a bug report or forum post.
+
.. _ekos-guide-dark-frames:
Dark Frames
@@ -516,3 +840,9 @@ Guiding Logs
.. |Guiding with GPG| image:: /images/ekos_guide_gpg_settings.png
.. |Ekos Dark frames library| image:: /images/dark_library.png
.. |Ekos Guide PHD2 settings| image:: /images/ekos_guide_phd2.png
+.. |AI Guiding Menu| image:: /images/ekos_guide_ai_menu.png
+.. |AI Wizard Mount Page| image:: /images/ekos_guide_ai_wizard_mount.png
+.. |AI Wizard Protocol Page| image:: /images/ekos_guide_ai_wizard_protocol.png
+.. |AI Wizard Progress Page| image:: /images/ekos_guide_ai_wizard_progress.png
+.. |AI Wizard Complete Page| image:: /images/ekos_guide_ai_wizard_complete.png
+.. |AI Guider Options| image:: /images/ekos_guide_ai_options.png
diff --git a/user_manual/ekos.rst b/user_manual/ekos.rst
index db019e06..f4582fb1 100755
--- a/user_manual/ekos.rst
+++ b/user_manual/ekos.rst
@@ -13,7 +13,7 @@ Features:
- Control your telescope, Camera (& DSLRs), filter wheel, focuser, guider, adaptive optics unit, and any INDI-compatible auxiliary device from Ekos.
-- *Built-in* native :doc:`autoguiding <ekos-guide>` with support for automatic dithering between exposures and support for Adaptive Optics devices in addition to traditional guiders.
+- *Built-in* native :doc:`autoguiding <ekos-guide>` with support for automatic dithering between exposures and support for Adaptive Optics devices in addition to traditional guiders, including an experimental AI-assisted predictive guiding mode.
- `Extremely accurate GOTOs <https://knro.blogspot.com/2013/10/demo-of-ekos-alignment-module.html>`__ using astrometry.net solver (both Online and Offline solvers supported).