Improve/simplify/modularize ST7789 SPI driver

Create helper functions for imshow() (could move these to a generic interface class for other display drivers to take advantage of)
Move machine dependency from example to display driver
Add extra checks for edge cases
Remove unused functions and arguments
Add clear() method
Fix imshow() with float images to clip instead of wrap the range 0-1
Other minor optimizations

Author: sfe-SparkFro

drivers/display/st7789_spi.py

@@ -3,6 +3,7 @@
 
 import struct
 from time import sleep_ms
+from machine import Pin, SPI
 from ulab import numpy as np
 import cv2
 
@@ -48,15 +49,6 @@
 
 _ENCODE_POS = const(">HH")
 
-_BIT7 = const(0x80)
-_BIT6 = const(0x40)
-_BIT5 = const(0x20)
-_BIT4 = const(0x10)
-_BIT3 = const(0x08)
-_BIT2 = const(0x04)
-_BIT1 = const(0x02)
-_BIT0 = const(0x01)
-
 # Rotation tables
 #   (madctl, width, height, xstart, ystart)[rotation % 4]
 
@@ -121,22 +113,58 @@
     ( b'\x29', b'\x00', 120)                # Turn on the display
 )
 
-class ST7789():
+class ST7789_SPI():
     """
-    ST7789 driver class base
+    OpenCV SPI driver for ST7789 displays
+
+    Args:
+        width (int): display width   **Required**
+        height (int): display height **Required**
+        spi_id (int): SPI bus ID
+        spi_baudrate (int): SPI baudrate, default 24MHz
+        pin_sck (pin): SCK pin number
+        pin_mosi (pin): MOSI pin number
+        pin_miso (pin): MISO pin number
+        pin_cs (pin): Chip Select pin number
+        pin_dc (pin): Data/Command pin number
+        rotation (int): Orientation of display
+          - 0-Portrait, default
+          - 1-Landscape
+          - 2-Inverted Portrait
+          - 3-Inverted Landscape
+        color_order (int):
+          - RGB: Red, Green Blue, default
+          - BGR: Blue, Green, Red
+        reverse_bytes_in_word (bool):
+          - Enable if the display uses LSB byte order for color words
     """
-    def __init__(self, width, height, backlight, bright, rotation, color_order, reverse_bytes_in_word):
-        """
-        Initialize display and backlight.
-        """
+    def __init__(
+        self,
+        width,
+        height,
+        spi_id,
+        spi_baudrate=24000000,
+        pin_sck=None,
+        pin_mosi=None,
+        pin_miso=None,
+        pin_cs=None,
+        pin_dc=None,
+        rotation=0,
+        color_order=BGR,
+        reverse_bytes_in_word=True,
+    ):
+        # Store SPI arguments
+        self.spi = SPI(spi_id, baudrate=spi_baudrate,
+                       sck=Pin(pin_sck, Pin.OUT) if pin_sck else None,
+                       mosi=Pin(pin_mosi, Pin.OUT) if pin_mosi else None,
+                       miso=Pin(pin_miso, Pin.IN) if pin_miso else None)
+        self.cs = Pin(pin_cs, Pin.OUT, value=1) if pin_cs else None
+        self.dc = Pin(pin_dc, Pin.OUT, value=1) if pin_dc else None
         # Initial dimensions and offsets; will be overridden when rotation applied
         self.width = width
         self.height = height
         self.xstart = 0
         self.ystart = 0
-        # backlight pin
-        self.backlight = backlight
-        self._pwm_bl = True
         # Check display is known and get rotation table
         self.rotations = self._find_rotations(width, height)
         if not self.rotations:
@@ -147,18 +175,17 @@ def __init__(self, width, height, backlight, bright, rotation, color_order, reve
         # Colors
         self.color_order = color_order
         self.needs_swap = reverse_bytes_in_word
-        # init the st7789
-        self.init_cmds = _ST7789_INIT_CMDS
+        # Reset the display
         self.soft_reset()
         # Yes, send init twice, once is not always enough
-        self.send_init(self.init_cmds)
-        self.send_init(self.init_cmds)
+        self.send_init(_ST7789_INIT_CMDS)
+        self.send_init(_ST7789_INIT_CMDS)
         # Initial rotation
         self._rotation = rotation % 4
         # Apply rotation
         self.rotation(self._rotation)
         # Create the framebuffer for the correct rotation
-        self.buffer = np.zeros((self.rotations[self._rotation][2], self.rotations[self._rotation][1], 2), dtype=np.uint8)
+        self.buffer = np.zeros((self.height, self.width, 2), dtype=np.uint8)
 
     def send_init(self, commands):
         """
@@ -220,112 +247,117 @@ def rotation(self, rotation):
         # TODO: Can we swap (modify) framebuffer width/height in the super() class?
         self._rotation = rotation
 
-    def imshow(self, image):
+    def _get_common_roi_with_buffer(self, image):
         """
-        Display an image on the screen.
+        Get the common region of interest (ROI) between the image and the 
+        display's internal buffer.
 
         Args:
-            image (Image): Image to display
+            image (ndarray): Image to display
+        
+        Returns:
+            tuple: (image_roi, buffer_roi)
         """
-        # Check if image is a NumPy ndarray
+        # Ensure image is a NumPy ndarray
         if type(image) is not np.ndarray:
             raise TypeError("Image must be a NumPy ndarray")
+        
+        # Determing number of rows and columns in the image
+        image_rows = image.shape[0]
+        if len(image.shape) < 2:
+            image_cols = 1
+        else:
+            image_cols = image.shape[1]
+        
+        # Get the common ROI between the image and the buffer
+        row_max = min(image_rows, self.height)
+        col_max = min(image_cols, self.width)
+        img_roi = image[:row_max, :col_max]
+        buffer_roi = self.buffer[:row_max, :col_max]
+        return img_roi, buffer_roi
+
+    def _convert_image_to_uint8(self, image):
+        """
+        Convert the image to uint8 format if necessary.
+
+        Args:
+            image (ndarray): Image to convert
+
+        Returns:
+            Image: Converted image
+        """
+        # Check if the image is already in uint8 format
+        if image.dtype is np.uint8:
+            return image
+        
+        # Convert to uint8 format. This unfortunately requires creating a new
+        # buffer for the converted image, which takes more memory
+        if image.dtype == np.int8:
+            return cv2.convertScaleAbs(image, alpha=1, beta=127)
+        elif image.dtype == np.int16:
+            return cv2.convertScaleAbs(image, alpha=1/255, beta=127)
+        elif image.dtype == np.uint16:
+            return cv2.convertScaleAbs(image, alpha=1/255)
+        elif image.dtype == np.float:
+            # This implementation creates an additional buffer from np.clip()
+            # TODO: Find another solution that avoids an additional buffer
+            return cv2.convertScaleAbs(np.clip(image, 0, 1), alpha=255)
+        else:
+            raise ValueError(f"Unsupported image dtype: {image.dtype}")
+
+    def _write_image_to_buffer_bgr565(self, image_roi, buffer_roi):
+        """
+        Convert the image ROI to BGR565 format and write it to the buffer ROI.
+
+        Args:
+            image_roi (ndarray): Image region of interest
+            buffer_roi (ndarray): Buffer region of interest
+        """
+        # Determine the number of channels in the image
+        if len(image_roi.shape) < 3:
+            ch = 1
+        else:
+            ch = image_roi.shape[2]
+
+        if ch == 1: # Grayscale
+            buffer_roi = cv2.cvtColor(image_roi, cv2.COLOR_GRAY2BGR565, buffer_roi)
+        elif ch == 2: # Already in BGR565 format
+            buffer_roi[:] = image_roi
+        elif ch == 3: # BGR
+            buffer_roi = cv2.cvtColor(image_roi, cv2.COLOR_BGR2BGR565, buffer_roi)
+        else:
+            raise ValueError("Image must be 1, 2 or 3 channels (grayscale, BGR565, or BGR)")
 
-        # Ensure image is 3D (row, col, ch) by reshaping if necessary
-        ndim = len(image.shape)
-        if ndim == 1:
-            image = image.reshape((image.shape[0], 1, 1))
-        elif ndim == 2:
-            image = image.reshape((image.shape[0], image.shape[1], 1))
-
-        # Determine number of rows, columns, and channels
-        row, col, ch = image.shape
-
-        # Crop input image to match display size
-        row_max = min(row, self.height)
-        col_max = min(col, self.width)
-        img_cropped = image[:row_max, :col_max]
-
-        # Crop the buffer if image is smaller than the display
-        row_max = min(row_max, self.buffer.shape[0])
-        col_max = min(col_max, self.buffer.shape[1])
-        buffer_cropped = self.buffer[:row_max, :col_max]
-
-        # Check dtype and convert to uint8 if necessary
-        if img_cropped.dtype is not np.uint8:
-            # Have to create a new buffer for non-uint8 images
-            if img_cropped.dtype == np.int8:
-                temp = cv2.convertScaleAbs(img_cropped, alpha=1, beta=127)
-            elif img_cropped.dtype == np.int16:
-                temp = cv2.convertScaleAbs(img_cropped, alpha=1/255, beta=127)
-            elif img_cropped.dtype == np.uint16:
-                temp = cv2.convertScaleAbs(img_cropped, alpha=1/255)
-            elif img_cropped.dtype == np.float:
-                # Standard OpenCV will clamp values to 0-1 using convertTo(),
-                # but this implementation wraps instead
-                temp = np.asarray(img_cropped * 255, dtype=np.uint8)
-            img_cropped = temp
-
-        # Convert image to BGR565 format
-        if ch == 3:  # BGR
-            buffer_cropped = cv2.cvtColor(img_cropped, cv2.COLOR_BGR2BGR565, buffer_cropped)
-        elif ch == 1:  # Grayscale
-            buffer_cropped = cv2.cvtColor(img_cropped, cv2.COLOR_GRAY2BGR565, buffer_cropped)
-        else: # Already in BGR565 format
-            buffer_cropped[:] = img_cropped
-
-        # Write  to display. Swap bytes if needed
+    def imshow(self, image):
+        """
+        Display a NumPy image on the screen.
+
+        Args:
+            image (ndarray): Image to display
+        """
+        # Get the common ROI between the image and internal display buffer
+        image_roi, buffer_roi = self._get_common_roi_with_buffer(image)
+
+        # Ensure the image is in uint8 format
+        image_roi = self._convert_image_to_uint8(image_roi)
+
+        # Convert the image to BGR565 format and write it to the buffer
+        self._write_image_to_buffer_bgr565(image_roi, buffer_roi)
+
+        # Write buffer to display. Swap bytes if needed
         if self.needs_swap:
             self._write(None, self.buffer[:, :, ::-1])
         else:
             self._write(None, self.buffer)
 
-class ST7789_SPI(ST7789):
-    """
-    ST7789 driver class for SPI bus devices
-
-    Args:
-        spi (bus): bus object        **Required**
-        width (int): display width   **Required**
-        height (int): display height **Required**
-        reset (pin): reset pin
-        cs (pin): cs pin
-        dc (pin): dc pin
-        backlight (pin) or (pwm): backlight pin
-          - can be type Pin (digital), PWM or None
-        bright (value): Initial brightness level; default 'on'
-          - a (float) between 0 and 1 if backlight is pwm
-          - otherwise (bool) or (int) for pin value()
-        rotation (int): Orientation of display
-          - 0-Portrait, default
-          - 1-Landscape
-          - 2-Inverted Portrait
-          - 3-Inverted Landscape
-        color_order (int):
-          - RGB: Red, Green Blue, default
-          - BGR: Blue, Green, Red
-        reverse_bytes_in_word (bool):
-          - Enable if the display uses LSB byte order for color words
-    """
-    def __init__(
-        self,
-        spi,
-        width,
-        height,
-        reset=None,
-        cs=None,
-        dc=None,
-        backlight=None,
-        bright=1,
-        rotation=0,
-        color_order=BGR,
-        reverse_bytes_in_word=True,
-    ):
-        self.spi = spi
-        self.reset = reset
-        self.cs = cs
-        self.dc = dc
-        super().__init__(width, height, backlight, bright, rotation, color_order, reverse_bytes_in_word)
+    def clear(self):
+        """
+        Clear the display by filling it with black color.
+        """
+        # Clear the buffer by filling it with zeros (black)
+        self.buffer[:] = 0
+        # Write the buffer to the display
+        self._write(None, self.buffer)
 
     def _write(self, command=None, data=None):
         """SPI write to the device: commands and data."""
@@ -339,21 +371,3 @@ def _write(self, command=None, data=None):
             self.spi.write(data)
         if self.cs:
             self.cs.on()
-
-    def hard_reset(self):
-        """
-        Hard reset display.
-        """
-        if self.cs:
-            self.cs.off()
-        if self.reset:
-            self.reset.on()
-        sleep_ms(10)
-        if self.reset:
-            self.reset.off()
-        sleep_ms(10)
-        if self.reset:
-            self.reset.on()
-        sleep_ms(120)
-        if self.cs:
-            self.cs.on()

examples/hello_opencv.py

@@ -9,26 +9,16 @@
 # implements an `imshow()` function that takes an NumPy array as input
 import st7789_spi as st7789
 
-# The display driver requires some hardware-specific imports
-from machine import Pin, SPI
-
-# Create SPI object
-spi = SPI(0, baudrate=24000000)
-
 # Create display object
-display = st7789.ST7789_SPI(spi,
-                            240, 320,
-                            reset=None,
-                            cs=machine.Pin(17, Pin.OUT, value=1),
-                            dc=machine.Pin(16, Pin.OUT, value=1),
-                            backlight=None,
-                            bright=1,
-                            rotation=1,
-                            color_order=st7789.BGR,
-                            reverse_bytes_in_word=True)
+display = st7789.ST7789_SPI(width=240,
+                            height=320,
+                            spi_id=0,
+                            pin_cs=17,
+                            pin_dc=16,
+                            rotation=1,)
 
 # Initialize an image (NumPy array) to be displayed
-img = np.zeros((240,320, 3), dtype=np.uint8)
+img = np.zeros((240, 320, 3), dtype=np.uint8)
 
 # Images can be modified directly if desired. Here we set the top 50 rows of the
 # image to blue (255, 0, 0) in BGR format
@@ -41,7 +31,7 @@
 # same variable `img`, which has almost no overhead
 img = cv2.ellipse(img, (160, 120), (100, 50), 0, 0, 360, (0, 255, 0), -1)
 
-# And the obligatory text, this time in red
+# And the obligatory "Hello OpenCV" text, this time in red
 img = cv2.putText(img, "Hello OpenCV!", (50, 200), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 0, 255), 2)
 
 # Once we have an image ready to show, just call `imshow()` as you would in