Introduce the new Planetary Guiding Tool (part 5)

[Eyeke2]

Introduce the new Planetary Guiding Tool, which can be optionally enabled for the detection of large celestial bodies such as the Sun, Moon, and planets. This feature detects them as either full light disks or crescent shapes occurring during eclipses or various Moon phases. This commit lays the foundation for subsequent updates needed to fully integrate this feature into PHD2 and ensure its functionality.

I'm stopping half a way right after this largest commit containing the core algorithm with its UI module. I'd like to get feedback first before continuing with the rest. I'm not sure I can split the algorithm into smaller commits and make it easier for code review. I have introduced enough comments in the source code which can be helpful for code review

[Eyeke2]

I can possibly split this PR into several commits, such as:

• Core algorithm and associated UI
• Handling display elements used as aid tool for adjusting min/max radii, etc.
• Tool icon
• Callbacks from PHD2 framework
• Camera settings accessible from the new tool

Reiterating here that this PR will be followed by more changes required to integrate this tool with PHD2 (including the Camera Simulator update).

UI screenshot

Graphical elements useful for tuning min/max radii are displayed for limited time.

[bwdev01]

I think it would help me if you could start with a "theory of operation" narrative that will help me see the big picture. I'm not talking about the algorithms for identifying non-stellar shapes, those are presumably well described elsewhere. My interest is what are the distinguishing characteristics of solar system imaging and how did you choose to handle those differences in the context of PHD2? To present just a few examples:

How would you characterize the motivation for this feature? Lunar and planetary imaging is traditionally done without guiding - even on commodity mounts - because the post-processing apps are very good at handling lateral displacements from one frame to the other. And the imaging sequences are typically fairly short because the targets are rotating and/or the solar altitude on the moon is changing quickly. So are you really focused on long-duration imaging? Setting aside the unusual case of eclipses, what other use-cases need this capability?
How is the current object model affected - for example, is there a "guider_solarsystem" subclass of "guider" following the model of "guider_multistar"? Or is this not useful?
What is the role of the "star" class and auto-find operations in your design? Is that all replaced by something else?
How are the guide camera exposures handled - are you using a streaming interface? If so, how does this affect the existing guider state machine? How do you handle the problem of not chasing the seeing and not overrunning the mount controller?
What is the overall UI model? Is solar system guiding a special mode or is it essentially the same as stellar guiding? Does it follow a 'wizard' paradigm? I see you have introduced a "tool" for solar system guiding - what is its role and how is it manifested in the UI?
What is the role of the "normal" tools in the context of solar system guiding - i.e. calibration, Guiding Assistant, etc. Do they apply? If not, how do you keep the user from blundering into them?

These are just a few examples of what is probably a long list of things you had to figure out. But I would prefer to start at this level of discussion before trying to pour through the entrails of the implementation. And in any case, it will probably be useful for the User Guide material you're going to do.

Cheers,
Bruce

[Eyeke2]

Thank you for your detailed questions and for the opportunity to elaborate on the design and implementation of the solar system guiding extension for PHD2. Let me address your queries with specific details:

1. Motivation for the Feature:
   The development of this feature is primarily driven by the need to support precise, long-duration imaging of solar system objects, very useful for capturing detailed phenomena such as solar flares or lunar surface features over extended periods. This capability is especially valuable during events like solar or lunar eclipses where accurate guiding enhances the quality and scientific value of the imaging results. The feature is also designed to aid in producing high-resolution composite images and supporting dynamic observation sessions without the need for periodic manual adjustments.

2. Object Model and Implementation:
   Unlike adapting the existing guider classes, this extension introduces a new base class, GuiderPlanet, which encapsulates all specific logic required for solar system object detection and tracking. This architecture is realized through two main modules: guider_planetary.cpp/h for the core algorithms and planetary_tool.cpp/h for the UI controls, along with a new toolbar icon to enhance user interaction.

3. Integration and Star Detection:
   The implementation adds a third mode to the star finding operation, named FIND_PLANET. This mode treats the center of detected planetary disks as a virtual guide star, allowing the system to utilize the existing guiding mechanisms as if it were tracking a typical star. This approach leverages PHD2's robust tracking infrastructure while introducing minimal disruption to the existing codebase.

4. Guide Camera Exposures and System Operation:
   Planetary guiding maintains the same operational model as traditional stellar guiding, allowing users to utilize all existing tools such as the Guiding Assistant and calibration routines. The system manages guide camera exposures and tracking corrections in a manner consistent with existing practices, ensuring a seamless experience for current PHD2 users.

5. UI Integration and User Interaction:
   The user interface introduces a new tool for solar system guiding, providing intuitive controls for adjusting parameters to successful planetary detection and tracking. The main features of this tool include:

Planetary guiding: a checkbox switch enables users to activate planetary detection mode or revert to traditional stellar guiding.
Planetary-Specific Parameters: Users can adjust the minimum and maximum radii of the planetary disk and the Edge Detection Threshold, which are essential for defining the tracking boundaries and enhancing the accuracy of the feature detection process. Although there is no wizard-like design of this tool, it provides a helpful tooltips for each control and also suggests initial suggestion for values of min/max radii based on current focal length and pixel size of the guiding scope.
Exposure and Timing Controls: Direct controls for camera exposure settings and time lapse delays are integrated within the planetary tool, ensuring quick adjustments tailored to dynamic solar system imaging requirements.
Camera and Mount Settings: The UI duplicates existing controls for camera binning, camera gain, and mount tracking states, including different tracking speeds (currently limited to ASCOM mounts). These parameters are fully synchronized with their counterparts in the main PHD2 interface, maintaining a cohesive user experience.

This streamlined interface ensures that all necessary controls are easily accessible, reducing the complexity of configuring the system for solar system imaging. The integration aims to provide a seamless transition between different guiding modes, facilitating both novice and experienced users in their imaging workflow.

6. Application and Future Directions:
   While the initial release focuses on tracking the centers of circular bodies, a second mode involving surface feature detection is under beta testing and may be integrated later. This phased approach helps ensure reliability and provides users with robust tools tailored to their immediate needs.

Conclusion:
This extension is intended to make solar system imaging more accessible and efficient within the PHD2 framework. By providing detailed explanations and integrating your feedback, I aim to foster a smooth incorporation of these new capabilities into the mainline project. I look forward to further discussions and am open to suggestions on refining this feature. Additionally, I anticipate needing some guidance on formatting the User Manual to ensure it meets the project's standards

[d33psky]

Great description (I assumed these were the project goals before you wrote this, but this wording helps).

I wonder if 'Planetary guiding' would not confuse people wanting to guide on Sol. Maybe rename to Planetary and Solar guiding ? Or disc guiding :P

What is the reason the different tracking speeds are limited to ASCOM for now ?

[Eyeke2]

@d33psky I prefer the name 'Planetary and Solar Guiding,' although 'Solar, Lunar, and Planetary Guiding' is more accurate but too lengthy. Perhaps 'Solar System Guiding' would be a suitable alternative? The initial implementation currently supports only ASCOM mounts. Adding support for INDI mounts will require additional coding.

[Eyeke2]

I recently posted a time lapse video that showcases the 'Planetary Guiding' PHD2 extension for lunar imaging. Here is the link 2-hour time lapse of the lunar surface

[bwdev01]

Hi Leo. I don't think you answered all my questions, so I will contact you off-forum to follow up. I would like to help get the feature integrated into the PHD2 mainstream release but I think there are quite a number of things that need to be cleared up first.

Bruce

[Eyeke2]

Hi Bruce, I've sent you a private message. I'd be happy to continue answering your questions to keep things moving forward.

Thanks!