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
ofImagePackedFile
, (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
ofRenderSlot
, (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
ofUDIMTile
, (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 fromquality (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, frame=0, tile_index=0)#
Scale the buffer of the image, in pixels
- Parameters:
width (int in [1, inf]) – Width
height (int in [1, inf]) – Height
frame (int in [0, inf], (optional)) – Frame, Frame (for image sequences)
tile_index (int in [0, inf], (optional)) – Tile, Tile index (for tiled images)
- 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