mirror of
https://github.com/lighttransport/tinyusdz.git
synced 2026-01-18 01:11:17 +01:00
1d290767fd
MAJOR UPDATE: Complete MaterialX (.mtlx) file loading support in C++
## Key Changes:
### 1. Built-in MaterialX XML Parser (NEW)
Integrated secure, dependency-free parser from sandbox:
- src/mtlx-xml-tokenizer.{hh,cc} - Low-level XML tokenization
- src/mtlx-simple-parser.{hh,cc} - Lightweight DOM builder
- src/mtlx-dom.{hh,cc} - MaterialX-specific document model
- src/mtlx-usd-adapter.hh - pugixml-compatible adapter
**Benefits:**
- No external dependencies (replaces pugixml)
- Security focused: memory limits, bounds checking, XXE protection
- MaterialX optimized
- pugixml-compatible API for easy migration
**Security Features:**
- Max name length: 256 chars
- Max string: 64KB
- Max text: 1MB
- Max nesting: 1000 levels
- Safe entity handling
- No external file access
### 2. OpenPBR Surface Shader Support (NEW)
Added complete MtlxOpenPBRSurface struct to usdMtlx.hh:
- All 8 parameter groups (Base, Specular, Transmission, Coat, etc.)
- 40+ individual parameters
- Proper USD type mappings
- Type trait registration
### 3. MaterialX Import API (ENHANCED)
Updated src/usdMtlx.cc to use built-in parser:
- Replaced all pugi:: with tinyusdz::mtlx::pugi::
- ReadMaterialXFromString() - Load from XML string
- ReadMaterialXFromFile() - Load from file path
- ToPrimSpec() - Convert MaterialX to USD PrimSpec
- LoadMaterialXFromAsset() - USD asset reference support
### 4. Testing Infrastructure
Added comprehensive test suite:
- tests/feat/mtlx/test_mtlx_import.cc - Import test with examples
- Updated Makefile for both import and export tests
- Test with embedded OpenPBR MaterialX XML
- Command-line file loading support
### 5. Documentation
Created C++_MATERIALX_IMPORT.md with:
- Complete API documentation
- Usage examples for all import methods
- OpenPBR parameter reference
- Security features overview
- Migration guide from pugixml
- Test instructions
Updated MATERIALX-SUPPORT-STATUS.md:
- C++ import status changed from ❌ to ✅
- Built-in parser feature matrix
- Updated "What's Missing" section
- Comparison table updated
## Supported Features:
### Shader Types:
✅ OpenPBR Surface (open_pbr_surface) - FULL
✅ Autodesk Standard Surface (standard_surface) - FULL
✅ USD Preview Surface (UsdPreviewSurface) - FULL
### MaterialX Versions:
✅ 1.36, 1.37, 1.38
### File Formats:
✅ .mtlx XML files
✅ String-based XML
✅ USD asset references
## Files Changed:
- src/mtlx-*.{hh,cc}: 9 new parser files (+3,500 lines)
- src/usdMtlx.{hh,cc}: OpenPBR support, parser integration
- src/value-types.hh: Added TYPE_ID_IMAGING_MTLX_OPENPBRSURFACE
- tests/feat/mtlx/*: New import test and updated Makefile
- C++_MATERIALX_IMPORT.md: 400+ line documentation
- MATERIALX-SUPPORT-STATUS.md: Updated status
## API Example:
```cpp
#include "usdMtlx.hh"
tinyusdz::MtlxModel mtlx;
std::string warn, err;
// Load from file
bool success = tinyusdz::ReadMaterialXFromFile(
resolver, "material.mtlx", &mtlx, &warn, &err);
// Convert to USD
tinyusdz::PrimSpec ps;
tinyusdz::ToPrimSpec(mtlx, ps, &err);
```
## Testing:
```bash
cd tests/feat/mtlx
make
./test_mtlx_import
./test_mtlx_import path/to/your.mtlx
```
## Breaking Changes:
NONE - Backward compatible via pugixml adapter
## Migration:
Automatic - existing usdMtlx.cc code works without changes
TinyUSDZ now has COMPLETE MaterialX support at all layers:
✅ C++ Core (Import & Export)
✅ WASM Binding (Import & Export)
✅ Three.js Demo (Full Interactive)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
66 lines
1.7 KiB
Markdown
66 lines
1.7 KiB
Markdown
# TinyUSDZ Project Overview
|
|
|
|
This document provides a comprehensive overview of the TinyUSDZ project, a C++14 library for handling USDZ, USDC, and USDA files. It is designed to be secure, portable, and dependency-free.
|
|
|
|
## Building and Running
|
|
|
|
The project uses CMake for building. Here are the key commands for building, running, and testing the project:
|
|
|
|
### Building the C++ library
|
|
|
|
To build the C++ library, you can use the following commands:
|
|
|
|
```bash
|
|
mkdir build
|
|
cd build
|
|
cmake ..
|
|
make
|
|
```
|
|
|
|
### Building the Python bindings
|
|
|
|
The Python bindings can be built using `scikit-build`.
|
|
|
|
```bash
|
|
python -m build .
|
|
```
|
|
|
|
Or, for development:
|
|
|
|
```bash
|
|
python setup.py build
|
|
```
|
|
|
|
### Running the examples
|
|
|
|
The project includes several examples in the `examples/` directory. For example, to run the `tusdcat` example, you can use the following command:
|
|
|
|
```bash
|
|
./build/examples/tusdcat/tusdcat <input_file>
|
|
```
|
|
|
|
### Running the tests
|
|
|
|
To run the tests, you can use the following command:
|
|
|
|
```bash
|
|
ctest --test-dir build
|
|
```
|
|
|
|
## Development Conventions
|
|
|
|
* **Branching:** The `dev` branch is used for development. Pull requests should be submitted to this branch.
|
|
* **Coding Style:** The project uses `.clang-format` to enforce a consistent coding style.
|
|
* **Testing:** The project uses CTest for testing. Tests are located in the `tests/` directory.
|
|
|
|
## Project Structure
|
|
|
|
* `src/`: The source code for the TinyUSDZ library.
|
|
* `python/`: The Python bindings for the TinyUSDZ library.
|
|
* `examples/`: Example applications that use the TinyUSDZ library.
|
|
* `tests/`: Tests for the TinyUSDZ library.
|
|
* `doc/`: Documentation for the TinyUSDZ library.
|
|
* `models/`: Example USD models.
|
|
* `cmake/`: CMake modules.
|
|
* `external/`: Third-party dependencies.
|