Version

Quick search

 

Image

Jump to API ⇓
 
Module: kivy.uix.image
Added in 1.0.0

The Image widget is used to display an image:

Example in python:

wimg = Image(source='mylogo.png')

Kv Example:

Image:
    source: 'mylogo.png'
    size: self.texture_size

Asynchronous Loading

To load an image asynchronously (for example from an external webserver), use the AsyncImage subclass:

aimg = AsyncImage(source='http://mywebsite.com/logo.png')

This can be useful as it prevents your application from waiting until the image is loaded. If you want to display large images or retrieve them from URL’s, using AsyncImage will allow these resources to be retrieved on a background thread without blocking your application.

Alignment

By default, the image is centered and fits inside the widget bounding box. If you don’t want that, you can set allow_stretch to True and keep_ratio to False.

You can also inherit from Image and create your own style. For example, if you want your image to be greater than the size of your widget, you could do:

class FullImage(Image):
    pass

And in your kivy language file:

<-FullImage>:
    canvas:
        Color:
            rgb: (1, 1, 1)
        Rectangle:
            texture: self.texture
            size: self.width + 20, self.height + 20
            pos: self.x - 10, self.y - 10
class kivy.uix.image.Image(**kwargs)[source]Added in 1.0.0

Bases: kivy.uix.widget.Widget

Image class, see module documentation for more information.

allow_stretchAdded in 1.0.7

If True, the normalized image size will be maximized to fit in the image box. Otherwise, if the box is too tall, the image will not be stretched more than 1:1 pixels.

allow_stretch is a BooleanProperty and defaults to False.

anim_delayAdded in 1.0.8

Delay the animation if the image is sequenced (like an animated gif). If anim_delay is set to -1, the animation will be stopped.

anim_delay is a NumericProperty and defaults to 0.25 (4 FPS).

anim_loopAdded in 1.9.0

Number of loops to play then stop animating. 0 means keep animating.

anim_loop is a NumericProperty and defaults to 0.

colorAdded in 1.0.6

Image color, in the format (r, g, b, a). This attribute can be used to ‘tint’ an image. Be careful: if the source image is not gray/white, the color will not really work as expected.

color is a ListProperty and defaults to [1, 1, 1, 1].

image_ratioAdded in 1.0.0

Ratio of the image (width / float(height).

image_ratio is an AliasProperty and is read-only.

keep_dataAdded in 1.3.0

If True, the underlaying _coreimage will store the raw image data. This is useful when performing pixel based collision detection.

keep_data is a BooleanProperty and defaults to False.

keep_ratioAdded in 1.0.8

If False along with allow_stretch being True, the normalized image size will be maximized to fit in the image box and ignores the aspect ratio of the image. Otherwise, if the box is too tall, the image will not be stretched more than 1:1 pixels.

keep_ratio is a BooleanProperty and defaults to True.

mipmapAdded in 1.0.7

Indicate if you want OpenGL mipmapping to be applied to the texture. Read Mipmapping for more information.

mipmap is a BooleanProperty and defaults to False.

nocacheAdded in 1.6.0

If this property is set True, the image will not be added to the internal cache. The cache will simply ignore any calls trying to append the core image.

nocache is a BooleanProperty and defaults to False.

norm_image_sizeAdded in 1.0.0

Normalized image size within the widget box.

This size will always fit the widget size and will preserve the image ratio.

norm_image_size is an AliasProperty and is read-only.

reload()[source]Added in 1.3.0

Reload image from disk. This facilitates re-loading of images from disk in case the image content changes.

Usage:

im = Image(source = '1.jpg')
# -- do something --
im.reload()
# image will be re-loaded from disk
sourceAdded in 1.0.0

Filename / source of your image.

source is a StringProperty and defaults to None.

textureAdded in 1.0.0

Texture object of the image. The texture represents the original, loaded image texture. It is stretched and positioned during rendering according to the allow_stretch and keep_ratio properties.

Depending of the texture creation, the value will be a Texture or a TextureRegion object.

texture is an ObjectProperty and defaults to None.

texture_sizeAdded in 1.0.0

Texture size of the image. This represents the original, loaded image texture size.

Warning

The texture size is set after the texture property. So if you listen to the change on texture, the property texture_size will not be up-to-date. Use self.texture.size instead.

class kivy.uix.image.AsyncImage(**kwargs)[source]Added in 1.0.0

Bases: kivy.uix.image.Image

Asynchronous Image class. See the module documentation for more information.

Note

The AsyncImage is a specialized form of the Image class. You may want to refer to the loader documentation and in particular, the ProxyImage for more detail on how to handle events around asynchronous image loading.

reload()[source]Added in 1.3.0

Reload image from disk. This facilitates re-loading of images from disk in case the image content changes.

Usage:

im = Image(source = '1.jpg')
# -- do something --
im.reload()
# image will be re-loaded from disk
« Grid Layout Label »