
**************
Image Settings
**************

.. figure:: /images/editors_image_image-settings_movie-image-panel.png
   :align: right

   Image tab.


.. _bpy.types.Image.source:

Source
======

Select the type of image to use. For images that come from files,
see :doc:`/files/media/image_formats`.


Single Image
------------

A single, static image.


.. _image-sequence:

Image Sequence
--------------

An animation where each frame is stored in a separate file.
See :ref:`image-formats-open-sequence`.
For options, see `Movie`_ below.


Movie
-----

A video file. Note that if you want to do motion tracking and video compositing
rather than simply using the video as a texture, you should load it into the
:doc:`Movie Clip Editor </editors/clip/introduction>` instead.

.. note::

   The options below are for preview purposes only; they don't affect the 3D Viewport
   or the render. For that, see the :doc:`/render/shader_nodes/textures/image`.

.. note::

   Blender plays all videos at the scene frame rate, not their original frame rate,
   meaning they'll be faster or slower than intended if these frame rates don't match up.
   To work around this, see the *Offset* field of the Image Texture Node
   linked above.

Frames
   How many frames of the video to play. Past this point, the video will be paused
   (unless *Cyclic* is enabled).

   .. _bpy.ops.image.match_movie_length:

   Match Movie Length
      Sets the *Frames* to the number of frames in the video file.

Start
   Scene frame at which the video should start playing.

Offset
   Number of frames to offset the video to an earlier point in time.
   (Put differently: how many frames at the start of the video to skip.)

Cyclic
   Start over after the last frame to create a continuous loop.

Auto Refresh
   Play the video in the Image Editor when the scene animation is playing.
   (The mouse cursor should be in the Image Editor or the Timeline when starting playback
   for this to work.)

Deinterlace
   Apply deinterlacing to interlaced (analog) video.


.. _image-generated:

Generated
---------

Image generated by Blender.

X, Y
   The width and height of the image in pixels.
Float Buffer
   Creates a 32-bit image. This has a larger file size,
   but holds much more color information than the standard 8-bit image.
   For close-ups and large gradients, it may be better to use a 32-bit image.
Type
   :Blank: Creates a blank image of a single specified color.
   :UV Grid: Creates a checkerboard pattern with a colored cross (+) in each square.
   :Color Grid:
      Creates a more complex colored grid with letters and numbers denoting locations.
      It could be used to check for stretching or distortion in the UV mapping.
Color
   The fill color when creating a *Blank* image.

.. _editors-image-image-settings-common:

Common Options
==============

.. _bpy.types.Image.filepath:

File
   Used for replacing or packing files.

   Pack
      Embed the resource into the current blend-file. See :doc:`/files/blend/packed_data`.
   Path
      Path to the linked file.
   Open
      Opens the :doc:`/editors/file_browser` to select a file from a drive.
   Reload
      Reloads the file. Useful when it has been reworked in an external application.

.. _bpy.types.Image.is_multiview:

Use Multi-View
   See :doc:`Multi-View </render/output/properties/stereoscopy/index>`.

.. _bpy.types.ColorManagedInputColorspaceSettings.name:

Color Space
   Specifies the :term:`Color Space` that the image file was saved in.
   This information is used to correctly convert the image to Blender's
   internal linear color space, which is used for all color computations and rendering.

   Textures and final renders are often stored in sRGB,
   while OpenEXR images are stored in a linear color space.
   Some images such as normal, bump or stencil maps do not strictly contain "colors"
   and should never have a color conversion applied to them.
   For such images, the color space should be set to *Non-Color*.

   The list of color spaces depends on the active :ref:`OCIO config <ocio-config>`.
   The default supported color spaces are described in detail here:
   :ref:`Default OpenColorIO Configuration <ocio-config-default-color-spaces>`.

.. _bpy.types.Image.alpha_mode:

Alpha
   How the image uses its :term:`Alpha Channel`.
   This option is only available if the image format supports transparency.

   :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.
      This preserves colors in parts of the image with zero alpha.
   :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.
      This can represent purely emissive effects like fire correctly, unlike straight alpha.
   :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:
      Ignore alpha channel from the file and make image fully opaque.

.. _bpy.types.Image.use_half_precision:

Half Float Precision
   Load the image with a :term:`bit depth` of only 16 bits per channel instead of 32, which saves memory.

.. _bpy.types.Image.use_view_as_render:

View as Render
   Apply the :ref:`color management <render-post-color-management>` settings when displaying this image on the screen.

.. _bpy.types.Image.seam_margin:

Seam Margin
   The thickness of the margin around UV islands for texture painting to bleed into. This margin ensures that
   no unpainted pixels remain at the island border.

   .. figure:: /images/editors_image_image-settings_seam-margin.png

      Painting a stroke across a seam in 3D space makes it extend past the UV island borders in the texture,
      until it gets cut off at the margin.

   A higher value will result in a thicker margin, which can be useful if you intend to create mipmaps
   of the texture. However, this may also reduce painting performance.

   .. note::

      This setting only affects Sculpt Mode, where texture painting support is currently experimental.
      In Texture Paint Mode, a fixed margin is used instead.

   .. todo
      Remove the above "is currently experimental" once these tickets get resolved:
      https://projects.blender.org/blender/blender/issues/96225
      https://projects.blender.org/blender/blender/issues/97352
      Also, the setting appears broken at the time of writing this comment: strokes don't actually
      get cut off, regardless of the margin value (had to cheat and edit the Blender source code to get it
      to work). Best retest it once it comes out of Experimental state and create a ticket if needed.
