Add zoom, flip, and mirror functionality

Adds the functions zoomTo(), zoomToCenter(), setVerticalFlip(),
setHorizontalMirror(), getResolutionWidth(), and
getResolutionHeight() to the Camera library. The old setResolution()
function is changed into the new private function
setResolutionWithZoom(), which is called by the new version of
setResolution(), as well as by the zoomTo() and zoomToCenter()
functions.

These changes required some changes in the abstract class
ImageSensor, which, in turn, required further changes in the camera
drivers. The only camera driver that fully supports the new
functionality is GC2145, and the others return -1 on all calls. The function
signature for setResolution() is changed, and two new functions are
added: setVerticalFlip() and setHorizontalMirror().

Author: Alrik Vidstrom

libraries/Camera/src/camera.cpp

@@ -137,6 +137,7 @@ const uint32_t restab[CAMERA_RMAX][2] = {
     {320,   240 }, // QVGA
     {320,   320 },
     {640,   480 }, // VGA
+    {0,       0 }, // Empty entry because there's a jump in the resolution enum initializers
     {800,   600 }, // SVGA
     {1600,  1200}, // UXGA
 };
@@ -504,36 +505,120 @@ int Camera::setFrameRate(int32_t framerate)
     return -1;
 }
 
-int Camera::setResolution(int32_t resolution)
+int Camera::setResolutionWithZoom(int32_t resolution, int32_t zoom_resolution, int32_t zoom_x, int32_t zoom_y)
 {
     if (this->sensor == NULL || resolution >= CAMERA_RMAX
             || pixformat >= CAMERA_PMAX || pixformat == -1) {
         return -1;
     }
 
+    // resolution = the full resolution to set the camera to
+    // zoom_resolution = the resolution to crop to when zooming (set equal to resolution for no zoom)
+    // final_resolution = the resolution to crop to (depends on zoom or not)
+    int32_t final_resolution;
+    // Check if zooming is asked for
+    if (resolution != zoom_resolution)
+    {
+        // Can't zoom into a larger window than the original
+        if (zoom_resolution > resolution)
+        {
+            return -1;
+        }
+        final_resolution = zoom_resolution;
+    }
+    else
+    {
+        final_resolution = resolution;
+    }
+
     /*
      * @param  X0    DCMI window X offset
      * @param  Y0    DCMI window Y offset
      * @param  XSize DCMI Pixel per line
      * @param  YSize DCMI Line number
      */
     HAL_DCMI_EnableCROP(&hdcmi);
-    uint32_t bpl = restab[resolution][0];
+    uint32_t bpl = restab[final_resolution][0];
     if (pixformat == CAMERA_RGB565 ||
        (pixformat == CAMERA_GRAYSCALE && !this->sensor->getMono())) {
         // If the pixel format is Grayscale and sensor is Not monochrome,
         // the actual pixel format will be YUV (i.e 2 bytes per pixel).
         bpl *= 2;
     }
-    HAL_DCMI_ConfigCROP(&hdcmi, 0, 0, bpl - 1, restab[resolution][1] - 1);
+    HAL_DCMI_ConfigCROP(&hdcmi, 0, 0, bpl - 1, restab[final_resolution][1] - 1);
 
-    if (this->sensor->setResolution(resolution) == 0) {
-        this->resolution = resolution;
+    if (this->sensor->setResolution(resolution, zoom_resolution, zoom_x, zoom_y) == 0) {
+        this->resolution = final_resolution;
         return 0;
     }
     return -1;
 }
 
+int Camera::setResolution(int32_t resolution)
+{
+    // Check for resolutions that would cause out-of-bounds indexing of restab
+    // This check is here because original_resolution will be trusted in all other code
+    if ((resolution < 0) || (resolution >= CAMERA_RMAX))
+    {
+        return -1;
+    }
+    original_resolution = resolution;
+    return setResolutionWithZoom(resolution, resolution, 0, 0);
+}
+
+int Camera::zoomTo(int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y)
+{
+    // Check for zoom resolutions that would cause out-of-bounds indexing of restab
+    if ((zoom_resolution < 0) || (zoom_resolution >= CAMERA_RMAX))
+    {
+        return -1;
+    }
+    // Check if the zoom window goes outside the frame on the x axis
+    // Notice that this form prevents uint32_t wraparound, so don't change it
+    if (zoom_x >= (restab[this->original_resolution][0]) - (restab[zoom_resolution][0]))
+    {
+         return -1;
+    }
+    // Check if the zoom window goes outside the frame on the y axis
+    // Notice that this form prevents uint32_t wraparound, so don't change it
+    if (zoom_y >= (restab[this->original_resolution][1]) - (restab[zoom_resolution][1]))
+    {
+        return -1;
+    }
+    return setResolutionWithZoom(this->original_resolution, zoom_resolution, zoom_x, zoom_y);
+}
+
+int Camera::zoomToCenter(int32_t zoom_resolution)
+{
+    // Check for zoom resolutions that would cause out-of-bounds indexing of restab
+    if ((zoom_resolution < 0) || (zoom_resolution >= CAMERA_RMAX))
+    {
+        return -1;
+    }
+    uint32_t zoom_x = (restab[this->original_resolution][0] - restab[zoom_resolution][0]) / 2;
+    uint32_t zoom_y = (restab[this->original_resolution][1] - restab[zoom_resolution][1]) / 2;
+    return setResolutionWithZoom(this->original_resolution, zoom_resolution, zoom_x, zoom_y);
+}
+
+int Camera::setVerticalFlip(bool flip_mode)
+{
+    return (this->sensor->setVerticalFlip(flip_mode));
+}
+
+int Camera::setHorizontalMirror(bool mirror_mode)
+{
+    return (this->sensor->setHorizontalMirror(mirror_mode));
+}
+
+uint32_t Camera::getResolutionWidth()
+{
+    return (restab[this->original_resolution][0]);
+}
+uint32_t Camera::getResolutionHeight()
+{
+    return (restab[this->original_resolution][1]);
+}
+
 int Camera::setPixelFormat(int32_t pixformat)
 {
     if (this->sensor == NULL || pixformat >= CAMERA_PMAX) {

libraries/Camera/src/camera.h

@@ -210,9 +210,12 @@ class ImageSensor {
          * @brief Set the resolution of the image sensor.
          * @note This has no effect on cameras that do not support variable resolutions.
          * @param resolution The desired resolution, as defined in the resolution enum
+         * @param zoom_resolution The desired zoom window size.
+         * @param zoom_x The desired x position of the zoom window.
+         * @param zoom_y The desired y position of the zoom window.
          * @return int 0 on success, non-zero on failure
          */
-        virtual int setResolution(int32_t resolution) = 0;
+        virtual int setResolution(int32_t resolution, int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y) = 0;
 
         /**
          * @brief Set the pixel (color) format of the image sensor.
@@ -277,11 +280,15 @@ class ImageSensor {
          */
         virtual int motionDetected() = 0;
 
+        virtual int setVerticalFlip(bool flip_mode) = 0;
+        virtual int setHorizontalMirror(bool flip_mode) = 0; 
+
+
         /**
          * @brief Output debug information to a stream.
          * You can use this function to output debug information to the serial port by passing Serial as the stream.
          * @param stream Stream to output the debug information
-         */
+         */       
         virtual void debug(Stream &stream) = 0;
 
         /**
@@ -370,13 +377,16 @@ class Camera {
     private:
         int32_t pixformat;       /// Pixel format
         int32_t resolution;      /// Camera resolution
+        int32_t original_resolution;    /// The resolution originally set through setResolution()
         int32_t framerate;       /// Frame rate
         ImageSensor *sensor;     /// Pointer to the camera sensor
         int reset();             /// Reset the camera
         ScanResults<uint8_t> i2cScan(); /// Perform an I2C scan
         Stream *_debug;          /// Pointer to the debug stream
         arduino::MbedI2C *_i2c;  /// Pointer to the I2C interface
         FrameBuffer *_framebuffer; /// Pointer to the frame buffer
+        int setResolutionWithZoom(int32_t resolution, int32_t zoom_resolution, int32_t zoom_x, int32_t zoom_y);
+
 
     public:
         /**
@@ -521,6 +531,12 @@ class Camera {
          * @return int 0 if no motion is detected, non-zero if motion is detected
          */
         int motionDetected();
+        int zoomTo(int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y);
+        int zoomToCenter(int32_t zoom_resolution);
+        int setVerticalFlip(bool flip_mode);
+        int setHorizontalMirror(bool mirror_mode);
+        uint32_t getResolutionWidth();
+        uint32_t getResolutionHeight();
 
         /**
          * @brief Output debug information to a stream.

libraries/GC2145/gc2145.cpp

@@ -763,7 +763,31 @@ int GC2145::setFrameRate(int32_t framerate)
     return 0;
 }
 
-int GC2145::setResolution(int32_t resolution)
+int GC2145::setVerticalFlip(bool flip_mode)
+{
+    // The GC2145 doesn't return this value when reading the Analog mode 1 register
+    // so we have to save it for setHorizontalMirror()
+    vertical_flip_state = flip_mode;
+    // Using the Analog mode 1 register (0x17)
+    uint8_t old_value = regRead(GC2145_I2C_ADDR, 0x17);
+    int retVal = regWrite(GC2145_I2C_ADDR, 0x17, (old_value & 0b11111100) | (flip_mode << 1) | horizontal_mirror_state);
+    // Notice that the error codes from regWrite() are positive ones passed on from Wire, not -1
+    return ((0 == retVal) ? 0 : -1);
+}
+
+int GC2145::setHorizontalMirror(bool mirror_mode)
+{
+    // The GC2145 doesn't return this value when reading the Analog mode 1 register
+    // so we have to save it for setVerticalFlip()
+    horizontal_mirror_state = mirror_mode;
+    // Using the Analog mode 1 register (0x17)
+    uint8_t old_value = regRead(GC2145_I2C_ADDR, 0x17);
+    int retVal = regWrite(GC2145_I2C_ADDR, 0x17, (old_value & 0b11111100) | mirror_mode | (vertical_flip_state << 1));
+    // Notice that the error codes from regWrite() are positive ones passed on from Wire, not -1
+    return ((0 == retVal) ? 0 : -1);
+}
+
+int GC2145::setResolution(int32_t resolution, int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y)
 {
     int ret = 0;
 
@@ -809,6 +833,44 @@ int GC2145::setResolution(int32_t resolution)
     // Set readout window first.
     ret |= setWindow(0x09, win_x, win_y, win_w + 16, win_h + 8);
 
+    // Zoom mode active
+    if (resolution != zoom_resolution)
+    {
+        // Can't zoom into a larger window than the original
+        if (zoom_resolution > resolution)
+        {
+            return -1;
+        }
+        
+        // The zoom resolution constant is outside of the allowed range
+        if ((zoom_resolution < 0) || (zoom_resolution >= CAMERA_RMAX))
+        {
+            return -1;
+        }
+
+        uint32_t zoom_w = restab[zoom_resolution][0];
+        uint32_t zoom_h = restab[zoom_resolution][1];
+
+        // Check if the zoom window goes outside the frame on the x axis
+        // Notice that this form prevents uint32_t wraparound, so don't change it
+        if (zoom_x >= (w - zoom_w))
+        {
+            return -1;
+        }
+        // Check of the zoom window goes outside the frame on the y axis
+        // Notice that this form prevents uint32_t wraparound, so don't change it
+        if (zoom_y >= (h - zoom_h))
+        {
+            return -1;
+        }
+
+        // Set the cropping window parameters to the zoom window parameters
+        x = zoom_x;
+        y = zoom_y;
+        w = zoom_w;
+        h = zoom_h;
+    }
+
     // Set cropping window next.
     ret |= setWindow(0x91, x, y, w, h);
 
@@ -820,7 +882,6 @@ int GC2145::setResolution(int32_t resolution)
     ret |= regWrite(GC2145_I2C_ADDR, 0x9A, 0x0E);
 
     return ret;
-
 }
 
 int GC2145::setPixelFormat(int32_t pixformat)

libraries/GC2145/gc2145.h

@@ -28,6 +28,8 @@ class GC2145: public ImageSensor {
         arduino::MbedI2C *_i2c;
         int regWrite(uint8_t dev_addr, uint16_t reg_addr, uint8_t reg_data, bool wide_addr = false);
         uint8_t regRead(uint8_t dev_addr, uint16_t reg_addr, bool wide_addr = false);
+        bool vertical_flip_state = false;
+        bool horizontal_mirror_state = false;
 
    public:
         GC2145(arduino::MbedI2C &i2c = CameraWire);
@@ -37,13 +39,15 @@ class GC2145: public ImageSensor {
         bool getMono() { return false; };
         uint32_t getClockFrequency() { return 12000000; };
         int setFrameRate(int32_t framerate);
-        int setResolution(int32_t resolution);
+        int setResolution(int32_t resolution, int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y);
         int setPixelFormat(int32_t pixformat);
         int enableMotionDetection(md_callback_t callback) { return 0; };
         int disableMotionDetection() { return 0; };
         int setMotionDetectionWindow(uint32_t x, uint32_t y, uint32_t w, uint32_t h) { return 0; };
         int setMotionDetectionThreshold(uint32_t threshold) { return 0; };
         int motionDetected() { return 0; };
+        int setVerticalFlip(bool flip_mode);
+        int setHorizontalMirror(bool mirror_mode);
         void debug(Stream &stream);
 };
 

libraries/Himax_HM01B0/himax.cpp

@@ -341,10 +341,25 @@ int HM01B0::reset()
     return (max_timeout > 0) ? 0 : -1;
 }
 
-int HM01B0::setResolution(int32_t resolution)
+int HM01B0::setVerticalFlip(bool flip_mode)
+{
+  return -1;
+}
+
+int HM01B0::setHorizontalMirror(bool mirror_mode)
+{
+  return -1;
+}
+
+int HM01B0::setResolution(int32_t resolution, int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y)
 {
   int ret = 0;
 
+  if (resolution != zoom_resolution)
+  {
+    return -1;
+  }
+
   switch (resolution) {
     case CAMERA_R160x120:
       for(uint32_t i = 0; himax_qqvga_regs[i][0]; i++) {

libraries/Himax_HM01B0/himax.h

@@ -40,7 +40,7 @@ class HM01B0: public ImageSensor {
         bool getMono() { return true; };
         uint32_t getClockFrequency() { return 6000000; };
         int setFrameRate(int32_t framerate);
-        int setResolution(int32_t resolution);
+        int setResolution(int32_t resolution, int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y);
         int setPixelFormat(int32_t pixformat);
         int setTestPattern(bool enable, bool walking) override;
         int enableMotionDetection(md_callback_t callback=NULL);
@@ -50,6 +50,8 @@ class HM01B0: public ImageSensor {
         int motionDetected();
         int pollMotionDetection();
         int clearMotionDetection();
+        int setVerticalFlip(bool flip_mode);
+        int setHorizontalMirror(bool mirror_mode);
 
         uint8_t printRegs();
         void debug(Stream &stream);

libraries/Himax_HM0360/hm0360.cpp

@@ -586,10 +586,25 @@ int HM0360::reset()
     return (max_timeout > 0) ? 0 : -1;
 }
 
-int HM0360::setResolution(int32_t resolution)
+int HM0360::setVerticalFlip(bool flip_mode)
+{
+  return -1;
+}
+
+int HM0360::setHorizontalMirror(bool mirror_mode)
+{
+  return -1;
+}
+
+int HM0360::setResolution(int32_t resolution, int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y)
 {
     int ret = 0;
 
+    if (resolution != zoom_resolution)
+    {
+        return -1;
+    }
+
     switch (resolution) {
         case CAMERA_R160x120:
             for(uint32_t i = 0; himax_qqvga_regs[i][0]; i++) {

libraries/Himax_HM0360/hm0360.h

@@ -40,7 +40,7 @@ class HM0360: public ImageSensor {
         bool getMono() { return true; };
         uint32_t getClockFrequency() { return 24000000; };
         int setFrameRate(int32_t framerate);
-        int setResolution(int32_t resolution);
+        int setResolution(int32_t resolution, int32_t zoom_resolution, uint32_t zoom_x, uint32_t zoom_y);
         int setPixelFormat(int32_t pixformat);
         int setTestPattern(bool enable, bool walking) override;
         int enableMotionDetection(md_callback_t callback=NULL);
@@ -50,6 +50,8 @@ class HM0360: public ImageSensor {
         int motionDetected();
         int pollMotionDetection();
         int clearMotionDetection();
+        int setVerticalFlip(bool flip_mode);
+        int setHorizontalMirror(bool mirror_mode);
 
         uint8_t printRegs();
         void debug(Stream &stream);