vrm-runtime 0.1.0

Renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime
Documentation
//! Image-source and VRM thumbnail conformance regressions.

use std::io::Cursor;

use image_crate::{DynamicImage, ImageFormat};
use serde_json::{Value, json};
use vrm_runtime::AvatarAsset;

const REQUIRED_HUMAN_BONES: [&str; 15] = [
    "hips",
    "spine",
    "head",
    "leftUpperLeg",
    "leftLowerLeg",
    "leftFoot",
    "rightUpperLeg",
    "rightLowerLeg",
    "rightFoot",
    "leftUpperArm",
    "leftLowerArm",
    "leftHand",
    "rightUpperArm",
    "rightLowerArm",
    "rightHand",
];

fn valid_vrm_json() -> Value {
    let mut nodes = REQUIRED_HUMAN_BONES
        .iter()
        .map(|bone| json!({ "name": bone }))
        .collect::<Vec<_>>();
    nodes[0]["children"] = json!([1, 3, 6]);
    nodes[1]["children"] = json!([2, 9, 12]);
    nodes[3]["children"] = json!([4]);
    nodes[4]["children"] = json!([5]);
    nodes[6]["children"] = json!([7]);
    nodes[7]["children"] = json!([8]);
    nodes[9]["children"] = json!([10]);
    nodes[10]["children"] = json!([11]);
    nodes[12]["children"] = json!([13]);
    nodes[13]["children"] = json!([14]);
    let human_bones = REQUIRED_HUMAN_BONES
        .iter()
        .enumerate()
        .map(|(index, bone)| (bone.to_string(), json!({ "node": index })))
        .collect::<serde_json::Map<_, _>>();

    json!({
        "asset": { "version": "2.0" },
        "extensionsUsed": ["VRMC_vrm"],
        "extensions": {
            "VRMC_vrm": {
                "specVersion": "1.0",
                "meta": {
                    "name": "Image fixture",
                    "authors": ["vrm-runtime"],
                    "licenseUrl": "https://vrm.dev/licenses/1.0/"
                },
                "humanoid": { "humanBones": human_bones }
            }
        },
        "nodes": nodes,
        "scenes": [{ "nodes": [0] }],
        "scene": 0
    })
}

fn glb(value: &Value) -> Vec<u8> {
    let mut json = serde_json::to_vec(value).expect("test JSON must serialize");
    while !json.len().is_multiple_of(4) {
        json.push(b' ');
    }
    let total_length = 12 + 8 + json.len();
    let mut bytes = Vec::with_capacity(total_length);
    bytes.extend_from_slice(b"glTF");
    bytes.extend_from_slice(&2_u32.to_le_bytes());
    bytes.extend_from_slice(&(total_length as u32).to_le_bytes());
    bytes.extend_from_slice(&(json.len() as u32).to_le_bytes());
    bytes.extend_from_slice(b"JSON");
    bytes.extend_from_slice(&json);
    bytes
}

fn encoded_image(format: ImageFormat, width: u32, height: u32) -> Vec<u8> {
    let image = DynamicImage::new_rgba8(width, height);
    let mut output = Cursor::new(Vec::new());
    image
        .write_to(&mut output, format)
        .expect("test image must encode");
    output.into_inner()
}

fn data_uri(mime_type: &str, data: &[u8]) -> String {
    format!("data:{mime_type};base64,{}", base64::encode(data))
}

#[test]
fn malformed_image_sources_return_errors_instead_of_panicking() {
    for image in [json!({}), json!({ "bufferView": 0 })] {
        let mut fixture = valid_vrm_json();
        fixture["images"] = json!([image]);
        let bytes = glb(&fixture);

        let result = std::panic::catch_unwind(|| AvatarAsset::from_bytes(&bytes));

        assert!(result.is_ok(), "malformed images must not unwind");
        assert!(result.unwrap().is_err());
    }
}

#[test]
fn data_uri_images_preserve_their_encoded_bytes_and_mime_type() {
    let png = encoded_image(ImageFormat::Png, 1, 1);
    let mut fixture = valid_vrm_json();
    fixture["images"] = json!([{ "uri": data_uri("image/png", &png) }]);

    let avatar = AvatarAsset::from_bytes(&glb(&fixture)).expect("data URI image must load");

    assert_eq!(avatar.images()[0].mime_type(), "image/png");
    assert_eq!(avatar.images()[0].data(), png);
}

#[test]
fn file_loading_resolves_relative_image_uris() {
    let png = encoded_image(ImageFormat::Png, 1, 1);
    let unique = format!(
        "vrm-runtime-image-{}-{}",
        std::process::id(),
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .expect("the system clock must be after the epoch")
            .as_nanos()
    );
    let directory = std::env::temp_dir().join(unique);
    std::fs::create_dir_all(&directory).expect("temporary directory must be created");
    let image_path = directory.join("texture image.png");
    std::fs::write(&image_path, &png).expect("temporary image must be written");
    let mut fixture = valid_vrm_json();
    fixture["images"] = json!([{ "uri": "texture%20image.png" }]);
    let avatar_path = directory.join("avatar.vrm");
    std::fs::write(
        &avatar_path,
        serde_json::to_vec(&fixture).expect("fixture must serialize"),
    )
    .expect("temporary avatar must be written");

    let avatar = AvatarAsset::from_file(&avatar_path).expect("relative image must resolve");

    assert_eq!(avatar.images()[0].data(), png);
    std::fs::remove_dir_all(&directory).expect("temporary directory must be removable");
}

#[test]
fn thumbnail_must_be_square_png_or_jpeg() {
    let mut nonsquare = valid_vrm_json();
    let png = encoded_image(ImageFormat::Png, 2, 1);
    nonsquare["images"] = json!([{ "uri": data_uri("image/png", &png) }]);
    nonsquare["extensions"]["VRMC_vrm"]["meta"]["thumbnailImage"] = json!(0);
    assert!(AvatarAsset::from_bytes(&glb(&nonsquare)).is_err());

    let mut unsupported = valid_vrm_json();
    unsupported["images"] = json!([{
        "uri": "data:image/webp;base64,UklGRg=="
    }]);
    unsupported["extensions"]["VRMC_vrm"]["meta"]["thumbnailImage"] = json!(0);
    assert!(AvatarAsset::from_bytes(&glb(&unsupported)).is_err());

    for format in [ImageFormat::Png, ImageFormat::Jpeg] {
        let mut valid = valid_vrm_json();
        let bytes = encoded_image(format, 1, 1);
        let mime = if format == ImageFormat::Png {
            "image/png"
        } else {
            "image/jpeg"
        };
        valid["images"] = json!([{ "uri": data_uri(mime, &bytes) }]);
        valid["extensions"]["VRMC_vrm"]["meta"]["thumbnailImage"] = json!(0);
        AvatarAsset::from_bytes(&glb(&valid)).expect("square PNG/JPEG thumbnail must load");
    }
}