:mod:`tof` --- time-of-flight sensor driver =========================================== .. module:: tof :synopsis: time-of-flight sensor driver The :mod:`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 :func:`snapshot` or composited onto a visible-light frame from the CSI sensor with :func:`draw_depth`, normally through a colour palette such as :data:`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 --------- .. function:: init(type:int=-1) -> None Initializes an onboard depth sensor. ``type`` indicates the type of TOF sensor: * `tof.TOF_VL53LX`: 8x8 pixels. By default ``type`` is ``-1`` which causes `tof.init()` to automatically scan and initialize an attached TOF sensor based on the I2C address. .. function:: reset() -> None Resets the depth sensor state. .. function:: deinit() -> None Deinitializes the depth sensor freeing up resources. .. function:: width() -> int Returns the width (horizontal resolution) of the depth sensor in-use. Raises a ``RuntimeError`` if the sensor is not initialized. .. function:: height() -> int Returns the height (vertical resolution) of the depth sensor in-use. Raises a ``RuntimeError`` if the sensor is not initialized. .. function:: type() -> int Returns the type of the depth sensor in-use: * `tof.TOF_VL53LX` Raises a ``RuntimeError`` if the sensor is not initialized. .. function:: refresh() -> int Returns the refresh rate (in Hz) of the depth sensor in-use: * `tof.TOF_VL53LX`: 15 Hz. Raises a ``RuntimeError`` if the sensor is not initialized. .. function:: 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. .. function:: draw_depth(image:image.Image, depth:List[float], x:int=0, y:int=0, x_scale:Optional[float]=None, y_scale:Optional[float]=None, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=255, color_palette:int=image.PALETTE_DEPTH, alpha_palette:Optional[int]=None, hint:int=0, scale:Optional[Tuple[float, float]]=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: * `image.AREA`: Use area scaling when downscaling. * `image.BILINEAR`: Use bilinear scaling. * `image.BICUBIC`: Use bicubic scaling. * `image.CENTER`: Center the image on the destination. * `image.HMIRROR`: Horizontally mirror. * `image.VFLIP`: Vertically flip. * `image.TRANSPOSE`: Transpose (swap x/y). * `image.EXTRACT_RGB_CHANNEL_FIRST`: Apply rgb_channel extraction before scaling. * `image.APPLY_COLOR_PALETTE_FIRST`: Apply color palette before scaling. * `image.SCALE_ASPECT_KEEP`: Fit inside the destination keeping aspect ratio. * `image.SCALE_ASPECT_EXPAND`: Fill the destination keeping aspect ratio (crops). * `image.SCALE_ASPECT_IGNORE`: Fill the destination ignoring aspect ratio (stretches). * `image.ROTATE_90`: Rotate by 90 degrees. * `image.ROTATE_180`: Rotate by 180 degrees. * `image.ROTATE_270`: Rotate by 270 degrees. ``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. .. function:: snapshot(hmirror:bool=False, vflip:bool=False, transpose:bool=False, x_scale:Optional[float]=None, y_scale:Optional[float]=None, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=255, color_palette:int=image.PALETTE_DEPTH, alpha_palette:Optional[int]=None, hint:int=0, scale:Optional[Tuple[float, float]]=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: * `image.AREA`: Use area scaling when downscaling. * `image.BILINEAR`: Use bilinear scaling. * `image.BICUBIC`: Use bicubic scaling. * `image.CENTER`: Center the image on the destination. * `image.HMIRROR`: Horizontally mirror. * `image.VFLIP`: Vertically flip. * `image.TRANSPOSE`: Transpose (swap x/y). * `image.EXTRACT_RGB_CHANNEL_FIRST`: Apply rgb_channel extraction before scaling. * `image.APPLY_COLOR_PALETTE_FIRST`: Apply color palette before scaling. * `image.SCALE_ASPECT_KEEP`: Fit inside the destination keeping aspect ratio. * `image.SCALE_ASPECT_EXPAND`: Fill the destination keeping aspect ratio (crops). * `image.SCALE_ASPECT_IGNORE`: Fill the destination ignoring aspect ratio (stretches). * `image.ROTATE_90`: Rotate by 90 degrees. * `image.ROTATE_180`: Rotate by 180 degrees. * `image.ROTATE_270`: Rotate by 270 degrees. ``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 --------- .. data:: TOF_VL53LX :type: int VL53L5CX or VL53L8CX TOF sensor (8x8 pixels).