Merge pull request #150 from UBC-MDS/fix-improve-introduction-tutorial

improve introduction tutorial from peer review

docs/first_things_first.ipynb

@@ -10,26 +10,36 @@
     "\n",
     "Before we explore the available functions, it's important to understand how to work with image data. This tutorial will guide you through the process of loading images from various sources, visualizing the results and converting them into numpy arrays. We will also cover the key differences between grayscale and RGB images, and explain when and why you might need to perform color scale conversions.\n",
     "\n",
-    "By the end of this tutorial, you'll have the foundational knowledge needed to effectively use the SharpEdge functions and interpret their effects on images."
+    "By the end of this tutorial, you'll have the foundational knowledge needed to effectively use the SharpEdge functions and interpret their effects on images.\n",
+    "\n",
+    "> If you are not familiar with how diffrent colors are represented numerically using RGB 0-1 or RGB 0-255, we recommend you check out this website [RGB Color Picker](https://rgbcolorpicker.com/0-1)."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Import Necessary Libraries"
+    "## Import Necessary Libraries\n",
+    "\n",
+    "Let us introduce you to the libraries used in this software package and/or tutorial:\n",
+    "\n",
+    "- **NumPy**: The core package in software for handling image data as arrays, enabling efficient manipulation of pixel values.\n",
+    "- **Pillow**: Enable image loading. Included as dependency in software for ease of user usage, not utilized in software functions.\n",
+    "- **Matplotlib**: Provide image display capabilities. Included as dependency in software for ease of user usage, not utilized in software functions..\n",
+    "- **skimage (scikit-image)**: Used purely for providing sample images for demonstration purposes in the tutorial."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
     "# Importing necessary libraries\n",
     "import numpy as np\n",
+    "from PIL import Image\n",
     "import matplotlib.pyplot as plt\n",
-    "from skimage import io, data"
+    "from skimage import data"
    ]
   },
   {
@@ -49,12 +59,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 50,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [],
    "source": [
     "# Load image locally available\n",
-    "image_disk = io.imread('../tests/test_image/seam_carve_input_2.png')"
+    "image_disk = Image.open('../tests/test_image/seam_carve_input_2.png')"
    ]
   },
   {
@@ -67,7 +77,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 51,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -85,7 +95,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 52,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
@@ -108,7 +118,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 53,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [
     {
@@ -144,7 +154,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 54,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [
     {
@@ -212,7 +222,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 55,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [
     {
@@ -247,7 +257,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 42,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {
@@ -269,21 +279,43 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Color Scale Conversion (If Needed)\n",
+    "## Color Scale Conversion (If Needed)\n",
     "\n",
     "As mentioned above, to ensure input range compatibility with functions within the SharpEdge package, it is necessary to convert the color scale of the image when working with images in the [0, 1] range. Below is one way to perform this conversion:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 56,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [],
    "source": [
     "# Convert image from [0,1] to [0,255]\n",
     "# image_converted = (image_to_convert * 255).astype(np.uint8)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Export Image (If Needed)\n",
+    "After transforming your images with our package, you might want to export the result to local disk. You can use the `plt.imsave()` function for this. Make sure to set the correct `vmin` and `vmax` to match the value range in your image array.\n",
+    "\n",
+    "- If your image is grayscale (2D array), you can set `cmap=\"gray\"`.\n",
+    "- If it’s an RGB image (3D array with shape (H, W, 3)), simply omit the cmap parameter."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Save output image array as image file in local disk\n",
+    "# plt.imsave(fname='SAMPLE_GRAY.png', arr=image_skimage, cmap=\"gray\", vmin=0, vmax=255)\n",
+    "# plt.imsave(fname='SAMPLE_RGB.png', arr=image_disk, vmin=0, vmax=1)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},