`image` — machine vision¶

The image module is used for machine vision.

Functions¶

image.binary_to_grayscale(binary_image_value: 0 | 1) → int¶: Returns a converted binary value (0-1) to a grayscale value (0-255).

image.binary_to_rgb(binary_image_value: 0 | 1) → Tuple[int, int, int]¶: Returns a converted binary value (0-1) to a 3 value RGB888 tuple.

image.binary_to_lab(binary_image_value: 0 | 1) → Tuple[int, int, int]¶

Returns a converted binary value (0-1) to a 3 value LAB tuple.

L goes between 0 and 100 and A/B go from -128 to 128.

image.binary_to_yuv(binary_image_value: 0 | 1) → Tuple[int, int, int]¶

Returns a converted binary value (0-1) to a 3 value YUV tuple.

Y goes between 0 and 255 and U/V go from -128 to 128.

image.grayscale_to_binary(grayscale_value: int) → 0 | 1¶: Returns a converted grayscale value (0-255) to a binary value (0-1).

image.grayscale_to_rgb(grayscale_value: int) → Tuple[int, int, int]¶: Returns a converted grayscale value to a 3 value RGB888 tuple.

Note

The OpenMV Cam firmware does the conversion using a RGB565->RGB888 process so this method won’t return the exact values as a pure RGB888 system would. However, it’s true to how the image lib works internally.

image.grayscale_to_lab(grayscale_value: int) → Tuple[int, int, int]¶

Returns a converted grayscale value to a 3 value LAB tuple.

L goes between 0 and 100 and A/B go from -128 to 128.

Note

The OpenMV Cam firmware does the conversion using a RGB565->LAB process so this method won’t return the exact values as a pure LAB system would. However, it’s true to how the image lib works internally.

image.grayscale_to_yuv(grayscale_value: int) → Tuple[int, int, int]¶

Returns a converted grayscale value to a 3 value YUV tuple.

Y goes between 0 and 255 and U/V go from -128 to 128.

Note

The OpenMV Cam firmware does the conversion using a RGB565->YUV process so this method won’t return the exact values as a pure YUV system would. However, it’s true to how the image lib works internally.

image.rgb_to_binary(rgb_tuple: Tuple[int, int, int]) → 0 | 1¶: Returns a converted 3 value RGB888 tuple to a center range thresholded binary value (0-1).

Note

The OpenMV Cam firmware does the conversion using a RGB888->RGB565 process so this method won’t return the exact values as a pure RGB888 system would. However, it’s true to how the image lib works internally.

image.rgb_to_grayscale(rgb_tuple: Tuple[int, int, int]) → int¶: Returns a converted 3 value RGB888 tuple to a grayscale value (0-255).

Note

The OpenMV Cam firmware does the conversion using a RGB888->RGB565 process so this method won’t return the exact values as a pure RGB888 system would. However, it’s true to how the image lib works internally.

image.rgb_to_lab(rgb_tuple: Tuple[int, int, int]) → Tuple[int, int, int]¶

Returns a converted 3 value RGB888 tuple to a 3 value LAB tuple.

L goes between 0 and 100 and A/B go from -128 to 128.

Note

The OpenMV Cam firmware does the conversion using a RGB888->RGB565 process so this method won’t return the exact values as a pure RGB888 system would. However, it’s true to how the image lib works internally.

image.rgb_to_yuv(rgb_tuple: Tuple[int, int, int]) → Tuple[int, int, int]¶

Returns a converted 3 value RGB888 tuple to a 3 value YUV tuple.

Y goes between 0 and 255 and U/V go from -128 to 128.

Note

The OpenMV Cam firmware does the conversion using a RGB888->RGB565 process so this method won’t return the exact values as a pure RGB888 system would. However, it’s true to how the image lib works internally.

image.lab_to_binary(lab_tuple: Tuple[int, int, int]) → 0 | 1¶: Returns a converted 3 value LAB tuple to a center range thresholded binary value (0-1).

Note

The OpenMV Cam firmware does the conversion using a LAB->RGB565 process so this method won’t return the exact values as a pure LAB system would. However, it’s true to how the image lib works internally.

image.lab_to_grayscale(lab_tuple: Tuple[int, int, int]) → int¶: Returns a converted 3 value LAB tuple to a grayscale value (0-255).

Note

The OpenMV Cam firmware does the conversion using a LAB->RGB565 process so this method won’t return the exact values as a pure LAB system would. However, it’s true to how the image lib works internally.

image.lab_to_rgb(lab_tuple: Tuple[int, int, int]) → Tuple[int, int, int]¶: Returns a converted 3 value LAB tuple to a 3 value RGB888 tuple.

Note

The OpenMV Cam firmware does the conversion using a LAB->RGB565 process so this method won’t return the exact values as a pure LAB system would. However, it’s true to how the image lib works internally.

image.lab_to_yuv(lab_tuple: Tuple[int, int, int]) → Tuple[int, int, int]¶

Returns a converted 3 value LAB tuple to a 3 value YUV tuple.

Y goes between 0 and 255 and U/V go from -128 to 128.

Note

The OpenMV Cam firmware does the conversion using a LAB->RGB565 process so this method won’t return the exact values as a pure LAB system would. However, it’s true to how the image lib works internally.

image.yuv_to_binary(yuv_tuple: Tuple[int, int, int]) → 0 | 1¶: Returns a converted 3 value YUV tuple to a center range thresholded binary value (0-1).

Note

The OpenMV Cam firmware does the conversion using a YUV->RGB565 process so this method won’t return the exact values as a pure YUV system would. However, it’s true to how the image lib works internally.

image.yuv_to_grayscale(yuv_tuple: Tuple[int, int, int]) → int¶: Returns a converted 3 value YUV tuple to a grayscale value (0-255).

Note

The OpenMV Cam firmware does the conversion using a YUV->RGB565 process so this method won’t return the exact values as a pure YUV system would. However, it’s true to how the image lib works internally.

image.yuv_to_rgb(lab_tuple: Tuple[int, int, int]) → Tuple[int, int, int]¶: Returns a converted 3 value YUV tuple to a 3 value RGB888 tuple.

Note

The OpenMV Cam firmware does the conversion using a YUV->RGB565 process so this method won’t return the exact values as a pure YUV system would. However, it’s true to how the image lib works internally.

image.yuv_to_lab(yuv_tuple: Tuple[int, int, int]) → Tuple[int, int, int]¶

Returns a converted 3 value YUV tuple to a 3 value LAB tuple.

L goes between 0 and 100 and A/B go from -128 to 128.

Note

The OpenMV Cam firmware does the conversion using a YUV->RGB565 process so this method won’t return the exact values as a pure YUV system would. However, it’s true to how the image lib works internally.

image.load_decriptor(path: str)¶

Loads a descriptor object from disk.

path is the path to the descriptor file to load.

image.save_descriptor(path: str, descriptor)¶

Saves the descriptor object descriptor to disk.

path is the path to the descriptor file to save.

image.match_descriptor(descritor0, descriptor1, threshold=70, filter_outliers=False)¶

For LBP descriptors this function returns an integer representing the difference between the two descriptors. You may then threshold/compare this distance metric as necessary. The distance is a measure of similarity. The closer it is to zero the better the LBP keypoint match.

For ORB descriptors this function returns the kptmatch object. See above.

threshold is used for ORB keypoints to filter ambiguous matches. A lower threshold value tightens the keypoint matching algorithm. threshold may be between 0-100 (int). Defaults to 70.

filter_outliers is used for ORB keypoints to filter out outlier keypoints allow you to raise the threshold. Defaults to False.

class HaarCascade – Feature Descriptor¶

The Haar Cascade feature descriptor is used for the Image.find_features() method. It doesn’t have any methods itself for you to call.

class image.HaarCascade(path: str, stages: int | None = None)¶

Loads a Haar Cascade into memory from a Haar Cascade binary file formatted for your OpenMV Cam. If you pass “frontalface” instead of a path then this constructor will load the built-in frontal face Haar Cascade into memory. Additionally, you can also pass “eye” to load a Haar Cascade for eyes into memory. Finally, this method returns the loaded Haar Cascade object for use with Image.find_features().

stages defaults to the number of stages in the Haar Cascade. However, you can specify a lower number of stages to speed up processing the feature detector at the cost of a higher rate of false positives.

Note

You can make your own Haar Cascades to use with your OpenMV Cam. First, Google for “<thing> Haar Cascade” to see if someone already made an OpenCV Haar Cascade for an object you want to detect. If not… then you’ll have to generate your own (which is a lot of work). See here for how to make your own Haar Cascade. Then see this script for converting OpenCV Haar Cascades into a format your OpenMV Cam can read.

Q: What is a Haar Cascade?

A: A Haar Cascade is a series of contrast checks that are used to determine if an object is present in the image. The contrast checks are split of into stages where a stage is only run if previous stages have already passed. The contrast checks are simple things like checking if the center vertical of the image is lighter than the edges. Large area checks are performed first in the earlier stages followed by more numerous and smaller area checks in later stages.

Q: How are Haar Cascades made?

A: Haar Cascades are made by training the generator algorithm against positive and negative labeled images. For example, you’d train the generator algorithm against hundreds of pictures with cats in them that have been labeled as images with cats and against hundreds of images with not cat like things labeled differently. The generator algorithm will then produce a Haar Cascade that detects cats.

class Similarity – Similarity Object¶

The similarity object is returned by Image.get_similarity().

class image.Similarity¶

Please call Image.get_similarity() to create this object.

mean() → float¶

Returns the mean of the similarity values computed across the image (float).

You may also get this value doing [0] on the object.

stdev() → float¶

Returns the standard deviation of the similarity values computed across the image ( (float).

You may also get this value doing [1] on the object.

min() → float¶

Returns the min of the similarity values computed across the image ( (float).

Generally, for the SSIM you want to threshold the min value to determine if two images are different.

You may also get this value doing [2] on the object.

max() → float¶

Returns the max of the similarity values computed across the image ( (float).

Generally, for the DSIM you want to threshold the max value to determine if two images are different.

You may also get this value doing [3] on the object.

class Histogram – Histogram Object¶

The histogram object is returned by Image.get_histogram().

Grayscale histograms have one channel with some number of bins. All bins are normalized so that all bins sum to 1.

RGB565 histograms have three channels with some number of bins each. All bins are normalized so that all bins in a channel sum to 1.

class image.histogram¶

Please call Image.get_histogram() to create this object.

bins() → List[float]¶

Returns a list of floats for the grayscale histogram.

You may also get this value doing [0] on the object.

l_bins() → List[float]¶

Returns a list of floats for the RGB565 histogram LAB L channel.

You may also get this value doing [0] on the object.

a_bins() → List[float]¶

Returns a list of floats for the RGB565 histogram LAB A channel.

You may also get this value doing [1] on the object.

b_bins() → List[float]¶

Returns a list of floats for the RGB565 histogram LAB B channel.

You may also get this value doing [2] on the object.

get_percentile(percentile) → percentile¶: Computes the CDF of the histogram channels and returns a image.percentile object with the values of the histogram at the passed in percentile (0.0 - 1.0) (float). So, if you pass in 0.1 this method will tell you (going from left-to-right in the histogram) what bin when summed into an accumulator caused the accumulator to cross 0.1. This is useful to determine min (with 0.1) and max (with 0.9) of a color distribution without outlier effects ruining your results for adaptive color tracking.

get_threshold() → threshold¶: Uses Otsu’s Method to compute the optimal threshold values that split the histogram into two halves for each channel of the histogram. This method returns a image.threshold object. This method is particularly useful for determining optimal Image.binary() thresholds.

get_statistics() → statistics¶

Computes the mean, median, mode, standard deviation, min, max, lower quartile, and upper quartile of each color channel in the histogram and returns a statistics object.

You may also use histogram.statistics() and histogram.get_stats() as aliases for this method.

class Percentile – Percentile Object¶

The percentile object is returned by histogram.get_percentile().

Grayscale percentiles have one channel. Use the non l_*, a_*, and b_* method.

RGB565 percentiles have three channels. Use the l_*, a_*, and b_* methods.

class image.percentile¶

Please call histogram.get_percentile() to create this object.

value() → int¶

Return the grayscale percentile value (between 0 and 255).

You may also get this value doing [0] on the object.

l_value() → int¶

Return the RGB565 LAB L channel percentile value (between 0 and 100).

You may also get this value doing [0] on the object.

a_value() → int¶

Return the RGB565 LAB A channel percentile value (between -128 and 127).

You may also get this value doing [1] on the object.

b_value() → int¶

Return the RGB565 LAB B channel percentile value (between -128 and 127).

You may also get this value doing [2] on the object.

class Threshold – Threshold Object¶

The threshold object is returned by histogram.get_threshold().

Grayscale thresholds have one channel. Use the non l_*, a_*, and b_* method.

RGB565 thresholds have three channels. Use the l_*, a_*, and b_* methods.

class image.threshold¶

Please call histogram.get_threshold() to create this object.

value() → int¶

Return the grayscale threshold value (between 0 and 255).

You may also get this value doing [0] on the object.

l_value() → int¶

Return the RGB565 LAB L channel threshold value (between 0 and 100).

You may also get this value doing [0] on the object.

a_value() → int¶

Return the RGB565 LAB A channel threshold value (between -128 and 127).

You may also get this value doing [1] on the object.

b_value() → int¶

Return the RGB565 LAB B channel threshold value (between -128 and 127).

You may also get this value doing [2] on the object.

class Statistics – Statistics Object¶

The percentile object is returned by histogram.get_statistics() or Image.get_statistics().

Grayscale statistics have one channel. Use the non l_*, a_*, and b_* method.

RGB565 statistics have three channels. Use the l_*, a_*, and b_* methods.

class image.statistics¶

Please call histogram.get_statistics() or Image.get_statistics() to create this object.

mean() → int¶

Returns the grayscale mean (0-255) (int).

You may also get this value doing [0] on the object.

median() → int¶

Returns the grayscale median (0-255) (int).

You may also get this value doing [1] on the object.

mode() → int¶

Returns the grayscale mode (0-255) (int).

You may also get this value doing [2] on the object.

stdev() → int¶

Returns the grayscale standard deviation (0-255) (int).

You may also get this value doing [3] on the object.

min() → int¶

Returns the grayscale min (0-255) (int).

You may also get this value doing [4] on the object.

max() → int¶

Returns the grayscale max (0-255) (int).

You may also get this value doing [5] on the object.

lq() → int¶

Returns the grayscale lower quartile (0-255) (int).

You may also get this value doing [6] on the object.

uq() → int¶

Returns the grayscale upper quartile (0-255) (int).

You may also get this value doing [7] on the object.

l_mean() → int¶

Returns the RGB565 LAB L mean (0-255) (int).

You may also get this value doing [0] on the object.

l_median() → int¶

Returns the RGB565 LAB L median (0-255) (int).

You may also get this value doing [1] on the object.

l_mode() → int¶

Returns the RGB565 LAB L mode (0-255) (int).

You may also get this value doing [2] on the object.

l_stdev() → int¶

Returns the RGB565 LAB L standard deviation (0-255) (int).

You may also get this value doing [3] on the object.

l_min() → int¶

Returns the RGB565 LAB L min (0-255) (int).

You may also get this value doing [4] on the object.

l_max() → int¶

Returns the RGB565 LAB L max (0-255) (int).

You may also get this value doing [5] on the object.

l_lq() → int¶

Returns the RGB565 LAB L lower quartile (0-255) (int).

You may also get this value doing [6] on the object.

l_uq() → int¶

Returns the RGB565 LAB L upper quartile (0-255) (int).

You may also get this value doing [7] on the object.

a_mean() → int¶

Returns the RGB565 LAB A mean (0-255) (int).

You may also get this value doing [8] on the object.

a_median() → int¶

Returns the RGB565 LAB A median (0-255) (int).

You may also get this value doing [9] on the object.

a_mode() → int¶

Returns the RGB565 LAB A mode (0-255) (int).

You may also get this value doing [10] on the object.

a_stdev() → int¶

Returns the RGB565 LAB A standard deviation (0-255) (int).

You may also get this value doing [11] on the object.

a_min() → int¶

Returns the RGB565 LAB A min (0-255) (int).

You may also get this value doing [12] on the object.

a_max() → int¶

Returns the RGB565 LAB A max (0-255) (int).

You may also get this value doing [13] on the object.

a_lq() → int¶

Returns the RGB565 LAB A lower quartile (0-255) (int).

You may also get this value doing [14] on the object.

a_uq() → int¶

Returns the RGB565 LAB A upper quartile (0-255) (int).

You may also get this value doing [15] on the object.

b_mean() → int¶

Returns the RGB565 LAB B mean (0-255) (int).

You may also get this value doing [16] on the object.

b_median() → int¶

Returns the RGB565 LAB B median (0-255) (int).

You may also get this value doing [17] on the object.

b_mode() → int¶

Returns the RGB565 LAB B mode (0-255) (int).

You may also get this value doing [18] on the object.

b_stdev() → int¶

Returns the RGB565 LAB B standard deviation (0-255) (int).

You may also get this value doing [19] on the object.

b_min() → int¶

Returns the RGB565 LAB B min (0-255) (int).

You may also get this value doing [20] on the object.

b_max() → int¶

Returns the RGB565 LAB B max (0-255) (int).

You may also get this value doing [21] on the object.

b_lq() → int¶

Returns the RGB565 LAB B lower quartile (0-255) (int).

You may also get this value doing [22] on the object.

b_uq() → int¶

Returns the RGB565 LAB B upper quartile (0-255) (int).

You may also get this value doing [23] on the object.

class Blob – Blob object¶

The blob object is returned by Image.find_blobs().

class image.blob¶

Please call Image.find_blobs() to create this object.

corners() → List[Tuple[int, int]]¶: Returns a list of 4 (x,y) tuples of the 4 corners of the object. Corners are always returned in sorted clock-wise order starting from the top left.

min_corners() → List[Tuple[int, int]]¶: Returns a list of 4 (x,y) tuples of the 4 corners than bound the min area rectangle of the blob. Unlike blob.corners() the min area rectangle corners do not necessarily lie on the blob.

rect() → Tuple[int, int, int, int]¶: Returns a rectangle tuple (x, y, w, h) for use with other image methods like Image.draw_rectangle() of the blob’s bounding box.

x() → int¶

Returns the blob’s bounding box x coordinate (int).

You may also get this value doing [0] on the object.

y() → int¶

Returns the blob’s bounding box y coordinate (int).

You may also get this value doing [1] on the object.

w() → int¶

Returns the blob’s bounding box w coordinate (int).

You may also get this value doing [2] on the object.

h() → int¶

Returns the blob’s bounding box h coordinate (int).

You may also get this value doing [3] on the object.

pixels() → int¶

Returns the number of pixels that are part of this blob (int).

You may also get this value doing [4] on the object.

cx() → int¶

Returns the centroid x position of the blob (int).

You may also get this value doing [5] on the object.

cxf() → int¶: Returns the centroid x position of the blob (float).

cy() → int¶

Returns the centroid y position of the blob (int).

You may also get this value doing [6] on the object.

cyf() → int¶: Returns the centroid y position of the blob (float).

rotation() → float¶

Returns the rotation of the blob in radians (float). If the blob is like a pencil or pen this value will be unique for 0-180 degrees. If the blob is round this value is not useful.

You may also get this value doing [7] on the object.

rotation_deg() → float¶: Returns the rotation of the blob in degrees.

rotation_rad() → float¶: Returns the rotation of the blob in radians. This method is more descriptive than just blob.rotation().

code() → int¶

Returns a 32-bit binary number with a bit set in it for each color threshold that’s part of this blob. For example, if you passed Image.find_blobs() three color thresholds to look for then bits 0/1/2 may be set for this blob. Note that only one bit will be set for each blob unless Image.find_blobs() was called with merge=True. Then its possible for multiple blobs with different color thresholds to be merged together. You can use this method along with multiple thresholds to implement color code tracking.

You may also get this value doing [8] on the object.

count() → int¶

Returns the number of blobs merged into this blob. This is 1 unless you called Image.find_blobs() with merge=True.

You may also get this value doing [9] on the object.

perimeter() → int¶: Returns the number of pixels on this blob’s perimeter.

roundness() → float¶: Returns a value between 0 and 1 representing how round the object is. A circle would be a 1.

elongation() → float¶: Returns a value between 0 and 1 representing how long (not round) the object is. A line would be a 1.

area() → int¶: Returns the area of the bounding box around the blob. (w * h).

density() → float¶: Returns the density ratio of the blob. This is the number of pixels in the blob over its bounding box area. A low density ratio means in general that the lock on the object isn’t very good. The result is between 0 and 1.

extent() → float¶: Alias for blob.density().

compactness() → float¶: Like blob.density(), but, uses the perimeter of the blob instead to measure the objects density and is thus more accurate. The result is between 0 and 1.

solidity() → float¶: Like blob.density() but, uses the minimum area rotated rectangle versus the bounding rectangle to measure density. The result is between 0 and 1.

convexity() → float¶: Returns a value between 0 and 1 representing how convex the object is. A square would be 1.

x_hist_bins() → List[float]¶: Returns a histogram of the x axis of all columns in a blob. Bin values are scaled between 0 and 1.

y_hist_bins() → List[float]¶: Returns a histogram of the y axis of all the rows in a blob. Bin values are scaled between 0 and 1.

major_axis_line() → Tuple[int, int, int, int]¶: Returns a line tuple (x1, y1, x2, y2) that can be drawn with Image.draw_line() of the major axis of the blob (the line going through the longest side of the min area rectangle).

minor_axis_line() → Tuple[int, int, int, int]¶: Returns a line tuple (x1, y1, x2, y2) that can be drawn with Image.draw_line() of the minor axis of the blob (the line going through the shortest side of the min area rectangle).

enclosing_circle() → Tuple[int, int, int]¶: Returns a circle tuple (x, y, r) that can be drawn with Image.draw_circle() of the circle that encloses the min area rectangle of a blob.

enclosed_ellipse() → Tuple[int, int, int, int, float]¶: Returns an ellipse tuple (x, y, rx, ry, rotation) that can be drawn with Image.draw_ellipse() of the ellipse that fits inside of the min area rectangle of a blob.

class Line – Line object¶

The line object is returned by Image.find_lines(), Image.find_line_segments(), or Image.get_regression().

class image.line¶

Please call Image.find_lines(), Image.find_line_segments(), or Image.get_regression() to create this object.

line() → Tuple[int, int, int, int]¶: Returns a line tuple (x1, y1, x2, y2) for use with other image methods like Image.draw_line().

x1() → int¶

Returns the line’s p1 x component.

You may also get this value doing [0] on the object.

y1() → int¶

Returns the line’s p1 y component.

You may also get this value doing [1] on the object.

x2() → int¶

Returns the line’s p2 x component.

You may also get this value doing [2] on the object.

y2() → int¶

Returns the line’s p2 y component.

You may also get this value doing [3] on the object.

length() → int¶

Returns the line’s length: sqrt(((x2-x1)^2) + ((y2-y1)^2).

You may also get this value doing [4] on the object.

magnitude() → int¶

Returns the magnitude of the line from the hough transform.

You may also get this value doing [5] on the object.

theta() → int¶

Returns the angle of the line from the hough transform - (0 - 179) degrees.

You may also get this value doing [7] on the object.

rho() → int¶

Returns the the rho value for the line from the hough transform.

You may also get this value doing [8] on the object.

class Circle – Circle object¶

The circle object is returned by Image.find_circles().

class image.circle¶

Please call Image.find_circles() to create this object.

x() → int¶

Returns the circle’s x position.

You may also get this value doing [0] on the object.

y() → int¶

Returns the circle’s y position.

You may also get this value doing [1] on the object.

r() → int¶

Returns the circle’s radius.

You may also get this value doing [2] on the object.

magnitude() → int¶

Returns the circle’s magnitude.

You may also get this value doing [3] on the object.

class Rect – Rectangle Object¶

The rect object is returned by Image.find_rects().

class image.rect¶

Please call Image.find_rects() to create this object.

corners() → List[Tuple[int, int]]¶: Returns a list of 4 (x,y) tuples of the 4 corners of the object. Corners are always returned in sorted clock-wise order starting from the top left.

rect() → Tuple[int, int, int, int]¶: Returns a rectangle tuple (x, y, w, h) for use with other image methods like Image.draw_rectangle() of the rect’s bounding box.

x() → int¶

Returns the rectangle’s top left corner’s x position.

You may also get this value doing [0] on the object.

y() → int¶

Returns the rectangle’s top left corner’s y position.

You may also get this value doing [1] on the object.

w() → int¶

Returns the rectangle’s width.

You may also get this value doing [2] on the object.

h() → int¶

Returns the rectangle’s height.

You may also get this value doing [3] on the object.

magnitude() → int¶

Returns the rectangle’s magnitude.

You may also get this value doing [4] on the object.

class QRCode – QRCode object¶

The qrcode object is returned by Image.find_qrcodes().

class image.qrcode¶

Please call Image.find_qrcodes() to create this object.

corners() → List[Tuple[int, int]]¶: Returns a list of 4 (x,y) tuples of the 4 corners of the object. Corners are always returned in sorted clock-wise order starting from the top left.

rect() → Tuple[int, int, int, int]¶: Returns a rectangle tuple (x, y, w, h) for use with other image methods like Image.draw_rectangle() of the qrcode’s bounding box.

x() → int¶

Returns the qrcode’s bounding box x coordinate (int).

You may also get this value doing [0] on the object.

y() → int¶

Returns the qrcode’s bounding box y coordinate (int).

You may also get this value doing [1] on the object.

w() → int¶

Returns the qrcode’s bounding box w coordinate (int).

You may also get this value doing [2] on the object.

h() → int¶

Returns the qrcode’s bounding box h coordinate (int).

You may also get this value doing [3] on the object.

payload() → str¶

Returns the payload string of the qrcode. E.g. the URL.

You may also get this value doing [4] on the object.

version() → int¶

Returns the version number of the qrcode (int).

You may also get this value doing [5] on the object.

ecc_level() → int¶

Returns the ecc_level of the qrcode (int).

You may also get this value doing [6] on the object.

mask() → int¶

Returns the mask of the qrcode (int).

You may also get this value doing [7] on the object.

data_type() → int¶

Returns the data type of the qrcode (int).

You may also get this value doing [8] on the object.

eci() → int¶

Returns the eci of the qrcode (int). The eci stores the encoding of data bytes in the QR Code. If you plan to handling QR Codes that contain more than just standard ASCII text you will need to look at this value.

You may also get this value doing [9] on the object.

is_numeric() → bool¶: Returns True if the data_type of the qrcode is numeric.

is_alphanumeric() → bool¶: Returns True if the data_type of the qrcode is alpha numeric.

is_binary() → bool¶: Returns True if the data_type of the qrcode is binary. If you are serious about handling all types of text you need to check the eci if this is True to determine the text encoding of the data. Usually, it’s just standard ASCII, but, it could be UTF8 that has some 2-byte characters in it.

is_kanji() → bool¶: Returns True if the data_type of the qrcode is alpha Kanji. If this is True then you’ll need to decode the string yourself as Kanji symbols are 10-bits per character and MicroPython has no support to parse this kind of text. The payload in this case must be treated as just a large byte array.

class AprilTag – AprilTag object¶

The apriltag object is returned by Image.find_apriltags().

class image.apriltag¶

Please call Image.find_apriltags() to create this object.

Attributes¶

corners: List[Tuple[int, int]]¶: Returns a list of 4 (x,y) tuples of the 4 corners of the object. Corners are always returned in sorted clock-wise order starting from the top left.

rect: Tuple[int, int, int, int]¶: Returns a rectangle tuple (x, y, w, h) for use with other image methods like Image.draw_rectangle() of the apriltag’s bounding box.

x: int¶: Returns the apriltag’s bounding box x coordinate (int).

y: int¶: Returns the apriltag’s bounding box y coordinate (int).

w: int¶: Returns the apriltag’s bounding box w coordinate (int).

h: int¶: Returns the apriltag’s bounding box h coordinate (int).

area: int¶: Returns the area (w * h) of the apriltag (int).

id: int¶

Returns the numeric id of the apriltag.

family: int¶

Returns the numeric family of the apriltag.

name: str¶

Returns the family of the apriltag.

cx: int¶: Returns the centroid x position of the apriltag (int).

cxf: float¶: Returns the centroid x position of the apriltag (float).

cy: int¶: Returns the centroid y position of the apriltag (int).

cyf: float¶: Returns the centroid y position of the apriltag (float).

rotation: float¶: Returns the rotation of the apriltag in radians (float).

decision_margin: float¶: Returns the quality of the apriltag match (0.0 - 1.0) where 1.0 is the best.

hamming: int¶

Returns the number of accepted bit errors for this tag.

goodness: float¶: Returns the quality of the apriltag image (0.0 - 1.0) where 1.0 is the best.

Note

This value is always 0.0 for now. We may enable a feature called “tag refinement” in the future which will allow detection of small apriltags. However, this feature currently drops the frame rate to less than 1 FPS.

x_translation: float¶

Returns the translation in unknown units from the camera in the X direction.

This method is useful for determining the apriltag’s location away from the camera. However, the size of the apriltag, the lens you are using, etc. all come into play as to actually determining what the X units are in. For ease of use we recommend you use a lookup table to convert the output of this method to something useful for your application.

Note that this is the left-to-right direction.

y_translation: float¶

Returns the translation in unknown units from the camera in the Y direction.

This method is useful for determining the apriltag’s location away from the camera. However, the size of the apriltag, the lens you are using, etc. all come into play as to actually determining what the Y units are in. For ease of use we recommend you use a lookup table to convert the output of this method to something useful for your application.

Note that this is the up-to-down direction.

z_translation: float¶

Returns the translation in unknown units from the camera in the Z direction.

This method is useful for determining the apriltag’s location away from the camera. However, the size of the apriltag, the lens you are using, etc. all come into play as to actually determining what the Z units are in. For ease of use we recommend you use a lookup table to convert the output of this method to something useful for your application.

Note that this is the front-to-back direction.

x_rotation: float¶: Returns the rotation in radians of the apriltag in the X plane. E.g. moving the camera left-to-right while looking at the tag.

y_rotation: float¶: Returns the rotation in radians of the apriltag in the Y plane. E.g. moving the camera up-to-down while looking at the tag.

z_rotation: float¶

Returns the rotation in radians of the apriltag in the Z plane. E.g. rotating the camera while looking directly at the tag.

Note that this is just a renamed version of apriltag.rotation.

class DataMatrix – DataMatrix object¶

The datamatrix object is returned by Image.find_datamatrices().

class image.datamatrix¶

Please call Image.find_datamatrices() to create this object.

corners() → List[Tuple[int, int]]¶: Returns a list of 4 (x,y) tuples of the 4 corners of the object. Corners are always returned in sorted clock-wise order starting from the top left.

rect() → Tuple[int, int, int, int]¶: Returns a rectangle tuple (x, y, w, h) for use with other image methods like Image.draw_rectangle() of the datamatrix’s bounding box.

x() → int¶

Returns the datamatrix’s bounding box x coordinate (int).

You may also get this value doing [0] on the object.

y() → int¶

Returns the datamatrix’s bounding box y coordinate (int).

You may also get this value doing [1] on the object.

w() → int¶

Returns the datamatrix’s bounding box w coordinate (int).

You may also get this value doing [2] on the object.

h() → int¶

Returns the datamatrix’s bounding box h coordinate (int).

You may also get this value doing [3] on the object.

payload() → str¶

Returns the payload string of the datamatrix. E.g. The string.

You may also get this value doing [4] on the object.

rotation() → float¶

Returns the rotation of the datamatrix in radians (float).

You may also get this value doing [5] on the object.

rows() → int¶

Returns the number of rows in the data matrix (int).

You may also get this value doing [6] on the object.

columns() → int¶

Returns the number of columns in the data matrix (int).

You may also get this value doing [7] on the object.

capacity() → int¶

Returns how many characters could fit in this data matrix.

You may also get this value doing [8] on the object.

padding() → int¶

Returns how many unused characters are in this data matrix.

You may also get this value doing [9] on the object.

class BarCode – BarCode object¶

The barcode object is returned by Image.find_barcodes().

class image.barcode¶

Please call Image.find_barcodes() to create this object.

corners() → List[Tuple[int, int]]¶: Returns a list of 4 (x,y) tuples of the 4 corners of the object. Corners are always returned in sorted clock-wise order starting from the top left.

rect() → Tuple[int, int, int, int]¶: Returns a rectangle tuple (x, y, w, h) for use with other image methods like Image.draw_rectangle() of the barcode’s bounding box.

x() → int¶

Returns the barcode’s bounding box x coordinate (int).

You may also get this value doing [0] on the object.

y() → int¶

Returns the barcode’s bounding box y coordinate (int).

You may also get this value doing [1] on the object.

w() → int¶

Returns the barcode’s bounding box w coordinate (int).

You may also get this value doing [2] on the object.

h() → int¶

Returns the barcode’s bounding box h coordinate (int).

You may also get this value doing [3] on the object.

payload() → str¶

Returns the payload string of the barcode. E.g. The number.

You may also get this value doing [4] on the object.

type() → int¶

Returns the type enumeration of the barcode (int).

You may also get this value doing [5] on the object.

rotation() → float¶

Returns the rotation of the barcode in radians (float).

You may also get this value doing [6] on the object.

quality() → int¶

Returns the number of times this barcode was detected in the image (int).

When scanning a barcode each new scanline can decode the same barcode. This value increments for a barcode each time that happens…

You may also get this value doing [7] on the object.

class Displacement – Displacement object¶

The displacement object is returned by Image.find_displacement().

class image.displacement¶

Please call Image.find_displacement() to create this object.

x_translation() → float¶

Returns the x translation in pixels between two images. This is sub pixel accurate so it’s a float.

You may also get this value doing [0] on the object.

y_translation() → float¶

Returns the y translation in pixels between two images. This is sub pixel accurate so it’s a float.

You may also get this value doing [1] on the object.

rotation() → float¶

Returns the rotation in radians between two images.

You may also get this value doing [2] on the object.

scale() → float¶

Returns the scale change between two images.

You may also get this value doing [3] on the object.

response() → float¶

Returns the quality of the results of displacement matching between two images. Between 0-1. A displacement object with a response less than 0.1 is likely noise.

You may also get this value doing [4] on the object.

class kptmatch – Keypoint Object¶

The kptmatch object is returned by image.match_descriptor() for keypoint matches.

class image.kptmatch¶

Please call image.match_descriptor() to create this object.

rect() → Tuple[int, int, int, int]¶: Returns a rectangle tuple (x, y, w, h) for use with other image methods like Image.draw_rectangle() of the kptmatch’s bounding box.

cx() → int¶

Returns the centroid x position of the kptmatch (int).

You may also get this value doing [0] on the object.

cy() → int¶

Returns the centroid y position of the kptmatch (int).

You may also get this value doing [1] on the object.

x() → int¶

Returns the kptmatch’s bounding box x coordinate (int).

You may also get this value doing [2] on the object.

y() → int¶

Returns the kptmatch’s bounding box y coordinate (int).

You may also get this value doing [3] on the object.

w() → int¶

Returns the kptmatch’s bounding box w coordinate (int).

You may also get this value doing [4] on the object.

h() → int¶

Returns the kptmatch’s bounding box h coordinate (int).

You may also get this value doing [5] on the object.

count() → int¶

Returns the number of keypoints matched (int).

You may also get this value doing [6] on the object.

theta() → int¶

Returns the estimated angle of rotation for the keypoint (int).

You may also get this value doing [7] on the object.

match() → List[Tuple[int, int]]¶

Returns the list of (x,y) tuples of matching keypoints.

You may also get this value doing [8] on the object.

class ImageIO – ImageIO Object¶

The ImageIO object allows you to read/write OpenMV Image objects in their native form to disk or to memory. This class provides fast read/write random access for loading/storing images.

class image.ImageIO(path: str, mode)¶

Creates an ImageIO object.

If path is a file name on disk then that file will be opened for reading if mode is 'r' or writing if mode is 'w'.

path may also be a 3-value tuple (w, h, bpp) for in-memory storage of images. mode in this case is then the number of image buffers to store in memory. Note that the in-memory storage buffer is not allowed to grow in size after being allocated. Use a bpp value of 0 for binary images, 1 for grayscale images, and 2 for rgb565 images.

type() → int¶: Returns if the ImageIO object is a FILE_STREAM or MEMORY_STREAM.

is_closed() → bool¶: Returns if the ImageIO object is closed and can no longer be used.

count() → int¶: Returns the number of frames stored.

offset() → int¶: Returns the image index offset.

version() → int | None¶: Returns the version of the object if it’s FILE_STREAM. MEMORY_STREAM versions are none.

buffer_size() → int¶

Returns the size allocated by the object for a frame in a single buffer.

buffer_size() * count() == size()

size() → int¶: Returns the number of bytes on disk or memory used by the ImageIO object.

write(img: Image) → ImageIO¶

Writes a new image img to the ImageIO object. For on disk ImageIO objects the file will grow as new images are added. For in-memory ImageIO objects this just writes an image to the current pre-allocated slot before advancing to the next slot.

Returns the ImageIO object.

read(copy_to_fb=True, loop=True, pause=True) → Image¶

Returns an image object from the ImageIO object. 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().

loop if True automatically causes the ImageIO object to seek to the beginning at the end of the stream of images.

pause if True causes this method to pause for a previously recorded number of milliseconds by write in-order to match the original frame rate that captured the image data.

seek(offset) → None¶

Seeks to the image slot number offset in the ImageIO object.

Works for on disk or in-memory objects.

sync() → None¶: Writes out all data pending for on-disk ImageIO objects.

close() → None¶: Closes the ImageIO object. For in-memory objects this free’s the allocated space and for on-disk files this closes the file and writes out all meta-data.

FILE_STREAM: int¶: ImageIO object was opened on a file.

MEMORY_STREAM: int¶: ImageIO object was opened in memory.

class Image – Image object¶

The image object is the basic object for machine vision operations.

class image.Image(arg, buffer: bytes | bytearray | memoryview | None = None, copy_to_fb: bool = False)¶

If arg is a string then this creates a new image object from a file at arg path. Supports loading bmp/pgm/ppm/jpg/jpeg/png image files from disk. If copy_to_fb is true the image is copied to the frame buffer verus being allocated on the heap.

If arg is an ndarray then this creates a new image object from the ndarray. ndarray objects with a shape of (w, h) are treated as grayscale images, (w, h, 3) are treated as RGB565 images. Only float32 point ndarrays are supported at this time. When creating an image this way if you pass a buffer argument it will be used to store the image data versus allocating space on the heap. If copy_to_fb is true the image is copied to the frame buffer verus being allocated on the heap or using the buffer.

If arg is an int it is then considered the width of a new image and a height value and a format value must follow to create a new blank image object. format can be be any image pixformat value like image.GRAYSCALE. The image will be initialized to all zeros. Note that a buffer value is expected for compressed image formats. buffer is considered as the source of image data for creating images this way. If used with copy_to_fb the data from buffer is copied to the frame buffer. If you’d like to create a JPEG image from a JPEG bytes() or bytearray() object you can pass the width, height, image.JPEG for the JPEG along with setting buffer to the JPEG byte stream to create a JPEG image.

Images support “[]” notation. Do image[index] = 8/16-bit value to assign an image pixel or image[index] to get an image pixel which will be either an 8-bit value for grayscale/bayer images of a 16-bit value for RGB565/YUV images. Binary images return a 1-bit value.

For JPEG images the “[]” allows you to access the compressed JPEG image blob as a byte-array. Reading and writing to the data array is opaque however as JPEG images are compressed byte streams.

Images also support read buffer operations. You can pass images to all sorts of MicroPython functions like as if the image were a byte-array object. In particular, if you’d like to transmit an image you can just pass it to the UART/SPI/I2C write functions to be transmitted automatically.

Basic Methods¶

width() → int¶: Returns the image width in pixels.

height() → int¶: Returns the image height in pixels.

format() → int¶: Returns image.GRAYSCALE for grayscale images, image.RGB565 for RGB565 images, image.BAYER for bayer pattern images, and image.JPEG for JPEG images.

size() → int¶: Returns the image size in bytes.

bytearray() → bytearray¶: Returns a bytearray object that points to the image data for byte-level read/write access.

Note

Image objects are automatically cast as bytes objects when passed to MicroPython driver that requires a bytes like object. This is read-only access. Call bytearray() to get read/write access.

get_pixel(x: int, y: int, rgbtuple: bool | None = None) → int | Tuple[int, int, int]¶

For grayscale images: Returns the grayscale pixel value at location (x, y). For RGB565 images: Returns the RGB888 pixel tuple (r, g, b) at location (x, y). For bayer pattern images: Returns the the pixel value at the location (x, y).

Returns None if x or y is outside of the image.

x and y may either be passed independently or as a tuple.

rgbtuple if True causes this method to return an RGB888 tuple. Otherwise, this method returns the integer value of the underlying pixel. I.e. for RGB565 images this method returns a RGB565 value. Defaults to True for RGB565 images and False otherwise.

Not supported on compressed images.

Note

Image.get_pixel() and Image.set_pixel() are the only methods that allow you to manipulate bayer pattern images. Bayer pattern images are literal images where pixels in the image are R/G/R/G/etc. for even rows and G/B/G/B/etc. for odd rows. Each pixel is 8-bits. If you call this method with rgbtuple set then Image.get_pixel() will debayer the source image at that pixel location and return a valid RGB888 tuple for the pixel location.

set_pixel(x: int, y: int, pixel: int | Tuple[int, int, int]) → Image¶

For grayscale images: Sets the pixel at location (x, y) to the grayscale value pixel. For RGB565 images: Sets the pixel at location (x, y) to the RGB888 tuple (r, g, b) pixel. For bayer pattern images: Sets the pixel value at the location (x, y) to the value pixel.

Returns the image object so you can call another method using . notation.

x and y may either be passed independently or as a tuple.

pixel may either be an RGB888 tuple (r, g, b) or the underlying pixel value (i.e. a RGB565 value for RGB565 images or an 8-bit value for grayscale images.

Not supported on compressed images.

Note

Image.get_pixel() and Image.set_pixel() are the only methods that allow you to manipulate bayer pattern images. Bayer pattern images are literal images where pixels in the image are R/G/R/G/etc. for even rows and G/B/G/B/etc. for odd rows. Each pixel is 8-bits. If you call this method with an RGB888 tuple the grayscale value of that RGB888 tuple is extracted and set to the pixel location.

Conversion Methods¶

to_ndarray(dtype: str, buffer: bytes | bytearray | memoryview | None = None) → ndarray¶

Returns a ndarray object created from the image. This only works for GRAYSCALE or RGB565 images currently.

dtype can be b, B, or f for creating a signed 8-bit, unsigned 8-bit, or 32-bit floating point ndarray. GRAYSCALE images are directly converted to unsigned 8-bit ndarray objects. For signed 8-bit ndarray objects the values (0:255) are mapped to (-127:128). For float 32-bit ndarray objects the values are mapped to (0.0:255.0). RGB565 images are converted to 3-channel ndarray objects and the same process described above for GRAYSCALE images is applied to each channel depending on dtype. Note that dtype also accepts the integer values (e.g. ord()) of b, B, and f respectively.

buffer if not None is a bytearray object to use as the buffer for the ndarray. If None a new buffer is allocated on the heap to store the ndarray image data. You can use the buffer argument to directly allocate the ndarray in a pre-allocated buffer saving a heap allocation and a copy operation.

The ndarray returned has the shape of (height, width) for GRAYSCALE images and (height, width, 3) for RGB565 images.

to_bitmap(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False) → Image¶

Converts an image to a bitmap image (1 bit per pixel).

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

Note

Bitmap images are like grayscale images with only two pixels values - 0 and 1. Additionally, bitmap images are packed such that they only store 1 bit per pixel making them very small. The OpenMV image library allows bitmap images to be used in all places sensor.GRAYSCALE and sensor.RGB565 images can be used. However, many operations when applied on bitmap images don’t make any sense because bitmap images only have 2 values. OpenMV recommends using bitmap images for mask values in operations and such as they fit on the MicroPython heap quite easily. Finally, bitmap image pixel values 0 and 1 are interpreted as black and white when being applied to sensor.GRAYSCALE or sensor.RGB565 images. The library automatically handles conversion.

Returns the image object so you can call another method using . notation.

to_grayscale(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, copy: bool = False, copy_to_fb: bool = False) → Image¶

Converts an image to a grayscale image (8-bits per pixel).

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

Returns the image object so you can call another method using . notation.

to_rgb565(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False) → Image¶

Converts an image to an RGB565 image (16-bits per pixel).

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

Returns the image object so you can call another method using . notation.

to_rainbow(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=PALETTE_RAINBOW, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False) → Image¶

Converts an image to an RGB565 rainbow image (16-bits per pixel).

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

Returns the image object so you can call another method using . notation.

to_ironbow(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=PALETTE_IRONBOW, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False) → Image¶

Converts an image to an RGB565 ironbow image (16-bits per pixel).

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

Returns the image object so you can call another method using . notation.

to_jpeg(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False, quality: int = 90, encode_for_ide: bool = False, subsampling: int = 0) → Image¶

Converts an image to a JPEG image.

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

quality controls the jpeg image compression quality. The value can be between 0 and 100.

encode_for_ide if True the image is encoded in a way that the IDE can display it if printed by doing print(image). This is useful for debugging purposes over UARTs via Open Terminal in the IDE.

subsampling can be:

Returns the image object so you can call another method using . notation.

to_png(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False) → Image¶

Converts an image to a PNG image.

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

Returns the image object so you can call another method using . notation.

compress(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False, quality: int = 90, encode_for_ide: bool = False, subsampling: int = 0) → Image¶

Converts an image to a JPEG image.

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

quality controls the jpeg image compression quality. The value can be between 0 and 100.

encode_for_ide if True the image is encoded in a way that the IDE can display it if printed by doing print(image). This is useful for debugging purposes over UARTs via Open Terminal in the IDE.

subsampling can be:

Returns the image object so you can call another method using . notation.

Note

Image.compress is an alias for Image.to_jpeg.

copy(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, hint: int = 0, copy_to_fb: float = False) → Image¶

Creates a deep copy of the image object.

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy_to_fb if True the image is loaded directly into the frame buffer. This has no special effect if the image is already in the frame buffer.

Returns the image object so you can call another method using . notation.

crop(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False) → Image¶

Modifies an image in-place without changing the underlying image type.

x_scale controls how much the 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 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 image to extract. 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 apply onto the final image. For example, if you pass rgb_channel=1 this will extract the green channel of the source RGB565 image and apply that in grayscale on the final image.

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

color_palette if not None 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 image is. This is applied after rgb_channel extraction if used.

alpha_palette if not None 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:

copy if True create a deep-copy on the heap of the image that’s been converted versus converting the original image in-place.

copy_to_fb if True the image is loaded directly into the frame buffer. copy_to_fb has priority over copy. This has no special effect if the image is already in the frame buffer.

Returns the image object so you can call another method using . notation.

scale(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 256, color_palette=None, alpha_palette=None, hint: int = 0, copy: bool = False, copy_to_fb: bool = False) → Image¶