Knowing what formats are supported for a camera.

[marsfan]

When setting up a capture configuration, there's the option to configure the format for each of the streams. However, it appears that not all raw modes are supported by all cameras, and instead of raising an exception that an invalid mode was specified, the library makes a "best fit" guess on what the correct configuration is.

As an example, with a HQ Camera on the Pi 5, I ran the following simple script.

from picamera2 import Picamera2
from picamera2.formats import BAYER_FORMATS

attempts: list[tuple[str, str]] = []
cam = Picamera2()
for fmt in BAYER_FORMATS:

    capture_config = cam.create_still_configuration(
        raw={"format": fmt},
        display=None,
    )
    cam.configure(capture_config)
    cam.start()
    result = cam.capture_request()
    cam.stop()

    attempts.append((fmt, result.config["raw"]["format"]))
cam.close()
print("Matches   Requested           Actual")
print("------------------------------------")
for attempt in attempts:
    print(f"{attempt[0] == attempt[1]!r:10}{attempt[0]:20}{attempt[1]}")

And only 2 of the options actually resulting in a capture that matched the requested format:

Matches   Requested           Actual
------------------------------------
False     SGBRG12_CSI2P       BGGR_PISP_COMP1
False     GBRG_PISP_COMP1     BGGR_PISP_COMP1
False     SRGGB12_CSI2P       BGGR_PISP_COMP1
False     SBGGR8              SBGGR16
False     SGBRG16             SBGGR16
False     SGBRG10             SBGGR16
False     SRGGB10             SBGGR16
True      SBGGR16             SBGGR16
False     SBGGR10             SBGGR16
False     SGRBG12_CSI2P       BGGR_PISP_COMP1
False     SGRBG10_CSI2P       BGGR_PISP_COMP1
False     RGGB_PISP_COMP1     BGGR_PISP_COMP1
False     SGBRG10_CSI2P       BGGR_PISP_COMP1
False     SRGGB10_CSI2P       BGGR_PISP_COMP1
False     SGBRG8              SBGGR16
False     SGRBG12             SBGGR16
False     SGRBG16             SBGGR16
False     SGRBG8              SBGGR16
False     SRGGB12             SBGGR16
False     SGRBG10             SBGGR16
False     SRGGB8              SBGGR16
True      BGGR_PISP_COMP1     BGGR_PISP_COMP1
False     SRGGB16             SBGGR16
False     SBGGR12             SBGGR16
False     SGBRG12             SBGGR16
False     SBGGR12_CSI2P       BGGR_PISP_COMP1
False     GRBG_PISP_COMP1     BGGR_PISP_COMP1
False     SBGGR10_CSI2P       BGGR_PISP_COMP1

This leads me to asking a few questions:

1. Is the behavior of this "best fit" selection documented anywhere?
2. Can this be disabled, so the program instead raises an exception when an invalid format is selected?
3. Where can I find documentation on what formats each camera model supports?

[davidplowman]

I would recommend calling the cam.sensor_modes property to discover the supported modes. Note that this will run through all the modes and configure them so as to query them for information, so you need to call this as the very first thing after creating the Picamera2 object.

You subsequently have only limited choices when you ask for a particular raw format (or sensor mode). You always have a choice about getting packed/compressed or unpacked/uncompressed data, though on a Pi 5 packed is interpreted as compressed (as packed outputs are not supported).

You may be able to choose the bit depth, depending on what bit depths are supported. On Pi 5, when you ask for unpacked/uncompressed pixels, you always get 16-bit output values. The sensor_mode in the configuration object will say how many bits the sensor produced.

You have no choice over the Bayer order, because the sensor only supports one. It will always correct what you request to what you can have. Note that the output Bayer order will change if you specify a different transform.

In the case of the HQ cam, you can only get BGGR output (unless you specify a different transform). You can either have uncompressed pixels (SBGGR16), or compressed pixels (BGGR_PISP_COMP1). In both cases, the sensor_mode will tell you how many bits the sensor is producing.

libcamera works hard to give you, whatever you ask for, the thing that actually works. I'm not sure I see any benefit in raising an error; it's always easy to check if you got what you asked for (remembering that in reality you have only limited choices). Section 4.2.2.3 of the manual does talk about this.

[marsfan]

Read cam.sensor_modes. That looks like what I'm looking for. Thanks.

As for selecting the thing that works vs raising an exception for a bad value, sounds like that's a difference of personal preference/style. I'm a fan of making code much more explicit, and erroring out if anything is not right. But if that's not the libcamera way, I'll just add some wrappers for myself to handle that.

[marsfan]

Also @davidplowman , the link to the manual you created seems to be broken, just a heads up.

[davidplowman]

Sorry, try this.