Image Classification: Add docstrings to exercises (#369)

* Add docstrings to the exercises in order to make them more clear

* Small fixes

---------

Co-authored-by: Edoardo Baldi <edoardob90@gmail.com>

Author: fabioacl

31_image_classification.ipynb

@@ -749,7 +749,20 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_scale_image(img, scale_factor: float):\n",
+    "import numpy as np\n",
+    "def solution_scale_image(img: np.ndarray, scale_factor: float):\n",
+    "    \"\"\"\n",
+    "    The function takes an image as input and rescales it to a new dimension.\n",
+    "    For that, you need to compute the new dimensions of the image using the scale factor \n",
+    "    and then use OpenCV's `cv2.resize` function to resize the image, e.g., `cv2.resize(img, (new_width, new_height))`.\n",
+    "\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "        scale_factor (float): The factor by which to scale the image.\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The scaled image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -798,7 +811,26 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_crop_image(img, x: int, y: int, width: int, height: int):\n",
+    "import numpy as np\n",
+    "def solution_crop_image(img: np.ndarray, x: int, y: int, width: int, height: int):\n",
+    "    \"\"\"\n",
+    "    The function takes an image as input and crops it to a specified rectangular region.\n",
+    "    In OpenCV, images are represented as NumPy arrays. You can crop the image by \n",
+    "    using array slicing, keeping in mind that the first dimension is the y-axis (rows) \n",
+    "    and the second dimension is the x-axis (columns): `img[y_start:y_end, x_start:x_end]`. \n",
+    "    You will need to calculate these start and end coordinates using the provided \n",
+    "    x, y, width, and height parameters.\n",
+    "\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "        x (int): The starting x-coordinate (column) of the crop.\n",
+    "        y (int): The starting y-coordinate (row) of the crop.\n",
+    "        width (int): The width of the cropped region.\n",
+    "        height (int): The height of the cropped region.\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The cropped image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -847,7 +879,22 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_horizontal_flip_image(img):\n",
+    "import numpy as np\n",
+    "def solution_horizontal_flip_image(img: np.ndarray):\n",
+    "    \"\"\"\n",
+    "    The function takes an image as input and flips it horizontally (creating a mirror image).\n",
+    "    To do this, use OpenCV's `cv2.flip(src, flipCode)` function. The `flipCode` integer \n",
+    "    determines the axis to flip around: \n",
+    "    - Use 1 for a horizontal flip (around the y-axis).\n",
+    "    - Use 0 for a vertical flip (around the x-axis).\n",
+    "    - Use -1 for both axes.\n",
+    "\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The horizontally flipped image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -896,7 +943,22 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_vertical_flip_image(img):\n",
+    "import numpy as np\n",
+    "def solution_vertical_flip_image(img: np.ndarray):\n",
+    "    \"\"\"\n",
+    "    The function takes an image as input and flips it vertically.\n",
+    "    To do this, use OpenCV's `cv2.flip(src, flipCode)` function. The `flipCode` integer \n",
+    "    determines the axis to flip around: \n",
+    "    - Use 1 for a horizontal flip (around the y-axis).\n",
+    "    - Use 0 for a vertical flip (around the x-axis).\n",
+    "    - Use -1 for both axes.\n",
+    "\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The vertically flipped image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -945,7 +1007,37 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_rotate_image(img, angle: float):\n",
+    "import numpy as np\n",
+    "def solution_rotate_image(img: np.ndarray, angle: float):\n",
+    "    \"\"\"\n",
+    "    The function takes an image as input and rotates it by a specified angle. \n",
+    "    To ensure the corners of the image are not cropped after rotation, you must \n",
+    "    calculate a new bounding box and adjust the rotation matrix. \n",
+    "    \n",
+    "    Follow these steps:\n",
+    "    1. Get the height and width.\n",
+    "    2. Find the center point of the image.\n",
+    "    3. Get the starting matrix: `mat = cv2.getRotationMatrix2D(center, angle, 1.0)`\n",
+    "    \n",
+    "    4. Calculate the new canvas size using this trigonometry:\n",
+    "       cos = np.abs(mat[0, 0])\n",
+    "       sin = np.abs(mat[0, 1])\n",
+    "       new_w = int((h * sin) + (w * cos))\n",
+    "       new_h = int((h * cos) + (w * sin))\n",
+    "       \n",
+    "    5. Adjust the matrix so the image is shifted to the middle of the new canvas:\n",
+    "       mat[0, 2] += (new_w / 2) - center[0]\n",
+    "       mat[1, 2] += (new_h / 2) - center[1]\n",
+    "       \n",
+    "    6. Return the final rotated image using: `cv2.warpAffine(img, mat, (new_w, new_h))`\n",
+    "\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "        angle (float): The angle of rotation in degrees.\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The rotated image on a properly sized canvas.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -1009,7 +1101,20 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_average_filter(img, kernel_size = (5, 5)):\n",
+    "import numpy as np\n",
+    "def solution_average_filter(img: np.ndarray, kernel_size: tuple = (5, 5)):\n",
+    "    \"\"\"\n",
+    "    Applies an average filter to blur the image using a specific kernel size.\n",
+    "    For that, you need to use OpenCV's `cv2.blur()` function, which takes the image and the kernel size as arguments.\n",
+    "    `cv2.blur()` requires two arguments: the image, and the size of the kernel.\n",
+    "    \n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "        kernel_size (tuple): The width and height of the blurring window. Default is (5, 5).\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The blurred image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -1058,7 +1163,20 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_median_filter(img, ksize):\n",
+    "import numpy as np\n",
+    "def solution_median_filter(img: np.ndarray, ksize: int):\n",
+    "    \"\"\"\n",
+    "    Applies a median filter to the image using a specific kernel size.\n",
+    "    For that, you need to use OpenCV's `cv2.medianBlur()` function, which takes the image and the kernel size as arguments.\n",
+    "    `cv2.medianBlur()` requires two arguments: the image, and the size of the kernel.\n",
+    "    \n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "        ksize (int): The size of the median filter kernel. Must be a positive odd integer.\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The blurred image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -1107,7 +1225,21 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_gaussian_filter(img, kernel_size = (5, 5), sigma = 0):\n",
+    "import numpy as np\n",
+    "def solution_gaussian_filter(img: np.ndarray, kernel_size: tuple = (5, 5), sigma: float = 0):\n",
+    "    \"\"\"\n",
+    "    Applies a Gaussian filter to the image using a specific kernel size and sigma value.\n",
+    "    For that, you need to use OpenCV's `cv2.GaussianBlur()` function, which takes the image, kernel size, and sigma as arguments.\n",
+    "    `cv2.GaussianBlur()` requires three arguments: the image, the size of the kernel, and the sigma value.\n",
+    "\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "        kernel_size (tuple): The width and height of the Gaussian kernel. Default is (5, 5).\n",
+    "        sigma (float): The standard deviation of the Gaussian kernel. Default is 0.\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The blurred image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -1170,7 +1302,18 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_adjust_brightness(img, brightness_value):\n",
+    "import numpy as np\n",
+    "def solution_adjust_brightness(img: np.ndarray, brightness_value: float):\n",
+    "    \"\"\"\n",
+    "    Adjusts the brightness of the image by adding a specified value to all pixel intensities.\n",
+    "    To adjust the brightness, you can use OpenCV's `cv2.convertScaleAbs()` function, which scales, calculates absolute values, and converts the result to 8-bit.\n",
+    "    `cv2.convertScaleAbs()` requires three arguments: the image, the alpha value (which is 1 for no scaling), and the beta value (which is the brightness adjustment value).\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "        brightness_value (float): The value to add to the pixel intensities. Positive values increase brightness, while negative values decrease it.\n",
+    "    Returns:\n",
+    "        np.ndarray: The brightness-adjusted image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -1222,7 +1365,18 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_adjust_contrast(img, contrast_value):\n",
+    "import numpy as np\n",
+    "def solution_adjust_contrast(img: np.ndarray, contrast_value: float):\n",
+    "    \"\"\"\n",
+    "    Adjusts the contrast of the image by scaling the pixel intensities.\n",
+    "    To adjust the contrast, you can use OpenCV's `cv2.convertScaleAbs()` function, which scales, calculates absolute values, and converts the result to 8-bit.\n",
+    "    `cv2.convertScaleAbs()` requires three arguments: the image, the alpha value (which is the contrast adjustment value), and the beta value (which is 0 for no additional brightness adjustment).\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image.\n",
+    "        contrast_value (float): The value to scale the pixel intensities. Values greater than 1 increase contrast, while values between 0 and 1 decrease it.\n",
+    "    Returns:\n",
+    "        np.ndarray: The contrast-adjusted image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"
@@ -1274,7 +1428,28 @@
     "%%ipytest\n",
     "\n",
     "import cv2\n",
-    "def solution_adjust_saturation(img, saturation_factor):\n",
+    "import numpy as np\n",
+    "def solution_adjust_saturation(img: np.ndarray, saturation_factor: float):\n",
+    "    \"\"\"\n",
+    "    Adjusts the saturation of the image by modifying the saturation channel in the HSV color space.\n",
+    "    To do that you need to convert the image from RGB to HSV, adjust the saturation channel, and then convert it back to RGB.\n",
+    "    Follow these steps:\n",
+    "    1. It is very hard to change saturation in standard RGB format because the colors are mixed. \n",
+    "       First, convert the image to HSV format (`cv2.COLOR_RGB2HSV`) format using: `hsv_img = cv2.cvtColor(img, cv2.COLOR_RGB2HSV)`.\n",
+    "    2. Now that the image is in HSV, you can isolate the Saturation. Split the image into its three separate channels using: `cv2.split(hsv_img)`.\n",
+    "    3. Multiply the saturation channel by the `saturation_factor`. \n",
+    "    4. Pixel values cannot go above 255 or below 0. Use NumPy's clip function (`np.clip`) to enforce this limit.\n",
+    "    5. Math operations can change the data type. Force the new saturation channel back into standard image format `uint8`.\n",
+    "    6. Put the three channels back together in the correct order using `cv2.merge()`.\n",
+    "    7. Finally, convert the image back to normal RGB format (`cv2.COLOR_HSV2RGB`).\n",
+    "\n",
+    "    Args:\n",
+    "        img (np.ndarray): The input image in RGB format.\n",
+    "        saturation_factor (float): The multiplier for the saturation channel. Values greater than 1 increase saturation, while values between 0 and 1 decrease it.\n",
+    "\n",
+    "    Returns:\n",
+    "        np.ndarray: The saturation-adjusted image.\n",
+    "    \"\"\"\n",
     "    # Start your code here\n",
     "    return\n",
     "    # End your code here"

tutorial/tests/test_31_image_classification.py

@@ -21,6 +21,7 @@ def test_scale_image(scale_factor, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, scale_factor)
     image_reference = reference_scale_image(image, scale_factor)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert image_test.shape == image_reference.shape
 
 
@@ -36,6 +37,7 @@ def test_crop_image(x, y, width, height, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, x, y, width, height)
     image_reference = reference_crop_image(image, x, y, width, height)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert image_test.shape == image_reference.shape
 
 
@@ -47,6 +49,7 @@ def test_horizontal_flip_image(function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image)
     image_reference = reference_horizontal_flip_image(image)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)
 
 
@@ -58,6 +61,7 @@ def test_vertical_flip_image(function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image)
     image_reference = reference_vertical_flip_image(image)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)
 
 
@@ -85,6 +89,7 @@ def test_rotate_image(angle, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, angle)
     image_reference = reference_rotate_image(image, angle)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)
 
 
@@ -97,6 +102,7 @@ def test_average_filter(kernel_size, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, kernel_size)
     image_reference = reference_average_filter(image, kernel_size)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)
 
 
@@ -109,6 +115,7 @@ def test_median_filter(ksize, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, ksize)
     image_reference = reference_median_filter(image, ksize)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)
 
 
@@ -123,6 +130,7 @@ def test_gaussian_filter(kernel_size, sigma, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, kernel_size, sigma)
     image_reference = reference_gaussian_filter(image, kernel_size, sigma)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)
 
 
@@ -135,6 +143,7 @@ def test_adjust_brightness(brightness_value, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, brightness_value)
     image_reference = reference_adjust_brightness(image, brightness_value)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)
 
 
@@ -147,6 +156,7 @@ def test_adjust_contrast(contrast_value, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, contrast_value)
     image_reference = reference_adjust_contrast(image, contrast_value)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)
 
 
@@ -172,4 +182,5 @@ def test_adjust_saturation(saturation_factor, function_to_test):
     image = np.ones((32, 32, 3), dtype=np.uint8) * 255
     image_test = function_to_test(image, saturation_factor)
     image_reference = reference_adjust_saturation(image, saturation_factor)
+    assert isinstance(image_test, np.ndarray), "Your function should return an image."
     assert np.allclose(image_test, image_reference)