Skip to main content

vrm_runtime/
image.rs

1use std::path::{Path, PathBuf};
2
3use image_crate::{GenericImageView, ImageFormat};
4
5use crate::LoadError;
6
7/// Encoded PNG or JPEG bytes stored by the avatar asset.
8///
9/// Images loaded from buffer views, data URIs, and relative file URIs retain
10/// their original encoded bytes. Loading rejects missing, empty, malformed, or
11/// unsupported sources instead of creating placeholder images.
12#[derive(Debug, Clone)]
13pub struct AvatarImage {
14    /// Media type (`image/png` or `image/jpeg`).
15    pub mime_type: String,
16    /// Original encoded PNG or JPEG bytes.
17    pub data: Vec<u8>,
18}
19
20impl AvatarImage {
21    /// Creates an encoded image for a programmatically assembled asset.
22    ///
23    /// Cross-object asset validation checks references, but callers are
24    /// responsible for supplying valid encoded bytes to this constructor.
25    pub fn new(mime_type: impl Into<String>, data: impl Into<Vec<u8>>) -> Self {
26        Self {
27            mime_type: mime_type.into(),
28            data: data.into(),
29        }
30    }
31
32    /// Returns the encoded image's media type.
33    pub fn mime_type(&self) -> &str {
34        &self.mime_type
35    }
36
37    /// Returns the original encoded image bytes.
38    pub fn data(&self) -> &[u8] {
39        &self.data
40    }
41}
42
43/// Validates the source shape without calling `gltf::Image::source`, whose
44/// infallible API unwraps malformed combinations of glTF image properties.
45pub(crate) fn validate_raw_sources(root: &gltf::json::Root) -> Result<(), LoadError> {
46    for (index, image) in root.images.iter().enumerate() {
47        let location = format!("/images/{index}");
48        match (&image.uri, &image.buffer_view) {
49            (Some(_), Some(_)) => {
50                return Err(invalid_image(format!(
51                    "{location} must contain exactly one of `uri` or `bufferView`"
52                )));
53            }
54            (None, None) => {
55                return Err(invalid_image(format!(
56                    "{location} must contain exactly one of `uri` or `bufferView`"
57                )));
58            }
59            (Some(uri), None) => {
60                if uri.is_empty() {
61                    return Err(invalid_image(format!("{location}/uri must not be empty")));
62                }
63                if let Some(mime_type) = image.mime_type.as_ref() {
64                    encoded_format_for_mime(&mime_type.0, &format!("{location}/mimeType"))?;
65                }
66            }
67            (None, Some(_)) => {
68                let mime_type = image.mime_type.as_ref().ok_or_else(|| {
69                    invalid_image(format!(
70                        "{location}/mimeType is required when `bufferView` is used"
71                    ))
72                })?;
73                encoded_format_for_mime(&mime_type.0, &format!("{location}/mimeType"))?;
74            }
75        }
76    }
77    Ok(())
78}
79
80pub(crate) fn load_images(
81    doc: &gltf::Document,
82    buffers: &[gltf::buffer::Data],
83    base: Option<&Path>,
84) -> Result<Vec<AvatarImage>, LoadError> {
85    doc.as_json()
86        .images
87        .iter()
88        .enumerate()
89        .map(|(index, image)| {
90            let location = format!("/images/{index}");
91            if let Some(view_index) = image.buffer_view.as_ref() {
92                let view = doc.views().nth(view_index.value()).ok_or_else(|| {
93                    invalid_image(format!(
94                        "{location}/bufferView references missing buffer view {}",
95                        view_index.value()
96                    ))
97                })?;
98                let buffer = buffers.get(view.buffer().index()).ok_or_else(|| {
99                    invalid_image(format!(
100                        "{location}/bufferView references missing buffer {}",
101                        view.buffer().index()
102                    ))
103                })?;
104                let end = view.offset().checked_add(view.length()).ok_or_else(|| {
105                    invalid_image(format!("{location}/bufferView byte range overflows"))
106                })?;
107                let data = buffer.0.get(view.offset()..end).ok_or_else(|| {
108                    invalid_image(format!("{location}/bufferView exceeds its parent buffer"))
109                })?;
110                let mime_type = image.mime_type.as_ref().ok_or_else(|| {
111                    invalid_image(format!(
112                        "{location}/mimeType is required when `bufferView` is used"
113                    ))
114                })?;
115                validated_image(data.to_vec(), Some(&mime_type.0), &location)
116            } else {
117                let uri = image.uri.as_deref().ok_or_else(|| {
118                    invalid_image(format!(
119                        "{location} must contain exactly one of `uri` or `bufferView`"
120                    ))
121                })?;
122                load_uri_image(
123                    uri,
124                    image.mime_type.as_ref().map(|mime| mime.0.as_str()),
125                    base,
126                    &location,
127                )
128            }
129        })
130        .collect()
131}
132
133pub(crate) fn validate_thumbnail(
134    images: &[AvatarImage],
135    thumbnail_index: Option<usize>,
136) -> Result<(), LoadError> {
137    let Some(index) = thumbnail_index else {
138        return Ok(());
139    };
140    let image = images.get(index).ok_or_else(|| {
141        invalid_image(format!(
142            "/extensions/VRMC_vrm/meta/thumbnailImage references missing image {index}"
143        ))
144    })?;
145    let location = "/extensions/VRMC_vrm/meta/thumbnailImage";
146    let format = encoded_format_for_mime(image.mime_type(), location)?;
147    let decoded =
148        image_crate::load_from_memory_with_format(image.data(), format).map_err(|error| {
149            invalid_image(format!(
150                "{location} does not reference a valid PNG or JPEG: {error}"
151            ))
152        })?;
153    let (width, height) = decoded.dimensions();
154    if width != height {
155        return Err(invalid_image(format!(
156            "{location} must reference a square image, found {width}x{height}"
157        )));
158    }
159    Ok(())
160}
161
162fn load_uri_image(
163    uri: &str,
164    declared_mime_type: Option<&str>,
165    base: Option<&Path>,
166    location: &str,
167) -> Result<AvatarImage, LoadError> {
168    if let Some(data_uri) = uri.strip_prefix("data:") {
169        let (metadata, payload) = data_uri
170            .split_once(',')
171            .ok_or_else(|| invalid_image(format!("{location}/uri is not a valid data URI")))?;
172        let mime_type = metadata.strip_suffix(";base64").ok_or_else(|| {
173            invalid_image(format!(
174                "{location}/uri must use a base64-encoded PNG or JPEG data URI"
175            ))
176        })?;
177        encoded_format_for_mime(mime_type, &format!("{location}/uri"))?;
178        if let Some(declared) = declared_mime_type
179            && declared != mime_type
180        {
181            return Err(invalid_image(format!(
182                "{location}/mimeType `{declared}` does not match data URI media type `{mime_type}`"
183            )));
184        }
185        let data = base64::decode(payload).map_err(|error| {
186            invalid_image(format!(
187                "{location}/uri contains invalid base64 data: {error}"
188            ))
189        })?;
190        return validated_image(data, Some(mime_type), location);
191    }
192
193    if uri.contains(':') && !uri.starts_with("file:") {
194        return Err(invalid_image(format!(
195            "{location}/uri uses an unsupported URI scheme"
196        )));
197    }
198    let base = base.ok_or_else(|| {
199        invalid_image(format!(
200            "{location}/uri is an external reference that cannot be resolved by `from_bytes`"
201        ))
202    })?;
203    let encoded_path = uri
204        .strip_prefix("file://")
205        .or_else(|| uri.strip_prefix("file:"))
206        .unwrap_or(uri);
207    let decoded_path = urlencoding::decode(encoded_path).map_err(|error| {
208        invalid_image(format!(
209            "{location}/uri is not valid percent-encoded UTF-8: {error}"
210        ))
211    })?;
212    let decoded_path = PathBuf::from(decoded_path.as_ref());
213    let path = if decoded_path.is_absolute() {
214        decoded_path
215    } else {
216        base.join(decoded_path)
217    };
218    let data = std::fs::read(&path).map_err(|source| LoadError::Io {
219        path: path.clone(),
220        source,
221    })?;
222    validated_image(data, declared_mime_type, location)
223}
224
225fn validated_image(
226    data: Vec<u8>,
227    declared_mime_type: Option<&str>,
228    location: &str,
229) -> Result<AvatarImage, LoadError> {
230    if data.is_empty() {
231        return Err(invalid_image(format!("{location} contains an empty image")));
232    }
233    let guessed_format = image_crate::guess_format(&data).map_err(|error| {
234        invalid_image(format!(
235            "{location} is not an encoded PNG or JPEG image: {error}"
236        ))
237    })?;
238    let guessed_mime_type = mime_for_encoded_format(guessed_format).ok_or_else(|| {
239        invalid_image(format!(
240            "{location} must contain an encoded PNG or JPEG image"
241        ))
242    })?;
243    if let Some(declared) = declared_mime_type {
244        let declared_format = encoded_format_for_mime(declared, location)?;
245        if declared_format != guessed_format {
246            return Err(invalid_image(format!(
247                "{location} declares `{declared}` but contains `{guessed_mime_type}` bytes"
248            )));
249        }
250    }
251    image_crate::load_from_memory_with_format(&data, guessed_format).map_err(|error| {
252        invalid_image(format!("{location} contains a malformed image: {error}"))
253    })?;
254    Ok(AvatarImage {
255        mime_type: guessed_mime_type.to_string(),
256        data,
257    })
258}
259
260fn encoded_format_for_mime(mime_type: &str, location: &str) -> Result<ImageFormat, LoadError> {
261    match mime_type {
262        "image/png" => Ok(ImageFormat::Png),
263        "image/jpeg" => Ok(ImageFormat::Jpeg),
264        _ => Err(invalid_image(format!(
265            "{location} must be `image/png` or `image/jpeg`, found `{mime_type}`"
266        ))),
267    }
268}
269
270fn mime_for_encoded_format(format: ImageFormat) -> Option<&'static str> {
271    match format {
272        ImageFormat::Png => Some("image/png"),
273        ImageFormat::Jpeg => Some("image/jpeg"),
274        _ => None,
275    }
276}
277
278fn invalid_image(message: String) -> LoadError {
279    LoadError::InvalidVrm(message)
280}