How the Blender Cubemap to HDRI Converter Addon Works

Introduction

The “Cubemap to HDRI Converter” addon for Blender 4.3.2 allows users to convert a set of six cubemap images (Right, Left, Top, Bottom, Front, Back) into a single equirectangular HDRI. This HDRI can then be used as an environment texture in Blender for realistic lighting and reflections.

In this article, we’ll break down how the addon works, explaining each part of the script.

1. Addon Metadata

At the beginning of the script, we define some essential metadata about the addon:

bl_info = {
    "name": "Cubemap to HDRI Converter",
    "author": "Your Name",
    "version": (1, 0),
    "blender": (4, 3, 2),
    "location": "View3D > Sidebar > Cubemap to HDRI",
    "description": "Converts a cubemap (6 images) into an HDRI equirectangular image.",
    "category": "Render",
}

This tells Blender the name, version, author, and supported Blender version (4.3.2).
It also defines where the addon appears in the UI (View3D > Sidebar > Cubemap to HDRI).

2. Operator to Convert the Cubemap

The core functionality of the addon is handled by an operator (CUBEMAP_OT_convert_hdri), which:

Takes six cubemap images from the user.
Sets up the render settings to generate an HDRI.
Configures a panoramic camera in equirectangular mode.
Creates a world node setup with an environment texture.
Renders and saves the final HDRI image.

Key Code for the Operator

class CUBEMAP_OT_convert_hdri(bpy.types.Operator):
    bl_idname = "cubemap.convert_hdri"
    bl_label = "Convert Cubemap to HDRI"
    bl_description = "Converts selected cubemap images into an HDRI"

This defines a custom operator (cubemap.convert_hdri) that will be triggered when the user clicks the Convert button in the UI.

3. Validating User Input

Before performing any operations, the script ensures that all necessary inputs are provided.

if not all([image_paths.right, image_paths.left, image_paths.top, 
            image_paths.bottom, image_paths.front, image_paths.back]):
    self.report({'ERROR'}, "Please select all six cubemap images.")
    return {'CANCELLED'}

If the user has not selected all six cubemap images, the script stops and shows an error.

if not output_path:
    self.report({'ERROR'}, "Please select an output file.")
    return {'CANCELLED'}

If the user hasn’t chosen where to save the HDRI, it stops execution.

4. Setting Up the Rendering Engine

The addon forces Blender to use Cycles for rendering because Eevee doesn’t support equirectangular projections.

bpy.context.scene.render.engine = 'CYCLES'
bpy.context.scene.cycles.device = 'GPU'  # Use GPU if available
bpy.ops.wm.redraw_timer(type='DRAW_WIN_SWAP', iterations=1)

It switches to Cycles and sets the device to GPU (if available) for faster rendering.

5. Setting Up the Camera

A panoramic camera is needed to capture the full 360° scene.

camera_data = bpy.data.cameras.new("Camera")
camera = bpy.data.objects.new("Camera", camera_data)
bpy.context.scene.collection.objects.link(camera)
bpy.context.scene.camera = camera

Creates a new camera object and assigns it to the scene.

Configuring the Camera as Equirectangular

camera.data.type = 'PANO'
camera.data.cycles.panorama_type = 'EQUIRECTANGULAR'

Sets the camera to panoramic mode.
Configures the projection type to Equirectangular, which is needed for HDRIs.

6. Setting Up the World Nodes

The environment texture must be set up correctly for rendering.

world = bpy.context.scene.world
world.use_nodes = True
nodes = world.node_tree.nodes
links = world.node_tree.links

# Clear existing nodes
for node in nodes:
    nodes.remove(node)

Enables node-based shading for the world.
Removes any existing nodes to prevent conflicts.

Adding the Environment Texture

node_env_texture = nodes.new(type='ShaderNodeTexEnvironment')
node_env_texture.image = bpy.data.images.load(image_paths.right)
node_env_texture.projection = 'EQUIRECTANGULAR'

Loads the cubemap texture as an environment map.
Sets the projection to Equirectangular (since Blender no longer supports CUBE projection in 4.3).

Connecting Nodes

node_background = nodes.new(type='ShaderNodeBackground')
node_output = nodes.new(type='ShaderNodeOutputWorld')

links.new(node_env_texture.outputs["Color"], node_background.inputs["Color"])
links.new(node_background.outputs["Background"], node_output.inputs["Surface"])

Background shader is used to illuminate the scene with the cubemap.
Connected to the world output for rendering.

7. Render and Save HDRI

Setting the Render Output Format

bpy.context.scene.render.image_settings.file_format = 'HDR'
bpy.context.scene.render.image_settings.color_mode = 'RGB'
bpy.context.scene.render.image_settings.color_depth = '32'

The file format is set to HDR.
Blender only supports 32-bit depth for HDR images, so we set it explicitly.

Rendering the HDRI

bpy.context.scene.render.filepath = output_path
bpy.ops.render.render(write_still=True)
self.report({'INFO'}, f"HDRI saved to {output_path}")

Blender renders the scene and saves the HDRI to the chosen file path.

8. Adding the UI Panel

The UI panel appears in the 3D Viewport sidebar under the “Cubemap to HDRI” tab.

class CUBEMAP_PT_ui_panel(bpy.types.Panel):
    bl_label = "Cubemap to HDRI"
    bl_idname = "CUBEMAP_PT_ui_panel"
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'
    bl_category = "Cubemap to HDRI"

The UI is added to the N-panel (sidebar).

Building the UI

layout.label(text="Select Cubemap Images:")
col = layout.column()
col.prop(scene.cubemap_images, "right")
col.prop(scene.cubemap_images, "left")
col.prop(scene.cubemap_images, "top")
col.prop(scene.cubemap_images, "bottom")
col.prop(scene.cubemap_images, "front")
col.prop(scene.cubemap_images, "back")

layout.separator()
layout.prop(scene, "hdri_output_path")
layout.operator("cubemap.convert_hdri", text="Convert to HDRI")

Adds six file pickers for cubemap images.
Adds an output file selector.
Adds a button to run the conversion.

9. Registering the Addon

Blender needs to register the classes and properties when the addon is enabled.

def register():
    bpy.utils.register_class(CUBEMAP_OT_convert_hdri)
    bpy.utils.register_class(CUBEMAP_PT_ui_panel)
    bpy.utils.register_class(CubemapProperties)
    bpy.types.Scene.cubemap_images = bpy.props.PointerProperty(type=CubemapProperties)
    bpy.types.Scene.hdri_output_path = bpy.props.StringProperty(name="Output HDRI Path", subtype='FILE_PATH')

def unregister():
    bpy.utils.unregister_class(CUBEMAP_OT_convert_hdri)
    bpy.utils.unregister_class(CUBEMAP_PT_ui_panel)
    bpy.utils.unregister_class(CubemapProperties)
    del bpy.types.Scene.cubemap_images
    del bpy.types.Scene.hdri_output_path

Registers the UI panel, operator, and file properties.

Conclusion

This addon provides an easy and automated way to convert cubemaps to HDRI inside Blender 4.3. By leveraging Cycles, world shaders, and equirectangular rendering, users can create high-quality HDRIs for lighting and reflections.