npm-tnb-usdz-viewer

A React component for viewing USDZ files using Three.js and the three-usdz-loader package. This component provides a powerful 3D viewer with orbit controls, automatic camera fitting, and support for loading USDZ files from both URLs and local client files.

Features

• 🚀 React Component - Easy to integrate into any React application
• 🎨 Three.js Powered - High-performance 3D rendering
• 📁 USDZ Support - Native support for USDZ file format
• 📂 Local File Loading - Load USDZ files directly from client's device
• 🌐 URL Loading - Load USDZ files from remote URLs
• 🖱️ Orbit Controls - Intuitive 3D navigation with mouse/touch
• 📱 Responsive - Adapts to container dimensions
• 🎯 TypeScript - Full TypeScript support with type definitions
• 🔧 Customizable - Configurable background, dimensions, and callbacks
• 📊 Event Handling - Load success/error callbacks
• 🎮 Auto-fit Camera - Automatically positions camera for optimal viewing
• 💾 File Management - Built-in file input with drag & drop support

Installation

npm install npm-tnb-usdz-viewer

Prerequisites

This package requires the following peer dependencies:

{
  "react": ">=16.8.0",
  "react-dom": ">=16.8.0"
}

And the following dependencies will be installed automatically:

{
  "three": "^0.166.1",
  "three-usdz-loader": "^1.0.9"
}

What's Included

This package bundles all necessary files, so clients don't need to provide:

• WASM files - Required for USDZ loading (emHdBindings.wasm, emHdBindings.js, etc.)
• HDR files - Environment maps for realistic lighting (studio_country_hall_1k.hdr)

Quick Start

import React from 'react';
import { USDZViewer } from 'npm-tnb-usdz-viewer';

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <USDZViewer 
        usdzUrl="https://example.com/model.usdz"
        autoLoad={true}
      />
    </div>
  );
}

Usage Examples

Basic Usage

import { USDZViewer } from 'npm-tnb-usdz-viewer';

function BasicViewer() {
  return (
    <USDZViewer 
      width="800px"
      height="600px"
      usdzUrl="https://example.com/model.usdz"
    />
  );
}

With Event Handlers

import { USDZViewer, USDZViewerProps } from 'npm-tnb-usdz-viewer';

function ViewerWithHandlers() {
  const handleLoad = (model: any) => {
    console.log('Model loaded successfully:', model);
  };

  const handleError = (error: Error) => {
    console.error('Failed to load model:', error);
  };

  return (
    <USDZViewer 
      usdzUrl="https://example.com/model.usdz"
      autoLoad={true}
      onLoad={handleLoad}
      onError={handleError}
    />
  );
}

Custom Styling

import { USDZViewer } from 'npm-tnb-usdz-viewer';

function CustomStyledViewer() {
  return (
    <USDZViewer 
      width="100%"
      height="100vh"
      backgroundColor="#000000"
      className="my-custom-viewer"
      style={{
        border: '2px solid #333',
        borderRadius: '8px'
      }}
    />
  );
}

Dynamic URL Loading

import React, { useState } from 'react';
import { USDZViewer } from 'npm-tnb-usdz-viewer';

function DynamicViewer() {
  const [modelUrl, setModelUrl] = useState('https://example.com/model1.usdz');

  const loadModel = (url: string) => {
    setModelUrl(url);
  };

  return (
    <div>
      <button onClick={() => loadModel('https://example.com/model1.usdz')}>
        Load Model 1
      </button>
      <button onClick={() => loadModel('https://example.com/model2.usdz')}>
        Load Model 2
      </button>
      
      <USDZViewer 
        usdzUrl={modelUrl}
        width="800px"
        height="600px"
      />
    </div>
  );
}

Local File Loading

import { USDZViewer } from 'npm-tnb-usdz-viewer';

function LocalFileViewer() {
  return (
    <USDZViewer 
      width="800px"
      height="600px"
      showFileInput={true} // Enable file input (default: true)
      backgroundColor="#f0f0f0"
    />
  );
}

Customized Viewer with Local File Support

import { USDZViewer } from 'npm-tnb-usdz-viewer';

function CustomViewer() {
  return (
    <USDZViewer 
      width="100%"
      height="100vh"
      backgroundColor="#000000"
      showFileInput={false} // Hide file input if you want to handle file loading programmatically
      onLoad={(model) => {
        console.log('Model loaded:', model);
        // Handle successful load
      }}
      onError={(error) => {
        console.error('Load error:', error);
        // Handle error
      }}
    />
  );
}

API Reference

Props

Events

onLoad

Called when a USDZ model is successfully loaded. Receives the loaded model instance.

const handleLoad = (model: USDZInstance) => {
  console.log('Model loaded:', model);
  // Access model properties, animations, etc.
};

onError

Called when there's an error loading the USDZ model. Receives the error object.

const handleError = (error: Error) => {
  console.error('Loading failed:', error.message);
  // Handle error (show user message, retry, etc.)
};

Browser Controls

The viewer provides intuitive 3D navigation controls:

• Left Click + Drag: Rotate the view around the model
• Right Click + Drag: Pan the view
• Scroll Wheel: Zoom in/out
• Touch: Pinch to zoom, drag to rotate/pan

Browser Compatibility

• Chrome/Edge: Full support
• Firefox: Full support
• Safari: Full support (macOS 11+)
• Mobile: Limited support (WebGL restrictions)

Troubleshooting

Common Issues

1. USDZ Loader Not Initializing

   • Ensure the three-usdz-loader package is installed
   • Check browser console for WebAssembly errors
   • Verify SharedArrayBuffer support in your browser

2. File Loading Errors

   • Check if the USDZ file URL is accessible
   • Ensure the file format is correct (.usdz)
   • Check CORS settings if loading from external domains

3. Performance Issues

   • Large USDZ files may take time to load
   • Consider file size optimization
   • Check device capabilities for WebGL support

Debug Mode

Enable console logging to debug issues:

// The component logs detailed information to console
// Check browser console for loading progress and errors
<USDZViewer 
  usdzUrl="https://example.com/model.usdz"
  onError={(error) => console.error('Viewer error:', error)}
/>

Development

Building from Source

git clone <repository-url>
cd npm-tnb-usdz-viewer
npm install
npm run build

Available Scripts

• npm run build - Build the package for production
• npm run dev - Build in watch mode for development
• npm run clean - Clean the dist directory
• npm run prepublishOnly - Clean and build before publishing

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions:

1. Check the troubleshooting section
2. Review browser console errors
3. Verify file formats and dependencies
4. Check browser compatibility

Built with ❤️ using React, Three.js, and TypeScript