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
cidlikecsi.LEPTONto select a FLIR Lepton sensor module. Ifcidis -1 the primary sensor is selected (typically a color camera module on multi-sensor boards).If
delaysisFalsethen 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 byCSI.snapshot. Disabling delays lets you batch updates and apply a single delay at the end before callingCSI.snapshot.If
fflushisFalsethen automatic framebuffer flushing mentioned inCSI.framebuffersis disabled. This removes any time limit on frames in the frame buffer fifo.streamselects whether this CSI is the stream source sent to the IDE. IfNone(default) the CSI becomes the stream source only if it is the primary (non-auxiliary) sensor. PassTrueto 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
hardisTrue.hardshould 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).
- flush() None
Copies the current frame buffer contents to the IDE preview. Call this after the last
CSI.snapshotif 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.Imageobject.If
timeand/orframesis passed snapshot will block for that manytimemilliseconds and/orframescaptured from the camera. Both arguments may be used at the same time. Aftertimeand/orframeshas passed snapshot will returnNone.blockingmay beFalseto enable non-blocking behavior which will cause snapshot to returnNonewhen the next image from the camera is not ready versus waiting.imagemay be anotherimage.Imageobject to update with the new image captured from the camera instead of returning a newimage.Imageobject. The previous image contents are overwritten via a deep copy.If
CSI.auto_rotationis enabled this method will return an already-rotatedimage.Image.
- 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, orcsi.SOFTCSI.
- readable() bool
Returns
Trueif there is an image ready to be returned byCSI.snapshotso 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, orcsi.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. WhenCSI.snapshotis 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.framerateworks 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 sensorCSI.frameratewill also reduce the camera sensor frame rate internally to save power and improve image quality by increasing the sensor exposure.CSI.frameratemay conflict withCSI.auto_exposureon 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.
roiis 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
Trueon success andFalseon failure.
- brightness(brightness: int) bool
Set the camera image brightness.
Returns
Trueon success andFalseon failure.
- contrast(contrast: int) bool
Set the camera image contrast.
Returns
Trueon success andFalseon failure.
- saturation(saturation: int) bool
Set the camera image saturation.
Returns
Trueon success andFalseon failure.
- quality(quality: int) bool
Set the camera image JPEG compression quality. 0 - 100.
Returns
Trueon success andFalseon 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
Trueon success andFalseon failure.
- auto_gain(enable: bool, gain_db: float | None = None, gain_db_ceiling: float | None = None) None
enableturns auto gain control on (True) or off (False). The camera starts up with auto gain control on.If
enableisFalseyou may set a fixed gain in decibels withgain_db.If
enableisTrueyou may set the maximum gain ceiling in decibels withgain_db_ceilingfor the automatic gain control algorithm.Note
You need to turn off white balance too if you want to track colors.
- auto_exposure(enable: bool, exposure_us: int = -1) None
enableturns auto exposure control on (True) or off (False). The camera starts up with auto exposure control on.If
enableisFalseyou may set a fixed exposure time in microseconds withexposure_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.
- auto_whitebal(enable: bool, rgb_gain_db: Tuple[float, float, float] | None = None) None
enableturns auto white balance on (True) or off (False). The camera starts up with auto white balance on.If
enableisFalseyou may set a fixed gain in decibels for the red, green, and blue channels respectively withrgb_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.
enablepassTrueorFalseto turn BLC on or off. You typically always want this on.regsif disabled then you can manually set the BLC register values from a previous call toCSI.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
imuinstalled 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, orCSI.windoware called.countof 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 wherecountbuffers are queued — useful for video recording to an SD card. On frame drop, all frame buffers except the active one are cleared soCSI.snapshotalways 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.NORMALorcsi.NEGATIVE).Returns
Trueon success andFalseon failure.
- lens_correction(enable: bool, radi: int, coef: int) bool
enableTrueto enable,Falseto disable.radiinteger radius of pixels to correct.coefpower of correction.Returns
Trueon success andFalseon failure.
- vsync_callback(cb: Callable[[int], None] | None = None) Callable[[int], None] | None
Registers callback
cbto be executed (in interrupt context) whenever the camera module generates a new frame (but before the frame is received).cbtakes 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
cbto be executed (in interrupt context) whenever the camera module generates a new frame and the frame is ready to be read viaCSI.snapshot.cbtakes no arguments. Use this to schedule reading a frame later withmicropython.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.csi.IOCTL_SET_READOUT_WINDOW— Pass an(x, y, w, h)or(w, h)tuple/list to set the readout window of the sensor. Increases frame rate at the cost of field-of-view.csi.IOCTL_GET_READOUT_WINDOW— Returns the current readout window as(x, y, w, h).csi.IOCTL_SET_TRIGGERED_MODE— PassTrue/Falseto set triggered mode (MT9V034).csi.IOCTL_GET_TRIGGERED_MODE— Returns the current triggered mode state.csi.IOCTL_SET_FOV_WIDE— PassTrue/Falseto enableCSI.framesizeto optimize for field-of-view over FPS.csi.IOCTL_GET_FOV_WIDE— Returns the current FOV-wide state.csi.IOCTL_SET_NIGHT_MODE— PassTrue/Falseto enable night mode (OV7725, OV5640).csi.IOCTL_GET_NIGHT_MODE— Returns the current night mode state.csi.IOCTL_TRIGGER_AUTO_FOCUS— Trigger auto focus on the OV5640 FPC module.csi.IOCTL_PAUSE_AUTO_FOCUS— Pause auto focus on the OV5640 FPC module.csi.IOCTL_RESET_AUTO_FOCUS— Reset auto focus on the OV5640 FPC module.csi.IOCTL_WAIT_ON_AUTO_FOCUS— Wait for auto focus to finish (OV5640 FPC). Optional second argument is the timeout in ms (default 5000).csi.IOCTL_LEPTON_GET_WIDTH— Returns the FLIR Lepton image width in pixels.csi.IOCTL_LEPTON_GET_HEIGHT— Returns the FLIR Lepton image height in pixels.csi.IOCTL_LEPTON_GET_RADIOMETRY— Returns the FLIR Lepton type (radiometric or not).csi.IOCTL_LEPTON_GET_REFRESH— Returns the FLIR Lepton refresh rate in Hz.csi.IOCTL_LEPTON_GET_RESOLUTION— Returns the FLIR Lepton ADC resolution in bits.csi.IOCTL_LEPTON_RUN_COMMAND— Pass a 16-bit value as the FLIR Lepton SDK command.csi.IOCTL_LEPTON_SET_ATTRIBUTE— Pass the 16-bit attribute id and a bytes/bytearray payload (multiple of 16 bits) as defined by the FLIR Lepton SDK.csi.IOCTL_LEPTON_GET_ATTRIBUTE— Pass the 16-bit attribute id and a 16-bit-word count. Returns a bytearray.csi.IOCTL_LEPTON_GET_FPA_TEMP— Returns the FLIR Lepton FPA temp in Celsius.csi.IOCTL_LEPTON_GET_AUX_TEMP— Returns the FLIR Lepton AUX temp in Celsius.csi.IOCTL_LEPTON_SET_MODE— Passmeasurement_enabledand optionallyhigh_temp_enabledto switch the Lepton between AGC and direct-temperature output.csi.IOCTL_LEPTON_GET_MODE— Returns(measurement_enabled, high_temp_enabled).csi.IOCTL_LEPTON_SET_RANGE— Pass(min_celsius, max_celsius)to set the temperature range mapped to 0..255 when measurement mode is enabled.csi.IOCTL_LEPTON_GET_RANGE— Returns the(min, max)temperature range in Celsius.csi.IOCTL_HIMAX_MD_ENABLE— PassTrue/Falseto enable HM01B0 motion detection.csi.IOCTL_HIMAX_MD_WINDOW— Pass(x, y, w, h)or(w, h)to set the HM01B0 motion detection window.csi.IOCTL_HIMAX_MD_THRESHOLD— Pass a 0-255 threshold for HM01B0 motion detection.csi.IOCTL_HIMAX_MD_CLEAR— Clears the HM01B0 motion detection interrupt.csi.IOCTL_HIMAX_OSC_ENABLE— PassTrue/Falseto enable the HM01B0 oscillator.csi.IOCTL_GET_RGB_STATS— Returns(r, gb, gr, b)RGB statistics from the sensor.csi.IOCTL_GENX320_SET_BIASES— Pass aGENX320_BIASES_*constant to apply a bias preset.csi.IOCTL_GENX320_SET_BIAS— Pass aGENX320_BIAS_*constant and an integer value to set a single bias.csi.IOCTL_GENX320_SET_AFK— Passenable(and optionallyfreq_low_hz,freq_high_hz) to control the anti-flicker filter.csi.IOCTL_GENX320_SET_STC— Pass aGENX320_STC_*constant (and optionally up to two further arguments) to control spatio-temporal contrast filtering.csi.IOCTL_GENX320_SET_MODE— Pass aGENX320_MODE_*constant. For event mode, pass the row-axis length of the eventndarrayas the second argument.csi.IOCTL_GENX320_READ_EVENTS— Pass a uint16ndarrayof shape(EVT_res, 6)(withEVT_resa power of two between 1024 and 65536). The columns are[0]event type (csi.PIX_OFF_EVENT/csi.PIX_ON_EVENT/trigger),[1]seconds,[2]milliseconds,[3]microseconds,[4]x coordinate,[5]y coordinate. Returns the number of events written.csi.IOCTL_GENX320_CALIBRATE— Pass an integer iteration count and a sigma float to turn off pixels outsidesigmastandard deviations of the normal distribution. Returns the number of pixels disabled.csi.IOCTL_GENX320_READ_EVENTS_RAW— Returns animage.Imagecontaining the raw event frame from the GENX320.
- 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, orimage.PALETTE_EVT_LIGHT.Returns the current setting if called with no arguments.
Functions
Constants
- csi.BINARY: int
BINARY (bitmap) pixel format. Each pixel is 1-bit. Useful for mask storage; can be used with
image.Image().
- csi.RGB565: int
RGB565 pixel format. Each pixel is 16-bits (5-bits red, 6-bits green, 5-bits blue).
- 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.qualityto control the JPEG quality. Only works for the OV2640/OV5640 cameras.
- csi.NORMAL: int
Normal mode for
CSI.special_effect.
- csi.NEGATIVE: int
Negative mode for
CSI.special_effect.
- csi.SXGA: int
1280x1024 resolution for the camera sensor. Only works for the OV2640/OV5640 cameras.
- csi.UXGA: int
1600x1200 resolution for the camera sensor. Only works for the OV2640/OV5640 cameras.
- csi.IOCTL_SET_FOV_WIDE: int
Enable
CSI.framesizeto optimize for field-of-view over FPS. SeeCSI.ioctl.
- csi.IOCTL_GET_FOV_WIDE: int
Returns whether
CSI.framesizeis optimizing for field-of-view over FPS. SeeCSI.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_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_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_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_THRESHOLD: int
Sets the motion detection threshold on the HM01B0. See
CSI.ioctl.
- csi.IOCTL_GENX320_SET_STC: int
Sets the GENX320 spatio-temporal contrast filter mode. See
CSI.ioctl.
- csi.IOCTL_GENX320_READ_EVENTS: int
Populates an ndarray with event information from the GENX320. See
CSI.ioctl.
- csi.IOCTL_GENX320_READ_EVENTS_RAW: int
Returns a raw event-frame
image.Imagefrom the GENX320. SeeCSI.ioctl.