diff --git a/docs/library/omv.image.rst b/docs/library/omv.image.rst index dfb10bf3d595a..9142565aabe7b 100644 --- a/docs/library/omv.image.rst +++ b/docs/library/omv.image.rst @@ -532,7 +532,7 @@ Methods class Line -- Line object ========================= -The line object is returned by ``image.find_lines`` or ``image.find_line_segments``. +The line object is returned by ``image.find_lines``, ``image.find_line_segments``, or ``image.get_regression``. .. method:: line.line() @@ -587,11 +587,99 @@ The line object is returned by ``image.find_lines`` or ``image.find_line_segment You may also get this value doing ``[8]`` on the object. +class Circle -- Circle object +============================= + +The circle object is returned by ``image.find_circles``. + +Methods +------- + +.. method:: circle.x() + + Returns the circle's x position. + + You may also get this value doing ``[0]`` on the object. + +.. method:: circle.y() + + Returns the circle's y position. + + You may also get this value doing ``[1]`` on the object. + +.. method:: circle.r() + + Returns the circle's radius. + + You may also get this value doing ``[2]`` on the object. + +.. method:: circle.magnitude() + + 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``. + +Methods +------- + +.. method:: rect.corners() + + 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. + +.. method:: rect.rect() + + Returns a rectangle tuple (x, y, w, h) for use with other ``image`` methods + like ``image.draw_rectangle`` of the rect's bounding box. + +.. method:: rect.x() + + Returns the rectangle's top left corner's x position. + + You may also get this value doing ``[0]`` on the object. + +.. method:: rect.y() + + Returns the rectangle's top left corner's y position. + + You may also get this value doing ``[1]`` on the object. + +.. method:: rect.w() + + Returns the rectangle's width. + + You may also get this value doing ``[2]`` on the object. + +.. method:: rect.h() + + Returns the rectangle's height. + + You may also get this value doing ``[3]`` on the object. + +.. method:: rect.magnitude() + + 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``. +Methods +------- + +.. method:: qrcode.corners() + + 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. + .. method:: qrcode.rect() Returns a rectangle tuple (x, y, w, h) for use with other ``image`` methods @@ -686,6 +774,14 @@ class AprilTag -- AprilTag object The apriltag object is returned by ``image.find_apriltags``. +Methods +------- + +.. method:: apriltag.corners() + + 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. + .. method:: apriltag.rect() Returns a rectangle tuple (x, y, w, h) for use with other ``image`` methods @@ -860,6 +956,14 @@ class DataMatrix -- DataMatrix object The datamatrix object is returned by ``image.find_datamatrices``. +Methods +------- + +.. method:: datamatrix.corners() + + 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. + .. method:: datamatrix.rect() Returns a rectangle tuple (x, y, w, h) for use with other ``image`` methods @@ -930,6 +1034,14 @@ class BarCode -- BarCode object The barcode object is returned by ``image.find_barcodes``. +Methods +------- + +.. method:: barcode.corners() + + 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. + .. method:: barcode.rect() Returns a rectangle tuple (x, y, w, h) for use with other ``image`` methods @@ -1008,6 +1120,9 @@ class kptmatch -- Keypoint Object The kptmatch object is returned by ``image.match_descriptor`` for keypoint matches. +Methods +------- + .. method:: kptmatch.rect() Returns a rectangle tuple (x, y, w, h) for use with other ``image`` methods @@ -1061,6 +1176,77 @@ The kptmatch object is returned by ``image.match_descriptor`` for keypoint match You may also get this value doing ``[7]`` on the object. +class ImageWriter -- ImageWriter object +======================================= + +The ImageWriter object allows you to write uncompressed images to disk quickly. + +Constructors +------------ + +.. class:: image.ImageWriter(path) + + Creates an ImageWriter object which allow you to write uncompressed images + to disk in a simple file format for OpenMV Cams. The uncompressed images + may then read back in using the ImageReader class. + +Methods +------- + +.. method:: imagewriter.size() + + Returns the size of the file being written to. + +.. method:: imagewriter.add_frame(img) + + Writes an image to disk. Since the image is uncompressed this executes + quickly but uses up a large amount of disk space. + +.. method:: imagewriter.close() + + Closes the image stream file. You must close files or they become corrupted. + +class ImageReader -- ImageReader object +======================================= + +The ImageReader object allows you to read uncompressed images from disk quickly. + +Constructors +------------ + +.. class:: image.ImageReader(path) + + Creates an ImageReader object that plays back image data written by an + ImageWriter object. The frames played back by the ImageWriter object will + be played back at the same FPS as they were written to disk at. + +Methods +------- + +.. method:: imagereader.size() + + Returns the size of the file being read. + +.. method:: imagereader.next_frame([copy_to_fb=True, loop=True]) + + Returns an image object from the file written by ImageWriter. If + ``copy_to_fb`` is True then the image object will be directly loaded into + the frame buffer. Otherwise, the image object will be placed in the heap. + Note that unless the image is small the heap likely doesn't have enough + space to store the image object. If ``loop`` is True then after the last + image from the stream is read playback will start from the beginning again. + Otherwise, this method will return None after all frames have been read. + + Note that next_frame() tries to limit playback speed by pausing after + reading frames to match the speed frames were recorded at. Otherwise this + method would zoom through all images at 200+ FPS. + +.. method:: imagereader.close() + + Closes the file being read. You should do this before destroying the + imagereader object. However, since the file is being only read it will + not be corrupted if it is not closed... + class Image -- Image object =========================== @@ -1705,7 +1891,72 @@ Methods ``roi``, ``bin_count``, and etc. are keyword arguments which must be explicitly invoked in the function call by writing ``roi=``, etc. -.. method:: image.find_blobs(thresholds, roi=Auto, x_stride=2, y_stride=1, invert=False, area_threshold=10, pixels_threshold=10, merge=False, margin=0, threshold_cb=None, merge_cb=None) +.. method:: image.get_linear_regression(thresholds, [roi=Auto, x_stride=2, y_stride=1, invert=False, robust=False]) + + Computes a linear regression on all the thresholded pixels in the image. The + linear regression is computed using least-squares normally which is fast but + cannot handle any outliers. If ``robust`` is True then the Theil–Sen linear + regression is used instead which computes the median of all slopes between + all thresholded pixels in the image. This is an N^2 operation which may drops + your FPS down to below 5 even on an 80x60 image if too many pixels are set + after thresholding. However, as long as the number of pixels set after + thresholding remains low the linear regression will be valid even in the case + of up to 30% of the thresholded pixels being outliers (e.g. it's robust). + + This method returns a ``line`` object. See this blog post on how to use the + line object easily: https://openmv.io/blogs/news/linear-regression-line-following + + ``thresholds`` must be a list of tuples + ``[(lo, hi), (lo, hi), ..., (lo, hi)]`` defining the ranges of color you + want to track. You may pass up to 16 threshold tuples in one + ``image.find_blobs`` call. For grayscale images each tuple needs to contain + two values - a min grayscale value and a max grayscale value. Only pixel + regions that fall between these thresholds will be considered. For RGB565 + images each tuple needs to have six values (l_lo, l_hi, a_lo, a_hi, b_lo, + b_hi) - which are minimums and maximums for the LAB L, A, and B channels + respectively. For easy usage this function will automatically fix swapped + min and max values. Additionally, if a tuple is larger than six values the + rest are ignored. Conversely, if the tuple is too short the rest of the + thresholds are assumed to be zero. + + .. note:: + + To get the thresholds for the object you want to track just select (click + and drag) on the object you want to track in the IDE frame buffer. The + histogram will then update to just be in that area. Then just write down + where the color distribution starts and falls off in each histogram channel. + These will be your low and high values for ``thresholds``. It's best to + manually determine the thresholds versus using the upper and lower + quartile statistics because they are too tight. + + The latest version of OpenMV IDE features a threshold editor to help make + picking thresholds easer. It lets you control the threshold with sliders + so you can see what the thresholds are segmenting. + + ``roi`` is the region-of-interest rectangle tuple (x, y, w, h). If not + specified, it is equal to the image rectangle. Only pixels within the + ``roi`` are operated on. + + ``x_stride`` is the number of x pixels to skip when searching for a blob. + Once a blob is found the line fill algorithm will be pixel accurate. + Increase ``x_stride`` to speed up finding blobs if blobs are know to be large. + + ``y_stride`` is the number of y pixels to skip when searching for a blob. + Once a blob is found the line fill algorithm will be pixel accurate. + Increase ``y_stride`` to speed up finding blobs if blobs are know to be large. + + ``invert`` inverts the thresholding operation such that instead of matching + pixels inside of some known color bounds pixels are matched that are outside + of the known color bounds. + + Not supported on compressed images. + + .. note:: + + All the arguments except ``thresholds`` are keyword arguments and must + be explicitly invoked with their name and an equal sign. + +.. method:: image.find_blobs(thresholds, [roi=Auto, x_stride=2, y_stride=1, invert=False, area_threshold=10, pixels_threshold=10, merge=False, margin=0, threshold_cb=None, merge_cb=None]) Finds all blobs (connected pixel regions that pass a threshold test) in the image and returns a list of ``blob`` objects which describe each blob. @@ -1878,6 +2129,71 @@ Methods All the arguments are keyword arguments and must be explicitly invoked with their name and an equal sign. +.. method:: image.find_circles([roi=Auto, x_stride=2, y_stride=1, threshold=1600, x_margin=10, y_margin=10, r_margin=10]) + + Finds circles in the image using the hough transform. Returns a list of + ``circle`` objects (see above). + + ``roi`` is the region-of-interest rectangle tuple (x, y, w, h). If not + specified, it is equal to the image rectangle. Only pixels within the + ``roi`` are operated on. + + ``x_stride`` is the number of x pixels to skip when doing the hough transform. + Only increase this if circles you are searching for are large and bulky. + + ``y_stride`` is the number of y pixels to skip when doing the hough transform. + Only increase this if circles you are searching for are large and bulky. + + ``threshold`` controls what circles are detected from the hough transform. Only + circles with a magnitude greater than or equal to ``threshold`` are returned. The + right value of ``threshold`` for your application is image dependent. Note that + the magnitude of a circle is the sum of all sobel filter magnitudes of pixels + that make up that circle. + + ``x_margin`` controls the merging of detected circles. Circles which are + ``x_margin``, ``y_margin``, and ``r_margin`` pixels apart are merged. + + ``y_margin`` controls the merging of detected circles. Circles which are + ``x_margin``, ``y_margin``, and ``r_margin`` pixels apart are merged. + + ``r_margin`` controls the merging of detected circles. Circles which are + ``x_margin``, ``y_margin``, and ``r_margin`` pixels apart are merged. + + .. note:: + + All the arguments are keyword arguments and must be explicitly invoked + with their name and an equal sign. + + .. note:: + + This method is only for the OpenMV Cam M7. + +.. method:: image.find_rects([roi=Auto, threshold=10000]) + + Find rectangles in the image using the quad detection algorithm used to find + apriltags. Works best of rectangles that have good contrast against their + background. The apriltag quad detection algorithm can handle + any scale/rotation/shear on rectangles. Returns a list of ``rect`` objects + (see above). + + ``roi`` is the region-of-interest rectangle tuple (x, y, w, h). If not + specified, it is equal to the image rectangle. Only pixels within the + ``roi`` are operated on. + + Rectangles which have an edge magnitude (which is computed by sliding the + sobel operator across all pixels on the edges of the rectangle and summing + the value) less than ``threshold`` are filtered out of the returned list. + The correct value of ``threshold`` is depended on your application/scene. + + .. note:: + + All the arguments are keyword arguments and must be explicitly invoked + with their name and an equal sign. + + .. note:: + + This method is only for the OpenMV Cam M7. + .. method:: image.find_qrcodes(roi=Auto) Finds all qrcodes within the ``roi`` and returns a list of ``qrcode`` diff --git a/docs/library/omv.sensor.rst b/docs/library/omv.sensor.rst index ea30e36500f67..456ef4e14932b 100644 --- a/docs/library/omv.sensor.rst +++ b/docs/library/omv.sensor.rst @@ -27,6 +27,12 @@ Functions Initializes the camera sensor. +.. function:: sensor.flush() + + Copies whatever was in the frame buffer to the IDE. You should call this + method to display the last image your OpenMV Cam takes if it's not running + a script with an infinite loop. + .. function:: sensor.snapshot(line_filter=None) Takes a picture using the camera and returns an ``image`` object. @@ -75,6 +81,14 @@ Functions If both are specified this method skips ``n`` number of frames but will timeout after ``time`` milliseconds. +.. function:: sensor.width() + + Returns the sensor resolution width. + +.. function:: sensor.height() + + Returns the sensor resolution height. + .. function:: sensor.get_fb() (Get Frame Buffer) Returns the image object returned by a previous call of