csi — camera sensors

The csi module is used for controlling camera sensors.

Example usage:

import csi

# Setup camera.
csi0 = csi.CSI()
csi0.reset()
csi0.pixformat(csi.RGB565)
csi0.framesize(csi.QVGA)
csi0.snapshot(time=2000)  # skip frames

# Take pictures.
while(True):
    csi0.snapshot()

class CSI – Camera Sensor Interface

The CSI class is used to control a camera sensor.

class csi.CSI(cid: int = -1, delays: bool = True, fflush: bool = True, stream: bool | None = None)

Create an object to talk with a camera sensor. On boards with multiple sensors, the particular CSI object may be selected by passing a cid like csi.LEPTON to select a FLIR Lepton sensor module. If cid is -1 the primary sensor is selected (typically a color camera module on multi-sensor boards).

If delays is False then all settling time delays in the csi driver are disabled. By default the sensor driver delays after reset / mode change to prevent corrupt frames being returned by CSI.snapshot. Disabling delays lets you batch updates and apply a single delay at the end before calling CSI.snapshot.

If fflush is False then automatic framebuffer flushing mentioned in CSI.framebuffers is disabled. This removes any time limit on frames in the frame buffer fifo.

stream selects whether this CSI is the stream source sent to the IDE. If None (default) the CSI becomes the stream source only if it is the primary (non-auxiliary) sensor. Pass True to force this CSI to be the stream source, or any false value to leave the existing stream source unchanged.

Methods

reset(hard: bool = True) None

Initializes the camera sensor. Performs a hardware reset by toggling the RESET signal GPIO to the camera module if hard is True. hard should be set to false when resetting auxiliary camera sensors that share the same RESET signal GPIO as the primary module.

shutdown(enable: bool) None

Puts the camera into a lower power mode than sleep (but the camera must be reset on being woken up).

sleep(enable: bool) None

Puts the camera to sleep if enable is True. Otherwise, wakes it back up.

flush() None

Copies the current frame buffer contents to the IDE preview. Call this after the last CSI.snapshot if the script terminates so the IDE shows the last frame.

snapshot(time: int = -1, frames: int = -1, blocking: bool = True, image: image.Image | None = None) image.Image | None

Takes a picture using the camera and returns an image.Image object.

If time and/or frames is passed snapshot will block for that many time milliseconds and/or frames captured from the camera. Both arguments may be used at the same time. After time and/or frames has passed snapshot will return None.

blocking may be False to enable non-blocking behavior which will cause snapshot to return None when the next image from the camera is not ready versus waiting.

image may be another image.Image object to update with the new image captured from the camera instead of returning a new image.Image object. The previous image contents are overwritten via a deep copy.

If CSI.auto_rotation is enabled this method will return an already-rotated image.Image.

width() int

Returns the sensor resolution width.

height() int

Returns the sensor resolution height.

cid() int

Returns the camera module chip ID. Compare against any of csi.OV2640, csi.OV5640, csi.OV7670, csi.OV7690, csi.OV7725, csi.OV9650, csi.MT9V022, csi.MT9V024, csi.MT9V032, csi.MT9V034, csi.MT9M114, csi.BOSON320, csi.BOSON640, csi.LEPTON, csi.HM01B0, csi.HM0360, csi.GC2145, csi.GENX320ES, csi.GENX320, csi.PAG7920, csi.PAG7936, csi.PAJ6100, csi.FROGEYE2020, or csi.SOFTCSI.

readable() bool

Returns True if there is an image ready to be returned by CSI.snapshot so a call to snapshot will not block.

pixformat(pixformat: int | None = None) int | None

Sets the pixel format for the camera module to one of csi.GRAYSCALE, csi.RGB565, csi.BAYER, csi.YUV422, or csi.JPEG (only on the OV2640/OV5640).

Returns the current pixformat if called with no arguments.

framesize(framesize: int | Tuple[int, int] | None = None) int | None

Sets the frame size for the camera module to one of the size constants (e.g. csi.QVGA, csi.VGA, csi.HD, etc. — see the constants section).

Alternatively, you may pass a custom framesize as a (w, h) tuple. When CSI.snapshot is called the custom framesize will be evaluated against DMA rules. Generally framesizes need to be a multiple of 8 pixels and/or 16 bytes.

Returns the current framesize if called with no arguments.

framerate(rate: int | None = None) int | None

Sets the frame rate in Hz for the camera module.

Returns the current framerate if called with no arguments.

Note

CSI.framerate works by dropping frames received by the camera module to keep the frame rate at or below the rate specified. By default the camera will run at the maximum frame rate. If implemented for the particular camera sensor CSI.framerate will also reduce the camera sensor frame rate internally to save power and improve image quality by increasing the sensor exposure. CSI.framerate may conflict with CSI.auto_exposure on some cameras.

window(roi: Tuple[int, int] | Tuple[int, int, int, int] | None = None) Tuple[int, int, int, int] | None

Sets the resolution of the camera to a sub-region of the current resolution. roi is a (x, y, w, h) tuple. You may also pass (w, h) and the window will be centered.

Returns the current (x, y, w, h) tuple if called with no arguments.

gainceiling(gainceiling: int) bool

Set the camera image gainceiling to one of 2, 4, 8, 16, 32, 64, or 128.

Returns True on success and False on failure.

brightness(brightness: int) bool

Set the camera image brightness.

Returns True on success and False on failure.

contrast(contrast: int) bool

Set the camera image contrast.

Returns True on success and False on failure.

saturation(saturation: int) bool

Set the camera image saturation.

Returns True on success and False on failure.

quality(quality: int) bool

Set the camera image JPEG compression quality. 0 - 100.

Returns True on success and False on failure.

Note

Only for the OV2640/OV5640 cameras.

colorbar(enable: bool) bool

Turns color bar mode on (True) or off (False). Defaults to off.

Returns True on success and False on failure.

auto_gain(enable: bool, gain_db: float | None = None, gain_db_ceiling: float | None = None) None

enable turns auto gain control on (True) or off (False). The camera starts up with auto gain control on.

If enable is False you may set a fixed gain in decibels with gain_db.

If enable is True you may set the maximum gain ceiling in decibels with gain_db_ceiling for the automatic gain control algorithm.

Note

You need to turn off white balance too if you want to track colors.

gain_db() float

Returns the current camera gain value in decibels.

auto_exposure(enable: bool, exposure_us: int = -1) None

enable turns auto exposure control on (True) or off (False). The camera starts up with auto exposure control on.

If enable is False you may set a fixed exposure time in microseconds with exposure_us.

Note

Camera auto exposure algorithms are pretty conservative about how much they adjust the exposure value by and will generally avoid changing the exposure value by much. Instead, they change the gain value a lot to deal with changing lighting.

exposure_us() int

Returns the current camera exposure value in microseconds.

auto_whitebal(enable: bool, rgb_gain_db: Tuple[float, float, float] | None = None) None

enable turns auto white balance on (True) or off (False). The camera starts up with auto white balance on.

If enable is False you may set a fixed gain in decibels for the red, green, and blue channels respectively with rgb_gain_db.

Note

You need to turn off gain control too if you want to track colors.

rgb_gain_db() Tuple[float, float, float]

Returns a tuple (r, g, b) of the current camera red, green, and blue gain values in decibels.

auto_blc(enable: bool, regs: List[int] | None = None) None

Sets the auto black-level calibration (BLC) on the camera.

enable pass True or False to turn BLC on or off. You typically always want this on.

regs if disabled then you can manually set the BLC register values from a previous call to CSI.blc_regs.

blc_regs() List[int]

Returns the sensor BLC registers as a list of integers. For use with CSI.auto_blc.

hmirror(enable: bool | None = None) bool | None

Turns horizontal mirror mode on (True) or off (False). Defaults to off.

Returns the current setting if called with no arguments.

vflip(enable: bool | None = None) bool | None

Turns vertical flip mode on (True) or off (False). Defaults to off.

Returns the current setting if called with no arguments.

transpose(enable: bool | None = None) bool | None

Turns transpose mode on (True) or off (False). Defaults to off.

  • vflip=False, hmirror=False, transpose=False -> 0 degree rotation

  • vflip=True, hmirror=False, transpose=True -> 90 degree rotation

  • vflip=True, hmirror=True, transpose=False -> 180 degree rotation

  • vflip=False, hmirror=True, transpose=True -> 270 degree rotation

Returns the current setting if called with no arguments.

auto_rotation(enable: bool | None = None) bool | None

Turns auto rotation mode on (True) or off (False). Defaults to off.

Returns the current setting if called with no arguments.

Note

This method only works when the OpenMV Cam has an imu installed and is enabled automatically.

framebuffers(count: int | None = None) int | None

Sets the number of frame buffers used to receive image data. By default the OpenMV Cam will try to allocate the maximum number of frame buffers it can. Reallocation occurs whenever CSI.pixformat, CSI.framesize, or CSI.window are called.

count of 1 (single buffer), 2 (double buffer), or 3 (triple buffer) selects the corresponding capture mode. Pass 4 or greater to put the driver into video FIFO mode where count buffers are queued — useful for video recording to an SD card. On frame drop, all frame buffers except the active one are cleared so CSI.snapshot always returns a recent frame.

Returns the current count if called with no arguments.

special_effect(effect: int) bool

Sets the special digital effect (one of csi.NORMAL or csi.NEGATIVE).

Returns True on success and False on failure.

lens_correction(enable: bool, radi: int, coef: int) bool

enable True to enable, False to disable. radi integer radius of pixels to correct. coef power of correction.

Returns True on success and False on failure.

vsync_callback(cb: Callable[[int], None] | None = None) Callable[[int], None] | None

Registers callback cb to be executed (in interrupt context) whenever the camera module generates a new frame (but before the frame is received).

cb takes one argument and is passed the current state of the vsync pin after changing.

Returns the registered callback if called with no arguments. Pass any non-callable to clear the callback.

frame_callback(cb: Callable[[], None] | None = None) Callable[[], None] | None

Registers callback cb to be executed (in interrupt context) whenever the camera module generates a new frame and the frame is ready to be read via CSI.snapshot.

cb takes no arguments. Use this to schedule reading a frame later with micropython.schedule().

Returns the registered callback if called with no arguments. Pass any non-callable to clear the callback.

ioctl(request: int, *args) Any

Executes a sensor-specific request. The first argument is one of the IOCTL_* constants; additional arguments and return value depend on the request.

color_palette(palette: int | None = None) int | None

Sets the color palette to use for things like FLIR Lepton grayscale to RGB565 conversion or GENX320 event visualization. One of image.PALETTE_RAINBOW, image.PALETTE_IRONBOW, and (when supported) image.PALETTE_DEPTH, image.PALETTE_EVT_DARK, or image.PALETTE_EVT_LIGHT.

Returns the current setting if called with no arguments.

__write_reg(address: int, value: int) None

Write value to the camera register at address.

Note

See the camera data sheet for register info.

__read_reg(address: int) int

Read the camera register at address.

Note

See the camera data sheet for register info.

Functions

csi.devices() List[int]

Returns a list of the detected sensor chip IDs.

Constants

csi.BINARY: int

BINARY (bitmap) pixel format. Each pixel is 1-bit. Useful for mask storage; can be used with image.Image().

csi.GRAYSCALE: int

GRAYSCALE pixel format (Y from YUV422). Each pixel is 8-bits.

csi.RGB565: int

RGB565 pixel format. Each pixel is 16-bits (5-bits red, 6-bits green, 5-bits blue).

csi.BAYER: int

RAW BAYER image pixel format.

csi.YUV422: int

YUV422 pixel format. Each pixel is stored as a grayscale 8-bit Y value followed by alternating 8-bit U/V color values shared between two Y values (Y1, U, Y2, V, …). Only some image processing methods work with YUV422.

csi.JPEG: int

JPEG mode. The camera module outputs compressed JPEG images. Use CSI.quality to control the JPEG quality. Only works for the OV2640/OV5640 cameras.

csi.OV2640: int

CSI.cid returns this for the OV2640 camera.

csi.OV5640: int

CSI.cid returns this for the OV5640 camera.

csi.OV7670: int

CSI.cid returns this for the OV7670 camera.

csi.OV7690: int

CSI.cid returns this for the OV7690 camera.

csi.OV7725: int

CSI.cid returns this for the OV7725 camera.

csi.OV9650: int

CSI.cid returns this for the OV9650 camera.

csi.MT9V022: int

CSI.cid returns this for the MT9V022 camera.

csi.MT9V024: int

CSI.cid returns this for the MT9V024 camera.

csi.MT9V032: int

CSI.cid returns this for the MT9V032 camera.

csi.MT9V034: int

CSI.cid returns this for the MT9V034 camera.

csi.MT9M114: int

CSI.cid returns this for the MT9M114 camera.

csi.BOSON320: int

CSI.cid returns this for the BOSON 320x256 camera.

csi.BOSON640: int

CSI.cid returns this for the BOSON 640x512 camera.

csi.LEPTON: int

CSI.cid returns this for the LEPTON1/2/3 cameras.

csi.HM01B0: int

CSI.cid returns this for the HM01B0 camera.

csi.HM0360: int

CSI.cid returns this for the HM0360 camera.

csi.GC2145: int

CSI.cid returns this for the GC2145 camera.

csi.GENX320ES: int

CSI.cid returns this for the GENX320 (engineering sample) camera.

csi.GENX320: int

CSI.cid returns this for the GENX320 camera.

csi.PAG7920: int

CSI.cid returns this for the PAG7920 camera.

csi.PAG7936: int

CSI.cid returns this for the PAG7936 camera.

csi.PAJ6100: int

CSI.cid returns this for the PAJ6100 camera.

csi.FROGEYE2020: int

CSI.cid returns this for the FROGEYE2020 camera.

csi.SOFTCSI: int

CSI.cid returns this for the software CSI camera.

csi.NORMAL: int

Normal mode for CSI.special_effect.

csi.NEGATIVE: int

Negative mode for CSI.special_effect.

csi.QCIF: int

176x144 resolution for the camera sensor.

csi.CIF: int

352x288 resolution for the camera sensor.

csi.QSIF: int

176x120 resolution for the camera sensor.

csi.SIF: int

352x240 resolution for the camera sensor.

csi.QQQVGA: int

80x60 resolution for the camera sensor.

csi.QQVGA: int

160x120 resolution for the camera sensor.

csi.QVGA: int

320x240 resolution for the camera sensor.

csi.VGA: int

640x480 resolution for the camera sensor.

csi.HQVGA: int

240x160 resolution for the camera sensor.

csi.HVGA: int

480x320 resolution for the camera sensor.

csi.WVGA: int

720x480 resolution for the MT9V034 camera sensor.

csi.WVGA2: int

752x480 resolution for the MT9V034 camera sensor.

csi.SVGA: int

800x600 resolution for the camera sensor.

csi.XGA: int

1024x768 resolution for the camera sensor.

csi.WXGA: int

1280x768 resolution for the MT9M114 camera sensor.

csi.SXGA: int

1280x1024 resolution for the camera sensor. Only works for the OV2640/OV5640 cameras.

csi.SXGAM: int

1280x960 resolution for the MT9M114 camera sensor.

csi.UXGA: int

1600x1200 resolution for the camera sensor. Only works for the OV2640/OV5640 cameras.

csi.HD: int

1280x720 resolution for the camera sensor.

csi.FHD: int

1920x1080 resolution for the camera sensor. Only works for the OV5640 camera.

csi.QHD: int

2560x1440 resolution for the camera sensor. Only works for the OV5640 camera.

csi.QXGA: int

2048x1536 resolution for the camera sensor. Only works for the OV5640 camera.

csi.WQXGA: int

2560x1600 resolution for the camera sensor. Only works for the OV5640 camera.

csi.WQXGA2: int

2592x1944 resolution for the camera sensor. Only works for the OV5640 camera.

csi.IOCTL_SET_READOUT_WINDOW: int

Sets the readout window. See CSI.ioctl.

csi.IOCTL_GET_READOUT_WINDOW: int

Gets the readout window. See CSI.ioctl.

csi.IOCTL_SET_TRIGGERED_MODE: int

Sets triggered mode for the MT9V034. See CSI.ioctl.

csi.IOCTL_GET_TRIGGERED_MODE: int

Gets the triggered mode state for the MT9V034. See CSI.ioctl.

csi.IOCTL_SET_FOV_WIDE: int

Enable CSI.framesize to optimize for field-of-view over FPS. See CSI.ioctl.

csi.IOCTL_GET_FOV_WIDE: int

Returns whether CSI.framesize is optimizing for field-of-view over FPS. See CSI.ioctl.

csi.IOCTL_TRIGGER_AUTO_FOCUS: int

Trigger auto focus on the OV5640 FPC camera module. See CSI.ioctl.

csi.IOCTL_PAUSE_AUTO_FOCUS: int

Pause auto focus (while running) for the OV5640 FPC camera module. See CSI.ioctl.

csi.IOCTL_RESET_AUTO_FOCUS: int

Reset auto focus to default for the OV5640 FPC camera module. See CSI.ioctl.

csi.IOCTL_WAIT_ON_AUTO_FOCUS: int

Wait for auto focus to finish on the OV5640 FPC camera module. See CSI.ioctl.

csi.IOCTL_SET_NIGHT_MODE: int

Turn night mode on or off. Reduces frame rate to increase exposure dynamically. See CSI.ioctl.

csi.IOCTL_GET_NIGHT_MODE: int

Returns whether night mode is enabled. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_WIDTH: int

Returns the FLIR Lepton image resolution width in pixels. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_HEIGHT: int

Returns the FLIR Lepton image resolution height in pixels. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_RADIOMETRY: int

Returns the FLIR Lepton type (radiometric or not). See CSI.ioctl.

csi.IOCTL_LEPTON_GET_REFRESH: int

Returns the FLIR Lepton refresh rate in Hz. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_RESOLUTION: int

Returns the FLIR Lepton ADC resolution in bits. See CSI.ioctl.

csi.IOCTL_LEPTON_RUN_COMMAND: int

Executes a 16-bit command from the FLIR Lepton SDK. See CSI.ioctl.

csi.IOCTL_LEPTON_SET_ATTRIBUTE: int

Sets a FLIR Lepton attribute from the FLIR Lepton SDK. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_ATTRIBUTE: int

Gets a FLIR Lepton attribute from the FLIR Lepton SDK. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_FPA_TEMP: int

Gets the FLIR Lepton FPA temp in Celsius. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_AUX_TEMP: int

Gets the FLIR Lepton AUX temp in Celsius. See CSI.ioctl.

csi.IOCTL_LEPTON_SET_MODE: int

Sets the FLIR Lepton driver into a mode where each pixel is a temperature value. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_MODE: int

Returns whether measurement mode is enabled for the FLIR Lepton sensor. See CSI.ioctl.

csi.IOCTL_LEPTON_SET_RANGE: int

Sets the temperature range mapped to pixel values in measurement mode. See CSI.ioctl.

csi.IOCTL_LEPTON_GET_RANGE: int

Returns the temperature range used for measurement mode. See CSI.ioctl.

csi.IOCTL_HIMAX_MD_ENABLE: int

Controls the motion detection interrupt on the HM01B0. See CSI.ioctl.

csi.IOCTL_HIMAX_MD_WINDOW: int

Sets the motion detection window on the HM01B0. See CSI.ioctl.

csi.IOCTL_HIMAX_MD_THRESHOLD: int

Sets the motion detection threshold on the HM01B0. See CSI.ioctl.

csi.IOCTL_HIMAX_MD_CLEAR: int

Clears the motion detection interrupt on the HM01B0. See CSI.ioctl.

csi.IOCTL_HIMAX_OSC_ENABLE: int

Controls the internal oscillator on the HM01B0. See CSI.ioctl.

csi.IOCTL_GET_RGB_STATS: int

Returns the RGB statistics from the camera sensor. See CSI.ioctl.

csi.IOCTL_GENX320_SET_BIASES: int

Sets the GENX320 sensor biases to a preset. See CSI.ioctl.

csi.GENX320_BIASES_DEFAULT: int

Default biases for the GENX320 camera sensor.

csi.GENX320_BIASES_LOW_LIGHT: int

Low light biases for the GENX320 camera sensor.

csi.GENX320_BIASES_ACTIVE_MARKER: int

Active marker biases for the GENX320 camera sensor.

csi.GENX320_BIASES_LOW_NOISE: int

Low noise biases for the GENX320 camera sensor.

csi.GENX320_BIASES_HIGH_SPEED: int

High speed biases for the GENX320 camera sensor.

csi.IOCTL_GENX320_SET_BIAS: int

Sets a single GENX320 camera sensor bias. See CSI.ioctl.

csi.GENX320_BIAS_DIFF_OFF: int

Selects the GENX320 DIFF OFF bias.

csi.GENX320_BIAS_DIFF_ON: int

Selects the GENX320 DIFF ON bias.

csi.GENX320_BIAS_FO: int

Selects the GENX320 FO bias.

csi.GENX320_BIAS_HPF: int

Selects the GENX320 HPF bias.

csi.GENX320_BIAS_REFR: int

Selects the GENX320 REFR bias.

csi.IOCTL_GENX320_SET_AFK: int

Sets the GENX320 anti-flicker filter. See CSI.ioctl.

csi.IOCTL_GENX320_SET_STC: int

Sets the GENX320 spatio-temporal contrast filter mode. See CSI.ioctl.

csi.GENX320_STC_DISABLE: int

Disable the GENX320 STC/trail filter.

csi.GENX320_STC_ONLY: int

Enable only the spatio-temporal contrast filter on the GENX320.

csi.GENX320_STC_TRAIL_ONLY: int

Enable only the trail filter on the GENX320.

csi.GENX320_STC_TRAIL: int

Enable both the STC and trail filters on the GENX320.

csi.IOCTL_GENX320_SET_MODE: int

Sets the GENX320 camera sensor operating mode. See CSI.ioctl.

csi.GENX320_MODE_HISTO: int

Sets the GENX320 to histogram mode.

csi.GENX320_MODE_EVENT: int

Sets the GENX320 to event mode.

csi.IOCTL_GENX320_READ_EVENTS: int

Populates an ndarray with event information from the GENX320. See CSI.ioctl.

csi.IOCTL_GENX320_CALIBRATE: int

Automatically turns off hot pixels on the GENX320. See CSI.ioctl.

csi.IOCTL_GENX320_READ_EVENTS_RAW: int

Returns a raw event-frame image.Image from the GENX320. See CSI.ioctl.

csi.PIX_OFF_EVENT: int

Pixel-off event.

csi.PIX_ON_EVENT: int

Pixel-on event.

csi.RST_TRIGGER_RISING: int

Pixel reset rising-edge event.

csi.RST_TRIGGER_FALLING: int

Pixel reset falling-edge event.

csi.EXT_TRIGGER_RISING: int

External trigger rising-edge event.

csi.EXT_TRIGGER_FALLING: int

External trigger falling-edge event.