Image¶

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 inside the widget bounding box.

Adjustment¶

To control how the image should be adjusted to fit inside the widget box, you should use the fit_mode property. Available options include:

"scale-down": maintains aspect ratio without stretching.
"fill": stretches to fill widget, may cause distortion.
"contain": maintains aspect ratio and resizes to fit inside widget.
"cover": maintains aspect ratio and stretches to fill widget, may clip

image.

For more details, refer to the fit_mode.

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.AsyncImage(**kwargs)[source]¶

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.

Note

AsyncImage currently does not support properties anim_loop and mipmap and setting those properties will have no effect.

remove_from_cache()[source]¶: Remove image from cache.

New in version 2.0.0.

class kivy.uix.image.Image(**kwargs)[source]¶

Bases: kivy.uix.widget.Widget

Image class, see module documentation for more information.

allow_stretch¶

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.

New in version 1.0.7.

Deprecated since version 2.2.0: allow_stretch have been deprecated. Please use fit_mode instead.

allow_stretch is a BooleanProperty and defaults to False.

anim_delay¶

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

New in version 1.0.8.

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

anim_loop¶

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

New in version 1.9.0.

anim_loop is a NumericProperty and defaults to 0.

color¶

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.

New in version 1.0.6.

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

Changed in version 2.0.0: Changed from ListProperty to ColorProperty.

fit_mode¶

If the size of the image is different than the size of the widget, determine how the image should be resized to fit inside the widget box.

Available options:

"scale-down": 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. If the image has a different aspect ratio than the widget, there will be blank areas on the widget box.

"fill": the image is stretched to fill the widget, **regardless of

its aspect ratio or dimensions**. If the image has a different aspect ratio than the widget, this option can lead to distortion of the image.

"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 is smaller than the widget size, unlike "scale-down, the image will be resized to fit inside the widget. If the image has a different aspect ratio than the widget, there will be blank areas on the widget box.

"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.

fit_mode is a OptionProperty and defaults to "scale-down".

image_ratio¶

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

image_ratio is an AliasProperty and is read-only.

keep_data¶

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

New in version 1.3.0.

keep_data is a BooleanProperty and defaults to False.

keep_ratio¶

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.

New in version 1.0.8.

Deprecated since version 2.2.0: keep_ratio have been deprecated. Please use fit_mode instead.

keep_ratio is a BooleanProperty and defaults to True.

mipmap¶

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

New in version 1.0.7.

mipmap is a BooleanProperty and defaults to False.

nocache¶

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.

New in version 1.6.0.

nocache is a BooleanProperty and defaults to False.

norm_image_size¶

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]¶

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

New in version 1.3.0.

Usage:

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

remove_from_cache()[source]¶: Remove image from cache.

New in version 2.0.0.

source¶

Filename / source of your image.

source is a StringProperty and defaults to None.

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.

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

texture is an ObjectProperty and defaults to None.

texture_size¶: 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.

« Grid Layout

Label »

Version

Quick search

Table Of Contents

Image¶

Asynchronous Loading¶

Alignment¶

Adjustment¶