feat(vat): Unreal demo project — Python-driven asset bootstrap

src/CLIPipeline.cpp

@@ -689,7 +689,7 @@
         "                                    triangle, rasterizes barycentric-interpolated vertex colors,\n"
         "                                    then dilates outward by N pixels to mask seam bleed at MIP time.\n"
         "                                    Default resolution=1024, dilation=4. Output PNG is RGBA.\n"
-        "  vat <file> --anim <name> [--fps N] [-o <dir>] [--include-shaders {godot,unity,unreal,all}] [--emit-uv2 [N]] [--json]\n"
+        "  vat <file> --anim <name> [--fps N] [-o <dir>] [--include-shaders {godot,unity,unreal,all}] [--emit-uv2 [N]] [--bake-precision {16,32}] [--json]\n"
         "                                    Bake a skeletal animation into a Vertex Animation Texture\n"
         "                                    in OpenVAT (sharpen3d/openvat) format: a single 16-bit RGB\n"
         "                                    PNG (height = 2 × frames; top half positions, bottom half\n"
@@ -5821,9 +5821,22 @@
         float vMin = std::numeric_limits<float>::infinity();
         float vMax = -std::numeric_limits<float>::infinity();
         for (size_t i = a; i < b; ++i) {
+            // i = Ogre vertex index = bake column index (the bake walks
+            // Ogre's vertex buffer in order, so column == Ogre index).
+            // gltfIdx = glTF buffer position of the SAME vertex after
+            // Assimp's JoinIdenticalVertices reorder.
             const uint32_t gltfIdx = permutation[i];
-            const uint32_t col = gltfIdx % static_cast<uint32_t>(texWidth);
-            const uint32_t row = gltfIdx / static_cast<uint32_t>(texWidth);
+            const uint32_t ogreIdx = static_cast<uint32_t>(i);
+            // The bake column we want this glTF vertex to read is the
+            // ORIGINAL Ogre column `i`, not `gltfIdx`. Earlier code
+            // mistakenly used `gltfIdx`, which on meshes with non-
+            // identity Assimp permutations (e.g. Mixamo Hip Hop Dancing)
+            // meant every vertex read animation data from a
+            // *different* vertex's column — body parts visibly flew
+            // apart on specific frames where the wrong-source motion
+            // was large.
+            const uint32_t col = ogreIdx % static_cast<uint32_t>(texWidth);
+            const uint32_t row = ogreIdx / static_cast<uint32_t>(texWidth);
             // The destination is glTF index gltfIdx, which is offset
             // (gltfIdx - a) within this primitive.
             const size_t localDst = static_cast<size_t>(gltfIdx) - a;
@@ -5916,7 +5929,7 @@
 
 int CLIPipeline::cmdVat(int argc, char* argv[])
 {
-    // Parse: vat <file> --anim <name> [--fps N] [-o <dir>] [--include-shaders {godot,unity,unreal,all}] [--emit-uv2 [N]] [--json]
+    // Parse: vat <file> --anim <name> [--fps N] [-o <dir>] [--include-shaders {godot,unity,unreal,all}] [--emit-uv2 [N]] [--bake-precision {16,32}] [--json]
     //
     // Output is always OpenVAT (sharpen3d/openvat) — a single packed
     // 16-bit RGB PNG (`<basename>_pos.png`, height = 2*frames, top half
@@ -5934,6 +5947,12 @@
     // bind-sidecar matching and just read TEXCOORD_<channel> as
     // (column % tex_width, column / tex_width) directly.
     int emitUv2Channel = -1;
+    // --bake-precision {16,32}: per-channel bit depth for the position
+    // texture. Default 16 (PNG, ~0.03mm precision over 2m bounds).
+    // 32 writes an EXR with raw float32 positions — sidesteps the
+    // sub-mm quantization artifact that flickers Mixamo's coplanar
+    // eye-sphere/head-plug geometry. ~2× larger file.
+    int bakeBitDepth = 16;
 
     for (int i = 1; i < argc; ++i) {
         QString arg(argv[i]);
@@ -5954,6 +5973,17 @@
         if ((arg == "-o" || arg == "--output") && i + 1 < argc) {
             outDir = QString(argv[++i]); continue;
         }
+        if (arg == "--bake-precision" && i + 1 < argc) {
+            bool ok = false;
+            const int v = QString(argv[++i]).toInt(&ok);
+            if (!ok || (v != 16 && v != 32)) {
+                err() << "Error: --bake-precision must be 16 or 32 "
+                         "(got \"" << argv[i] << "\")." << Qt::endl;
+                return 2;
+            }
+            bakeBitDepth = v;
+            continue;
+        }
         // --include-shaders <list>: comma-separated subset of
         // {godot, unity, unreal} (or "all") — copies the matching
         // drop-in shader templates into the bake's output directory
@@ -6023,7 +6053,7 @@
 
     if (filePath.isEmpty()) {
         err() << "Error: No input file specified." << Qt::endl;
-        err() << "Usage: qtmesh vat <file> --anim <name> [--fps N] [-o <dir>] [--include-shaders {godot,unity,unreal,all}] [--emit-uv2 [N]] [--json]" << Qt::endl;
+        err() << "Usage: qtmesh vat <file> --anim <name> [--fps N] [-o <dir>] [--include-shaders {godot,unity,unreal,all}] [--emit-uv2 [N]] [--bake-precision {16,32}] [--json]" << Qt::endl;
         return 2;
     }
     if (animName.isEmpty()) {
@@ -6225,6 +6255,7 @@
     opts.fps               = fps;
     opts.outputDir         = outDir;
     opts.basename          = animName;
+    opts.bitDepth          = bakeBitDepth;
     // Keep a copy for the UV2 post-pass (the move below sinks the
     // original into VATBaker::Options).
     std::vector<uint32_t> vertexPermCopy = vertexPerm;

src/CMakeLists.txt

@@ -91,6 +91,7 @@ VertexColorBaker.cpp
 VATBaker.cpp
 VATBakerController.cpp
 VATShaderEmitter.cpp
+MinimalEXRWriter.cpp
 MorphAnimationManager.cpp
 NodeAnimationManager.cpp
 PoseLibrary.cpp

src/MinimalEXRWriter.cpp

@@ -0,0 +1,214 @@
+#include "MinimalEXRWriter.h"
+
+#include <QFile>
+#include <QIODevice>
+#include <cstring>
+
+namespace MinimalEXR {
+
+namespace {
+
+// EXR LE writers — the format is always little-endian regardless of host.
+void writeU32LE(QByteArray& buf, uint32_t v) {
+    char b[4];
+    b[0] = static_cast<char>(v & 0xff);
+    b[1] = static_cast<char>((v >> 8) & 0xff);
+    b[2] = static_cast<char>((v >> 16) & 0xff);
+    b[3] = static_cast<char>((v >> 24) & 0xff);
+    buf.append(b, 4);
+}
+void writeI32LE(QByteArray& buf, int32_t v) { writeU32LE(buf, static_cast<uint32_t>(v)); }
+void writeU64LE(QByteArray& buf, uint64_t v) {
+    writeU32LE(buf, static_cast<uint32_t>(v & 0xffffffffu));
+    writeU32LE(buf, static_cast<uint32_t>(v >> 32));
+}
+void writeF32LE(QByteArray& buf, float v) {
+    uint32_t bits;
+    std::memcpy(&bits, &v, sizeof(bits));
+    writeU32LE(buf, bits);
+}
+
+// Append a NUL-terminated string. EXR uses C-strings for attr names + types.
+//
+// Bounded against a 256-byte cap so a malformed (un-terminated) caller
+// can't walk off the end of the source buffer. All current call sites
+// pass string literals at most ~16 chars long, so the cap is a defense-
+// in-depth measure; if it ever fires the EXR output is structurally
+// malformed and we let the file write succeed but report nothing —
+// downstream `file` will fail to parse and the caller sees the error.
+void writeCStr(QByteArray& buf, const char* s) {
+    if (s == nullptr) return;
+    // Bounded scan — portable equivalent of `strnlen` so the function
+    // is safe even if a future caller forgets to NUL-terminate.
+    constexpr size_t kMaxAttrLen = 256;
+    size_t n = 0;
+    while (n < kMaxAttrLen && s[n] != '\0') ++n;
+    buf.append(s, static_cast<int>(n));
+    buf.append('\0');
+}
+
+// Attribute header: name\0 type\0 size_u32 payload[size].
+// `payload` is appended verbatim — caller has already serialized it LE.
+void writeAttr(QByteArray& buf,
+               const char* name,
+               const char* type,
+               const QByteArray& payload) {
+    writeCStr(buf, name);
+    writeCStr(buf, type);
+    writeI32LE(buf, static_cast<int32_t>(payload.size()));
+    buf.append(payload);
+}
+
+// Channel-list attribute: a sequence of channel records terminated by a NUL
+// byte. Each record:
+//   name\0  pixelType(u32)  pLinear(u8)  reserved[3]  xSampling(u32)  ySampling(u32)
+// pixelType: 0=UINT 1=HALF 2=FLOAT.
+//
+// Order matters: EXR reads back the channels in the order they appear, and
+// the convention for RGB is alphabetical (B, G, R). We write B then G then R
+// to match what every EXR-reading tool expects to find.
+QByteArray buildChannelListBGR_F32() {
+    QByteArray out;
+    const char* names[3] = { "B", "G", "R" };
+    for (const char* n : names) {
+        writeCStr(out, n);
+        writeU32LE(out, 2u);   // FLOAT
+        out.append('\0');      // pLinear = 0
+        out.append('\0');      // reserved
+        out.append('\0');
+        out.append('\0');
+        writeU32LE(out, 1u);   // xSampling
+        writeU32LE(out, 1u);   // ySampling
+    }
+    out.append('\0');          // terminator
+    return out;
+}
+
+QByteArray buildBox2i(int xMin, int yMin, int xMax, int yMax) {
+    QByteArray out;
+    writeI32LE(out, xMin);
+    writeI32LE(out, yMin);
+    writeI32LE(out, xMax);
+    writeI32LE(out, yMax);
+    return out;
+}
+
+QByteArray buildV2f(float a, float b) {
+    QByteArray out;
+    writeF32LE(out, a);
+    writeF32LE(out, b);
+    return out;
+}
+
+QByteArray buildF32(float v) {
+    QByteArray out;
+    writeF32LE(out, v);
+    return out;
+}
+
+QByteArray buildU32(uint32_t v) {
+    QByteArray out;
+    writeU32LE(out, v);
+    return out;
+}
+
+QByteArray buildU8(uint8_t v) {
+    QByteArray out(1, static_cast<char>(v));
+    return out;
+}
+
+} // namespace
+
+bool writeRGB32F(const QString& path,
+                 int width,
+                 int height,
+                 const std::vector<float>& rgbData)
+{
+    if (width <= 0 || height <= 0) return false;
+    const size_t expected = static_cast<size_t>(width)
+                          * static_cast<size_t>(height) * 3u;
+    if (rgbData.size() != expected) return false;
+
+    // ── Header ────────────────────────────────────────────────────────
+    QByteArray header;
+    // Magic + version.
+    writeU32LE(header, 0x01312f76u);  // EXR magic
+    writeU32LE(header, 2u);            // version 2, no special flags
+
+    // Attributes — name\0 type\0 size payload, terminated by a single NUL.
+    writeAttr(header, "channels",            "chlist",
+              buildChannelListBGR_F32());
+    writeAttr(header, "compression",         "compression",
+              buildU8(0));                              // NO_COMPRESSION
+    writeAttr(header, "dataWindow",          "box2i",
+              buildBox2i(0, 0, width - 1, height - 1));
+    writeAttr(header, "displayWindow",       "box2i",
+              buildBox2i(0, 0, width - 1, height - 1));
+    writeAttr(header, "lineOrder",           "lineOrder",
+              buildU8(0));                              // INCREASING_Y
+    writeAttr(header, "pixelAspectRatio",    "float",
+              buildF32(1.0f));
+    writeAttr(header, "screenWindowCenter",  "v2f",
+              buildV2f(0.0f, 0.0f));
+    writeAttr(header, "screenWindowWidth",   "float",
+              buildF32(1.0f));
+
+    // Attribute-list terminator.
+    header.append('\0');
+
+    // ── Scanline offset table ────────────────────────────────────────
+    // One uint64 per scanline. The offset is the absolute file position
+    // of that scanline's payload block (which starts with the y-coord
+    // u32 then the data-size u32 then the pixel bytes).
+    //
+    // Each scanline payload = 4 (y) + 4 (size) + (width × 3 channels ×
+    // 4 bytes/float) = 8 + width × 12.
+    const uint64_t scanlinePayloadSize = 8u
+        + static_cast<uint64_t>(width) * 3u * 4u;
+    const uint64_t offsetTableSize = static_cast<uint64_t>(height) * 8u;
+    const uint64_t firstScanlineOffset =
+        static_cast<uint64_t>(header.size()) + offsetTableSize;
+
+    QByteArray offsetTable;
+    offsetTable.reserve(static_cast<int>(offsetTableSize));
+    for (int y = 0; y < height; ++y) {
+        const uint64_t off = firstScanlineOffset
+            + static_cast<uint64_t>(y) * scanlinePayloadSize;
+        writeU64LE(offsetTable, off);
+    }
+
+    // ── Scanlines ────────────────────────────────────────────────────
+    // Channels are written out in the order declared in the channel list
+    // — i.e. B, G, R per scanline. Inside each channel block, the entire
+    // row of pixels for THAT channel is written contiguously.
+    QByteArray pixels;
+    pixels.reserve(static_cast<int>(
+        static_cast<uint64_t>(height) * scanlinePayloadSize));
+    const uint32_t pixelDataSize =
+        static_cast<uint32_t>(width) * 3u * 4u;
+
+    for (int y = 0; y < height; ++y) {
+        writeI32LE(pixels, y);
+        writeU32LE(pixels, pixelDataSize);
+        // Row pointer into the caller's interleaved RGB buffer.
+        const float* row = rgbData.data()
+            + static_cast<size_t>(y) * static_cast<size_t>(width) * 3u;
+        // B channel.
+        for (int x = 0; x < width; ++x) writeF32LE(pixels, row[x * 3 + 2]);
+        // G channel.
+        for (int x = 0; x < width; ++x) writeF32LE(pixels, row[x * 3 + 1]);
+        // R channel.
+        for (int x = 0; x < width; ++x) writeF32LE(pixels, row[x * 3 + 0]);
+    }
+
+    // ── Write to disk in one shot ────────────────────────────────────
+    QFile out(path);
+    if (!out.open(QIODevice::WriteOnly | QIODevice::Truncate)) return false;
+    if (out.write(header) != header.size()) return false;
+    if (out.write(offsetTable) != offsetTable.size()) return false;
+    if (out.write(pixels) != pixels.size()) return false;
+    out.close();
+    return out.error() == QFile::NoError;
+}
+
+} // namespace MinimalEXR

src/MinimalEXRWriter.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <QString>
+#include <cstdint>
+#include <vector>
+
+#include <cstddef>
+
+/// Minimal OpenEXR 2.0 writer — 3-channel (R,G,B) float32 scanline images,
+/// uncompressed. Just enough to round-trip a VAT bake's position+normal
+/// texture into a format Unreal Engine's TextureFactory accepts as a
+/// non-color HDR source (TC_HDR / TC_VectorDisplacementmap).
+///
+/// Why we ship our own writer instead of pulling OpenEXR:
+///   * Qt has no native EXR support in 6.9.x.
+///   * Adding the OpenEXR/Imath dependency for a single one-off code path
+///     would balloon the bake module's link surface and CI matrix.
+///   * The spec is small enough that a no-compression scanline writer is
+///     ~150 LOC and trivially testable.
+///
+/// Format: spec-compliant subset of OpenEXR 2.0 with these fixed choices:
+///   * Magic 0x01312f76, version 2, no tile bit, no long-names bit.
+///   * Attributes: channels (R, G, B float32), compression NO_COMPRESSION,
+///     dataWindow = displayWindow = (0,0,W-1,H-1), lineOrder INCREASING_Y,
+///     pixelAspectRatio 1.0, screenWindowCenter (0,0), screenWindowWidth 1.
+///   * Scanline payload: R-row then G-row then B-row per scanline, no
+///     compression, no padding.
+///
+/// Not implemented (intentional):
+///   * Tiled / multi-part files.
+///   * Compression (zip / piz / pxr24).
+///   * Half-precision channels (the whole point is full float32 precision).
+///   * Alpha / Z / sampled-rate / arbitrary attributes.
+namespace MinimalEXR {
+
+/// Write a 3-channel float32 scanline EXR to `path`.
+///
+/// @param path  Output filesystem path. Overwritten if it exists.
+/// @param width Image width in pixels (must be > 0).
+/// @param height Image height in pixels (must be > 0).
+/// @param rgbData Row-major (height × width × 3) float buffer. The pixel at
+///                (x, y) is at index (y * width + x) * 3 + {0,1,2} for R/G/B.
+///                Caller owns; the writer only reads.
+///
+/// @return true on success. false if the buffer size mismatches the
+///         declared dimensions or the file write fails.
+bool writeRGB32F(const QString& path,
+                 int width,
+                 int height,
+                 const std::vector<float>& rgbData);
+
+} // namespace MinimalEXR