user: How do I use Image Data in Blender? Include parameters, examples, warnings and best practices.

assistant: 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.

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`](bpy.types.bpy_struct.html#bpy.types.bpy_struct "bpy.types.bpy_struct"), [`ID`](bpy.types.ID.html#bpy.types.ID "bpy.types.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'`

    channels
    :   Number of channels in pixels buffer

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

    colorspace_settings
    :   Input color space settings

        Type:
        :   [`ColorManagedInputColorspaceSettings`](bpy.types.ColorManagedInputColorspaceSettings.html#bpy.types.ColorManagedInputColorspaceSettings "bpy.types.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`](mathutils.html#mathutils.Vector "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 All Items](bpy_types_enum_items/image_type_all_items.html#rna-enum-image-type-all-items), default `'TARGA'`

    filepath
    :   Image/Movie file name

        Type:
        :   string, default “”, (never None, blend relative `//` prefix supported)

    filepath_raw
    :   Image/Movie file name (without data refreshing)

        Type:
        :   string, default “”, (never None, blend relative `//` prefix supported)

    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](bpy_types_enum_items/image_generated_type_items.html#rna-enum-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`](bpy.types.PackedFile.html#bpy.types.PackedFile "bpy.types.PackedFile"), (readonly)

    packed_files
    :   Collection of packed images

        Type:
        :   [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`ImagePackedFile`](bpy.types.ImagePackedFile.html#bpy.types.ImagePackedFile "bpy.types.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.types.RenderSlots.html#bpy.types.RenderSlots "bpy.types.RenderSlots") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`RenderSlot`](bpy.types.RenderSlot.html#bpy.types.RenderSlot "bpy.types.RenderSlot"), (readonly)

    resolution
    :   X/Y pixels per meter, for the image buffer

        Type:
        :   [`mathutils.Vector`](mathutils.html#mathutils.Vector "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 cannot 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`](bpy.types.Stereo3dFormat.html#bpy.types.Stereo3dFormat "bpy.types.Stereo3dFormat"), (readonly, never None)

    tiles
    :   Tiles of the image

        Type:
        :   [`UDIMTiles`](bpy.types.UDIMTiles.html#bpy.types.UDIMTiles "bpy.types.UDIMTiles") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`UDIMTile`](bpy.types.UDIMTile.html#bpy.types.UDIMTile "bpy.types.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 True

    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](bpy_types_enum_items/views_format_items.html#rna-enum-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`](bpy.types.Scene.html#bpy.types.Scene "bpy.types.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_copy=False*)
    :   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
            - **save_copy** (*boolean**,* *(**optional**)*) – Save Copy, Save the image as a copy, without updating current image’s filepath

    pack(*\**, *data=''*, *data_len=0*)
    :   Pack an image as embedded data into the .blend file

        Parameters:
        :   - **data** (*byte 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](bpy_types_enum_items/unpack_method_items.html#rna-enum-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`](bpy.types.ImageUser.html#bpy.types.ImageUser "bpy.types.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** (*str*) – The RNA type identifier.

        Returns:
        :   The RNA type or default when not found.

        Return type:
        :   [`bpy.types.Struct`](bpy.types.Struct.html#bpy.types.Struct "bpy.types.Struct") subclass

    *classmethod* bl_rna_get_subclass_py(*id*, *default=None*, */*)
    :   Parameters:
        :   **id** (*str*) – The RNA type identifier.

        Returns:
        :   The class or default when not found.

        Return type:
        :   [type](#bpy.types.Image.type "bpy.types.Image.type")

### Inherited Properties

|  |  |
| --- | --- |
| - [`bpy_struct.id_data`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.id_data "bpy.types.bpy_struct.id_data") - [`ID.name`](bpy.types.ID.html#bpy.types.ID.name "bpy.types.ID.name") - [`ID.name_full`](bpy.types.ID.html#bpy.types.ID.name_full "bpy.types.ID.name_full") - [`ID.id_type`](bpy.types.ID.html#bpy.types.ID.id_type "bpy.types.ID.id_type") - [`ID.session_uid`](bpy.types.ID.html#bpy.types.ID.session_uid "bpy.types.ID.session_uid") - [`ID.is_evaluated`](bpy.types.ID.html#bpy.types.ID.is_evaluated "bpy.types.ID.is_evaluated") - [`ID.original`](bpy.types.ID.html#bpy.types.ID.original "bpy.types.ID.original") - [`ID.users`](bpy.types.ID.html#bpy.types.ID.users "bpy.types.ID.users") - [`ID.use_fake_user`](bpy.types.ID.html#bpy.types.ID.use_fake_user "bpy.types.ID.use_fake_user") - [`ID.use_extra_user`](bpy.types.ID.html#bpy.types.ID.use_extra_user "bpy.types.ID.use_extra_user") - [`ID.is_embedded_data`](bpy.types.ID.html#bpy.types.ID.is_embedded_data "bpy.types.ID.is_embedded_data") | - [`ID.is_linked_packed`](bpy.types.ID.html#bpy.types.ID.is_linked_packed "bpy.types.ID.is_linked_packed") - [`ID.is_missing`](bpy.types.ID.html#bpy.types.ID.is_missing "bpy.types.ID.is_missing") - [`ID.is_runtime_data`](bpy.types.ID.html#bpy.types.ID.is_runtime_data "bpy.types.ID.is_runtime_data") - [`ID.is_editable`](bpy.types.ID.html#bpy.types.ID.is_editable "bpy.types.ID.is_editable") - [`ID.tag`](bpy.types.ID.html#bpy.types.ID.tag "bpy.types.ID.tag") - [`ID.is_library_indirect`](bpy.types.ID.html#bpy.types.ID.is_library_indirect "bpy.types.ID.is_library_indirect") - [`ID.library`](bpy.types.ID.html#bpy.types.ID.library "bpy.types.ID.library") - [`ID.library_weak_reference`](bpy.types.ID.html#bpy.types.ID.library_weak_reference "bpy.types.ID.library_weak_reference") - [`ID.asset_data`](bpy.types.ID.html#bpy.types.ID.asset_data "bpy.types.ID.asset_data") - [`ID.override_library`](bpy.types.ID.html#bpy.types.ID.override_library "bpy.types.ID.override_library") - [`ID.preview`](bpy.types.ID.html#bpy.types.ID.preview "bpy.types.ID.preview") |

### Inherited Functions

|  |  |
| --- | --- |
| - [`bpy_struct.as_pointer`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.as_pointer "bpy.types.bpy_struct.as_pointer") - [`bpy_struct.driver_add`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.driver_add "bpy.types.bpy_struct.driver_add") - [`bpy_struct.driver_remove`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.driver_remove "bpy.types.bpy_struct.driver_remove") - [`bpy_struct.get`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.get "bpy.types.bpy_struct.get") - [`bpy_struct.id_properties_clear`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.id_properties_clear "bpy.types.bpy_struct.id_properties_clear") - [`bpy_struct.id_properties_ensure`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.id_properties_ensure "bpy.types.bpy_struct.id_properties_ensure") - [`bpy_struct.id_properties_ui`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.id_properties_ui "bpy.types.bpy_struct.id_properties_ui") - [`bpy_struct.is_property_hidden`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.is_property_hidden "bpy.types.bpy_struct.is_property_hidden") - [`bpy_struct.is_property_overridable_library`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.is_property_overridable_library "bpy.types.bpy_struct.is_property_overridable_library") - [`bpy_struct.is_property_readonly`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.is_property_readonly "bpy.types.bpy_struct.is_property_readonly") - [`bpy_struct.is_property_set`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.is_property_set "bpy.types.bpy_struct.is_property_set") - [`bpy_struct.items`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.items "bpy.types.bpy_struct.items") - [`bpy_struct.keyframe_delete`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.keyframe_delete "bpy.types.bpy_struct.keyframe_delete") - [`bpy_struct.keyframe_insert`](bpy.types.bpy_struct.html#bpy.types.bpy_struct.keyframe_insert "bpy.types.bpy_struct.keyframe_insert") - [`bpy_stru