How To Gradio: Components — Image

10 min readJan 19, 2024

In this series, Components, we are going to assist you in becoming familiar with using the various available Gradio components so that you can build apps more efficiently using the Gradio library.

Components are an essential part of the Gradio library. They create the interactive and visual elements of the user interface. Gradio component's major function is accepting user input and displaying output for your Gradio app. To use Gradio components effectively, it’s important to understand how data flows within the Gradio app.

If you would like to develop a better understanding of how Gradio components work, the following articles are a great guide:

Gradio’s Image Component

Use the image component if you need to upload or display image data.

Image Input Component:

Users can upload an image from a file, webcam, or clipboard.
The uploaded image data is passed to the linked Gradio interface/blocks function as the datatype numpy.array, PIL.Image or str file path depending on components type= parameter.

Image Output Component:

Displays an image to the user.
Displayed image data should be returned by the Gradio interface/blocks function as the datatype numpy.array, PIL.Image or str or pathlib.Path file path to an image.

String Shortcut: “image”

Image Component as Input Component (left) and Output Component (right).

How To Use: The Gradio Image Component As An Input Component

Task: Allow users to upload an image from a file, webcam, or clipboard.

Datatype passed to Python function: numpy.array, PIL.Image or str file path.

The datatype used by the Image component can be controlled using the type= parameter.

Image adapted from https://www.gradio.app/docs/image

It’s important to remember that the default datatype used by the Gradio image component is numpy.array. This means that if you don’t set the datatype using the type=parameter, Gradio will automatically pass your image data to the function as numpy.array.

default: “numpy” = numpy.array

import gradio as gr

def show_image(img):
    print(type(img))
    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component"), # type= parameter not set. Defaults to numpy.array
    outputs=gr.Image(label="Output Image Component"),
)

app.launch()

Image of print() result in Python Console

The code snippet above demonstrates that the image input component passes the image data as numpy.array by default.

The line of code print(type(img)) prints to the console the data type of the “img” object passed to the Python function by the image input component.

As you can see from the Python console image, the datatype is ‘numpy.ndarry’

type=”numpy” numpy.array

“”numpy” converts the image to a numpy array with shape (height, width, 3) and values from 0 to 255"

import gradio as gr

def show_image(img):
    print(type(img))
    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", type="numpy"), # Set image component's type= parameter to "numpy" numpy.array
    outputs=gr.Image(label="Output Image Component"),
)

app.launch()

In the above code snippet, the image input component’s type=parameter is set as “numpy”. In this case, the image input component will always pass the image data to the Python function as a numpy array with shape (height, width, 3) and values from 0 to 255.

type=”pil” PIL.Image

“”pil” converts the image to a PIL image object”

import gradio as gr

def show_image(img):
    print(type(img))
    return img

app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", type="pil"), # Set image componet's type= parameter to "pil" PIL.Image
    outputs=gr.Image(label="Output Image Component"),
)

app.launch()

In the above code snippet, the image input component’s type=parameter is set as “pil”. In this case, the image input component will always pass the image data to the Python function as a PIL.Image object.

type=”str” str

““filepath” passes a str path to a temporary file containing the image.”

import gradio as gr

def show_image(img):
    print(type(img))
    print(img)
    return img

app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", type="filepath"), # Set image componet's type= parameter to "filepath" str
    outputs=gr.Image(label="Output Image Component"),
)

app.launch()

In the above code snippet, the image input component’s type=parameter is set as “filepath”. In this case, the image is first uploaded to a temporary folder. The image input component then passes the string file path of the image in the temporary folder to the Python function as a str object.

The line of code print(img) prints to the console the temporary file path of “img” which is passed to the Python function by the image input component.

How To Use: The Gradio Image Component As An Output Component

Task: Display images to users

Datatype returned by Python function: numpy.array, PIL.Image ,str or pathlib.Path file path to an image

The type=parameter is ignored when using the image component as an output component. As long as the linked function returns the image in one of the datatypes numpy.array, PIL.Image, str or pathlib.Path file path to an image, the image will be displayed.

"type=parameter is ignored when using the image component as an output component”

import gradio as gr
from PIL import Image
import numpy as np

def show_image(img):

    # Convert To PIL Image
    image = Image.open(img)
    print(type(image))

    # Convert the image to a NumPy array
    image_array = np.array(image)
    print(type(image_array))

    return image_array, image

app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", type="filepath"),
    outputs=[gr.Image(label="Output Image Component-1", type="filepath"),
             gr.Image(label="Output Image Component-2", type="filepath")]
)

app.launch()

The code snippet and image of its Gradio’s app output above demonstrate that the type=parameter is ignored when using the image component as an output component.

As you can see, the gr.Interface has two image output components with both their type=parameters set as “filepath”. The linked function show_image returns two values, one of datatype PIL.Image and the other of type numpy.array. Although the type=parameters datatype and the linked function’s return datatypes don’t match, the app will still execute and display both images

When using the image component as an output component, the type= parameter is ignored. What’s most important is that the linked function returns the image data in the expected datatypes numpy.array, PIL.Image, str or pathlib.Path

Using SVG files with Gradio Image Components

“If the image is SVG, the type is ignored and the filepath of the SVG is returned.”

As of Gradio 4.0.2, Gradio image components can’t handle SVG images directly. Using SVG images results in an error.

import gradio as gr

image = "Cute-Smiley-Face.svg"

def show_image(img):
   
    return img

app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", value=image),
    outputs=gr.Image(label="Output Image Component")
)

app.launch()

Error from Python console when using SVG files and Gradio Image Components

As you can see from the error message, the Gradio image component uses the pillow library to handle the image data. However, the pillow library is specialized for handling raster file formats that use pixels such as PNG, JPEG, and TIFF and can’t handle vector-based images like SVG.

If you want to make use of SVG files, as of Gradio 4.0.2, you will have to first convert the SVG file into a format compatible with the pillow library such as raster formats or image arrays.

Image Component Parameters

gradio.Image(value=) parameter

This parameter allows for the setting of a default image for the component. When the Gradio app is launched, the default image is automatically loaded by the component. The image value should be one of the expected datatypes: a PIL Image, numpy array, path or URL. The value= parameter can also accept a callable/function that returns one of the expected datatypes.

“A PIL Image, numpy array, path or URL for the default value that Image component is going to take.”

filepath of image

import gradio as gr

default_image = "monkey_engineer.png"


def show_image(img):

    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", value=default_image), # type = str
    outputs=[gr.Image(label="Output Image Component")]
)

app.launch()

PIL Image

import gradio as gr
from PIL import Image

default_image = Image.open("monkey_engineer.png")


def show_image(img):

    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", value=default_image), # type = PIL.Image
    outputs=[gr.Image(label="Output Image Component")]
)

app.launch()

numpy array

import gradio as gr
from PIL import Image
import numpy as np

image = Image.open("monkey_engineer.png")

default_image = np.array(image)


def show_image(img):

    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", value=default_image), # type = numpy.ndarray
    outputs=[gr.Image(label="Output Image Component")]
)

app.launch()

URL

import gradio as gr

default_image_url = "https://upload.wikimedia.org/wikipedia/commons/4/49/Abstract_-_Coconut_Leaf_%28Imagicity_186%29.jpg"

def show_image(img):
    return img

app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", value=image_url),  # url of image
    outputs=[gr.Image(label="Output Image Component")]
)

app.launch()

“If callable, the function will be called whenever the app loads to set the initial value of the component.”

callable/ function

import gradio as gr

image = "monkey_engineer.png"


def default_image(img: str):
    return img


def show_image(img):
    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", value=default_image(image)),  # callable/function
    outputs=[gr.Image(label="Output Image Component")]
)

app.launch()

import gradio as gr
from PIL import Image


def show_image(img):
    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", value=Image.open("monkey_engineer.png")),  # callable/function
    outputs=[gr.Image(label="Output Image Component")]
)

app.launch()

Image of a monkey engineer- Output for code snippets (**filepath of image, PIL Image, numpy array, callable/ function)**

Image of a coconut leaf- Output for code snippet (**URL)**

The value=parameter works the same for both Input Image Components and Output Image Components.

Output Image Component example using value=parameter

import gradio as gr

image = "monkey_engineer.png"

def show_image(img):
    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component"),  
    outputs=gr.Image(label="Output Image Component", value=image) # value= parameter set for output image component
)

app.launch()

gradio.Image(height=) parameter

This parameter allows you to change the height of the image displayed by the image component. The effect is the same for both input and output image components

import gradio as gr

def show_image(img):
    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", height=1000), # Set height= parameter
    outputs=gr.Image(label="Output Image Component")
)

app.launch()

gradio.Image(width=) parameter

This parameter allows you to change the width of the image displayed by the image component. The effect is the same for both input and output image components

import gradio as gr

def show_image(img):
    return img


app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", width=300),
    outputs=gr.Image(label="Output Image Component")
)

app.launch()

gradio.Image(image_mode=) parameter

Gradio image component mainly uses the pillow library to handle image data. The image_mode=parameter extends the pillow library’s ability to load images in different color modes. To use the image_mode=parameter, you need to pass a string representation of the color space/model to load the image.

It’s important to note that Gradio image components use the “RGB” color space by default. If your image’s colors look a bit off when loaded by the image component it may be caused by the incompatible color formats between your image and the Gradio image component.

How To Use Transparent PNG Files with Gradio Image Components

Many people run into this issue when working with PNG files that have transparency (an alpha channel). The PNG image with a transparent layer displays without issue using the input image component but displays with a black background using the output image component.

import gradio as gr

def show_image(img):
    print(img.mode)
    return img

app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", type="pil"),
    outputs=gr.Image(label="Output Image Component")
)

app.launch()

As demonstrated by the code snippet and output image above, the Gradio image component uses the “RGB” color mode by default. This means that when you press submit, the image will be passed to your linked function in the “RGB” format. As a result of the conversion to the “RGB’ format, your original image’s transparency (alpha layer) is lost. All the transparent pixels are converted to black, resulting in a black background.

The image_mode= parameter provides a solution to this issue. To prevent the black background when using transparent PNG files with Gradio image components, set the image_mode= parameter to “RGBA”

import gradio as gr

def show_image(img):
    print(img.mode)
    return img

app = gr.Interface(
    fn=show_image,
    inputs=gr.Image(label="Input Image Component", type="pil", image_mode="RGBA"),
    outputs=gr.Image(label="Output Image Component")
)

app.launch()

gradio.Image(sources=) parameter

This parameter allows you to select the way to upload your image by providing a list of sources as strings. It only has an effect when using input image components. You can load the image using a file explorer box (“upload”), from the clipboard (“clipboard”) or webcam (“webcam”). By default, the image components display all three options.