UI

bDiff adds two new tools to Image Editor toolbar: Loupe, Slider and Transform and bDiff category with Image panel to Image Editor sidebar.

General Use

• Load or select an image in Image Editor first. UV Editor will work as well unless uv editing is active.
• All custom image drawing is done with bDiff Image Engine. It will draw over original image in Image Editor. While this is happening, small bDiff logo is drawn at bottom left corner of Image Editor. Original image is never modified, everything is done on gpu with custom shaders.
• Loupe Z, Slider S and Transform R are used as other tools from Image Editor Toolbar (show toolbar with T shortcut), they will start engine if invoked via shortcut, or, if clicked in toolbar, when they are used for a first time.
• Other types from Compare mode and all types from Overlay mode, need to be started from Image Editor Sidebar (show sidebar with N shortcut), bDiff tab and Image panel with Compare! or Overlay! button (depends on selected mode), or engine can be toggled on using E shortcut.
• When you no longer need engine running, stop it with Stop button from panel, or with E shortcut.
• If UV editing is detected, drawing is disabled, but engine is left running.
• If image has been modified in any way by Blender while engine is running, to update cached pixels and update drawn image, click Refresh button or use its Image Editor global shortcut R, or Stop engine and start again using one of the main buttons (depends on Mode), or stop and start engine using E Image Editor global shortcut twice. Whichever option you prefer.

⚠️ Image Data-Block Limitations

Because of Blender API, there are some limitations regarding image source and type. See Support Table for quick overview.

Supported are images loaded from files, image sequences from files and movies, generated images, Multilayer EXRs (only first View Layer and Combined pass) and Render Result image and its Slots (including slot to slot comparison) although its View Layer setting is not supported. Viewer Node image is not supported because it is used in many workarounds to get pixels from other image source and types. Tiled images are not supported at the moment, but might be in future. The same aplies on Multilayer EXR passes other than Combined.

In general, Blender API has good support for plain simple images loaded from files on disk (except Multilayer EXR). Anything other that that, workarounds have to be used. Some still relatively fast, but most of the time performance suffers. Some workarounds include writing temporary image to disk and reading back, some include reading pixels to array with or without sRGB/Linear conversion, some both and some extra. Worst performance is when Image has View as Render enabled - to get image pixels with scene color management applied, image have to be saved, read and converted in one go. These issues are hanging in Blender Issue Tracker for years..

If there is a problem with unsupported image source, type or Render Result slot has no image data, incompatible Color Management or any other caught problem, message is displayed on screen and pink pixel is drawn instead of image.

Multilayer EXR and Render Result image will always use pixels from first View Layer (I haven't found any workaround yet, here are some technical details in case you are interested: you can get layer index from image user type, but compositor image node needs layer name and because its ui layer enum items are generated by blender internally, you have no access to its items in order to read layer names and enum cannot be set by index that you know, only by name you can't get from Blender) and Combined pass and will erase Viewer Node image in order to load pixels. It will be also somewhat slow because workaround (aplies also on Render Result image) is used since there is no direct way to read pixels https://projects.blender.org/blender/blender/issues/53768.

Render Result image will have all its render slots to choose from when used both as Source and Target to compare between slots. If slot has no image, error message will be displayed. If Source is different image (e.g. loaded from file), and Target is Render Result, only first slot can be used, other slots will be unavailable.

If Source image is still image and Target is a file sequence, Blender will not update sequence frame number and will report it as path to 0000.EXT file, regardless of the current frame. If sequence is used as Source, this problem does not occur. Movie can be both Source and Target without issues.

Scene Color Management, Display Device must be set to sRGB, if other option need to be used, image have to have View as Render enabled in order to read pixels correctly. Other Color Management settings are always aplied on Render Result image, other images (i.e. loaded from files) need to have View as Render enabled so settings are aplied. Expect worse performance when View as Render is enabled, to read pixels with aplied Color Management, workaround have to be used which is slow.

Because of (i suspect) internal double conversion between sRGB and linear, image tones especially in darker areas are tiny bit off in comparison with plain Image Editor image. I added correction in custom shaders to match closer to Image Editor tones, but it is not exactly the same, difference is only less prominent.

Blender API does not allow to choose interpolation for gpu textures, so all textures (images) passed to shaders are interpolated. To show individual pixels not interpolated when zoomed in (i.e. to mimic Image Editor), image is pixelated as an extra effect in shader. This has side effect on transparency, black from fully transparent pixels bleed slightly to semi-transparent pixels on edge of transparent area causing them to be slightly darker. With darker checkerboard pattern it is not much noticeable, but with lighter it is.

For performance reasons, images being drawn on screen are not updated if modified from outside (except for Sequence and Movie types that are updated on frame change). Because of Blender API, especially getting pixels from Multilayer EXR or Render Result is too slow to be interactive and executed on every screen redraw. To update pixels, click Refresh button, Stop and start bDiff again (Magnify, Compare! or Overlay! buttons (depends on context)) or Image Editor global shortcut E to toggle engine.

Support Table

• Legend:
• yes, is supported by Blender API out of box
• yes, is supported with workaround
• partial support with workaround
• not supported, but may be in future with workaround
• not supported by Blender API and no workaround exists
• combination does not exist