Push info about multi-star guiding to event server

[pludov]

This MR adds a new event on the event-server, to publish detailed info about multi-star (list all stars, their status, ...), so a third party app can show what multi-star guiding is doing.

I am not sure about the impact of adding this new event for existing app: it might be worth making it a per client opt-in.

Events look like:

{
  "Event": "MultiStarReport",
  "Timestamp": 1771099742.883,
  "Host": "xubuntu",
  "Inst": 1,
  "Stars": [
    {
      "X": 912.002,
      "Y": 1763,
      "RefX": 912.002,
      "RefY": 1763,
      "Mass": 52862.2,
      "SNR": 75.5823,
      "HFD": 8.24756,
      "used": true,
      "err": null
    },
    {
      "X": 829.996,
      "Y": 222.982,
      "RefX": 829.99,
      "RefY": 223.001,
      "Mass": 18362.8,
      "SNR": 63.3208,
      "HFD": 8.2487,
      "used": true,
      "err": null
    },
    {
      "X": 68.0043,
      "Y": 1836,
      "RefX": 67.9971,
      "RefY": 1836,
      "Mass": 16162.3,
      "SNR": 66.9968,
      "HFD": 8.24832,
      "used": true,
      "err": "M8"
    },
    {
      "X": 2192.01,
      "Y": 560.981,
      "RefX": 2191.98,
      "RefY": 560.983,
      "Mass": 11518.2,
      "SNR": 53.6009,
      "HFD": 8.23794,
      "used": true,
      "err": "M4"
    },

[bwdev01]

It would be helpful if you could explain the use case, I really can't picture what it would be. I can understand a method to get the number of stars used (I thought we had one) but not anything having to do with the internals of the algorithm and certainly not anything that's going to increase event broadcasts for every exposure.

[agalasso]

re: failing CI tests: please pull 9b2adc9 (on master branch) and try again.

[pludov]

Thank you for the feedback.

I am building a mobile/webapp UI for telescope control operation, mostly based on INDI + PHD2 : https://github.com/pludov/mobindi
It includes a UI showing live PHD status (RA/DEC curve and capture image view), from the event-server.

The goal of this MR is to be able to display the same level of info than the native PHD2 UI about multi-star (secondary ones actually which are not exposed today by the event-server), so that -as a user - I can be confident the system correctly detected a fair set of realistic secondary stars. That really means at least drawing them on the live image view.

Implementing the required changes to the event-server, I opted to add a broader set of information in the PHD status, to make it future proof (like reference vs actual pos, SNR, ...) and not too coupled to the algorithm (it exposes the set of stars).
That's in the hope that it could be useful to others; I myself foresee other use cases than mine of today, like forwarding the values in a metric DB to do some data analysis on it, or do astrometry to confirm/reject secondary stars, ....

Also, I've learned that the multi-star algorithm does not necessarily use all the secondary stars, so I added this per star status to the report (taken from the debug log). My goal here is to render the secondary stars with a color code that indicates if they contribute or not to the guiding.
I think this display logic could be added to the PHD UI: currently you can end up in a situation where the current UI display many green stars, yet they are not used for some reason. To be discussed since it might not be inline with the "Dummy" spirit of PHD...

Regarding the broadcast increase, I am not sure what your concern is here, as the volume is not that big (a few KB at most per frame). It might maybe disturb applications that have some tight assumption on the protocol (like line size, event types, ...) Anyway, I can add an opt-in JsonRPC method, by which a client can requests this messages explictely. That would avoid disturbing existing clients that do not need this info.

[agalasso]

@pludov Thanks for the PR! After reviewing it, we see this primarily as reproducing the PHD2 UI display on another device, and that's not a direction we're looking to go. We'd like PHD2 to be fully automatic when it comes to guiding — the idea that a user needs to monitor multi-star selection and potentially micro-manage it runs against our goals.
Our intent for the server API is to support automated imaging and spectroscopy. We envision users interacting with the PHD2 UI directly for initial setup and troubleshooting — if something goes wrong, we'd rather they engage with PHD2 itself than through a secondary app.
For diagnosing star selection issues, we'd prefer to lean on the debug log rather than a mirrored display. Hope that context makes sense, and thanks again for contributing!