Camera capabilities and image formats

Camera adapters describe advanced settings through get_advanced_setting_capabilities(). Each entry contains a CameraSettingCapability with the current value, available choices, whether the adapter can change the value, whether acquisition must be stopped, and an explanation when the control is unavailable.

Query the connected device instead of inferring its capabilities from its model name. The connection type, driver version and operating mode can affect which settings are available. Querying capabilities must not change camera settings. Discard incomplete results after a driver error; a partial list is not a reliable description of the connected camera.

The base implementation reports bit-depth control as unavailable and set_bit_depth() raises NotImplementedError. The methods are concrete, so existing adapters continue to load without implementing them. An adapter can report a readable current value while leaving selection disabled. Only advertise writable choices when the complete acquisition path supports them.

Keep three representations distinct

  • Camera output depth describes meaningful output precision. It can be unknown even when the array storage type is known.

  • SDK transport layout describes incoming bytes, including packed pixels, row padding and bit alignment. The camera adapter owns this layout.

  • Array format describes the unpacked, right-aligned monochrome values that the adapter delivers to navigate. CameraImageFormat records the NumPy dtype and optional meaningful bit depth.

For example, CameraImageFormat.for_bit_depth(8) selects uint8, while CameraImageFormat.for_bit_depth(12) selects uint16 with 12 meaningful bits. The latter still uses two bytes per pixel. Never reinterpret packed native bytes as an unpacked array, and never infer camera precision from the brightest pixel in a frame.

Legacy adapters return CameraImageFormat() with a uint16 array and unknown meaningful depth. This preserves the existing buffer contract without making a claim about the sensor’s precision.

DCAM discovery

The Hamamatsu wrapper exposes get_property_values(name) for small discrete settings and is_property_writable(name) for the SDK writable attribute. Enumeration uses dcamprop_queryvalue rather than filling the interval between the minimum and maximum. Missing properties, malformed values, non-progressing enumeration and failed queries return an unavailable result.

The writable attribute alone does not authorize a setting change during acquisition. Adapters must enforce idle requirements and verify actual readback when implementing setters. A successful SDK query is not evidence of physical acquisition validation for a particular model and interface.

Hamamatsu validation boundaries

DCAM depth choices are discovered from the connected camera in its current mode. The adapter checks exact readback and restores captured settings if application fails. A failed restoration blocks acquisition until the camera is reconnected. Quest restart restores and verifies depth and pixel type before attaching buffers.

Pixel type must be selected before precision. For example, an ORCA-Quest 2 can report writable 12/16 choices in MONO16, then report fixed/read-only 8 after selecting MONO8. The adapter combines the advertised pixel types with precision choices. When idle in MONO8, it temporarily selects MONO16 to query its choices, then restores and verifies the original format and timing before returning. Discovery during capture, after failed restoration, or for ORCA-Lightning never performs that probe. No camera-model table supplies guessed depth choices.

Only unpacked MONO8 and MONO16 layouts are currently accepted. Row padding and buffer top offsets are handled using native scratch buffers; normalized arrays preserve integer counts without scaling. Packed MONO12/MONO12P and color layouts are rejected. An advertised 12-bit option therefore still requires a supported unpacked transport layout. ORCA-Lightning remains read-only until its coupled High Dynamic Range/full-well mode and timing changes are implemented.

Automated fake-SDK tests cover discovery, rollback, attachment, padding, offsets, range checks and restart failures. They do not certify a physical camera model. Before declaring a model tested, record its model/serial, firmware, DCAM version, connection, sensor/readout mode, each offered depth, confirmed native layout, exact saved counts and measured acquisition throughput. Repeat after a restart and a mode change. Unsupported or untested models must never receive guessed choices from a product-name table.

On 2026-11-05, direct SDK tests on a USB-connected ORCA-Quest 2 C15550-22UP, firmware 3.20, driver 1.2.6.0 and Linux DCAM 4.0.7087 verified MONO8 capture in Normal and Light-Sheet modes. Starting in either 12 or 16 bits, writing BITSPERCHANNEL=8 first returned INVALIDVALUE; selecting MONO8 first succeeded and made precision read back as 8. Native 512 by 512 frames used 262,144 bytes in MONO8 versus 524,288 bytes in MONO16. This establishes native byte counts, not sustained throughput or support for other camera/firmware combinations.