How k2209/usdz_convertor_node_api works
Project Type and Purpose
• This is a self-hosted backend REST API service (“usdz_convertor_node_api”) that offers on-demand conversion of remote .glb 3D model URLs into .usdz format for iOS AR QuickLook.
• It leverages two supporting Docker builds:
• A base “Pixar USD” image (usd directory + Dockerfile)
• A “gltf-to-usdz” image layered on top of USD (usd-from-gltf directory + Dockerfile)
• The Node.js/Express app orchestrates conversions by invoking Docker, serving files and cleanup.
File Structure
• Top-level:
• usd/ → Dockerfile to build Pixar USD libraries
• usd-from-gltf/ → Dockerfile that installs Google’s usd_from_gltf tool atop USD
• usdz_convertor_api/ → The Node.js Express REST API
• Inside usdz_convertor_api:
• public/converted → Exposed folder for final .usdz files
• temp/ → Temp workspace for downloads & intermediate outputs
• config.js, .env, server.js → API configuration and entrypoint
• No frontend code; this is a pure backend/microservice architecture.
• Dependencies and scripts managed via package.json.
README for Additional Insights
• Workflow described in Quick Setup:
1. Build base USD image (docker build in usd)
2. Build glTF-to-USDZ image (docker build in usd-from-gltf)
3. Install Node.js deps, configure .env, launch server.js
4. API exposes:
• GET /convertglbtousdz?url=<GLB_URL>
• PATCH /health
• Mentions optional Nginx reverse proxy for pretty URLs.
a. Components:
1. Client (curl, mobile/web AR viewer)
2. (Optional) Nginx Reverse Proxy
3. Node.js Express API Service
– Config, Environment Variables
– public/converted folder (static hosting)
– temp/ folder (ephemeral workspace)
4. Docker Engine
– USD Base Image (leon/usd:latest)
– glTF→USDZ Image (gltf-to-usdz:latest)
5. External Storage/Download (for remote .glb URLs)
b. Interactions & Data Flow:
• Client → (Nginx) → Express API
• Express downloads .glb into temp/
• Express issues Docker run: mounts temp/, public/converted into container
• Converter container uses usd_from_gltf within gltf-to-usdz image to produce .usdz
• Container writes .usdz to public/converted
• Express deletes temp, responds with a link to the .usdz in public/converted
• Client → HTTP GET on returned URL → iOS AR QuickLook
c. Architectural Patterns & Principles:
– Microservice/Worker pattern: the API delegates heavy-lift conversion to Docker containers
– Separation of concerns: Docker images handle conversion logic; Node API handles orchestration & HTTP layer
– Ephemeral compute: temporary files are auto-removed after each run
– Static asset hosting via Express (or optional Nginx)
d. Key Technologies & Frameworks:
– Node.js + Express
– Docker Engine
– Pixar USD, Google usd_from_gltf
– Linux filesystem mounts for sharing between host & container
– (Optional) Nginx reverse proxy for SSL and URL rewriting