fir — thermal sensor driver (fir == far infrared)

The fir module is used for controlling the thermal sensors.

Example usage:

import sensor, fir

# Setup camera.
sensor.reset()
sensor.set_pixformat(sensor.RGB565)
sensor.set_framesize(sensor.QVGA)
sensor.skip_frames()
fir.init()

# Show image.
while(True):
    img = sensor.snapshot()
    ta, ir, to_min, to_max = fir.read_ir()
    fir.draw_ir(image, ir)
    print("====================")
    print("Ambient temperature: %0.2f" % ta)
    print("Min temperature seen: %0.2f" % to_min)
    print("Max temperature seen: %0.2f" % to_max)

Functions

fir.init

fir.init(type=-1, refresh: int | None = None, resolution: int | None = None) -> None

Initializes an attached thermopile shield using I/O pins P4 and P5 (and P0, P1, P2, P3 for fir.FIR_LEPTON)

type indicates the type of thermopile shield:

fir.FIR_NONE: 0 pixels.
fir.FIR_SHIELD: 16x4 pixels.
fir.FIR_MLX90621: 16x4 pixels.
fir.FIR_MLX90640: 32x24 pixels.
fir.FIR_MLX90641: 16x12 pixels.
fir.FIR_AMG8833: 8x8 pixels.
fir.FIR_LEPTON: 80x60 pixels (FLIR Lepton 1.x/2.x) or 160x120 pixels (FLIR Lepton 3.x)

By default type is -1 which will cause fir.init() to automatically scan and initialize an attached thermal sensor based on the I2C address. Note that fir.FIR_MLX90640 and fir.FIR_MLX90641 have the same I2C address so you must pass fir.FIR_MLX90641 to type to initialize it specifically.

fir.FIR_LEPTON on the OpenMV Cam Pure Thermal this uses internal I/O pins and does not use P0-P5.

refresh is the thermopile sensor power-of-2 refresh rate in Hz:

fir.FIR_NONE: N/A
fir.FIR_SHIELD: Defaults to 64 Hz. Can be 1 Hz, 2 Hz, 4 Hz, 8 Hz, 16 Hz, 32 Hz, 64 Hz, 128 Hz, 256 Hz, or 512 Hz. Note that a higher refresh rate lowers the accuracy and vice-versa.
fir.FIR_MLX90621: Defaults to 64 Hz. Can be 1 Hz, 2 Hz, 4 Hz, 8 Hz, 16 Hz, 32 Hz, 64 Hz, 128 Hz, 256 Hz, or 512 Hz. Note that a higher refresh rate lowers the accuracy and vice-versa.
fir.FIR_MLX90640: Defaults to 32 Hz. Can be 1 Hz, 2 Hz, 4 Hz, 8 Hz, 16 Hz, 32 Hz, or 64 Hz. Note that a higher refresh rate lowers the accuracy and vice-versa.
fir.FIR_MLX90641: Defaults to 32 Hz. Can be 1 Hz, 2 Hz, 4 Hz, 8 Hz, 16 Hz, 32 Hz, or 64 Hz. Note that a higher refresh rate lowers the accuracy and vice-versa.
fir.FIR_AMG8833: 10 Hz
fir.FIR_LEPTON: 9 Hz (really 8.7 Hz).

resolution is the thermopile sensor measurement resolution:

fir.FIR_NONE: N/A
fir.FIR_SHIELD: Defaults to 18-bits. Can be 15-bits, 16-bits, 17-bits, or 18-bits. Note that a higher resolution lowers the maximum temperature range and vice-versa.
fir.FIR_MLX90621: Defaults to 18-bits. Can be 15-bits, 16-bits, 17-bits, or 18-bits. Note that a higher resolution lowers the maximum temperature range and vice-versa.
fir.FIR_MLX90640: Defaults to 19-bits. Can be 16-bits, 17-bits, 18-bits, or 19-bits. Note that a higher resolution lowers the maximum temperature range and vice-versa.
fir.FIR_MLX90641: Defaults to 19-bits. Can be 16-bits, 17-bits, 18-bits, or 19-bits. Note that a higher resolution lowers the maximum temperature range and vice-versa.
fir.FIR_AMG8833: 12-bits.
fir.FIR_LEPTON: 14-bits.

For the fir.FIR_SHIELD and fir.FIR_MLX90621:

15-bits -> Max of ~950C.
16-bits -> Max of ~750C.
17-bits -> Max of ~600C.
18-bits -> Max of ~450C.

For the fir.FIR_MLX90640 and fir.FIR_MLX90641:

16-bits -> Max of ~750C.
17-bits -> Max of ~600C.
18-bits -> Max of ~450C.
19-bits -> Max of ~300C.

For the fir.FIR_AMG8833:

Max of ~80C.

For the fir.FIR_LEPTON:

Max of ~140C (can be up to 400C-450C in low-gain mode).

Note

For fir.FIR_LEPTON mode this driver implements triple buffering to receive the FLIR Lepton image. This uses 28.125 KB of RAM for the FLIR Lepton 1.x/2.x and 112.5 KB of RAM for the FLIR Lepton 3.x. Triple buffering ensures that reading an image with fir.read_ir() and fir.snapshot() never block. For all other sensors the I2C bus is accessed to read the image.

fir.deinit

fir.deinit() -> None

Deinitializes the thermal sensor freeing up resources.

fir.width

fir.width() -> int

Returns the width (horizontal resolution) of the thermal sensor in-use:

fir.FIR_NONE: 0 pixels.
fir.FIR_SHIELD: 16 pixels.
fir.FIR_MLX90621: 16 pixels.
fir.FIR_MLX90640: 32 pixels.
fir.FIR_MLX90641: 16 pixels.
fir.FIR_AMG8833: 8 pixels.
fir.FIR_LEPTON: 80 pixels (FLIR Lepton 1.x/2.x) or 160 pixels (FLIR Lepton 3.x).

fir.height

fir.height() -> int

Returns the height (vertical resolution) of the thermal sensor in-use:

fir.FIR_NONE: 0 pixels.
fir.FIR_SHIELD: 4 pixels.
fir.FIR_MLX90621: 4 pixels.
fir.FIR_MLX90640: 24 pixels.
fir.FIR_MLX90641: 12 pixels.
fir.FIR_AMG8833: 8 pixels.
fir.FIR_LEPTON: 60 pixels (FLIR Lepton 1.x/2.x) or 120 pixels (FLIR Lepton 3.x).

fir.type

fir.type() -> int

Returns the type of the thermal sensor in-use:

fir.FIR_NONE
fir.FIR_SHIELD
fir.FIR_MLX90621
fir.FIR_MLX90640
fir.FIR_MLX90641
fir.FIR_AMG8833
fir.FIR_LEPTON

fir.refresh

fir.refresh() -> int

Returns the current refresh rate set during fir.init() call.

fir.resolution

fir.resolution() -> int

Returns the current resolution set during the fir.init() call.

fir.radiometric

fir.radiometric() -> bool

Returns if the thermal sensor reports accurate temperature readings (True or False). If False this means that the thermal sensor reports relative temperature readings based on its ambient temperature which may not be very accurate.

fir.register_vsync_cb

fir.register_vsync_cb(cb) -> None

For the fir.FIR_LEPTON mode only on the OpenMV Cam Pure Thermal.

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

This nomially triggers at 9 Hz.

cb takes no arguments.

fir.register_frame_cb

fir.register_frame_cb(cb) -> None

For the fir.FIR_LEPTON mode only on the OpenMV Cam Pure Thermal.

Registers callback cb to be executed (in interrupt context) whenever the FLIR Lepton generates a new frame and the frame is ready to be read via fir.read_ir() or fir.snapshot().

This nomially triggers at 9 Hz.

cb takes no arguments.

Use this to get an interrupt to schedule reading a frame later with micropython.schedule().

fir.get_frame_available

fir.get_frame_available() -> bool

Returns True if a frame is available to read by calling fir.read_ir() or fir.snapshot().

fir.trigger_ffc

fir.trigger_ffc(timeout=-1) -> None

For the fir.FIR_LEPTON mode only.

Triggers the Flat-Field-Correction process on your FLIR Lepton which calibrates the thermal image. This process happens automatically with the sensor. However, you may call this function to force the process to happen.

timeout if not -1 then how many milliseconds to wait for FFC to complete.

fir.read_ta

fir.read_ta() -> float

Returns the ambient temperature (i.e. sensor temperature).

Example:

ta = fir.read_ta()

The value returned is a float that represents the temperature in celsius.

fir.read_ir

fir.read_ir(hmirror=False, vflip=False, transpose=False, timeout=-1)

Returns a tuple containing the ambient temperature (i.e. sensor temperature), the temperature list (width * height), the minimum temperature seen, and the maximum temperature seen.

hmirror if set to True horizontally mirrors the ir array.

vflip if set to True vertically flips the ir array.

transpose if set to True transposes the ir array.

timeout if not -1 then how many milliseconds to wait for the new frame.

If you want to rotate an image by multiples of 90 degrees pass the following:

* 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

Example:

ta, ir, to_min, to_max = fir.read_ir()

The values returned are floats that represent the temperature in celsius.

Note

ir is a (width * height) list of floats (4-bytes each).

fir.draw_ir

fir.draw_ir(image: image.Image, ir, x: int | None = None, y: int | None = None, x_scale=1.0, y_scale=1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel=-1, alpha=128, color_palette=image.PALETTE_RAINBOW, alpha_palette=-1, hint=0, scale=Optional[Tuple[float, float]]) -> None

Draws an ir array on image whose top-left corner starts at location x, y. This method automatically handles rendering the image passed into the correct pixel format for the destination image while also handling clipping seamlessly.

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. Note that if y_scale is not specified then it will match x_scale to maintain the 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. Note that if x_scale is not specified then it will match x_scale to maintain the aspect ratio.

roi is the region-of-interest rectangle tuple (x, y, w, h) of the source image to draw. This allows you to extract just the pixels in the ROI to scale and draw on the destination image.

rgb_channel is the RGB channel (0=R, G=1, B=2) to extract from an RGB565 image (if passed) and to render onto the destination image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and draw that in grayscale on the destination image.

alpha controls how much of the source image to blend into the destination image. A value of 256 draws an opaque source image while a value lower than 256 produces a blend between the source and destination image. 0 results in no modification to the destination image.

color_palette if not -1 can be image.PALETTE_RAINBOW, image.PALETTE_IRONBOW, or a 256 pixel in total RGB565 image to use as a color lookup table on the grayscale value of whatever the source image is. This is applied after rgb_channel extraction if used.

alpha_palette if not -1 can be a 256 pixel in total GRAYSCALE image to use as a alpha palette which modulates the alpha value of the source image being drawn at a pixel pixel level allowing you to precisely control the alpha value of pixels based on their grayscale value. A pixel value of 255 in the alpha lookup table is opaque which anything less than 255 becomes more transparent until 0. This is applied after rgb_channel extraction if used.

hint can be a logical OR of the flags:

image.AREA: Use area scaling when downscaling versus the default of nearest neighbor.
image.BILINEAR: Use bilinear scaling versus the default of nearest neighbor scaling.
image.BICUBIC: Use bicubic scaling versus the default of nearest neighbor scaling.
image.CENTER: Center the image being drawn on the display. This is applied after scaling.
image.HMIRROR: Horizontally mirror the image.
image.VFLIP: Vertically flip the image.
image.TRANSPOSE: Transpose the image (swap x/y).
image.EXTRACT_RGB_CHANNEL_FIRST: Do rgb_channel extraction before scaling.
image.APPLY_COLOR_PALETTE_FIRST: Apply color palette before scaling.
image.SCALE_ASPECT_KEEP: Scale the image being drawn to fit inside the display.
image.SCALE_ASPECT_EXPAND: Scale the image being drawn to fill the display (results in cropping)
image.SCALE_ASPECT_IGNORE: Scale the image being drawn to fill the display (results in stretching).
image.ROTATE_90: Rotate the image by 90 degrees (this is just VFLIP | TRANSPOSE).
image.ROTATE_180: Rotate the image by 180 degrees (this is just HMIRROR | VFLIP).
image.ROTATE_270: Rotate the image by 270 degrees (this is just HMIRROR | TRANSPOSE).

scale is a two value tuple which controls the min and max temperature (in celsius) to scale the ir image. By default it’s equal to the image ir min and ir max.

If x/y are not specified the image will be centered in the field of view. If x_scale/y_scale or x_size/y_size are not specified the ir array will be scaled to fit on the image.

Note

To handle a transposed ir array read_ir remembers if it was called with transposed True. This is then passed to draw_ir internally. However, you may pass a 3-value tuple (w, h, ir) as the ir array instead to use draw_ir to draw any floating point array with width w and height h.

fir.snapshot

fir.snapshot(hmirror=False, vflip=False, transpose=False, x_scale=1.0, y_scale=1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel=-1, alpha=128, color_palette=image.PALETTE_RAINBOW, alpha_palette=None, hint=0, scale: Tuple[float, float] | None = None, pixformat=image.RGB565, copy_to_fb=False, timeout=-1) -> image.Image

Works like sensor.snapshot() and returns an image object that is either image.GRAYSCALE (grayscale) or image.RGB565 (color). If copy_to_fb is False then the new image is allocated on the MicroPython heap. However, the MicroPython heap is limited and may not have space to store the new image if exhausted. Instead, set copy_to_fb to True to set the frame buffer to the new image making this function work just like sensor.snapshot().

hmirror if set to True horizontally mirrors the new image.

vflip if set to True vertically flips the new image.

transpose if set to True transposes the new image.

If you want to rotate an image by multiples of 90 degrees pass the following:

* 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

roi is the region-of-interest rectangle tuple (x, y, w, h) of the source image to draw. This allows you to extract just the pixels in the ROI to scale and draw on the destination image.

hint can be a logical OR of the flags:

image.AREA: Use area scaling when downscaling versus the default of nearest neighbor.
image.BILINEAR: Use bilinear scaling versus the default of nearest neighbor scaling.
image.BICUBIC: Use bicubic scaling versus the default of nearest neighbor scaling.
image.CENTER: Center the image being drawn on the display. This is applied after scaling.
image.HMIRROR: Horizontally mirror the image.
image.VFLIP: Vertically flip the image.
image.TRANSPOSE: Transpose the image (swap x/y).
image.EXTRACT_RGB_CHANNEL_FIRST: Do rgb_channel extraction before scaling.
image.APPLY_COLOR_PALETTE_FIRST: Apply color palette before scaling.
image.SCALE_ASPECT_KEEP: Scale the image being drawn to fit inside the display.
image.SCALE_ASPECT_EXPAND: Scale the image being drawn to fill the display (results in cropping)
image.SCALE_ASPECT_IGNORE: Scale the image being drawn to fill the display (results in stretching).
image.ROTATE_90: Rotate the image by 90 degrees (this is just VFLIP | TRANSPOSE).
image.ROTATE_180: Rotate the image by 180 degrees (this is just HMIRROR | VFLIP).
image.ROTATE_270: Rotate the image by 270 degrees (this is just HMIRROR | TRANSPOSE).

scale is a two value tuple which controls the min and max temperature (in celsius) to scale the ir image. By default it’s equal to the image ir min and ir max.

pixformat if specified controls the final image pixel format.

timeout if not -1 then how many milliseconds to wait for the new frame.

Returns an image object.