Image Processing in Python with Pillow and Jupyter Notebook.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "752ccdc9-f13d-4423-8bbd-47f3acfc41ed",
   "metadata": {},
   "source": [
    "# Companion Jupyter Notebook for the Auth0 by Okta Blog Article [_Image Processing in Python with Pillow and Jupyter Notebook_](https://auth0.com/blog/image-processing-in-python-with-pillow/)\n",
    "\n",
    "This notebook contains all the code in the article [_Image Processing in Python with Pillow and Jupyter Notebook_](https://auth0.com/blog/image-processing-in-python-with-pillow/) from the Auth0 by Okta blog.\n",
    "\n",
    "The code was originally written by [Joyce Echessa](https://auth0.com/blog/authors/joyce-echessa/) and updated and converted into a Jupyter Notebook by [Joey de Villa](https://auth0.com/blog/authors/joey-devilla/)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64fedd3c-2481-4384-8212-6b50578b5f28",
   "metadata": {},
   "source": [
    "## Installation and Project Setup\n",
    "\n",
    "You can run any command that works in your system’s command line in Jupyter Notebook by adding the `!` character before it. The commands below install the Pillow module.\n",
    "\n",
    "Uncomment the command appropriate for your system and run this cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "66451c19-9fef-4084-8871-d1f42705b73a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# To install Pillow on Windows, uncomment and run the following line:\n",
    "# ! python -m pip install --upgrade Pillow\n",
    "\n",
    "# To install Pillow on macOS or Linux, uncomment and run the following line:\n",
    "# ! python3 -m pip install --upgrade Pillow"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85ff7967-47c3-4e8d-9c9d-47bee0b24585",
   "metadata": {},
   "source": [
    "### Downloading the images\n",
    "\n",
    "To follow along, you can [download the images](https://github.com/echessa/imgs/blob/master/auth0/image_processing/images.zip?raw=true)\n",
    "(courtesy of [Unsplash](https://unsplash.com/)) used in this notebook.\n",
    "\n",
    "All the code in this notebook will assume the required images are in the same directory as this Jupyter Notebook file."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c45426c-dad8-4e15-99ce-9b8dc02632ca",
   "metadata": {},
   "source": [
    "## The `Image` Object\n",
    "\n",
    "### Loading and displaying an image\n",
    "\n",
    "Of all the classes in Pillow, you’ll probably use `Image` the most. It's defined in the `Image` module and is the class that represents images and provides methods for loading or creating them, processing them, and displaying them.\n",
    "\n",
    "To load an image from a file, use the `open()` function in the `Image` module, which takes the filepath for the image as its argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "61cb3475",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Pillow is a fork of PIL, so we’re importing from PIL\n",
    "from PIL import Image\n",
    "\n",
    "# Load an image from a file\n",
    "puffin_image = Image.open('demo_image.jpg')\n",
    "\n",
    "# To display a Pillow image object in Jupyter Notebook,\n",
    "# just run a cell whose result is that image. \n",
    "puffin_image"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1d72fef4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# If you’re using the Python REPL instead of Jupyter Notebook,\n",
    "# use Image.show() to create a temporary file for the image\n",
    "# and display it with the default system image viewer.\n",
    "puffin_image.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "67df948b-2f2d-4831-a826-ef5e7b5b9496",
   "metadata": {},
   "source": [
    "### Getting information about an image\n",
    "\n",
    "You can get some information about an `Image` object using its attributes. For more on what you can do with the `Image` class, check out the [documentation](https://pillow.readthedocs.io/en/stable/reference/Image.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "45ddd6b8",
   "metadata": {},
   "outputs": [],
   "source": [
    "# The file format of the source file.\n",
    "print(f\"Image's file format: {puffin_image.format}\")\n",
    "\n",
    "# The pixel format used by the image. Typical values are \"1\", \"L\", \"RGB\", or \"CMYK.\"\n",
    "print(f\"Image’s pixel format: {puffin_image.mode}\")\n",
    "\n",
    "# Image size, in pixels. The size is given as a 2-tuple (width, height).\n",
    "print(f\"Image size (width, height): {puffin_image.size}\")\n",
    "\n",
    "# Colour palette table, if any.\n",
    "print(f\"Image palette: {puffin_image.palette}\")\n",
    "\n",
    "# Output:\n",
    "# Image's file format: JPEG\n",
    "# Image’s pixel format: RGB\n",
    "# Image size (width, height): (1920, 1280)\n",
    "# Image palette: None"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92327908-7f41-47e8-a03b-ed56737b518c",
   "metadata": {},
   "source": [
    "## Resizing Images\n",
    "\n",
    "### The `resize()` method\n",
    "\n",
    "`Image`’s `resize()` method takes a two integer tuple argument representing the width and height to which the image should be resized.\n",
    "`resize()` doesn't modify the image but returns another `Image`instance with the new dimensions.\n",
    "\n",
    "Since resize() changes the image’s dimensions to the ones you provide, it doesn’t preserve the image’s aspect ratio unless you purposely do so. The resulting image may end up looking stretched or compressed, which may not be the effect you want. You can see this in the newly-created image from the code above; it looks a bit squished horizontally:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7f5703ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Image.resize() makes a resized copy of the original image.\n",
    "puffin_image_resized = puffin_image.resize((300, 300))\n",
    "puffin_image_resized"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "25521c77-28cd-4323-9360-06f9ea9af05b",
   "metadata": {},
   "source": [
    "### The `thumbnail()` method\n",
    "\n",
    "If you want to resize images and keep their aspect ratios, use `Image`’s `thumbnail()` method instead. Like `resize()`, `thumbnail()` takes a two-integer tuple argument. However, the values in the tuple represent the maximum x- and y-sizes allowed while also preserving the image’s aspect ratio.\n",
    "\n",
    "Note that unlike `resize()`, the `thumbnail()` method does not create a new `Image` instance. Instead, it modifies the original. That’s why the code above first makes a copy of the image.\n",
    "\n",
    "Another significant difference between the `resize()` and `thumbnail()` methods is that `resize()` enalrges an image if given parameters that are larger than the original image, while `thumbnail()` doesn't. \n",
    "\n",
    "For example, given an image of size 400 × 200, a call to `resize((1200, 600))` will create a larger-sized image 1200 pixels wide and 600 pixels tall, along with the expected loss of sharpness. A similar call to `thumbnail((1200, 600))` using the original image will not enlarge the image since the `thumbnail()` method cannot expand an image beyond either of its original dimensions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "139df515",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Unlike Image.resize(), which makes a copy of the original image,\n",
    "# Image.thumbnail() modifies the original image.\n",
    "# The dimensions you provide specify maximum x- and y-size\n",
    "# and the method preserves the image’s aspect ratio.\n",
    "# Let’s make a copy of the original and convert it\n",
    "# into a thumbnail.\n",
    "puffin_image_thumbnail = puffin_image.copy()\n",
    "puffin_image_thumbnail.thumbnail((300, 300))\n",
    "print(f\"The thumbnail image’s size is: {puffin_image_thumbnail.size}.\")\n",
    "puffin_image_thumbnail"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e1480c9-c3d3-4402-ba54-e12adfc2e1f3",
   "metadata": {},
   "source": [
    "### “Pixelating” an image with resizing\n",
    "\n",
    "The rise of [retrocomputing](https://kevinboone.me/retrocomputing.html?i=1) and [retrogaming](https://plarium.com/en/blog/the-rise-in-popularity-of-retro-games/) has created a lot of interest in old-school “pixelated” graphics. \n",
    "\n",
    "You can use a combination of `Image`’s `thumbnail()` and `resize()` methods to turn a modern, high-resolution image into a “retro” one with this code. It takes advantage of the `resize()` method’s optional `resample` parameter, which specifies how to draw pixels when resizing the image. When making an image larger, the “nearest neighbor” resampling method creates a “retro” pixel effect."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b7909217",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Pixelate the image\n",
    "\n",
    "# Shrink the image while preserving the aspect ratio.\n",
    "puffin_image_150px = puffin_image.copy()\n",
    "puffin_image_150px.thumbnail((125, 125))\n",
    "\n",
    "# Scale the image back up to its original size,\n",
    "# but using “nearest neighbor” resampling.\n",
    "puffin_image_pixelated = puffin_image_150px.resize((1920, 1200), resample = Image.Resampling.NEAREST)\n",
    "puffin_image_pixelated"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "870514f0-40d7-4846-848a-9eae8f271648",
   "metadata": {},
   "source": [
    "## Flipping Images\n",
    "\n",
    "Pillow’s `Image` class provides the `transpose()` method for quick image flipping. `transpose()` takes the following arguments:\n",
    "\n",
    "- `Image.FLIP_LEFT_RIGHT`\n",
    "- `Image.FLIP_TOP_BOTTOM`\n",
    "- `Image.ROTATE_90`\n",
    "- `Image.ROTATE_180`\n",
    "- `Image.ROTATE_270`\n",
    "- `Image.TRANSPOSE`\n",
    "- `Image.TRANSVERSE`\n",
    "\n",
    "Here’s how you would create a horizontal mirror image of the original:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e85b752b",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_lr_flip = puffin_image.transpose(Image.FLIP_LEFT_RIGHT)\n",
    "image_lr_flip"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ecdde60-d273-4daa-a7bb-7780681b5301",
   "metadata": {},
   "source": [
    "Providing the `transpose()` method with `Image.FLIP_TOP_BOTTOM` creates a vertical mirror image:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ac63f163",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_tb_flip = puffin_image.transpose(Image.FLIP_TOP_BOTTOM)\n",
    "image_tb_flip"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "241b9c6f-6ead-4f8f-9e66-e3faa866f53d",
   "metadata": {},
   "source": [
    "The `Image.ROTATE_90`, `Image.ROTATE_180`, `Image.ROTATE_270` arguments rotate the image counterclockwise 90, 180, and 270 degrees, respectively. The following rotates the image 180 degrees:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27a0c4a9",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_rot_180 = puffin_image.transpose(Image.ROTATE_180)\n",
    "image_rot_180"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ad03f5d-59a9-4ceb-87f2-737141efc5b7",
   "metadata": {},
   "source": [
    "_Transposing_ an image means mirroring it along the diagonal line that runs from the top left to the bottom right, while _tranversing_ it means mirroring it along the diagonal line running from the bottom left to the top right. This is yet another case where _showing_ is better than telling, so let’s make the code do that."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ad25689",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Transposing an image mirrors it along the line running from\n",
    "# the top left to the bottom right.\n",
    "image_transpose = puffin_image.transpose(Image.TRANSPOSE)\n",
    "image_transpose"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "56c4e81c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Transversing an image mirrors it along the line running from\n",
    "# the bottom left to the top right.\n",
    "image_transverse = puffin_image.transpose(Image.TRANSVERSE)\n",
    "image_transverse"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a845ed84-6a4a-4d50-96b0-e9eb537b2ba7",
   "metadata": {},
   "source": [
    "## Rotating Images\n",
    "\n",
    "You can rotate images with Pillow using `Image`’s `rotate()` method. This takes an integer or float argument representing the degrees to rotate an image (positive for counterclockwise, negative for clockwise) and returns a new `Image` object for the rotated image.\n",
    "\n",
    "By default, the rotated image keeps the dimensions of the original image. This means that for angles other than multiples of 180, the image will be cut and/or padded to fit the original dimensions. Consider this code, which rotates an image 90 degrees counterclockwise:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a7f521e2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Image.rotate() uses degrees, and positive rotation\n",
    "# is *counterclockwise*.\n",
    "# Rotating an image preserves its dimensions by default,\n",
    "# so the image may be clipped.\n",
    "puffin_image_rot_90 = puffin_image.rotate(90)\n",
    "puffin_image_rot_90"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1427e56a-6afa-4e22-bf7a-ef940a670681",
   "metadata": {},
   "source": [
    "Notice that the image has been “clipped” to fit the original height, and its sides have been padded with black background (on some operating systems, the padding will be made of transparent pixels) to fit the original width. \n",
    "\n",
    "The example below, where the original image is rotated 18 degrees counterclockwise, shows this “clipping” effect more clearly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "25cbb66c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Rotate the image by 18 degrees.\n",
    "puffin_image_rot_18 = puffin_image.rotate(18)\n",
    "puffin_image_rot_18"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c389118-daab-4786-8287-ad6019de4562",
   "metadata": {},
   "source": [
    "To expand the dimensions of the rotated image to fit the entire view, you pass a second argument to `rotate()` as shown below. Now the contents of the image will be fully visible, and the dimensions of the image will have increased to account for this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b86471e2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Setting Image.rotate()’s optional “expand” parameter to True\n",
    "# avoids clipping by scaling the resulting image to accomodate\n",
    "# the rotation.\n",
    "puffin_image_rot_18_expand = puffin_image.rotate(18, expand=True)\n",
    "print(f\"Original image dimensions: {puffin_image.size}\")\n",
    "print(f\"Rotated expanded image dimensions: {puffin_image_rot_18_expand.size}\")\n",
    "puffin_image_rot_18_expand"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f93dff1d-a6f0-4cbf-9711-f9dbb8d21b22",
   "metadata": {},
   "source": [
    "## Cropping Images\n",
    "\n",
    "Use `Image`’s `crop()` method to create a new image by cropping a section from an existing one. This method takes a 4-tuple that defines the position and size of the cropped region, as shown in the method call example below:\n",
    "\n",
    "```python\n",
    "my_image.crop(x_left, y_top, x_right, y_bottom)\n",
    "```\n",
    "\n",
    "Pillow’s coordinate system starts with (0, 0) in the upper left corner, with x increasing from left to right and y increasing from top to bottom:\n",
    "\n",
    "![Pillow’s coordinate system](https://images.ctfassets.net/23aumh6u8s0i/3OMipn13HefqrmEi8Lnvrh/b653ae86f49a72357bcec52ca4ff71b2/pillow_coordinate_system.png)\n",
    "\n",
    "The cropped section includes the left column and the upper row of pixels and goes up to — but _doesn't_ include — the right column and bottom row of pixels. This is better explained with a diagram:\n",
    "\n",
    "![Pixel diagram showing the crop rectangle.](https://images.ctfassets.net/23aumh6u8s0i/0Er4ZZjUekX4GEwKaEzpj/77e63852e9403538f049816028e13e5a/crop_rectangle.png)\n",
    "\n",
    "Here’s an example that creates a new image by cropping the rectangle described below:\n",
    "\n",
    "- left: 200\n",
    "- top: 300\n",
    "- right: 700\n",
    "- bottom: 600"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "33194e01",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Image.crop() returns a new image made from \n",
    "# the rectangular area of the original specified by\n",
    "# a 4-tuple (x_left, y_top, x_right, y_bottom).\n",
    "box = (200, 300, 700, 600)\n",
    "puffin_image_cropped = puffin_image.crop(box)\n",
    "print(f\"The cropped image’s size is: {puffin_image_cropped.size}.\")\n",
    "puffin_image_cropped"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e6159a0-9e49-4e10-a49a-17e1f4265eea",
   "metadata": {},
   "source": [
    "## Pasting an Image onto Another Image\n",
    "\n",
    "Pillow enables you to paste an image onto another one. Some example use cases where this could be useful is in the protection of publicly available images by adding watermarks on them, the branding of images by adding a company logo, and in any other case where there is a need to merge two images.\n",
    "\n",
    "### Pasting without an opacity mask\n",
    "\n",
    "The `Image` class’ `paste()` method pastes another image onto the current one. This is useful for protecting publicly available images by adding watermarks, branding images with a company logo, or simply creating compositions of two or more images.\n",
    "\n",
    "`paste()` is unlike many `Image` methods (but like `thumbnail()`) in that it modifies the `Image` object in place rather than return a new `one. Because of this, we'll first make a copy of our puffin image before performing the paste so that we can continue with the other examples using the original."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7a2b8b60",
   "metadata": {},
   "outputs": [],
   "source": [
    "python_logo_image = Image.open('logo.png')\n",
    "python_logo_image"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f50e3c9b-0e95-4675-a50d-966926b9f05a",
   "metadata": {},
   "source": [
    "The code above loads a new image, `logo.png` and makes a copy of the puffin image. We want to paste the logo image onto the puffin image copy at the bottom right corner. The code calculates the coordinates for pasting the logo, which can be:\n",
    "\n",
    "- A 2-tuple specifying the upper left corner of the pasted image, \n",
    "- a 4-tuple defining the left, upper, right, and lower pixel coordinates of the pasted image, or\n",
    "- `None`, which simply pastes the image at the coordinates (0, 0)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e94333f3",
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Pasting without an opacity mask\n",
    "\n",
    "python_logo_image = Image.open('logo.png')\n",
    "\n",
    "# paste() modifies the image in place,\n",
    "#so let’s work with a copy.\n",
    "puffin_image_with_logo = puffin_image.copy()\n",
    "\n",
    "# We want the logo at the puffin image’s lower right corner.\n",
    "logo_position = (\n",
    "    (puffin_image_with_logo.width - python_logo_image.width), \n",
    "    (puffin_image_with_logo.height - python_logo_image.height)\n",
    ")\n",
    "\n",
    "# Image.paste() pastes another image onto the current image.\n",
    "puffin_image_with_logo.paste(python_logo_image, logo_position)\n",
    "puffin_image_with_logo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f823274-d4c1-4085-8b6d-884c7d690e6f",
   "metadata": {},
   "source": [
    "### Pasting with an opacity mask\n",
    "\n",
    "When you perform a `paste()`, transparent pixels are pasted as solid pixels by default. Hence the black (white on some OSs) box surrounding the logo. Most of the time, this isn't what you want. You can't have your watermark covering the underlying image's content. We would rather have transparent pixels appear as such.\n",
    "\n",
    "To achieve this, you need to pass in an optional third argument to the `paste()` method. This argument is an `Image` object that acts as an _opacity mask_.\n",
    "\n",
    "An opacity mask is an `Image` object where only the alpha value is significant, while  its green, red, and blue values are ignored. If a mask is provided as an optional third argument to `paste()`, the method updates only the regions indicated by the mask. You can use either `1`, `L`, or `RGBA` images for masks. Pasting an RGBA image and also using it as the mask pastes only the opaque portion of the image — not its transparent background."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6500ffd9",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Pasting with an opacity mask\n",
    "puffin_image_with_logo = puffin_image.copy()\n",
    "\n",
    "# Pasting the logo while using it as its own opacity mask\n",
    "# ensures that transparent pixels are rendered properly.\n",
    "puffin_image_with_logo.paste(python_logo_image, logo_position, python_logo_image)\n",
    "puffin_image_with_logo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92f72f49-b124-45db-ade8-a79ba49f2a31",
   "metadata": {},
   "source": [
    "## Drawing on Images\n",
    "\n",
    "With Pillow, you can also draw on an image using the [ImageDraw](https://pillow.readthedocs.io/en/stable/reference/ImageDraw.html) module. You can draw lines, points, ellipses, rectangles, arcs, bitmaps, chords, pie slices, polygons, shapes, and text.\n",
    "\n",
    "The code below draws a black rectangle with a fine white outline near the lower left corner of the puffin image from the previous code example. It then draws the text message “Hello, puffins!” in large white text inside the rectangle:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0b467e4e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# The ImageDraw module provides basic 2-D graphics and text drawing.\n",
    "from PIL import ImageDraw\n",
    "\n",
    "puffin_image_with_title = puffin_image_with_logo.copy()\n",
    "\n",
    "# ImageDraw.Draw() takes an image as an argument and returns\n",
    "# an object we can use as a drawing surface.\n",
    "title_canvas = ImageDraw.Draw(puffin_image_with_title)\n",
    "title_canvas.rectangle((50, 1050, 830, 1210), outline='white', fill='black')\n",
    "title_canvas.text((70, 1050), 'Hello, puffins!', fill='white', font_size=120)\n",
    "puffin_image_with_title"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c11d6e55-13cb-4305-8064-753dc143b1a8",
   "metadata": {},
   "source": [
    "## Transforming Image Colors\n",
    "\n",
    "### Converting an image from color to grayscale\n",
    "\n",
    "`Image`’s `convert()` method can convert images between different pixel representations, such as the RGB (red-green-blue) format used by screens and the CMYK (cyan-magenta-yellow-black) format used in printing. Like most `Image` methods, `convert()` returns a new `Image` object.\n",
    "\n",
    "`convert()` also supports converting images to the `L` (luminance) format, which is a grayscale image format. The code below converts our puffin image from color to grayscale monochrome:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a1e6afe",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Convert image to grayscale\n",
    "grayscale_image = puffin_image.convert(\"L\")\n",
    "print(f\"Original image mode: {puffin_image.mode}\") # Output: RGB\n",
    "print(f\"Grayscale image mode: {grayscale_image.mode}\") # Output: L\n",
    "grayscale_image\n",
    "\n",
    "# Output:\n",
    "# Original image mode: RGB\n",
    "# Grayscale image mode: L"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22ce18b6-098f-4cdf-830f-3dec8d6bca73",
   "metadata": {},
   "source": [
    "### Reducing the number of colors in an image\n",
    "\n",
    "In addition to pixelation, another way to make an image look “retro” is to reduce the number of colors it uses to 256 or fewer. You can do this with a single call to `Image`’s `quantize()` method.\n",
    "\n",
    "The code below reduces the number of colors in our puffin photo to 16, producing an effect that should remind you of 1990s computer graphics:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9e20561c",
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Image.quantize() creates a copy of the image in palette mode\n",
    "# and reduces the colors to the given number.\n",
    "\n",
    "# Reduce the image to a 16-color palette:\n",
    "puffin_image_quantize = puffin_image.quantize(16)\n",
    "print(f\"Image’s pixel format: {puffin_image_quantize.mode}\")\n",
    "puffin_image_quantize"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "912d3f32-c0f9-4fd9-95fb-670de4319960",
   "metadata": {},
   "source": [
    "### Splitting and Merging Bands\n",
    "\n",
    "The `split()` method of Pillow’s `Image` class makes it possible to split a multi-band image into individual bands, such as the R, G, and B bands from an RGB image. `split()` creates new images, each containing one band from the original image.\n",
    "\n",
    "`split()` has an inverse function, `merge()`, which merges a set of single band images into a new multi-band image. `merge()` takes a mode and a tuple of images and combines them into a new image.\n",
    "\n",
    "The code below takes the original “puffin” image, splits it into three images — one for each of the R, G, and B bands — and then merges them so that:\n",
    "\n",
    "- The blue color information replaces the original red color information\n",
    "- The red color information replaces the original green color information\n",
    "- The green color information replaces the original blue color information"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee51edee",
   "metadata": {},
   "outputs": [],
   "source": [
    "(red_channel, \n",
    " green_channel, \n",
    " blue_channel) = puffin_image.split()\n",
    "\n",
    "print(f\"Image’s pixel format: {puffin_image.mode}\") # Output: RGB\n",
    "print(f\"Red channel’s pixel format: {red_channel.mode}\") # Output: L\n",
    "print(f\"Green channel’s pixel format: {green_channel.mode}\") # Output: L\n",
    "print(f\"Blue channel’s pixel format: {blue_channel.mode}\") # Output: L\n",
    "\n",
    "# Output:\n",
    "# Image’s pixel format: RGB\n",
    "# Red channel’s pixel format: L\n",
    "# Green channel’s pixel format: L\n",
    "# Blue channel’s pixel format: L\n",
    "\n",
    "grb_image = Image.merge(\"RGB\", (blue_channel, red_channel, green_channel))\n",
    "grb_image"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1c0c649-3433-4ed7-806f-b97de8d8211e",
   "metadata": {},
   "source": [
    "## Enhancing Images\n",
    "\n",
    "### Enhancing contrast\n",
    "\n",
    "Pillow allows you to enhance an image by adjusting its contrast, color, brightness, and sharpness using classes in the `ImageEnhance` module.\n",
    "\n",
    "### Enhancing contrast\n",
    "\n",
    "Here’s code that boosts the contrast of the “puffin” image. The code above adjusts the image contrast by a factor of 3; smaller values will produce more subtle effects. A factor of 1.0 returns a copy of the original image; lower factors produce images with lower contrast."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cd1088ee",
   "metadata": {},
   "outputs": [],
   "source": [
    "from PIL import ImageEnhance\n",
    "\n",
    "puffin_image_enhanced_contrast = ImageEnhance.Contrast(puffin_image)\n",
    "puffin_image_enhanced_contrast.enhance(3.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ad14e95a-e808-4ccd-b39a-a7c5f5d87a7f",
   "metadata": {},
   "source": [
    "### Enhancing color\n",
    "\n",
    "Below, we increase the color of the image. If we used a factor of `0.0`, we would get a black and white image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6486f6f8",
   "metadata": {},
   "outputs": [],
   "source": [
    "puffin_image_enhanced_color = ImageEnhance.Color(puffin_image)\n",
    "puffin_image_enhanced_color.enhance(3.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba403c8a-4863-4b5b-a863-6b1a746cbe88",
   "metadata": {},
   "source": [
    "### Enhancing brightness\n",
    "\n",
    "Below we make the image brighter. A factor of `0.0` would produce a black image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9e65fc81",
   "metadata": {},
   "outputs": [],
   "source": [
    "puffin_image_enhanced_brightness = ImageEnhance.Brightness(puffin_image)\n",
    "puffin_image_enhanced_brightness.enhance(3.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db95c3cf-2fe4-4c65-9646-7d6053470616",
   "metadata": {},
   "source": [
    "### Enhancing sharpness\n",
    "\n",
    "Below we make the image brighter. A factor of `0.0` would produce a black image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b84719d6",
   "metadata": {},
   "outputs": [],
   "source": [
    "puffin_image_enhanced_sharpness = ImageEnhance.Sharpness(puffin_image)\n",
    "puffin_image_enhanced_sharpness.enhance(3.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "744df1b5-a05a-48a3-83f0-0f38e16f4976",
   "metadata": {},
   "source": [
    "## Saving Your Image Work\n",
    "\n",
    "To save an image, use `Image`’s `save()` method. For example, here’s how you’d save the image from the _Enhancing sharpness_ exercise above as a PNG file. Pillow sees the file extension has been specified as `.png` and converts it to PNG before saving it to a file. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9a7d6f7b-6b6c-4264-9926-2403ed0e5e78",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save the sharpened puffin image as a .png file\n",
    "puffin_image_enhanced_sharpness.save(\"puffins_sharp.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0303afe8-b155-428f-9f7e-f71c6fb51afa",
   "metadata": {},
   "source": [
    "To save it as a JPEG image, use this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14582987-81c2-4bdd-93b8-b4053933a178",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save the sharpened puffin image as a .jpg file\n",
    "puffin_image_enhanced_sharpness.save(\"puffins_sharp.jpg\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dae581a9-f75d-45ed-9336-4ed3d332f7f0",
   "metadata": {},
   "source": [
    "You can provide a second argument to `save()` to explicitly specify a file format. `puffin_image_enhanced_sharpness.save(\"puffins_sharp.png\", \"PNG\")` will do the same thing as the previous save(). Usually, it's unnecessary to supply this second argument as Pillow will determine the file storage format to use from the filename extension, but if you're using non-standard extensions, you should always specify the format this way."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}