O3D – Model Viewer for Flutter

https://pub.dev/packages/model_viewer_plus – Fork from this package.

This is a Flutter widget for rendering interactive 3D models in the glTF and GLB formats.

The widget embeds Google’s <model-viewer> web component in a WebView.

Screenshot

old man	Astronaut

Compatibility

Android
iOS (AR View may not available on iOS 16+)
Web, with a recent system browser version.

Notes

We use the Google APP, com.google.android.googlequicksearchbox to display interactive 3D models on Android. The model displays in ‘ar_preferred’ mode by default, Scene Viewer launches in AR native mode as the entry mode. If Google Play Services for AR (ARCore, com.google.ar.core) isn’t present, Scene Viewer gracefully falls back to 3D mode as the entry mode.

Installation

`pubspec.yaml`

dependencies:
  o3d: any

`AndroidManifest.xml` (Android 9+ only)

To use this widget on Android 9+ devices, your app must be permitted to make an HTTP connection to http://localhost:XXXXX. Android 9 (API level 28) changed the default for android:usesCleartextTraffic from true to false, so you will need to configure your app’s android/app/src/main/AndroidManifest.xml as follows:

     <application
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher"
        android:label="example"
+       android:usesCleartextTraffic="true">
        <activity
            android:name=".MainActivity"

This does not affect Android 8 and earlier. See [#7] for more information.

`app/build.gradle` (Android only)

Change minSdkVersion to 21.

defaultConfig {
    ...
    minSdkVersion 21
    ...
}

`Info.plist` (iOS only)

To use this widget on iOS, you need to opt-in to the embedded views preview by adding a boolean property to your app’s ios/Runner/Info.plist file, with the key io.flutter.embedded_views_preview and the value YES:

  <key>io.flutter.embedded_views_preview</key>
  <true/>

`web/index.html` (Web only)

Modify the <head> tag of your web/index.html to load the JavaScript, like so:

<head>

  <!-- Other stuff -->

   <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.1.1/model-viewer.min.js" defer></script>
</head>

./assets/packages/model_viewer_plus/assets/model-viewer.min.js will use the default js file which is included in this package’s asset. The official site uses unpkg, by using https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js, you are using the latest version of <model-viewier>. You may replace the value of src attribute with another CDN mirror’s URL. But please notice that our model-viewer-plus maybe not able to keep up with the <model-viewier>‘s latest version.

Features

Renders glTF and GLB models. (Also, USDZ models on iOS 12+.)
Supports animated models, with a configurable auto-play setting.
Optionally supports launching the model into an AR viewer.
Optionally auto-rotates the model, with a configurable delay.
Supports a configurable background color for the widget.

Examples

Importing the library

import 'package:o3d/o3d.dart';

Creating a `O3D` widget

class _MyHomePageState extends State<MyHomePage> {
  
  // to control the animation
+ O3DController controller = O3DController();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(widget.title),
        actions: [
          IconButton(
              onPressed: () => 
+                 controller.cameraOrbit(20, 20, 5),
              icon: const Icon(Icons.change_circle)),
          IconButton(
              onPressed: () =>
+                 controller.cameraTarget(1.2, 1, 4), 
              icon: const Icon(Icons.change_circle_outlined)),
        ],
      ),
+     body: O3D(
+       controller: controller,
+       src: 'assets/glb/jeff_johansen_idle.glb',
+     ),
    );
  }
}

New feature is controller

methods:

cameraTarget:

use controller.cameraTarget(20, 20, 5)

According to web-based features https://modelviewer.dev/examples: Set the starting and/or subsequent point the camera orbits around. Accepts values of the form “$X $Y $Z”, like “0m 1.5m -0.5m”. Also supports units in centimeters (“cm”) or millimeters (“mm”). A special value “auto” can be used, which sets the target to the center of the model’s bounding box in that dimension. Any time this value changes from its initially configured value, the camera will interpolate from its current position to the new value.

cameraOrbit:

use controller.cameraOrbit(1.2, 1, 4)

According to web-based features https://modelviewer.dev/examples: Set the starting and/or subsequent orbital position of the camera. You can control the azimuthal, theta, and polar, phi, angles (phi is measured down from the top), and the radius from the center of the model. Accepts values of the form “$theta $phi $radius”, like “10deg 75deg 1.5m”. Also supports units in radians (“rad”) for angles and centimeters (“cm”) or millimeters (“mm”) for camera distance. Camera distance can also be set as a percentage (‘%’), where 100% gives the model tight framing within any window based on all possible theta and phi values. Any time this value changes from its initially configured value, the camera will interpolate from its current position to the new value. Any value set to ‘auto’ will revert to the default. For camera-orbit, camera-target and field-of-view, parts of the property value can be configured with CSS-like functions. The CSS calc() function is supported for these values, as well as a specialized form of the env() function. You can use env(window-scroll-y) anywhere in the expression to get a number from 0-1 that corresponds to the current top-level scroll position of the current frame. For example, a value like “calc(30deg – env(window-scroll-y) * 60deg) 75deg 1.5m” cause the camera to orbit horizontally around the model as the user scrolls down the page.

other methods will be added as soon as possible.

Loading a bundled Flutter asset

body: O3D(
// ...
  src: 'assets/MyModel.glb',
// ...
),

Loading a model from the file system

This is not avaliable on Web.

body: O3D(
// ...
  src: 'file:///path/to/MyModel.glb',
// ...
),

Loading a model from the web

body: O3D(
// ...
  src: 'https://modelviewer.dev/shared-assets/models/Astronaut.glb',
// ...
),

Note that due to browsers’ CORS security restrictions, the model file must be served with a Access-Control-Allow-Origin: * HTTP header.

Frequently Asked Questions

Q: Why doesn’t my 3D model load and/or render?

A: There are several reasons why your model URL could fail to load and render:

It might not be possible to parse the provided glTF or GLB file. Some tools can produce invalid files when exporting glTF. Always run your model files through the glTF Validator to check for this.

GitHub

View Github