NINA does not handle Gains in an ASCOM compliant matter, GAINS INDEX not supported

[Jeremy Burton]

For reporting bugs please use the following guideline to describe the problem:

[ X] Is the issue reproducible?
[ X] Are all prerequisites that are mentioned inside the manual met?

Which Version are you running?

2.0 HF1 RC002

Description

The ASCOM standard has 2 modes for camera gain. There is an absolute mode where gain is set as an integer between GainMax and GainMin. This is common for CMOS cameras

There is also in index mode where the gain is a predefined list of named values. These are returned in the Gains ArrayList as a list of string names corresponding to the names of the gains.

This is explicitly stated in the documentation for ICameraV3:

The Gain property is used to adjust the gain setting of the camera and has two modes of operation:

• GAIN VALUE MODE - The Gain property is a direct numeric representation of the camera's gain.

  • In this mode the GainMin and GainMax properties must return integers specifying the valid range for Gain
  • The Gains property must return a PropertyNotImplementedException.

• GAINS INDEX MODE - The Gain property is the selected gain's index within the Gains array of textual gain descriptions.

  • In this mode the Gains method returns a 0-based array of strings, which describe available gain settings e.g. "ISO 200", "ISO 1600"
  • GainMin and GainMax must throw PropertyNotImplementedExceptions.
  • Please note that the Gains array is zero based.

NINA makes a faulty assumption that all gains, including those in the Gains ArrayList are integers.

From AscomCamera.cs in Nina.Equipment:

           foreach (object o in device.Gains) {
                if (o.GetType() == typeof(string)) {
                    var gain = Regex.Match(o.ToString(), @"\d+").Value;
                    Gains.Add(int.Parse(gain, CultureInfo.InvariantCulture));
                }

The code makes the assumption that the value can be parsed as an integer. In fact, these are names, and the index into the ArrayList for the current mode is set by the Gain value from the ASCOM driver. As noted in the remarks for the Gains property in the ASCOM documentation:

When Gain is operating in GAINS INDEX mode:

• The Gains property must return a zero-based ArrayList of available gain setting names.
• The GainMin and GainMax properties must throw PropertyNotImplementedExceptions.

The returned gain names could, for example, be a list of ISO settings for a DSLR camera or a list of gain names for a CMOS camera. Typically the application software will display the returned gain names in a drop list, from which the astronomer can select the required value. The application can then configure the required gain by setting the camera's Gain property to the array index of the selected description.

It is recommended that this function be called only after a connection is established with the camera hardware to ensure that the driver is aware of the capabilities of the specific camera model.

This is only available in Camera Interface Version 2 and later.

‌

Steps to Reproduce

• Start Nina and select a QSI camera
• Connect to the camera
• Note that the gain values for the camera on the equipment page are invalid with max and Min both at -1

Expected behaviour

The available list of gains should be displayed as a dropdown of available gains by name

Actual behaviour

See above. Gains are inoperable in NINA in GAINS INDEX mode.

Additional Notes

This assumption on gains seems to permeate across the NINA ecosystem, including all sequencer instructions. Fixing this comprehensively will be a major bear. As an interim patch to at least start supporting GAINS INDEX, I would suggest that when the ASCOM driver is using GAINS INDEX mode, GainMin is set to zero and GainMax is set to the length of ArrayList-1. It should be possible to add information on the camera equipment page that provides the gain mappings to the user, allowing them to select 0, 1 etc. for the gain elsewhere in the system, such as in the sequencer instructions.

[Stefan B]

Fixed by reporter with 04190cd

[Stefan B]

Removing version: 2.0 HF1 Beta (automated comment)

[Ingvar Stepanyan]

Hi, I don’t think this was fixed - I’m still seeing this issue with any ASCOM cameras that use Gain Names (gains index mode) in NINA 2.2:

Or maybe it was a regression? Or should I create a new issue?

[Ingvar Stepanyan]

Ah I see the comment in the linked commit says:

// Per the ASCOM spec, if we have Gains, then they are names, not values.
// Add an index for each value and write the mapping to the log.
// TODO - Look at how to carry the names to the UI
// eg by adding a GainsPreset string list to ICamera.
// Making Gains a string has too many ripple effects with the 
// UI for a quick fix. 

So I guess it was fixed only in the sense that it’s not crashing on those but not in terms of UI implementation?

[Jeremy Burton]

“So I guess it was fixed only in the sense that it’s not crashing on those but not in terms of UI implementation?”

‌

Correct. The gains do work now, but the names are missing. Gain is tied directly to ISO for DSLRs and numerical gain for CMOS as currently implemented in NINA. Untangling that would have caused a whole slew of breaking changes. At the time, it only appeared to impact QSI cameras, and I figured it wasn’t worth attempting to fix this.

As it stands today, the gain numbers are mapped to the index in the gain array. So, for my QSI the gains are reported as High Gain and Low Gain. These get mapped to 0 and 1 respectively. So, if you know the order, you can set the gain. You can get the order by interrogating the ASCOM driver with a Powershell script.

It is a bit of a hack, but it does work, and I got it done with no breaking changes. I’m happy to jump in if you want to bring this up with the key maintainers, but my personal take is that unless it is impacting a lot of users it isn't worth the effort. It mainly impacts legacy CCD cameras, and only a handful at that.

‌

[Ingvar Stepanyan]

It also impacts DSLRs not supported by NINA. I’m currently writing one such driver (for Alpaca, but for all intents and purposes ASCOM one). I now see ASCOM.DSLR had to work around same issue by specifically singling out NINA as separate settings profile and returning min/max ISO instead of list of actually supported values: https://github.com/vtorkalo/ASCOM.DSLR/blob/57615bb2e890c82690353b120ffed7292d2a6e26/ASCOM.DSLR/Camera.cs#L462-L482

I guess I can do the same but it does seem like a pretty unfortunate hack for something that should be supported natively...