ThreeDViewer

A high-performance Flutter package for viewing 3D models (GLB/GLTF) with support for animations, camera controls, custom textures, and AR using Three.js and InAppWebView.

Features

  • GLB/GLTF Support: Render high-quality 3D models seamlessly.
  • Flutter Widget Overlays: Place any native Flutter widget (buttons, labels, etc.) at specific 3D coordinates. These widgets track the model and support occlusion detection.
  • Integrated AR: Launch models in Augmented Reality (Scene Viewer on Android, Quick Look on iOS).
  • Animation Control: Play, pause, and scrub through specific animation layers.
  • Interactive Hotspots: Add clickable HTML-based hotspots that track points on the model.
  • Auto-Rotate: Customizable auto-rotation with controllable speed and direction.
  • Intuitive Camera: Supports orbit controls with customizable limits (up, down, left, right).
  • Zoom Configuration: Set initial zoom levels and define min/max zoom constraints.
  • Auto-Centering: Automatically center models at the origin for consistent viewing.
  • Debug Helpers: Toggle grid, axes, and target markers for development and positioning.
  • Custom Loader: Add your own Flutter widget as a loading indicator while the model loads.
  • Background Transparency: Support for transparent or custom-colored backgrounds.
  • Local & Remote Assets: Load models from Flutter assets or remote URLs.
  • Cross-Platform: Support for Android, iOS, and Flutter Web.

Getting started

Add three_d_viewer to your pubspec.yaml:

dependencies:
  three_d_viewer: ^0.3.1

Platform Setup

Android

Ensure your minSdkVersion is at least 21 in android/app/build.gradle.

iOS

Ensure your Deployment Target is at least 15.0. To use AR features, add the following to your Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>https</string>
  <string>http</string>
</array>

Usage

Simple Implementation

import 'package:three_d_viewer/three_d_viewer.dart';

ThreeDViewer(
  assetPath: 'assets/models/my_model.glb', // or URL
  autoPlay: true,
)

Advanced Implementation

final ThreeDViewerController _controller = ThreeDViewerController();

ThreeDViewer(
  controller: _controller,
  assetPath: 'assets/models/my_model.glb',
  backgroundColor: Colors.transparent,
  autoCenter: true,
  autoRotateConfig: ThreeDAutoRotateConfig(
    autoRotate: true,
    speed: 5.0,
  ),
  debugConfig: ThreeDDebugConfig(
    showGrid: true,
    showAxes: true,
  ),
  hotspots: [
    ThreeDHotspot(
      id: 'h1',
      position: [0, 1.5, 0],
      label: 'Head',
      color: Colors.red,
    ),
  ],
  onHotspotTapped: (id) => print("Tapped hotspot: $id"),
  onAnimationsLoaded: (animations) {
    print("Loaded ${animations.length} animations");
  },
  overlays: [
    ThreeDOverlay(
      id: 'info_label',
      position: [0, 2, 0],
      child: Container(
        padding: EdgeInsets.all(8),
        color: Colors.black54,
        child: Text("Part Info", style: TextStyle(color: Colors.white)),
      ),
    ),
  ],
)

// Control the viewer
_controller.toggleAnimation(true);
_controller.playAnimation('Walk', loop: true); // Play specific animation
_controller.setMaterialColor('Body_Mesh', Colors.blue);
_controller.goToView(180, 90, 5.0); // Yaw, Pitch, Distance
_controller.launchAR();

Additional information

For a full implementation example, check the example folder.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you encounter any bugs or have feature requests, please file an issue on the GitHub repository.

Libraries

three_d_viewer