tof — time-of-flight sensor driver

The tof module drives time-of-flight (ToF) ranging sensors attached to an OpenMV Cam over I2C. Each frame returns a per-pixel depth value in millimetres for an 8x8 zone grid (VL53L5CX / VL53L8CX), which can be rendered as a standalone depth image with snapshot() or composited onto a visible-light frame from the CSI sensor with draw_depth(), normally through a colour palette such as image.PALETTE_DEPTH.

Example usage:

import csi
import tof

csi0 = csi.CSI()
csi0.reset()
csi0.pixformat(csi.RGB565)
csi0.framesize(csi.QVGA)

tof.init()

while True:
    img = csi0.snapshot()
    depth, depth_min, depth_max = tof.read_depth()
    tof.draw_depth(img, depth)
    print("====================")
    print("Min depth in mm seen: %0.2f" % depth_min)
    print("Max depth in mm seen: %0.2f" % depth_max)

If you want to rotate the depth array/image by multiples of 90 degrees pass the following hmirror/vflip/transpose combinations to read_depth, draw_depth, or snapshot:

  • 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

Functions

tof.init(type: int = -1) → None

Initializes an onboard depth sensor.

type indicates the type of TOF sensor:

By default type is -1 which causes tof.init() to automatically scan and initialize an attached TOF sensor based on the I2C address.

tof.reset() → None

Resets the depth sensor state.

tof.deinit() → None

Deinitializes the depth sensor freeing up resources.

tof.width() → int

Returns the width (horizontal resolution) of the depth sensor in-use. Raises a RuntimeError if the sensor is not initialized.

tof.height() → int

Returns the height (vertical resolution) of the depth sensor in-use. Raises a RuntimeError if the sensor is not initialized.

tof.type() → int

Returns the type of the depth sensor in-use:

Raises a RuntimeError if the sensor is not initialized.

tof.refresh() → int

Returns the refresh rate (in Hz) of the depth sensor in-use:

Raises a RuntimeError if the sensor is not initialized.

tof.read_depth(hmirror: bool = False, vflip: bool = False, transpose: bool = False, timeout: int = 100) → Tuple[List[float], float, float]

Returns a tuple containing the depth list (width * height floats in mm), the minimum depth seen, and the maximum depth seen.

hmirror if True horizontally mirrors the depth array.

vflip if True vertically flips the depth array.

transpose if True transposes the depth array.

timeout how many milliseconds to wait for the new frame before raising a RuntimeError. If 0 waits forever.

tof.draw_depth(image: image.Image, depth: List[float], x: int = 0, y: int = 0, x_scale: float | None = None, y_scale: float | None = None, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int = image.PALETTE_DEPTH, alpha_palette: int | None = None, hint: int = 0, scale: Tuple[float, float] | None = None) → None

Draws a depth array (as returned by read_depth) onto image whose top-left corner starts at location x, y.

x_scale controls how much the displayed image is scaled by in the x direction (float). If this value is negative the image will be flipped horizontally. If unspecified it matches y_scale to maintain aspect ratio.

y_scale controls how much the displayed image is scaled by in the y direction (float). If this value is negative the image will be flipped vertically. If unspecified it matches x_scale to maintain aspect ratio.

roi is the region-of-interest rectangle tuple (x, y, w, h) of the source depth array to draw.

rgb_channel is the RGB channel (0=R, 1=G, 2=B) to extract from the source. -1 (default) uses all channels.

alpha controls how much of the source is blended into the destination image. 255 is opaque, 0 results in no modification. Range: 0-255.

color_palette is a color palette enum (e.g. image.PALETTE_DEPTH, image.PALETTE_RAINBOW) or a 256-pixel RGB565 image used as a color lookup table on the grayscale depth value.

alpha_palette if not None is a 256-pixel GRAYSCALE image used as an alpha lookup table modulating alpha per pixel.

hint is a logical OR of:

scale is a two-value tuple (min, max) controlling the min and max depth (in mm) used to scale the depth image. Defaults to the depth array’s actual min and max.

Note

read_depth remembers if it was called with transpose=True and draw_depth uses that internally to size the source array.

tof.snapshot(hmirror: bool = False, vflip: bool = False, transpose: bool = False, x_scale: float | None = None, y_scale: float | None = None, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int = image.PALETTE_DEPTH, alpha_palette: int | None = None, hint: int = 0, scale: Tuple[float, float] | None = None, pixformat: int = image.RGB565, copy_to_fb: bool = False, timeout: int = 100) → image.Image

Reads a frame from the depth sensor and returns a new image.Image object that is either image.GRAYSCALE or image.RGB565.

hmirror if True horizontally mirrors the new image.

vflip if True vertically flips the new image.

transpose if True transposes the new image.

x_scale controls how much the image is scaled in the x direction (float). Negative values flip horizontally. If unspecified it matches y_scale.

y_scale controls how much the image is scaled in the y direction (float). Negative values flip vertically. If unspecified it matches x_scale.

roi is the region-of-interest rectangle tuple (x, y, w, h) of the source to extract.

rgb_channel is the RGB channel (0=R, 1=G, 2=B) to extract. -1 (default) uses all channels.

alpha controls source-to-destination blending. 255 is opaque, 0 leaves the destination unchanged. Range: 0-255.

color_palette is a color palette enum (e.g. image.PALETTE_DEPTH) or a 256-pixel RGB565 image used as a color lookup table.

alpha_palette if not None is a 256-pixel GRAYSCALE image used as an alpha lookup table.

hint is a logical OR of:

scale is a two-value tuple (min, max) controlling the min and max depth (in mm) used to scale the image. Defaults to the frame’s actual min/max.

pixformat controls the final image pixel format. Must be image.GRAYSCALE or image.RGB565.

copy_to_fb if True writes the new image into the frame buffer instead of allocating it on the MicroPython heap.

timeout how many milliseconds to wait for the new frame before raising a RuntimeError. If 0 waits forever.

Constants

tof.TOF_VL53LX: int

VL53L5CX or VL53L8CX TOF sensor (8x8 pixels).