Kivy - Images

Being able to display images is an essential requirement of any GUI application. Kivy framework includes Image widget as an image container. It is capable of loading the image data from png, jpg and GIF files. For SVG files, you may have to another widget named as Svg itself.

Kivy contains two image widgets − Image and AsyncImage. They are defined in the "kivy.uix.image" module.

The Image widget is used to load an image file available in the local machine.

from kivy.uix.image import Image
img = Image(source = 'logo.png')

To load any image from any external source, you need to use the AsyncImage widget. AsyncImage class is a subclass of the Image class.

from kivy.uix.image import AsyncImage
img = AsyncImage(source = 'http://xyz.com/logo.png')

If you need to display images by retrieving them from URL's, AsyncImage does it in a background thread without blocking your application.

The Image class defines following properties −

source − Filename / source of your image. source is a StringProperty and defaults to None.
fit_mode − If the size of the image is different than the size of the widget, this property determines how the image should be resized to fit inside the widget box.

Available Options

scale-down − For an image bigger than the Image widget dimensions, the image will be scaled down to fit inside the widget box, maintaining its aspect ratio and without stretching. If the size of the image is smaller than the widget, it will be displayed at its original size.
fill − the image is stretched to fill the widget regardless of its aspect ratio or dimensions. This option can lead to distortion of the image, if the image has a different aspect ratio than the widget.
contain − the image is resized to fit inside the widget box, maintaining its aspect ratio. If the image size is larger than the widget size, the behavior will be similar to "scale-down". However, if the size of the image size is smaller than the widget size, unlike "scale-down, the image will be resized to fit inside the widget.
cover − the image will be stretched horizontally or vertically to fill the widget box, maintaining its aspect ratio. If the image has a different aspect ratio than the widget, then the image will be clipped to fit.
texture − Texture object of the image. The texture represents the original, loaded image texture. It is stretched and positioned during rendering according to the fit_mode property.
texture_size − Texture size of the image. This represents the original, loaded image texture size.
color − Image color, in the format (r, g, b, a). This attribute can be used to 'tint' an image. However, if the source image is not gray/white, the color will not really work as expected.
image_ratio − A read-only property that returns Ratio of the image (width / float(height).
reload() − Reload image from disk. This facilitates re-loading of images from disk in case the image content changes.

img = Image(source = '1.jpg')
img.reload()

Example

In the following example code, we mainly try to demonstrate the effect of fit_mode property. Given below is a "kv" language script that displays different images in carousel widget. Each image has a different value of fit_mode property.

The "kv" language script is −

Carousel:
   direction:'top'
   Image:
      source:'1.png'
      fit_mode:"scale-down"
   Image:
      source:"TPlogo.png"
      fit_mode:"contain"
   Image:
      source:"TPlogo.png"
      fit_mode:"fill"
   Image:
      source:"TPlogo.png"
      fit_mode:"cover"