gltf-v1-json

glTF 1.0 JSON serialization and deserialization

Complete glTF 1.0 JSON schema implementation with validation

:book: Table of Contents

:pencil: About The Crate

gltf-v1-json provides JSON serialization and deserialization for the glTF 1.0 specification. This crate is part of the asset-importer-rs project and implements the complete glTF 1.0 JSON schema with comprehensive validation support, enabling robust parsing and generation of glTF 1.0 files.

This crate provides the essential functionality for:

• JSON Serialization - Complete glTF 1.0 to JSON conversion
• JSON Deserialization - JSON to glTF 1.0 structure parsing
• Schema Validation - Comprehensive validation system
• Extension Support - glTF 1.0 extension compatibility
• Error Reporting - Path-based error reporting and validation
• Type Safety - Strongly typed glTF 1.0 data structures

:cloud: Features

• Complete glTF 1.0 Schema - Full JSON schema implementation
• Serde Integration - Seamless serialization and deserialization
• Comprehensive Validation - Automatic validation through derive macros
• Extension Support - Feature flag-based extension compatibility
• Path-based Error Reporting - Detailed error location and context
• Type Safety - Strongly typed data structures
• Custom Validation Hooks - Extensible validation system
• Indexed Collections - Efficient hash map support with serialization

:puzzle_piece: Supported Extensions

The following glTF 1.0 extensions are supported through feature flags:

Core Extensions

• KHR_binary_glTF - Binary buffer support
• KHR_materials_common - Common material types

Feature Flags

• extensions - Enable all extension support
• extras - Enable extras field support

:floppy_disk: Main Components

Core glTF Components

• Root - Main glTF document structure
• Asset - Version and metadata information
• Buffer - Raw data storage
• Accessor - Buffer access and type information
• Animation - Keyframe animations
• Camera - Camera definitions
• Material - Material properties and techniques
• Mesh - Geometry data
• Node - Scene graph nodes
• Scene - Scene organization
• Shader - GLSL shader programs
• Skin - Skeletal animations
• Texture - Image and sampler definitions

Serialization Functions

• deserialize - JSON to glTF structure conversion
• serialize - glTF structure to JSON conversion
• from_str - String-based deserialization
• to_string_pretty - Pretty-printed JSON output

:book: Getting Started

Add the following to your Cargo.toml:

[dependencies]
gltf-v1-json = "0.3.0"

# Or for development from source:
gltf-v1-json = { path = "../path/to/gltf-v1-json" }

# Enable specific extensions
[features]
default = []
extensions = []
extras = []
KHR_binary_glTF = []
KHR_materials_common = []

:small_orange_diamond: Usage Examples

Basic JSON deserialization example:

use gltf_v1_json::{
    Root,
    deserialize,
    serialize,
};

// Deserialize from JSON string
let json_str = r#"{
    "asset": { "version": "1.0" },
    "scenes": [],
    "meshes": []
}"#;
let gltf: Root = deserialize::from_str(json_str)?;

// Access glTF data
println!("glTF version: {}", gltf.asset.version);
println!("Number of scenes: {}", gltf.scenes.len());

JSON serialization example:

use gltf_v1_json::{Root, serialize};

// Create a glTF structure
let mut gltf = Root::default();
gltf.asset.version = "1.0".to_string();

// Serialize to JSON
let json = serialize::to_string_pretty(&gltf)?;
println!("Generated JSON:\n{}", json);

Working with extensions:

use gltf_v1_json::{Root, deserialize};

// Deserialize with extension support
let json_with_extensions = r#"{
    "asset": { "version": "1.0" },
    "extensionsUsed": ["KHR_materials_common"],
    "materials": [{
        "name": "material1",
        "extensions": {
            "KHR_materials_common": {
                "technique": "BLINN",
                "values": {
                    "ambient": [0.1, 0.1, 0.1],
                    "diffuse": [0.8, 0.8, 0.8]
                }
            }
        }
    }]
}"#;

let gltf: Root = deserialize::from_str(json_with_extensions)?;

:warning: Validation

The crate includes a robust validation system designed to ensure glTF 1.0 specification compliance and provide detailed error reporting for debugging and development.

Validation Features

• Automatic Validation - Validation through derive macros
• Path-based Error Reporting - Detailed error location information
• Extension-specific Validation - Extension compatibility checking
• Custom Validation Hooks - Extensible validation system
• Schema Compliance - glTF 1.0 specification validation

:small_orange_diamond: Dependencies

Core Dependencies

• serde - Serialization framework
• serde_json - JSON serialization
• serde_derive - Serialization derive macros
• indexmap - Indexed hash map with serialization support
• gltf-v1-derive - Validation derive macros

Feature Dependencies

• indexmap/serde - Serialization support for indexed maps

:scroll: License

This project is part of the asset-importer-rs workspace and follows its licensing terms. See the main project LICENSE file for details.

Copyright (c) 2024 Jackson Levitt