Image(ID)

Image Data

The Image data-block is a shallow wrapper around image or video file(s) (on disk, as packed data, or generated).

All actual data like the pixel buffer, size, resolution etc. is cached in an imbuf.types.ImBuf image buffer (or several buffers in some cases, like UDIM textures, multi-views, animations…).

Several properties and functions of the Image data-block are then actually using/modifying its image buffer, and not the Image data-block itself.

Warning

One key limitation is that image buffers are not shared between different Image data-blocks, and they are not duplicated when copying an image.

So until a modified image buffer is saved on disk, duplicating its Image data-block will not propagate the underlying buffer changes to the new Image.

This example script generates an Image data-block with a given size, change its first pixel, rescale it, and duplicates the image.

The duplicated image still has the same size and colors as the original image at its creation, all editing in the original image’s buffer is ‘lost’ in its copy.

import bpy

image_src = bpy.data.images.new('src', 1024, 102)
print(image_src.size)
print(image_src.pixels[0:4])

image_src.scale(1024, 720)
image_src.pixels[0:4] = (0.5, 0.5, 0.5, 0.5)
image_src.update()
print(image_src.size)
print(image_src.pixels[0:4])

image_dest = image_src.copy()
image_dest.update()
print(image_dest.size)
print(image_dest.pixels[0:4])

base classes — bpy_struct, ID

class bpy.types.Image(ID)

Image data-block referencing an external or packed image

alpha_mode

Representation of alpha in the image file, to convert to and from when saving and loading the image

  • STRAIGHT Straight – Store RGB and alpha channels separately with alpha acting as a mask, also known as unassociated alpha. Commonly used by image editing applications and file formats like PNG.

  • PREMUL Premultiplied – Store RGB channels with alpha multiplied in, also known as associated alpha. The natural format for renders and used by file formats like OpenEXR.

  • CHANNEL_PACKED Channel Packed – Different images are packed in the RGB and alpha channels, and they should not affect each other. Channel packing is commonly used by game engines to save memory.

  • NONE None – Ignore alpha channel from the file and make image fully opaque.

Type

enum in [‘STRAIGHT’, ‘PREMUL’, ‘CHANNEL_PACKED’, ‘NONE’], default ‘STRAIGHT’

bindcode

OpenGL bindcode

Type

int in [0, inf], default 0, (readonly)

channels

Number of channels in pixels buffer

Type

int in [0, inf], default 0, (readonly)

colorspace_settings

Input color space settings

Type

ColorManagedInputColorspaceSettings, (readonly)

depth

Image bit depth

Type

int in [0, inf], default 0, (readonly)

display_aspect

Display Aspect for this image, does not affect rendering

Type

mathutils.Vector of 2 items in [0.1, inf], default (1.0, 1.0)

file_format

Format used for re-saving this file

Type

enum in Image Type Items, default ‘TARGA’

filepath

Image/Movie file name

Type

string, default “”, (never None)

filepath_raw

Image/Movie file name (without data refreshing)

Type

string, default “”, (never None)

frame_duration

Duration (in frames) of the image (1 when not a video/sequence)

Type

int in [0, inf], default 0, (readonly)

generated_color

Fill color for the generated image

Type

float array of 4 items in [0, inf], default (0.0, 0.0, 0.0, 0.0)

generated_height

Generated image height

Type

int in [1, 65536], default 1024

generated_type

Generated image type

Type

enum in Image Generated Type Items, default ‘UV_GRID’

generated_width

Generated image width

Type

int in [1, 65536], default 1024

has_data

True if the image data is loaded into memory

Type

boolean, default False, (readonly)

is_dirty

Image has changed and is not saved

Type

boolean, default False, (readonly)

is_float

True if this image is stored in floating-point buffer

Type

boolean, default False, (readonly)

is_multiview

Image has more than one view

Type

boolean, default False, (readonly)

is_stereo_3d

Image has left and right views

Type

boolean, default False, (readonly)

packed_file

First packed file of the image

Type

PackedFile, (readonly)

packed_files

Collection of packed images

Type

bpy_prop_collection of ImagePackedFile, (readonly)

pixels

Image buffer pixels in floating-point values

Type

float in [-inf, inf], default 0.0

render_slots

Render slots of the image

Type

RenderSlots bpy_prop_collection of RenderSlot, (readonly)

resolution

X/Y pixels per meter, for the image buffer

Type

mathutils.Vector of 2 items in [-inf, inf], default (0.0, 0.0)

seam_margin

Margin to take into account when fixing UV seams during painting. Higher number would improve seam-fixes for mipmaps, but decreases performance

Type

int in [-32768, 32767], default 8

size

Width and height of the image buffer in pixels, zero when image data can’t be loaded

Type

int array of 2 items in [-inf, inf], default (0, 0), (readonly)

source

Where the image comes from

  • FILE Single Image – Single image file.

  • SEQUENCE Image Sequence – Multiple image files, as a sequence.

  • MOVIE Movie – Movie file.

  • GENERATED Generated – Generated image.

  • VIEWER Viewer – Compositing node viewer.

  • TILED UDIM Tiles – Tiled UDIM image texture.

Type

enum in [‘FILE’, ‘SEQUENCE’, ‘MOVIE’, ‘GENERATED’, ‘VIEWER’, ‘TILED’], default ‘FILE’

stereo_3d_format

Settings for stereo 3d

Type

Stereo3dFormat, (readonly, never None)

tiles

Tiles of the image

Type

UDIMTiles bpy_prop_collection of UDIMTile, (readonly)

type

How to generate the image

Type

enum in [‘IMAGE’, ‘MULTILAYER’, ‘UV_TEST’, ‘RENDER_RESULT’, ‘COMPOSITING’], default ‘IMAGE’, (readonly)

use_deinterlace

Deinterlace movie file on load

Type

boolean, default False

use_generated_float

Generate floating-point buffer

Type

boolean, default False

use_half_precision

Use 16 bits per channel to lower the memory usage during rendering

Type

boolean, default False

use_multiview

Use Multiple Views (when available)

Type

boolean, default False

use_view_as_render

Apply render part of display transformation when displaying this image on the screen

Type

boolean, default False

views_format

Mode to load image views

Type

enum in Views Format Items, default ‘INDIVIDUAL’

save_render(filepath, scene=None, quality=0)

Save image to a specific path using a scenes render settings

Parameters
  • filepath (string, (never None)) – Output path

  • scene (Scene, (optional)) – Scene to take image parameters from

  • quality (int in [0, 100], (optional)) – Quality, Quality for image formats that support lossy compression, uses default quality if not specified

save(filepath='', quality=0)

Save image

Parameters
  • filepath (string, (optional, never None)) – Output path, uses image data-block filepath if not specified

  • quality (int in [0, 100], (optional)) – Quality, Quality for image formats that support lossy compression, uses default quality if not specified

pack(data='', data_len=0)

Pack an image as embedded data into the .blend file

Parameters
  • data (string, (optional, never None)) – data, Raw data (bytes, exact content of the embedded file)

  • data_len (int in [0, inf], (optional)) – data_len, length of given data (mandatory if data is provided)

unpack(method='USE_LOCAL')

Save an image packed in the .blend file to disk

Parameters

method (enum in Unpack Method Items, (optional)) – method, How to unpack

reload()

Reload the image from its source path

update()

Update the display image from the floating-point buffer

scale(width, height)

Scale the buffer of the image, in pixels

Parameters
  • width (int in [1, inf]) – Width

  • height (int in [1, inf]) – Height

gl_touch(frame=0, layer_index=0, pass_index=0)

Delay the image from being cleaned from the cache due inactivity

Parameters
  • frame (int in [0, inf], (optional)) – Frame, Frame of image sequence or movie

  • layer_index (int in [0, inf], (optional)) – Layer, Index of layer that should be loaded

  • pass_index (int in [0, inf], (optional)) – Pass, Index of pass that should be loaded

Returns

Error, OpenGL error value

Return type

int in [-inf, inf]

gl_load(frame=0, layer_index=0, pass_index=0)

Load the image into an OpenGL texture. On success, image.bindcode will contain the OpenGL texture bindcode. Colors read from the texture will be in scene linear color space and have premultiplied or straight alpha matching the image alpha mode

Parameters
  • frame (int in [0, inf], (optional)) – Frame, Frame of image sequence or movie

  • layer_index (int in [0, inf], (optional)) – Layer, Index of layer that should be loaded

  • pass_index (int in [0, inf], (optional)) – Pass, Index of pass that should be loaded

Returns

Error, OpenGL error value

Return type

int in [-inf, inf]

gl_free()

Free the image from OpenGL graphics memory

filepath_from_user(image_user=None)

Return the absolute path to the filepath of an image frame specified by the image user

Parameters

image_user (ImageUser, (optional)) – Image user of the image to get filepath for

Returns

File Path, The resulting filepath from the image and its user

Return type

string, (never None)

buffers_free()

Free the image buffers from memory

classmethod bl_rna_get_subclass(id, default=None)
Parameters

id (string) – The RNA type identifier.

Returns

The RNA type or default when not found.

Return type

bpy.types.Struct subclass

classmethod bl_rna_get_subclass_py(id, default=None)
Parameters

id (string) – The RNA type identifier.

Returns

The class or default when not found.

Return type

type

Inherited Properties

Inherited Functions

References