vrm-runtime 0.1.0

Renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime
Documentation
use std::path::{Path, PathBuf};

use image_crate::{GenericImageView, ImageFormat};

use crate::LoadError;

/// Encoded PNG or JPEG bytes stored by the avatar asset.
///
/// Images loaded from buffer views, data URIs, and relative file URIs retain
/// their original encoded bytes. Loading rejects missing, empty, malformed, or
/// unsupported sources instead of creating placeholder images.
#[derive(Debug, Clone)]
pub struct AvatarImage {
    /// Media type (`image/png` or `image/jpeg`).
    pub mime_type: String,
    /// Original encoded PNG or JPEG bytes.
    pub data: Vec<u8>,
}

impl AvatarImage {
    /// Creates an encoded image for a programmatically assembled asset.
    ///
    /// Cross-object asset validation checks references, but callers are
    /// responsible for supplying valid encoded bytes to this constructor.
    pub fn new(mime_type: impl Into<String>, data: impl Into<Vec<u8>>) -> Self {
        Self {
            mime_type: mime_type.into(),
            data: data.into(),
        }
    }

    /// Returns the encoded image's media type.
    pub fn mime_type(&self) -> &str {
        &self.mime_type
    }

    /// Returns the original encoded image bytes.
    pub fn data(&self) -> &[u8] {
        &self.data
    }
}

/// Validates the source shape without calling `gltf::Image::source`, whose
/// infallible API unwraps malformed combinations of glTF image properties.
pub(crate) fn validate_raw_sources(root: &gltf::json::Root) -> Result<(), LoadError> {
    for (index, image) in root.images.iter().enumerate() {
        let location = format!("/images/{index}");
        match (&image.uri, &image.buffer_view) {
            (Some(_), Some(_)) => {
                return Err(invalid_image(format!(
                    "{location} must contain exactly one of `uri` or `bufferView`"
                )));
            }
            (None, None) => {
                return Err(invalid_image(format!(
                    "{location} must contain exactly one of `uri` or `bufferView`"
                )));
            }
            (Some(uri), None) => {
                if uri.is_empty() {
                    return Err(invalid_image(format!("{location}/uri must not be empty")));
                }
                if let Some(mime_type) = image.mime_type.as_ref() {
                    encoded_format_for_mime(&mime_type.0, &format!("{location}/mimeType"))?;
                }
            }
            (None, Some(_)) => {
                let mime_type = image.mime_type.as_ref().ok_or_else(|| {
                    invalid_image(format!(
                        "{location}/mimeType is required when `bufferView` is used"
                    ))
                })?;
                encoded_format_for_mime(&mime_type.0, &format!("{location}/mimeType"))?;
            }
        }
    }
    Ok(())
}

pub(crate) fn load_images(
    doc: &gltf::Document,
    buffers: &[gltf::buffer::Data],
    base: Option<&Path>,
) -> Result<Vec<AvatarImage>, LoadError> {
    doc.as_json()
        .images
        .iter()
        .enumerate()
        .map(|(index, image)| {
            let location = format!("/images/{index}");
            if let Some(view_index) = image.buffer_view.as_ref() {
                let view = doc.views().nth(view_index.value()).ok_or_else(|| {
                    invalid_image(format!(
                        "{location}/bufferView references missing buffer view {}",
                        view_index.value()
                    ))
                })?;
                let buffer = buffers.get(view.buffer().index()).ok_or_else(|| {
                    invalid_image(format!(
                        "{location}/bufferView references missing buffer {}",
                        view.buffer().index()
                    ))
                })?;
                let end = view.offset().checked_add(view.length()).ok_or_else(|| {
                    invalid_image(format!("{location}/bufferView byte range overflows"))
                })?;
                let data = buffer.0.get(view.offset()..end).ok_or_else(|| {
                    invalid_image(format!("{location}/bufferView exceeds its parent buffer"))
                })?;
                let mime_type = image.mime_type.as_ref().ok_or_else(|| {
                    invalid_image(format!(
                        "{location}/mimeType is required when `bufferView` is used"
                    ))
                })?;
                validated_image(data.to_vec(), Some(&mime_type.0), &location)
            } else {
                let uri = image.uri.as_deref().ok_or_else(|| {
                    invalid_image(format!(
                        "{location} must contain exactly one of `uri` or `bufferView`"
                    ))
                })?;
                load_uri_image(
                    uri,
                    image.mime_type.as_ref().map(|mime| mime.0.as_str()),
                    base,
                    &location,
                )
            }
        })
        .collect()
}

pub(crate) fn validate_thumbnail(
    images: &[AvatarImage],
    thumbnail_index: Option<usize>,
) -> Result<(), LoadError> {
    let Some(index) = thumbnail_index else {
        return Ok(());
    };
    let image = images.get(index).ok_or_else(|| {
        invalid_image(format!(
            "/extensions/VRMC_vrm/meta/thumbnailImage references missing image {index}"
        ))
    })?;
    let location = "/extensions/VRMC_vrm/meta/thumbnailImage";
    let format = encoded_format_for_mime(image.mime_type(), location)?;
    let decoded =
        image_crate::load_from_memory_with_format(image.data(), format).map_err(|error| {
            invalid_image(format!(
                "{location} does not reference a valid PNG or JPEG: {error}"
            ))
        })?;
    let (width, height) = decoded.dimensions();
    if width != height {
        return Err(invalid_image(format!(
            "{location} must reference a square image, found {width}x{height}"
        )));
    }
    Ok(())
}

fn load_uri_image(
    uri: &str,
    declared_mime_type: Option<&str>,
    base: Option<&Path>,
    location: &str,
) -> Result<AvatarImage, LoadError> {
    if let Some(data_uri) = uri.strip_prefix("data:") {
        let (metadata, payload) = data_uri
            .split_once(',')
            .ok_or_else(|| invalid_image(format!("{location}/uri is not a valid data URI")))?;
        let mime_type = metadata.strip_suffix(";base64").ok_or_else(|| {
            invalid_image(format!(
                "{location}/uri must use a base64-encoded PNG or JPEG data URI"
            ))
        })?;
        encoded_format_for_mime(mime_type, &format!("{location}/uri"))?;
        if let Some(declared) = declared_mime_type
            && declared != mime_type
        {
            return Err(invalid_image(format!(
                "{location}/mimeType `{declared}` does not match data URI media type `{mime_type}`"
            )));
        }
        let data = base64::decode(payload).map_err(|error| {
            invalid_image(format!(
                "{location}/uri contains invalid base64 data: {error}"
            ))
        })?;
        return validated_image(data, Some(mime_type), location);
    }

    if uri.contains(':') && !uri.starts_with("file:") {
        return Err(invalid_image(format!(
            "{location}/uri uses an unsupported URI scheme"
        )));
    }
    let base = base.ok_or_else(|| {
        invalid_image(format!(
            "{location}/uri is an external reference that cannot be resolved by `from_bytes`"
        ))
    })?;
    let encoded_path = uri
        .strip_prefix("file://")
        .or_else(|| uri.strip_prefix("file:"))
        .unwrap_or(uri);
    let decoded_path = urlencoding::decode(encoded_path).map_err(|error| {
        invalid_image(format!(
            "{location}/uri is not valid percent-encoded UTF-8: {error}"
        ))
    })?;
    let decoded_path = PathBuf::from(decoded_path.as_ref());
    let path = if decoded_path.is_absolute() {
        decoded_path
    } else {
        base.join(decoded_path)
    };
    let data = std::fs::read(&path).map_err(|source| LoadError::Io {
        path: path.clone(),
        source,
    })?;
    validated_image(data, declared_mime_type, location)
}

fn validated_image(
    data: Vec<u8>,
    declared_mime_type: Option<&str>,
    location: &str,
) -> Result<AvatarImage, LoadError> {
    if data.is_empty() {
        return Err(invalid_image(format!("{location} contains an empty image")));
    }
    let guessed_format = image_crate::guess_format(&data).map_err(|error| {
        invalid_image(format!(
            "{location} is not an encoded PNG or JPEG image: {error}"
        ))
    })?;
    let guessed_mime_type = mime_for_encoded_format(guessed_format).ok_or_else(|| {
        invalid_image(format!(
            "{location} must contain an encoded PNG or JPEG image"
        ))
    })?;
    if let Some(declared) = declared_mime_type {
        let declared_format = encoded_format_for_mime(declared, location)?;
        if declared_format != guessed_format {
            return Err(invalid_image(format!(
                "{location} declares `{declared}` but contains `{guessed_mime_type}` bytes"
            )));
        }
    }
    image_crate::load_from_memory_with_format(&data, guessed_format).map_err(|error| {
        invalid_image(format!("{location} contains a malformed image: {error}"))
    })?;
    Ok(AvatarImage {
        mime_type: guessed_mime_type.to_string(),
        data,
    })
}

fn encoded_format_for_mime(mime_type: &str, location: &str) -> Result<ImageFormat, LoadError> {
    match mime_type {
        "image/png" => Ok(ImageFormat::Png),
        "image/jpeg" => Ok(ImageFormat::Jpeg),
        _ => Err(invalid_image(format!(
            "{location} must be `image/png` or `image/jpeg`, found `{mime_type}`"
        ))),
    }
}

fn mime_for_encoded_format(format: ImageFormat) -> Option<&'static str> {
    match format {
        ImageFormat::Png => Some("image/png"),
        ImageFormat::Jpeg => Some("image/jpeg"),
        _ => None,
    }
}

fn invalid_image(message: String) -> LoadError {
    LoadError::InvalidVrm(message)
}