CI/CD Render Validation

# Example GitHub Actions snippet
- name: Install Vulkan and SwiftShader
  run: |
    sudo apt-get update
    sudo apt-get install -y vulkan-tools libvulkan-dev

    # Download SwiftShader
    wget https://github.com/google/swiftshader/releases/download/latest/swiftshader-linux-x64.tar.gz
    tar xzf swiftshader-linux-x64.tar.gz

    # Point Vulkan to the software renderer
    echo "VK_ICD_FILENAMES=$PWD/swiftshader/vk_swiftshader_icd.json" >> $GITHUB_ENV

// Simplified HeadlessVulkanApp focusing on the offscreen setup
class HeadlessVulkanApp {
public:
    HeadlessVulkanApp(uint32_t width, uint32_t height) : width_(width), height_(height) {
        // Standard Vulkan setup (Instance, Device, etc.) omitted for brevity
        setupVulkanHeadless();
        createFramebuffer();
    }

    void createFramebuffer() {
        // Create offscreen image (no swapchain needed)
        vk::ImageCreateInfo imageInfo{
            .imageType = vk::ImageType::e2D,
            .format = vk::Format::eR8G8B8A8Unorm,
            .extent = {width_, height_, 1},
            .tiling = vk::ImageTiling::eLinear,  // Linear for easy CPU readback
            .usage = vk::ImageUsageFlagBits::eColorAttachment | vk::ImageUsageFlagBits::eTransferSrc,
            // ...
        };
        framebufferImage_ = device_.createImage(imageInfo);

        // Allocate and bind host-visible memory for direct CPU access
        // (In a real app, you'd use a more efficient staging buffer approach)
        auto memReqs = framebufferImage_.getMemoryRequirements();
        allocateAndBindMemory(framebufferImage_, vk::MemoryPropertyFlagBits::eHostVisible);
    }

    std::vector<uint8_t> readFramebuffer() {
        void* mapped = framebufferMemory_.mapMemory(0, imageSize_);
        std::vector<uint8_t> pixels(imageSize_);
        std::memcpy(pixels.data(), mapped, imageSize_);
        framebufferMemory_.unmapMemory();
        return pixels;
    }

    // ... rendering and boilerplate omitted ...
};

class LPIPSValidator {
public:
    // ... setup and ONNX session initialization ...

    float computeSimilarity(const std::vector<uint8_t>& img1, const std::vector<uint8_t>& img2) {
        // Preprocess: convert RGBA to RGB and normalize to [-1, 1]
        auto tensor1 = preprocessImage(img1);
        auto tensor2 = preprocessImage(img2);

        // Run LPIPS ONNX model
        auto outputs = session_.Run(Ort::RunOptions{nullptr}, inputNames, inputs.data(), 2, outputNames, 1);

        // Return the perceptual distance (lower is more similar)
        return outputs[0].GetTensorMutableData<float>()[0];
    }
};

bool testSanityCheck() {
    HeadlessVulkanApp app(800, 600);
    auto pixels = app.readFramebuffer();
    auto reference = loadReferenceImage("references/main_menu.png");

    LPIPSValidator validator("models/lpips_vgg.onnx");
    float lpips = validator.computeSimilarity(pixels, reference);

    if (lpips > 0.15f) {
        std::cerr << "Sanity check FAILED: LPIPS distance " << lpips << " > 0.15\n";
        return false;
    }
    return true;
}

# Option 1: Use pre-converted LPIPS-VGG model
wget https://github.com/richzhang/PerceptualSimilarity/releases/download/v0.1/lpips_vgg.onnx \
     -O models/lpips_vgg.onnx

# Option 2: Convert from PyTorch yourself
python3 << 'EOF'
import torch
import lpips  # pip install lpips

# Load pre-trained LPIPS model
model = lpips.LPIPS(net='vgg', version='0.1')
model.eval()

# Export to ONNX
dummy_img1 = torch.randn(1, 3, 224, 224)
dummy_img2 = torch.randn(1, 3, 224, 224)

torch.onnx.export(
    model,
    (dummy_img1, dummy_img2),
    'models/lpips_vgg.onnx',
    input_names=['input0', 'input1'],
    output_names=['output'],
    dynamic_axes={
        'input0': {0: 'batch', 2: 'height', 3: 'width'},
        'input1': {0: 'batch', 2: 'height', 3: 'width'}
    }
)
print("LPIPS model exported to lpips_vgg.onnx")
EOF

Reference: Cube rotated 0°
Test:      Cube rotated 1° (due to timing differences)
MSE:       High - thousands of pixels differ
Human:     Looks identical
Result:    False positive failure

Reference: Cube rotated 0°
Test:      Cube rotated 1°
LPIPS:     0.03 - features are nearly identical (shape, lighting, texture)
Human:     Looks identical
Result:    Pass

Reference: Cube with brick texture
Test:      Cube with checkerboard texture (wrong texture loaded)
MSE:       High
LPIPS:     0.45 - features differ significantly (texture pattern changed)
Human:     Obviously wrong
Result:    Correctly fails

bool testSanityCheckOptimized() {
    HeadlessVulkanApp app(800, 600);
    auto pixels = app.readFramebuffer();
    auto reference = loadReferenceImage("references/main_menu.png");

    // Level 1a: Quick pixel check (< 1ms)
    // Catches black screens or catastrophic corruption instantly
    if (countDrasticDifferences(pixels, reference) > threshold) {
        return false;
    }

    // Level 1b: LPIPS for perceptual similarity (~30ms)
    LPIPSValidator validator("models/lpips_vgg.onnx");
    return validator.computeSimilarity(pixels, reference) < 0.15f;
}

struct TextMatch {
    std::string text;
    Rect bounds;
};

class OCRValidator {
public:
    std::vector<TextMatch> detectAndRead(const std::vector<uint8_t>& pixels) {
        // 1. Detect: Find all bounding boxes containing text
        // (Using an ONNX model like EAST)
        std::vector<Rect> boxes = textDetector_.findBoxes(pixels);
        std::vector<TextMatch> results;

        for (const auto& box : boxes) {
            // 2. Recognize: Convert the pixels in this box to a string
            // (Using an ONNX model like CRNN)
            auto cropped = cropPixels(pixels, box);
            std::string text = textRecognizer_.read(cropped);
            results.push_back({text, box});
        }
        return results;
    }
};

bool validateTextFitting(const TextMatch& detected, const Rect& expectedUIBox) {
    // Check if the detected text is entirely contained within the expected box
    bool isInside = expectedUIBox.contains(detected.bounds);

    // Check for "legibility margin" - text shouldn't be touching the very edge.
    // We expect at least a 2-pixel gap on all sides.
    bool hasMargin = expectedUIBox.width > (detected.bounds.width + 4) &&
                     expectedUIBox.height > (detected.bounds.height + 4);

    return isInside && hasMargin;
}

# Simpler, faster model than before - just needs to detect "broken" vs "correct"
import torch
import torch.nn as nn

class FastRenderValidator(nn.Module):
    def __init__(self):
        super().__init__()

        # Lightweight architecture - only 3 conv layers
        self.features = nn.Sequential(
            nn.Conv2d(3, 32, 5, stride=2, padding=2),  # 800x600 -> 400x300
            nn.ReLU(),
            nn.MaxPool2d(2),  # 400x300 -> 200x150

            nn.Conv2d(32, 64, 3, padding=1),
            nn.ReLU(),
            nn.MaxPool2d(2),  # 200x150 -> 100x75

            nn.Conv2d(64, 64, 3, padding=1),
            nn.ReLU(),
            nn.AdaptiveAvgPool2d((8, 8)),  # 100x75 -> 8x8
        )

        self.classifier = nn.Sequential(
            nn.Flatten(),
            nn.Linear(64 * 8 * 8, 128),
            nn.ReLU(),
            nn.Dropout(0.3),
            nn.Linear(128, 2)  # Binary: correct=0, broken=1
        )

    def forward(self, x):
        x = self.features(x)
        x = self.classifier(x)
        return x

# Simple training loop snippet
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
criterion = nn.CrossEntropyLoss()

for epoch in range(10):
    for images, labels in dataloader:
        optimizer.zero_grad()
        outputs = model(images)
        loss = criterion(outputs, labels)
        loss.backward()
        optimizer.step()

# Export to ONNX for CI use
dummy_input = torch.randn(1, 3, 224, 224)
torch.onnx.export(model, dummy_input, "models/semantic_validator.onnx",
                  input_names=['input'], output_names=['output'])

class SemanticValidator {
public:
    SemanticValidator(const std::string& modelPath) : session_(env_, modelPath.c_str(), options_) {}

    bool isRenderCorrect(const std::vector<uint8_t>& pixels) {
        // 1. Preprocess: resize to 224x224 and normalize
        std::vector<float> input = preprocess(pixels);

        // 2. Run inference
        auto outputTensors = session_.Run(Ort::RunOptions{nullptr}, ...);

        // 3. Interpret results: Argmax of [correct_score, broken_score]
        float* results = outputTensors[0].GetTensorMutableData<float>();
        return results[0] > results[1]; // Index 0 is 'Correct'
    }
};