Cubemap Assembly Tool

01 What Problem It Solves

A cubemap is six square images bolted together in a fixed order — but "fixed" only helps if every tool along the pipeline agrees on what that order is. DirectX expects +X, −X, +Y, −Y, +Z, −Z. Source frames rendered from a Houdini camera rig, exported from a panorama stitcher, or handed off by another artist rarely arrive labelled that way, and reassembling them by hand in a generic image editor means eyeballing rotations and hoping the skybox doesn't show a seam.

The Cubemap Assembly Tool is a free, open-source desktop utility that takes over exactly that hand-off: six explicit face slots in the correct DirectX order, automatic face guessing from common filenames, per-face rotate/flip correction, and a live preview — both an orbiting 3D cube and a from-the-inside 360° view — before anything is exported to a cross, strip, or DDS texture.

02 Face Assignment & Live Preview

Automatic Face Detection

Dropping in six arbitrarily named files still needs to end up on the correct face. The tool normalizes each filename stem and checks it against a small alias table before falling back to manual assignment:

Pressing AUTO LOAD 6 FILES selects a batch, matches whatever filenames it recognises to their face, and drops any leftover unrecognised files into the remaining empty slots in DirectX order. Nothing is silently discarded — files that don't match an alias still get placed, just without a guessed face, so the artist confirms the rest manually.

3D Cube & Inside 360° Preview

Screenshot 02: the same six-face cubemap in both live preview modes — 3D Cube (outside) and Inside 360° (from the centre). Both panels also show the face grid, Output Configuration, and Export panel, since the whole tool fits in one window.

Both previews and the four 2D layout previews (H-Cross, V-Cross, H-Strip, V-Strip) run entirely offline in the desktop window — nothing is written to disk until EXPORT CUBEMAP is pressed.

03 Output Formats & Export Pipeline

Export always runs on a background thread with progress reported back to the UI, so the window stays responsive on large face sizes. The output filename encodes the size and layout so it's identifiable without reopening the tool:

// Naming format:
cubemap_<face-size>px_<type>.<ext>

// Examples:
cubemap_1024px_hcross.png
cubemap_2048px_vcross_fnz.png
cubemap_512px_hstrip.tga
cubemap_2048px_cubemap.dds

PNG / TGA / BMP Layouts

Rendered in pure Python with Pillow — no external binary, works identically on Windows and Linux. Five layouts are available:

Each face is resized to a shared square size (1–32768 px) with a selectable resampling filter — Lanczos, Cubic, Linear, or Point (nearest-neighbour) — then composited with alpha onto a transparent canvas. The save dialog offers PNG, TGA, or BMP as the output container.

DDS via texassemble

For an engine-ready DirectDraw Surface cubemap, the tool shells out to Microsoft's texassemble — part of the open-source DirectXTex suite — invoked as a plain argument list, never through a shell. It is located automatically, in this order: the TEXASSEMBLE_PATH environment variable, a tools/texassemble.exe next to the app, then PATH.

If texassemble isn't found, DDS export is disabled in the UI with an explanation — PNG/TGA/BMP layout export keeps working regardless, since it has no external dependency.

04 Architecture & Project Structure

The tool is a Python desktop app (pywebview) with a clean split between the offline HTML/JS interface and the Python services doing the real work. app.py is the only supported entry point.

The bridge deliberately never exposes the native window object to JavaScript. Outbound links are allow-listed to three known destinations rather than opened freely, export work always runs off the UI thread via threading.Thread, and texassemble is invoked as a Python argument list — never through a shell — so a stray character in a file path can't be interpreted as a shell command.

05 Installation — Windows & Linux

// Step 1: install once
win_install.bat

// Step 2: run anytime
win_RUN.bat

// Debug mode (keeps console open)
win_RUN_debug.bat

// Verify dependencies — read-only, no changes
.venv\Scripts\python.exe install.py --check

// Optional: DDS export backend
winget install Microsoft.DirectXTex.Texassemble

// Step 1: make scripts executable
chmod +x lnx_install.sh lnx_RUN.sh

// Step 2: install once
./lnx_install.sh

// Step 3: run anytime
./lnx_RUN.sh

// Verify — read-only
.venv/bin/python install.py --check

The app also detects a tools/texassemble.exe placed next to it, or a TEXASSEMBLE_PATH environment variable, as alternatives to a system-wide install. PNG/TGA/BMP layout export needs none of this — it works natively on both platforms.

Installation Safety Model

06 Workflow

The Output Configuration and Export panels are visible in both screenshots in § 02 — DDS options (DXGI format, sRGB, DX10, overwrite) on the left, filename preview and progress bar at the bottom right.

07 Current Scope & Limitations

The current release focuses specifically on assembling a single six-image cubemap. A few things are explicitly out of scope for now, called out here rather than left for someone to discover mid-export:

DDS export depends on locating a working texassemble binary — straightforward on Windows via winget, less standardised on Linux, where it's up to the user to place a compatible build on PATH, in tools/, or point TEXASSEMBLE_PATH at it. PNG/TGA/BMP layout export has no such dependency on either platform.