diff --git a/docs/library/network.WINC.rst b/docs/library/network.WINC.rst index 06008dff81340..cd6e88b29d83f 100644 --- a/docs/library/network.WINC.rst +++ b/docs/library/network.WINC.rst @@ -96,13 +96,13 @@ Constructors .. method:: connected_sta() - This method returns a list containing the connected client's IP adress. + This method returns a list containing the connected client's IP address. .. method:: wait_for_sta(timeout) This method blocks and waits for a client to connect. If timeout is 0 this will block forever. This method returns a list containing the - connected client's IP adress. + connected client's IP address. .. method:: ifconfig([ip_addr, subnet_addr, gateway_addr, dns_addr]) diff --git a/docs/library/omv.audio.rst b/docs/library/omv.audio.rst index 3c35b004ce69a..26cdf6b503669 100644 --- a/docs/library/omv.audio.rst +++ b/docs/library/omv.audio.rst @@ -25,7 +25,7 @@ Functions ``highpass`` is the high pass filter cut-off given the target sample frequency. This parameter is applicable for the Arduino Portenta H7 only. - ``samples`` is the number of samples to accumulate per callback. This is typically caluclated + ``samples`` is the number of samples to accumulate per callback. This is typically calculated based on the decimation factor and number of channels. If set to -1, the number of samples will be calculated automatically based on the decimation factor and number of channels. diff --git a/docs/library/omv.image.rst b/docs/library/omv.image.rst index 7b6d614d12d3b..440869e946f6d 100644 --- a/docs/library/omv.image.rst +++ b/docs/library/omv.image.rst @@ -1862,7 +1862,7 @@ The image object is the basic object for machine vision operations. 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 becuase bitmap images only have 2 values. OpenMV recommends + 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` @@ -2628,10 +2628,10 @@ The image object is the basic object for machine vision operations. image. You can pass greater than 0 integer or floating point values. ``x_spacing`` allows you to add (if positive) or subtract (if negative) x - pixels between cahracters. + pixels between characters. ``y_spacing`` allows you to add (if positive) or subtract (if negative) y - pixels between cahracters (for multi-line text). + pixels between characters (for multi-line text). ``mono_space`` defaults to True which forces text to be fixed spaced. For large text scales this looks terrible. Set the False to get non-fixed width @@ -2689,7 +2689,7 @@ The image object is the basic object for machine vision operations. .. method:: draw_edges(image:Image, corners, color:Optional[int,Tuple[int,int,int]]=None, size=0, thickness=1, fill=False) -> Image - Draws line edges between a corner list returned by methods like `blob.corners`. Coners is + Draws line edges between a corner list returned by methods like `blob.corners`. Corners is a four valued tuple of two valued x/y tuples. E.g. [(x1,y1),(x2,y2),(x3,y3),(x4,y4)]. ``color`` is an RGB888 tuple for Grayscale or RGB565 images. Defaults to @@ -2706,14 +2706,13 @@ The image object is the basic object for machine vision operations. Not supported on compressed images or bayer images. - .. method:: draw_image(image:Image, x:int, y:int, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0) -> Image + .. method:: draw_image(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - Draws an ``image`` whose top-left corner starts at location x, y. You may either pass x, y - separately or as a tuple (x, y). This method automatically handles rendering the image passed - into the correct pixel format for the destination image while also handling clipping seamlessly. - - You may also pass a path instead of an image object for this method to automatically load the image - from disk and use it in one step. E.g. ``draw_image("test.jpg")``. + Draws an ``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. ``image`` may also be a RGB888 tuple to draw a color instead + of an image. You may also pass a path instead of an image object for this method to automatically + load the image from disk and use it in one step. E.g. ``draw_image("test.jpg")``. ``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 @@ -2764,13 +2763,17 @@ The image object is the basic object for machine vision operations. * `image.ROTATE_270`: Rotate the image by 270 degrees (this is just HMIRROR | TRANSPOSE). * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + ``mask`` is another image to use as a pixel level mask for the operation. + Returns the image object so you can call another method using ``.`` notation. + Not supported on compressed images or bayer/yuv images. + .. method:: draw_keypoints(keypoints, color:Optional[int,Tuple[int,int,int]]=None, size=10, thickness=1, fill=False) -> Image Draws the keypoints of a keypoints object on the image. You may also pass a list of three value tuples containing the (x, y, rotation_angle_in_degrees) to - re-use this method for drawing keypoint glyphs which are a cirle with a line + reuse this method for drawing keypoint glyphs which are a circle with a line pointing in a particular direction. ``color`` is an RGB888 tuple for Grayscale or RGB565 images. Defaults to @@ -2909,7 +2912,7 @@ The image object is the basic object for machine vision operations. 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 becuase bitmap images only have 2 values. OpenMV recommends + 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` @@ -2931,177 +2934,453 @@ The image object is the basic object for machine vision operations. Not supported on compressed images or bayer/yuv images. - .. method:: b_and(image:Image, mask:Optional[Image]=None) -> Image + .. method:: b_and(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - Logically ANDs this image with another image. + Finds the logical ``AND`` of ``image`` and this image (e.g. ``a & b``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``b_and("test.jpg")``. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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. - ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. + ``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. - Returns the image object so you can call another method using ``.`` notation. + ``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. - Not supported on compressed images or bayer images. + ``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 ``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 source image is. This is applied after ``rgb_channel`` extraction if used. - .. method:: b_nand(image:Image, mask:Optional[Image]=None) -> Image + ``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. - Logically NANDs this image with another image. + ``hint`` can be a logical OR of the flags: - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. Returns the image object so you can call another method using ``.`` notation. - Not supported on compressed images or bayer images. + Not supported on compressed images or bayer/yuv images. - .. method:: b_or(image:Image, mask:Optional[Image]=None) -> Image + .. method:: b_nand(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - Logically ORs this image with another image. + Finds the logical ``NAND`` of ``image`` and this image (e.g. ``~(a & b)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``b_nand("test.jpg")``. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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. - ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. + ``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. - Returns the image object so you can call another method using ``.`` notation. + ``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. - Not supported on compressed images or bayer images. + ``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 ``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 source image is. This is applied after ``rgb_channel`` extraction if used. - .. method:: b_nor(image:Image, mask:Optional[Image]=None) -> Image + ``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. - Logically NORs this image with another image. + ``hint`` can be a logical OR of the flags: - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. Returns the image object so you can call another method using ``.`` notation. - Not supported on compressed images or bayer images. + Not supported on compressed images or bayer/yuv images. - .. method:: b_xor(image:Image, mask:Optional[Image]=None) -> Image + .. method:: b_or(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - Logically XORs this image with another image. + Finds the logical ``OR`` of ``image`` and this image (e.g. ``(a | b)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``b_or("test.jpg")``. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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. - ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. + ``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. - Returns the image object so you can call another method using ``.`` notation. + ``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. - Not supported on compressed images or bayer images. + ``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. - .. method:: b_xnor(image:Image, mask:Optional[Image]=None) -> 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. - Logically XNORs this image with another 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 source image is. This is applied after ``rgb_channel`` extraction if used. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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. - ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. + ``hint`` can be a logical OR of the flags: - Returns the image object so you can call another method using ``.`` notation. + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. - Not supported on compressed images or bayer images. + ``mask`` is another image to use as a pixel level mask for the operation. - ISP Methods - ~~~~~~~~~~~ + Returns the image object so you can call another method using ``.`` notation. - .. method:: awb(max:bool=False) -> Image + Not supported on compressed images or bayer/yuv images. - Performs automatic white balance on the image using the gray-world algorithm. This method - operates on RAW Bayer Images so that you can improve image quality before converting - to RGB565 or passing the RAW Bayer Image to an image processing funciton. You may also - call this on a RGB565. This method has no affect on binary/grayscale images. + .. method:: b_nor(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - ``max`` if True uses the white-patch algorithm instead. + Finds the logical ``NOR`` of ``image`` and this image (e.g. ``~(a | b)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``b_nor("test.jpg")``. - Returns the image object so you can call another method using ``.`` notation. + ``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. - Not supported on compressed or yuv images. + ``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. - .. method:: ccm(matrix) -> Image + ``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. - Multiples the passed floating-point color-correction-matrix with the image. Matrices may be in the form of:: + ``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. - [[rr, rg, rb], [gr, gg, gb], [br, bg, bb]] - [[rr, rg, rb], [gr, gg, gb], [br, bg, bb], [xx, xx, xx]] - [[rr, rg, rb, ro], [gr, gg, gb, go], [br, bg, bb, bo]] - [[rr, rg, rb, ro], [gr, gg, gb, go], [br, bg, bb, bo], [xx, xx, xx, xx]] + ``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. - [rr, rg, rb, ro, gr, gg, gb, go, br, bg, bb, bo] - [rr, rg, rb, ro, gr, gg, gb, go, br, bg, bb, bo, xx, xx, xx, xx] + ``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 source image is. This is applied after ``rgb_channel`` extraction if used. - The CCM Method does:: + ``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. - |R'| |R| |R'| |R| - |G'| = 3x3 Matrix * |G| or |G'| = 3x4 Matrix * |G| - |B'| |B| |B'| |B| - |1| + ``hint`` can be a logical OR of the flags: - Note that the sum of each row in the 3x3 matrix should generally be -1, +1, or 0. - Weights may either be positive or negative. + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. - You may want to use this method to eliminate systemic cross talk between color channels. - Or alternatively, to do color correction on the whole image. + ``mask`` is another image to use as a pixel level mask for the operation. Returns the image object so you can call another method using ``.`` notation. Not supported on compressed images or bayer/yuv images. - .. method:: gamma(gamma:float=1.0, contrast:float=1.0, brightness:float=0.0) -> Image + .. method:: b_xor(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - Quickly changes the image gamma, contrast, and brightness. + Finds the logical ``XOR`` of ``image`` and this image (e.g. ``(a ^ b)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``b_xor("test.jpg")``. - ``gamma`` with values greater than 1.0 makes the image darker in a non-linear - manner while less than 1.0 makes the image brighter. The gamma value is applied - to the image by scaling all pixel color channels to be between [0:1) and then - doing a remapping of ``pow(pixel, 1/gamma)`` on all pixels before scaling back. + ``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. - ``contrast`` with values greater than 1.0 makes the image brighter in a linear - manner while less than 1.0 makes the image darker. The contrast value is applied - to the image by scaling all pixel color channels to be between [0:1) and then - doing a remapping of ``pixel * contrast`` on all pixels before scaling back. + ``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. - ``brightness`` with values greater than 0.0 makes the image brighter in a constant - manner while less than 0.0 makes the image darker. The brightness value is applied - to the image by scaling all pixel color channels to be between [0:1) and then - doing a remapping of ``pixel + brightness`` on all pixels before scaling back. + ``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 ``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 source 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: + + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + + ``mask`` is another image to use as a pixel level mask for the operation. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed images or bayer/yuv images. + + .. method:: b_xnor(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image + + Finds the logical ``XNOR`` of ``image`` and this image (e.g. ``~(a ^ b)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``b_xnor("test.jpg")``. + + ``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 ``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 source 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: + + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + + ``mask`` is another image to use as a pixel level mask for the operation. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed images or bayer/yuv images. + + ISP Methods + ~~~~~~~~~~~ + + .. method:: awb(max:bool=False) -> Image + + Performs automatic white balance on the image using the gray-world algorithm. This method + operates on RAW Bayer Images so that you can improve image quality before converting + to RGB565 or passing the RAW Bayer Image to an image processing function. You may also + call this on a RGB565. This method has no affect on binary/grayscale images. + + ``max`` if True uses the white-patch algorithm instead. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed or yuv images. + + .. method:: ccm(matrix) -> Image + + Multiples the passed floating-point color-correction-matrix with the image. Matrices may be in the form of:: + + [[rr, rg, rb], [gr, gg, gb], [br, bg, bb]] + [[rr, rg, rb], [gr, gg, gb], [br, bg, bb], [xx, xx, xx]] + [[rr, rg, rb, ro], [gr, gg, gb, go], [br, bg, bb, bo]] + [[rr, rg, rb, ro], [gr, gg, gb, go], [br, bg, bb, bo], [xx, xx, xx, xx]] + + [rr, rg, rb, ro, gr, gg, gb, go, br, bg, bb, bo] + [rr, rg, rb, ro, gr, gg, gb, go, br, bg, bb, bo, xx, xx, xx, xx] + + The CCM Method does:: + + |R'| |R| |R'| |R| + |G'| = 3x3 Matrix * |G| or |G'| = 3x4 Matrix * |G| + |B'| |B| |B'| |B| + |1| + + Note that the sum of each row in the 3x3 matrix should generally be -1, +1, or 0. + Weights may either be positive or negative. + + You may want to use this method to eliminate systemic cross talk between color channels. + Or alternatively, to do color correction on the whole image. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed images or bayer/yuv images. + + .. method:: gamma(gamma:float=1.0, contrast:float=1.0, brightness:float=0.0) -> Image + + Quickly changes the image gamma, contrast, and brightness. + + ``gamma`` with values greater than 1.0 makes the image darker in a non-linear + manner while less than 1.0 makes the image brighter. The gamma value is applied + to the image by scaling all pixel color channels to be between [0:1) and then + doing a remapping of ``pow(pixel, 1/gamma)`` on all pixels before scaling back. + + ``contrast`` with values greater than 1.0 makes the image brighter in a linear + manner while less than 1.0 makes the image darker. The contrast value is applied + to the image by scaling all pixel color channels to be between [0:1) and then + doing a remapping of ``pixel * contrast`` on all pixels before scaling back. + + ``brightness`` with values greater than 0.0 makes the image brighter in a constant + manner while less than 0.0 makes the image darker. The brightness value is applied + to the image by scaling all pixel color channels to be between [0:1) and then + doing a remapping of ``pixel + brightness`` on all pixels before scaling back. Returns the image object so you can call another method using ``.`` notation. @@ -3153,169 +3432,657 @@ The image object is the basic object for machine vision operations. `Image.negate` is an alias for `Image.invert`. - .. method:: replace(image:Image, hmirror=False, vflip=False, transpose=False, mask:Optional[Image]=None) -> Image + .. method:: replace(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - Replaces all pixels in the image object with a new image. + Draws an ``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. ``image`` may also be a RGB888 tuple to draw a color instead + of an image. You may also pass a path instead of an image object for this method to automatically + load the image from disk and use it in one step. E.g. ``replace("test.jpg")``. + + ``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. - ``image`` can either be another image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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. - Set ``hmirror`` to True to horizontally mirror the replacing image. + ``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. - Set ``vflip`` to True to vertically flip the replacing 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. - Set ``transpose`` to True to flip the image along the diagonal (this changes - the image image width/height if the image is non-square). + ``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. - If you want to rotate an image by multiples of 90 degrees pass the following: + ``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 source image is. This is applied after ``rgb_channel`` extraction if used. - * 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 + ``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. - .. note:: + ``hint`` can be a logical OR of the flags: - If you don't pass an ``image`` this method will operate on the underlying - image that you were going to replace by applying the ``hmirror``, ``vflip``, - and ``transpose`` options to rotate the image around. E.g. if you want - to do ``img.replace(img, etc...)`` you just need to do ``img.replace(etc..)``. + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. Note that the mask is applied on the image before hmirror/vflip/transpose - so the mask should be the same width/height of the initial unmodifed image. Returns the image object so you can call another method using ``.`` notation. - Not supported on compressed images or bayer images. - - .. method:: assign(image:Image, hmirror=False, vflip=False, transpose=False, mask:Optional[Image]=None) -> Image - - Alias for `Image.replace`. - - .. method:: set(image:Image, hmirror=False, vflip=False, transpose=False, mask:Optional[Image]=None) -> Image - - Alias for `Image.replace`. - - .. method:: add(image:Image, mask:Optional[Image]=None) -> Image - - Adds an image pixel-wise to this one. - - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). - - ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. + Not supported on compressed images or bayer/yuv images. - Returns the image object so you can call another method using ``.`` notation. + .. note:: - Not supported on compressed images or bayer images. + `Image.replace` is an alias for `Image.draw_image`. - .. method:: sub(image:Image, reverse=False, mask:Optional[Image]=None) -> Image + .. method:: assign(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - Subtracts an image pixel-wise to this one. + Draws an ``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. ``image`` may also be a RGB888 tuple to draw a color instead + of an image. You may also pass a path instead of an image object for this method to automatically + load the image from disk and use it in one step. E.g. ``assign("test.jpg")``. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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. - Set ``reverse`` to True to reverse the subtraction operation from - ``this_image-image`` to ``image-this_image``. + ``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. - ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. + ``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. - Returns the image object so you can call another method using ``.`` notation. + ``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. - Not supported on compressed images or bayer images. + ``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. - .. method:: min(image:Image, mask:Optional[Image]=None) -> 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 source image is. This is applied after ``rgb_channel`` extraction if used. - Returns the minimum image of two images pixel-wise. + ``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. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``hint`` can be a logical OR of the flags: - ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + + ``mask`` is another image to use as a pixel level mask for the operation. Returns the image object so you can call another method using ``.`` notation. - Not supported on compressed images or bayer images. + Not supported on compressed images or bayer/yuv images. + + .. note:: + + `Image.assign` is an alias for `Image.draw_image`. + + .. method:: set(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image + + Draws an ``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. ``image`` may also be a RGB888 tuple to draw a color instead + of an image. You may also pass a path instead of an image object for this method to automatically + load the image from disk and use it in one step. E.g. ``set("test.jpg")``. + + ``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. - .. method:: max(image:Image, mask:Optional[Image]=None) -> 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 source image is. This is applied after ``rgb_channel`` extraction if used. - Returns the maximum image of two images pixel-wise. + ``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. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. Returns the image object so you can call another method using ``.`` notation. - Not supported on compressed images or bayer images. + Not supported on compressed images or bayer/yuv images. + + .. note:: + + `Image.set` is an alias for `Image.draw_image`. + + .. method:: add(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image - .. method:: difference(image:Image, mask:Optional[Image]=None) -> Image + Numerically adds ``image`` and this image (e.g. ``min(a + b, 255)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``add("test.jpg")``. - Returns the absolute difference image between two images (e.g. ||a-b||). + ``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. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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 ``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 source 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: + + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. Returns the image object so you can call another method using ``.`` notation. - Not supported on compressed images or bayer images. + Not supported on compressed images or bayer/yuv images. + + .. method:: sub(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image + + Numerically subtracts ``image`` and this image (e.g. ``max(a - b, 0)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``sub("test.jpg")``. + + ``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. - .. method:: blend(image:Image, alpha=128, mask:Optional[Image]=None) -> 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. - Alpha blends two images with each other. + ``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 source image is. This is applied after ``rgb_channel`` extraction if used. - ``image`` can either be an image object, a path to an uncompressed image - file (bmp/pgm/ppm), or a scalar value. If a scalar value the value can - either be an RGB888 tuple or the underlying pixel value (e.g. an 8-bit grayscale - for grayscale images or a RGB565 value for RGB images). + ``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. - ``alpha`` controls how much of the other image to blend into this image. - ``alpha`` should be an integer value between 0 and 256. A value closer to - zero blends more of the other image into this image and a value closer to - 256 does the opposite. + ``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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. ``mask`` is another image to use as a pixel level mask for the operation. - The mask should be an image with just black or white pixels and should be the - same size as the image being operated on. Only pixels set in the mask are - modified. Returns the image object so you can call another method using ``.`` notation. - Not supported on compressed images or bayer images. + Not supported on compressed images or bayer/yuv images. + + .. method:: rsub(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image + + Numerically reverse subtracts ``image`` and this image (e.g. ``max(b - a, 0)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``rsub("test.jpg")``. + + ``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 ``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 source 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: + + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + + ``mask`` is another image to use as a pixel level mask for the operation. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed images or bayer/yuv images. + + .. method:: min(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image + + Numerically finds the minimum of ``image`` and this image (e.g. ``min(a, b)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``min("test.jpg")``. + + ``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 ``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 source 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: + + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + + ``mask`` is another image to use as a pixel level mask for the operation. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed images or bayer/yuv images. + + .. method:: max(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image + + Numerically finds the maximum of ``image`` and this image (e.g. ``max(a, b)``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``max("test.jpg")``. + + ``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 ``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 source 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: + + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + + ``mask`` is another image to use as a pixel level mask for the operation. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed images or bayer/yuv images. + + .. method:: difference(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image + + Numerically finds the absolute difference of ``image`` and this image (e.g. ``|a - b|``), + color channel by color channel, from the top-left corner 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. ``image`` may also be a RGB888 + tuple to draw a color instead of an image. You may also pass a path instead of an image object + for this method to automatically load the image from disk and use it in one step. E.g. ``difference("test.jpg")``. + + ``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 ``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 source 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: + + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + + ``mask`` is another image to use as a pixel level mask for the operation. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed images or bayer/yuv images. + + .. method:: blend(image:Image, x:int=0, y:int=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, mask:Optional[Image]=None) -> Image + + Draws an ``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. ``image`` may also be a RGB888 tuple to draw a color instead + of an image. You may also pass a path instead of an image object for this method to automatically + load the image from disk and use it in one step. E.g. ``blend("test.jpg")``. + + ``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 ``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 source 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: + + * `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). + * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. + + ``mask`` is another image to use as a pixel level mask for the operation. + + Returns the image object so you can call another method using ``.`` notation. + + Not supported on compressed images or bayer/yuv images. + + .. note:: + + `Image.blend` is an alias for `Image.draw_image`. .. method:: histeq(adaptive=False, clip_limit=-1, mask:Optional[Image]=None) -> Image @@ -3579,11 +4346,11 @@ The image object is the basic object for machine vision operations. .. method:: gaussian(size:int, unsharp:Optional[bool]=False, mul:Optional[float]=1.0, add:Optional[float]=0.0, threshold:Optional[bool]=False, offset:Optional[int]=0, invert:Optional[bool]=False, mask:Optional[Image]=None) -> Image - Convolves the image by a smoothing guassian kernel. + Convolves the image by a smoothing gaussian kernel. ``size`` is the kernel size. Use 1 (3x3 kernel), 2 (5x5 kernel), etc. - If ``unsharp`` is set to the True then instead of doing just a guassian + If ``unsharp`` is set to the True then instead of doing just a gaussian filtering operation this method will perform an unsharp mask operation which improves image sharpness on edges. @@ -3770,7 +4537,7 @@ The image object is the basic object for machine vision operations. .. method:: get_similarity(image:Image, x:Optional[int]=0, y:Optional[int]=0, x_scale:float=1.0, y_scale:float=1.0, roi:Optional[Tuple[int,int,int,int]]=None, rgb_channel:int=-1, alpha:int=256, color_palette=None, alpha_palette=None, hint:int=0, dssim:bool=False) -> Similarity Computes the similarity between two images. The similarity is computed by - using the structural similiary index (SSIM). The SSIM is a metric that + using the structural similarity index (SSIM). The SSIM is a metric that compares the structural similarity between two images. The SSIM is a value between -1 and 1. A value of 1 means the images are identical, a value of 0 means the images are not similar, and a value of -1 means the images are @@ -3836,7 +4603,7 @@ The image object is the basic object for machine vision operations. * `image.ROTATE_270`: Rotate the image by 270 degrees (this is just HMIRROR | TRANSPOSE). * `image.BLACK_BACKGROUND`: Assume the background image being drawn on is black speeding up blending. - ``dssim`` if true will compute the structual disimilarity index (DSSIM) instead of the SSIM. A + ``dssim`` if true will compute the structural disimilarity index (DSSIM) instead of the SSIM. A value of 0 means the images are identical. A value of 1 means the images are completely different. Returns a `image.Similarity` object. @@ -3892,7 +4659,7 @@ The image object is the basic object for machine vision operations. channels. For grayscale images use ``bins`` and for RGB565 images use the others for each channel. The bin counts must be greater than 2 for each channel. Additionally, it makes no sense to set the bin count larger than - the number of unique pixel values for each channel. By default, the historgram + the number of unique pixel values for each channel. By default, the histogram will have the maximum number of bins per channel. ``difference`` may be set to an image object to cause this method to operate @@ -3956,7 +4723,7 @@ The image object is the basic object for machine vision operations. channels. For grayscale images use ``bins`` and for RGB565 images use the others for each channel. The bin counts must be greater than 2 for each channel. Additionally, it makes no sense to set the bin count larger than - the number of unique pixel values for each channel. By default, the historgram + the number of unique pixel values for each channel. By default, the histogram will have the maximum number of bins per channel. ``difference`` may be set to an image object to cause this method to operate @@ -4082,10 +4849,10 @@ The image object is the basic object for machine vision operations. If a blob's pixel count is less than ``pixels_threshold`` it is filtered out. - ``merge`` if True merges all not filtered out blobs whos bounding + ``merge`` if True merges all not filtered out blobs whose bounding rectangles intersect each other. ``margin`` can be used to increase or decrease the size of the bounding rectangles for blobs during the - intersection test. For example, with a margin of 1 blobs whos bounding + intersection test. For example, with a margin of 1 blobs whose bounding rectangles are 1 pixel away from each other will be merged. Merging blobs allows you to implement color code tracking. Each blob object @@ -4169,13 +4936,13 @@ The image object is the basic object for machine vision operations. specified, it is equal to the image rectangle. Only pixels within the ``roi`` are operated on. - ``merge_distance`` specifies the maximum number of pixels two line segements - can be seperated by each other (at any point on one line) to be merged. + ``merge_distance`` specifies the maximum number of pixels two line segments + can be separated by each other (at any point on one line) to be merged. ``max_theta_difference`` is the maximum theta difference in degrees two line - segements that are ``merge_distance`` apart to be merged. + segments that are ``merge_distance`` apart to be merged. - This method uses the LSD library (also used by OpenCV) to find line segements + This method uses the LSD library (also used by OpenCV) to find line segments in the image. It's somewhat slow but very accurate and lines don't jump around. This method is not available on the OpenMV Cam M4. @@ -4395,13 +5162,13 @@ The image object is the basic object for machine vision operations. If not specified, it is equal to the image rectangle. ``roi`` and ``template`` roi must have the same w/h but may have any x/y - location in the image. You may slide smaller rois arround a larger image to + location in the image. You may slide smaller rois around a larger image to get an optical flow gradient image... `Image.find_displacement()` normally computes the x/y translation between two images. However, if you pass ``logpolar=True`` it will instead find rotation and scale changes between the two images. The same `image.displacement` object - result encodes both possible repsonses. + result encodes both possible responses. Not supported on compressed images or bayer images. @@ -4557,7 +5324,7 @@ The image object is the basic object for machine vision operations. Takes a double wide grayscale image that contains the output of two camera sensors side-by-side and replaces one of the images in the double wide image with the stero-disparity - image where each pixel reprsents depth. E.g. if you have two 320x240 cameras then this method + image where each pixel represents depth. E.g. if you have two 320x240 cameras then this method takes a 640x240 image. ``reversed`` By default the left image is compared to the right image and the right image @@ -4570,7 +5337,7 @@ The image object is the basic object for machine vision operations. not match this then you will get useless results. ``max_disparity`` is the maximum distance to search for a matching pixel block using the - sum-of-absolute differences algorith. Larger values take exponentially longer to search with + sum-of-absolute differences algorithm. Larger values take exponentially longer to search with but result in higher quality images. Lower values make the algorithm run faster but may result in nonsense output. @@ -4653,7 +5420,7 @@ Constants and is fast. When downscaling an image this method will subsample the input image to produce the downscaled - image. Use `image.AREA` for the higest quality downscaling if speed is not an issue. + image. Use `image.AREA` for the highest quality downscaling if speed is not an issue. .. data:: BICUBIC :type: int @@ -4662,7 +5429,7 @@ Constants but is slow. When downscaling an image this method will subsample the input image to produce the downscaled - image. Use `image.AREA` for the higest quality downscaling if speed is not an issue. + image. Use `image.AREA` for the highest quality downscaling if speed is not an issue. .. data:: VFLIP :type: int @@ -4701,7 +5468,7 @@ Constants :type: int Scale the image being drawn to fit inside of the image/canvas being drawn on while maintaining - the aspect ratio. Unless the image aspect ratios match the image being drawn will not completley + the aspect ratio. Unless the image aspect ratios match the image being drawn will not completely cover the image/canvas being drawn on. Any x_scale/y_scale values passed will additionally scale the scaled image. diff --git a/docs/library/omv.imu.rst b/docs/library/omv.imu.rst index 2de17eeaaf501..65f89c7693587 100644 --- a/docs/library/omv.imu.rst +++ b/docs/library/omv.imu.rst @@ -43,7 +43,7 @@ Functions Returns the rotation angle in degrees (float) of the camera module. * 0 -> Camera is standing up. - * 90 -> Camera is roated left. + * 90 -> Camera is rotated left. * 180 -> Camera is upside down. * 270 -> Camera is rotated right. diff --git a/docs/library/omv.ml.preprocessing.rst b/docs/library/omv.ml.preprocessing.rst index 9b5a0fe0b4335..5df91ba3c7bc5 100644 --- a/docs/library/omv.ml.preprocessing.rst +++ b/docs/library/omv.ml.preprocessing.rst @@ -51,3 +51,5 @@ Constructors allows you to directly specify the range of the input data, the mean, and the standard deviation. The Grayscale or RGB88 image is then converted into a floating point tensor for the model to process based on these values. + + uint16 and int16 input tensors are not supported. diff --git a/docs/library/omv.ml.rst b/docs/library/omv.ml.rst index 07a83f3f9c0b5..c4d083685d0ee 100644 --- a/docs/library/omv.ml.rst +++ b/docs/library/omv.ml.rst @@ -65,7 +65,7 @@ Constructors using this option, but, you need to be careful if you deallocate. Once a model is loaded you can execute it multiple times with different inputs using `predict()`. - The model will rember its internal state between calls to `predict()`. + The model will remember its internal state between calls to `predict()`. When deleted the model will automatically free up any memory it used from the heap or frame buffer stack. @@ -78,15 +78,15 @@ Constructors to the number of input tensors the model supports. The method returns a list of numpy ``ndarray`` objects corresponding to the number of output tensors the model has. - The model input tensors can be up to 4D tensors of uint8, int8, int16, or float32 values. The passed + The model input tensors can be up to 4D tensors of uint8, int8, uint16, int16, or float32 values. The passed numpy ``ndarray`` for an input tensor is then converted to floating point and scaled/offset based on the input tensor's scale and zero point values before being passed to the model. For example, an ``ndarray`` of uint8 values will be converted to float32s between 0.0-255.0, divided by the input tensor's scale, and - then have the input tensor's zero point added to it. The same process is done for int8 and int16 values + then have the input tensor's zero point added to it. The same process is done for int8, uint16, and int16 values whereas float32 values are passed directly to the model ignoring the scale and zero point values. - The model's output tensors can be up to 4D tensors of uint8, int8, or float32 values. For uint8 - and int8 tensors the returned numpy ndarray is created by subtracting the output tensor's zero + The model's output tensors can be up to 4D tensors of uint8, int8, uint16, int16, or float32 values. For uint8, + int8, uint16, and int16 tensors the returned numpy ndarray is created by subtracting the output tensor's zero point value before multiplying by the output tensor's scale value. For float32 tensors, values are passed directly to the output without any scaling or offset being applied. @@ -127,7 +127,7 @@ Constructors :type: list[str] A list of strings containing the data type of each input tensor. - 'b', 'B', 'h', and 'f' respectively for uint8, int8, int16, and float32. + 'B', 'b', 'H', 'h', and 'f' respectively for uint8, int8, uint16, int16, and float32. .. attribute:: input_scale :type: list[float] diff --git a/docs/library/omv.rpc.rst b/docs/library/omv.rpc.rst index e8a56c1843734..1266937ac8dff 100644 --- a/docs/library/omv.rpc.rst +++ b/docs/library/omv.rpc.rst @@ -34,10 +34,10 @@ size. Once the remote method finishes executing it will return a ``memory_view_o can also be up to 2^32-1 bytes in size. Because the argument and response are both generic byte containers you can pass anything through the ``rpc`` library and receive any type of response. A simple way to pass arguments is to use ``struct.pack()`` to create the argument and ``struct.unpack()`` to -receieve the argument on the other side. For the response, the other side may send a string +receive the argument on the other side. For the response, the other side may send a string object or json string as the result which the master can then interpret. -As for errors, if you try to execute a non-existant function or method name the +As for errors, if you try to execute a non-existent function or method name the ``rpc_master.call()`` method will return an empty ``bytes()`` object. If the ``rpc`` library failed to communicate with the slave the ``rpc`` library will return None. @@ -159,12 +159,12 @@ Constructors Executes a remote call on the slave device. ``name`` is a string name of the remote function or method to execute. ``data`` is the ``bytes`` like object that will be sent as the argument of the remote function - or method to exeucte. ``send_timeout`` defines how many milliseconds to wait while trying to connect to + or method to execute. ``send_timeout`` defines how many milliseconds to wait while trying to connect to the slave and get it to execute the remote function or method. Once the master starts sending the - argument to the slave deivce ``send_timeout`` does not apply. The library will allow the argument to + argument to the slave device ``send_timeout`` does not apply. The library will allow the argument to take up to 5 seconds to be sent. ``recv_timeout`` defines how many milliseconds to wait after the slave - started executing the remote method to receive the repsonse. Note that once the master starts - receiving the repsonse ``recv_timeout`` does not apply. The library will allow the response to take up + started executing the remote method to receive the response. Note that once the master starts + receiving the response ``recv_timeout`` does not apply. The library will allow the response to take up to 5 seconds to be received. Note that a new packet that includes a copy of ``data`` will be created internally inside the ``rpc`` diff --git a/docs/library/omv.sensor.rst b/docs/library/omv.sensor.rst index f8c18eb30daa7..9de955b4a2197 100644 --- a/docs/library/omv.sensor.rst +++ b/docs/library/omv.sensor.rst @@ -137,7 +137,7 @@ Functions Creating secondary images normally requires creating them on the heap which has a limited amount of RAM... but, also gets fragmented making it hard to - grab a large contigous memory array to store an image in. With this method + grab a large contiguous memory array to store an image in. With this method you are able to allocate a very large memory array for an image instantly by taking space away from our frame buffer stack memory which we use for computer vision algorithms. That said, this also means you'll run out of @@ -156,9 +156,9 @@ Functions fixed by firmware. The stack then grows down until it hits the heap. Next, frame buffers are stored in a secondary memory region. Memory is liad out with the main frame buffer on the bottom and the frame buffer - stack on the top. When `sensor.snapshot()` is called it fills the frame bufer + stack on the top. When `sensor.snapshot()` is called it fills the frame buffer from the bottom. The frame buffer stack is then able to use whatever is - left over. This memory allocation method is extremely efficent for computer + left over. This memory allocation method is extremely efficient for computer vision on microcontrollers. .. function:: set_pixformat(pixformat:int) -> None @@ -264,7 +264,7 @@ Functions Set the camera image gainceiling. 2, 4, 8, 16, 32, 64, or 128. -.. function:: set_contrast(constrast:int) -> None +.. function:: set_contrast(contrast:int) -> None Set the camera image contrast. -3 to +3. @@ -318,7 +318,7 @@ Functions Camera auto exposure algorithms are pretty conservative about how much they adjust the exposure value by and will generally avoid changing the - exposure value by much. Instead, they change the gain value alot of deal + exposure value by much. Instead, they change the gain value a lot to deal with changing lighting. .. function:: get_exposure_us() -> int @@ -410,7 +410,7 @@ Functions `sensor.snapshot()` will automatically handle switching active frame buffers in the background. From your code's perspective there is only ever 1 active frame buffer even though there might - be more than 1 frame buffer on the system and another frame buffer reciving data in the background. + be more than 1 frame buffer on the system and another frame buffer receiving data in the background. If count is: @@ -425,7 +425,7 @@ Functions In double buffer mode your OpenMV Cam will allocate two frame buffers for receiving images. When you call `sensor.snapshot()` one framebuffer will be used to receive the image and the camera driver will continue to run. When the next frame is received it will be stored - in the other frame bufer. In the advent you call `sensor.snapshot()` again + in the other frame buffer. In the advent you call `sensor.snapshot()` again before the first line of the next frame after is received your code will execute at the frame rate of the camera. Otherwise, the image will be dropped. @@ -520,7 +520,7 @@ Functions * `sensor.IOCTL_SET_READOUT_WINDOW` - Pass this enum followed by a rect tuple (x, y, w, h) or a size tuple (w, h). * This IOCTL allows you to control the readout window of the camera sensor which dramatically improves the frame rate at the cost of field-of-view. - * If you pass a rect tuple (x, y, w, h) the readout window will be positoned on that rect tuple. The rect tuple's x/y position will be adjusted so the size w/h fits. Additionally, the size w/h will be adjusted to not be smaller than the ``framesize``. + * If you pass a rect tuple (x, y, w, h) the readout window will be positioned on that rect tuple. The rect tuple's x/y position will be adjusted so the size w/h fits. Additionally, the size w/h will be adjusted to not be smaller than the ``framesize``. * If you pass a size tuple (w, h) the readout window will be centered given the w/h. Additionally, the size w/h will be adjusted to not be smaller than the ``framesize``. * This IOCTL is extremely helpful for increasing the frame rate on higher resolution cameras like the OV2640/OV5640. * `sensor.IOCTL_GET_READOUT_WINDOW` - Pass this enum for `sensor.ioctl` to return the current readout window rect tuple (x, y, w, h). By default this is (0, 0, maximum_camera_sensor_pixel_width, maximum_camera_sensor_pixel_height). @@ -551,7 +551,7 @@ Functions * `sensor.IOCTL_LEPTON_SET_MEASUREMENT_MODE` - Pass this followed by True or False to turn off automatic gain control on the FLIR Lepton and force it to output an image where each pixel value represents an exact temperature value in celsius. A second True enables high temperature mode enabling measurements up to 500C on the Lepton 3.5, False is the default low temperature mode. * `sensor.IOCTL_LEPTON_GET_MEASUREMENT_MODE` - Pass this to get a tuple for (measurement-mode-enabled, high-temp-enabled). * `sensor.IOCTL_LEPTON_SET_MEASUREMENT_RANGE` - Pass this when measurement mode is enabled to set the temperature range in celsius for the mapping operation. The temperature image returned by the FLIR Lepton will then be clamped between these min and max values and then scaled to values between 0 to 255. To map a pixel value back to a temperature (on a grayscale image) do: ((pixel * (max_temp_in_celsius - min_temp_in_celsius)) / 255.0) + min_temp_in_celsius. - * The first arugment should be the min temperature in celsius. + * The first argument should be the min temperature in celsius. * The second argument should be the max temperature in celsius. If the arguments are reversed the library will automatically swap them for you. * `sensor.IOCTL_LEPTON_GET_MEASUREMENT_RANGE` - Pass this to return the sorted (min, max) 2 value temperature range tuple. The default is -10C to 40C if not set yet. * `sensor.IOCTL_HIMAX_MD_ENABLE` - Pass this enum followed by ``True``/``False`` to enable/disable motion detection on the HM01B0. You should also enable the I/O pin (PC15 on the Arduino Portenta) attached the HM01B0 motion detection line to receive an interrupt. diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst index 7cf8fd8e460cc..be8907a7f2a89 100644 --- a/docs/library/pyb.I2C.rst +++ b/docs/library/pyb.I2C.rst @@ -66,11 +66,11 @@ Constructors the bus, if any). If extra arguments are given, the bus is initialised. See ``init`` for parameters of initialisation. - The physical pins of the I2C busses on the OpenMV Cam are: + The physical pins of the I2C buses on the OpenMV Cam are: - ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (P4, P5) = (PB10, PB11)`` - The physical pins of the I2C busses on the OpenMV Cam M7 are: + The physical pins of the I2C buses on the OpenMV Cam M7 are: - ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (P4, P5) = (PB10, PB11)`` - ``I2C(4)`` is on the Y position: ``(SCL, SDA) = (P7, P8) = (PD12, PD13)`` diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst index 989f8797d7827..4292e9d70abcd 100644 --- a/docs/library/pyb.UART.rst +++ b/docs/library/pyb.UART.rst @@ -57,7 +57,7 @@ Constructors - ``UART(3)``: ``(TX, RX) = (P4, P5) = (PB10, PB11)`` - The physical pins of the UART busses are for the OpenMV Cam M7 and H7: + The physical pins of the UART buses are for the OpenMV Cam M7 and H7: - ``UART(1)``: ``(TX, RX) = (P1, P0) = (PB14, PB15)`` - ``UART(3)``: ``(TX, RX) = (P4, P5) = (PB10, PB11)`` diff --git a/docs/openmvcam/quickref.rst b/docs/openmvcam/quickref.rst index c0db8a8fa9ad6..f4ec3f7369f0e 100644 --- a/docs/openmvcam/quickref.rst +++ b/docs/openmvcam/quickref.rst @@ -40,7 +40,7 @@ General OpenMV Cams Board Control --------------------------------- All OpenMV Cams can use the `machine` module to control the camera hardware. Please refer to the -pinout image for which SPI/I2C/UART/CAN/PWM/TIMER channels are avialable on what I/O pins. +pinout image for which SPI/I2C/UART/CAN/PWM/TIMER channels are available on what I/O pins. Delay and timing ^^^^^^^^^^^^^^^^ diff --git a/docs/openmvcam/tutorial/openmvide_overview.rst b/docs/openmvcam/tutorial/openmvide_overview.rst index c9fcdafed5a2c..2af7c75caab57 100644 --- a/docs/openmvcam/tutorial/openmvide_overview.rst +++ b/docs/openmvcam/tutorial/openmvide_overview.rst @@ -60,7 +60,7 @@ text for the replace. Additionally, it also can preserve case while replacing. Finally, the find and replace features works not only on the current file, but, it can work on all files in a folder or all open files in OpenMV IDE. -In addition to the nice text editing enviornment OpenMV IDE also provides +In addition to the nice text editing environment OpenMV IDE also provides auto-completion support hover tool-tips on keywords. So, after typing ``.`` for example in Python OpenMV IDE will detect that you're about to write a function or method name and it will show you an auto-completion text box. Once you've @@ -353,7 +353,7 @@ your computer first before playing them since disk I/O over USB on your OpenMV Cam is slow. Finally, FFMPEG is used to provide conversion and video player support and may -be used for any non-OpenMV Cam activites you like. FFMPEG can convert/play +be used for any non-OpenMV Cam activities you like. FFMPEG can convert/play a large number of file formats. * diff --git a/docs/openmvcam/tutorial/overview.rst b/docs/openmvcam/tutorial/overview.rst index 5ecf94f8c5c3d..d77847c52e2de 100644 --- a/docs/openmvcam/tutorial/overview.rst +++ b/docs/openmvcam/tutorial/overview.rst @@ -27,7 +27,7 @@ happily forever. But, if I want to use a 2D sensor like a camera everything changes. Since a camera sensor generates tons of data a faster more resourceful computer is required to process the sensor data. Now, with this faster more powerful computer -you can definately do many more things. But, what if my goal were still to just +you can definitely do many more things. But, what if my goal were still to just turn on an LED? Spin a motor? Or open a valve? Could I still get the Arduino like experience with a camera sensor? diff --git a/docs/openmvcam/tutorial/system_architecture.rst b/docs/openmvcam/tutorial/system_architecture.rst index 2a1b51a170117..8dc7e80a2fbcb 100644 --- a/docs/openmvcam/tutorial/system_architecture.rst +++ b/docs/openmvcam/tutorial/system_architecture.rst @@ -16,7 +16,7 @@ revved the OpenMV Cam with a faster and faster main processor the SDR DRAM speed also has not kept up with the internal RAM speed. On the STM32H7 for example the internal RAM bandwidth is 3.2GB/s versus a maximum SDR RAM bandwidth of 666MB/s even if we built the system with an 8-layer board using a 32-bit DRAM bus -requring 50+ I/O pins for the DRAM. +requiring 50+ I/O pins for the DRAM. So, since we're built on the STM32 architecture and limited to using expensive and slow SDR DRAM for now we haven't added it as our internal SRAM is way faster. @@ -28,7 +28,7 @@ Memory Architecture Given the above memory architecture limitations we built all of our code to run inside of the STM32 microcontroller memory. However, the STM32 doesn't have one -large contigous memory map. It features different segments of RAM for different +large contiguous memory map. It features different segments of RAM for different situations. First, there's a segment of RAM which contains global variables, the heap, and diff --git a/docs/reference/filesystem.rst b/docs/reference/filesystem.rst index ccae4bf3e93b6..ef71db5d29384 100644 --- a/docs/reference/filesystem.rst +++ b/docs/reference/filesystem.rst @@ -35,7 +35,7 @@ mounted. On STM32 / Pyboard, the internal flash is mounted at ``/flash``, and optionally the SDCard at ``/sd``. On ESP8266/ESP32, the primary filesystem is mounted at ``/``. On the OpenMV Cam the internal flash is mounted at ``/`` unless an SDCard -is installed which will be moutned at ``/`` instead. +is installed which will be mounted at ``/`` instead. Block devices -------------